HLD alignment and correction review

This review records the earlier module-to-package proposal. The current package structure consolidates those responsibilities into eight reusable packages and one validation tool.

Review date: 2026-10-25. Scope: current working-tree astrology HLDs, package plans and existing Binder source. This is a design/source review; no runtime packages or deployment are established by it. No external reference-software or almanac certification has been performed.

What is established

The HLDs support shared chart assembly above Binder and separate Vedic/Western calculation ownership. Every planned calculation family maps to an existing component or detailed HLD below. They do not prescribe 35 packages, npm paths, TypeScript factory names or feature-registration generics. Those are implementation proposals added for the requested package granularity. Contracts, context and evidence are supporting extractions of required behaviors, not additional astrological features. Exact schemas, profile conventions and numerical fixtures still need their named contract/design tasks before implementation.

Source precedence is: existing Binder code for available capabilities and input semantics; the Vedic/Western HLD component maps for current logical ownership; detailed calculation HLDs for rules; and package specifications for the proposed physical organization. Previously added package links in HLD introductions are navigation, not independent evidence for these choices.

Compose source traceability

Composer modules live under packages/chart-composer/src/; Binder adaptation lives in runtime. See module ownership.

Package	Source concern	Basis
`contracts`	Shared snapshot and port	Required common contract; separate package is a supporting extraction
`context`	Context-tagged chart facts	Required convention/context checks; extraction
`evidence`	Versions, chart/probe evidence	Required reproducibility; extraction
`binder-client`	Binder client and facade separation	Existing logical component, adapted to the real in-process API
`chart-core`	Frame, placement and rosters	Neutral subset only; judgments move to the appropriate tradition
`geometry`	Cross-chart geometry through Composer	Required shared surface; reuse existing semantics
`probes`	Bounded astronomy access	Required port/budgets; no new astronomy or interpretation
`composer`	Composition facade	Shared orchestration subset; no tradition calculations

Vedic source traceability

Each path is under packages/vedic/. See exports and dependencies.

Package	Source concern	Basis
`contracts`	Operation inputs and response evidence	Supporting extraction of common domain types
`profiles`	Profiles and rulebooks	Profile selection split from registry/integrity
`rulebooks`	One resolved rulebook per response	Registry/integrity split; table ownership stays with calculators
`chart-judgments`	Dignity, combustion and planetary war	Vedic ownership from the revised family HLD
`drishti`	Vedic drishti ownership	Policy/results wrapper over the existing semantics primitive
`varga`	Varga calculation HLD	Direct calculation family
`dasha`	Dasha calculation HLD	Direct calculation family
`ashtakavarga`	Natal BAV/SAV and transit scoring	Independent natal result reused by transit; extracted from the older transit grouping
`strengths`	Named strength systems and input audit	Gated family; Shadbala is not yet defined for implementation
`panchang`	Panchang calculation HLD	Direct family, gated by actual sunrise capability
`transit`	Transit calculation HLD	Direct family; BAV is supplied, never recalculated from moving positions
`matching`	Ashtakoota HLD	Pure Moon-fact calculation, independent of batching
`yoga-dosha`	Chart judgments and named exceptions	Extracted pack family; exact first pack requires V-12 definition
`muhurta`	Purpose-specific election operation	Direct family; V-13 defines the first purpose before implementation
`engine`	Coordinator and result assembly	Public orchestration; feature registration is a proposed wiring choice

Western source traceability

Each path is under packages/western/. See exports and dependencies.

Package	Source concern	Basis
`contracts`	Operation and derived-result evidence	Supporting extraction of common domain types
`profiles`	Profiles and convention selection	Selection split from registry/integrity
`rulebooks`	Versioned technique resources	Registry/integrity split; technique-owned rules
`natal`	Natal judgments	Direct calculation family
`transit`	Moving/reference contacts	Direct family; fixed-reference motion must be explicit
`synastry`	Cross-chart aspects and overlays	Direct family using the shared geometry surface
`composite`	Named relationship-chart methods	Direct family; W-05 midpoint definition
`progressions`	Mapped chart contexts and angle conventions	Direct family; W-05 progression definition
`returns`	Bounded return search and location policy	Direct family; W-05 return definition
`directions`	Solar arc; primary directions deferred	Direct family; W-05 direction definition
`harmonics`	Labelled coordinate transformation	Direct family; W-05 harmonic definition
`engine`	Coordinator and evidence assembly	Public orchestration; generic feature registration is a proposed wiring choice

Mistakes corrected in this review

Finding	Evidence	Correction and task impact
One observer field could silently change geocentric positions (from Earth’s centre) to topocentric (from the observer’s surface location)	Actual request/declaration contract	Separate position origin/observer from house observer in C-01/C-07/C-08 and profile/fixture tasks; local houses with geocentric planets are valid
“Unrounded/full precision” promised digits Binder does not return	Normalization defaults and rounding, provenance	Preserve returned values; identity includes normalization/semantics metadata; audit dasha tolerance against the actual upstream policy
A single same-read origin check could reject valid house/position combinations	Distinct declaration origins and ARMC meaning	Validate each operation’s expected origin; retain equatorial ARMC (the right ascension of the meridian) without ayanamsa (sidereal) subtraction
Cross-chart phase could reuse unrelated natal velocities	Aspect helper uses the difference of supplied speeds	C-03/W-03 use fixed natal-reference derivative; timeless synastry phase stays unknown unless explicitly defined
Dasha HLD incorrectly wrapped 359.9999° into Ashwini, the first nakshatra	Authoritative nakshatra intervals	Retain Revati pada 4 there; canonical 0° enters Ashwini. V-05 fixtures now state this directly
Remaining dasha balance was described as a shortened parent	Dasha cumulative-subdivision rule	Keep nominal full-parent subdivisions; birth selects the active child rather than rescaling every child
Dasha sensitivity was confused with the Moon’s physical travel time	Dasha balance definition	Recomputed from its own formula: seven-year period / 48000 arcseconds = 4602.15 seconds per arcsecond for a 365.25-day year
Native timeseries was a blanket prerequisite, including for pure matching	Revised family capability boundary, matching scope	C-04 real bounded per-instant acquisition may serve windows; batching is an optimization; matching has no astronomy prerequisite
Optional features acquired unnecessary implementation/type dependencies	Consumer requirements, shared geometry contract	Contact types live in compose/contracts; transit consumes a minimal BAV view; remaining mandatory type dependencies are reflected in task predecessors
Solver tolerance was presented as leap-second support	Current instant parser rejects second 60	Reuse the parser and reject unsupported strings; the one-second numerical tolerance is not a time-scale conversion
Old Binder privacy/licensing anchor no longer existed	Current Binder host boundary	Replaced the broken heading link and checked all local Markdown links/images under docs/astrology

Remaining implementation gates

B-01/C-05 must deliver actual rise/set support; current Binder advertises positions/houses only.
V-06/V-19, V-12/V-13 and W-05 still need system/pack/technique definitions and independently reviewed fixtures; no package name or export is proof of implemented support.
V-08 must freeze host-resolved day windows and offsets across civil-time transitions. C-01 must freeze origin, motion, optional-port and numerical-policy schemas before consumer implementation.
HLD latency/call budgets and astronomical accuracy require real measurements/reference fixtures. Structural link/dependency checks cannot establish those properties.

Verification evidence

The review checked HLD/source ownership, the documented package/task dependency graphs, local files/heading anchors and Markdown rendering. The existing semantics helper was exercised at 359.9999° and 0° and returned Revati pada 4 and Ashwini pada 1 respectively. The dasha sensitivity example was recomputed arithmetically from the documented period/fraction formula. A conjunction (aspect at 0° separation) example at transit longitude 121°/speed 1 and reference longitude 120° gives applying (see applying and separating) if historical reference speed 2 is incorrectly used, and separating with the fixed reference derivative 0. This checks the shared helper’s actual semantics; the missing policy was in the proposed cross-chart contract, not a defect in that helper. Documentation build/test results are reported with the task handoff; they verify documentation integration and do not replace future calculator, native-provider or published-almanac acceptance.