Chart Composer tasks

Modules share the Composer domain package. Read the module specifications and current package boundaries for source ownership and public APIs. See the overall assignment and integration plan. Implementation status: C-01–C-09 are implemented, including native Hindu solar events.

Verification: pnpm build:chart-composer, pnpm check:chart-composer, pnpm test:chart-composer. The native test runs real Swiss → Binder → reader → Composer for tropical/sidereal, geocentric/topocentric (measured from the observer’s place on Earth’s surface) charts, ARMC preservation, replay and events. Fixtures use independently compiled official Swiss C, not another astronomy model. The broader cross-engine S-02 slice remains separate. See host wiring.

C-01 — Specify the shared snapshot and Composer port

HLD: Vedic shared contract, Western shared contract, Composer chart contract. Depends on: S-01 for package compilation; agree the API before runtime work. Write scope: packages/chart-composer/**.

Define the contract both engines consume: resolved context, ordered body geometry, shared facts, cusps/angles, provenance, capabilities and errors. Export from @astrology/chart-composer.

Acceptance criteria:

[x] Contract includes instant, explicit position origin/observer separately from house observer, zodiac/ayanamsa (the angular offset between the tropical and sidereal zodiacs), house/frame, body/node and speed selection, and aspect policy identity; units and optional fields are documented.
[x] Snapshot identity covers those inputs and contributing versions; position and house evidence remain distinguishable.
[x] Position-only and house-dependent operation requirements are explicit; missing houses/nakshatra/speed have documented representations.
[x] Both engine consumer examples type-check against the same contract and sidereal/tropical fixture snapshots.
[x] Contract exports load without native-provider imports or initialization; snapshots are readonly and preserve Binder’s returned normalized values and rounding provenance, with no promise of unavailable raw digits.
[x] Snapshot identity records normalizer/semantics versions, rounding policy and provider/binding/data identities; future optional event ports need no fake initial implementation.

C-02 — Implement pure neutral chart assembly

HLD: Binder integration, chart-core responsibilities, current Binder API. Depends on: C-01, C-08, C-09. Write scope: packages/chart-composer/**.

Implement the HLD’s frame selection, house placement, rosters and snapshot assembly. Leave dignity/combustion/war to Vedic V-02. Receive a supplied read set; C-07 reads Binder and C-06 coordinates acquisition. Reuse existing semantics helpers for assembly.

Acceptance criteria:

[x] Supplied positions/houses match the instant, zodiac and each operation’s expected observer/origin; geocentric positions plus local houses are explicitly valid.
[x] Lagna, Moon and Sun frame selections follow the requested convention and appear in the result; required missing reference facts fail.
[x] Whole-sign occupancy uses supplied sign IDs; cusp occupancy uses Binder’s resolveHouse; exact boundaries follow the shared helper’s rule.
[x] All exports are pure and make no Binder/port calls; assembly also works with position-only read sets where the operation permits them.
[x] Body order and house rosters are stable; original facts and both Binder evidence blocks survive assembly; inputs remain unchanged.
[x] Unsupported/missing placement is explicit; assembly never substitutes a house system or zodiac.
[x] Zodiacal angles and equatorial ARMC retain their meanings; sidereal assembly never shifts ARMC with the ayanamsa.

C-03 — Expose shared aspect and cross-chart geometry

HLD: Western shared contract, Composer aspect ownership. Depends on: C-01, C-08. Write scope: packages/chart-composer/**.

Expose same-chart aspects, source-to-target aspects and placement against a target chart’s cusps using existing semantics implementations. The Western engine interprets the resulting contacts.

Acceptance criteria:

[x] Named orb policy matches the geometry actually evaluated; Binder’s construction-time defaults cannot silently stand in for a requested policy.
[x] Cross-chart contacts retain source/target chart and body IDs; overlay direction is explicit.
[x] Incompatible coordinate contexts are rejected; charts may legitimately have different instants/locations when the technique requires them.
[x] Wraparound, inclusive orb limits, exact contacts and missing-speed phase state match existing semantics helpers.
[x] No second aspect-separation or cusp-placement algorithm is introduced in either engine.
[x] Geometry accepts explicitly tagged derived points as well as observed charts; unknown transformed speed/houses remain absent and no fabricated Binder snapshot is required.
[x] Phase uses an explicit motion policy: transit references are fixed, natal pairs use returned speeds, timeless synastry has unknown phase and transformed points need defined derivatives. Tests distinguish a moving reference from a fixed one without changing the source snapshot.

C-04 — Implement bounded astronomy probes and series acquisition

HLD: Vedic probe contract, Western time-dependent techniques, transit rules. Depends on: C-01, C-08, C-09; port extensions reviewed by both consumers. Write scope: packages/chart-composer/**; shared contract changes go through the C-01 owner.

Expose position evaluation at requested instants and a bounded series operation. Engines choose target conditions and solver policies. Composer executes Binder reads without interpolation.

Acceptance criteria:

[x] Window, body-count, step and evaluation limits are validated before reads; consumed evaluations and evidence are returned.
[x] Out-of-window or exhausted requests fail explicitly; cancellation/deadline stops further scheduling.
[x] Every sampled/probed position comes from Binder; repeated contexts can be reused within a request without changing evidence.
[x] Serial Binder position reads work without an assumed batch endpoint; native batching may be added later with equivalent results.
[x] The bounded series operation supplies real per-instant Binder positions/speeds and satisfies the revised transit HLD’s acquisition contract; an unavailable reader or unsatisfied window budget keeps window support disabled. A native batch endpoint is not assumed.

C-05 — Add the rise/set bridge after Binder supports it

Implemented: Native Hindu events use windows of at most 72 hours. Standalone official-C fixtures cover Mumbai, London and polar no-event results. Tests cover a clipped next sunrise, optional sunset and installed-coverage edges.

HLD: rise/set gap, panchang input contract, Vedic capability gates. Depends on: C-04, C-07 and B-01’s implemented/tested Binder rise/set capability. Write scope: packages/chart-composer/src/probes/events.ts and tests; event translation in packages/runtime/ is handed off to its C-07 owner.

Acceptance criteria:

[x] Upstream handoff identifies real Binder method/types, horizon/refraction definition, supported observer/date range, no-event result and provenance, with passing provider reference tests.
[x] Composer returns actual sunrise, next sunrise and optional sunset with requested definition and evidence unchanged.
[x] Polar no-rise/no-next-rise cases remain explicit; no manufactured 24-hour day or midnight fallback.
[x] Unsupported sunrise definitions are rejected; the capability is absent before the Binder prerequisite passes.
[x] No solar altitude, horizon model or native provider call is added to Composer.

C-06 — Finish capabilities, failure behavior and package verification

HLD: integration rules, failure behavior, both engines’ contract. Depends on: C-02, C-03, C-04, C-07, C-08, C-09; extend event checks after C-05. Write scope: packages/chart-composer/**.

Acceptance criteria:

[x] Capabilities distinguish supported bodies/houses/geometry/probes/events and required context; unimplemented ports are not advertised.
[x] Upstream codes/causes and precision degradation remain visible; there is no implicit convention/provider fallback.
[x] Pinned inputs yield stable snapshots/identities; changing zodiac, houses, orb policy or contributing versions changes identity.
[x] Public consumer example works with injected Binder and documents host TT (Terrestrial Time)/timezone responsibilities.
[x] Host wraps Binder with createBinderReader and injects that reader into the facade; the facade never imports/constructs a provider or Binder.
[x] A natal composition reads positions once and houses at most once; position-only operations do not acquire unrelated houses.
[x] Package build, type checks and tests pass; neither an engine dependency nor tradition-specific rule table is present.

C-07 — Implement the Binder reader package

HLD: integration rules, current Binder API. Depends on: C-01. Write scope: packages/runtime/**.

Implement the binder-client exports against an injected initialized Binder. It is the only Compose package that translates Binder’s API.

Acceptance criteria:

[x] createBinderReader implements the shared reader port and preserves each response’s evidence and code/cause on failure.
[x] Body order, observer, zodiac/ayanamsa, houses and speed requirements map exactly to Binder requests.
[x] A house location never silently makes positions topocentric: geocentric requests omit observer, while topocentric requests use the explicit position observer. Returned origin/declaration is verified.
[x] Importing the bridge does not import/initialize concrete native adapters; Binder types use import type and the host owns construction.
[x] No provider selection, retry, default convention substitution or second normalization pass is added.
[x] Controlled reader tests pass without native files; S-02 separately verifies the real Binder path.

C-08 — Implement canonical context and compatibility

HLD: shared context, chart-core frame rules. Depends on: C-01. Write scope: packages/chart-composer/**.

Implement the context exports, separate from acquisition or chart assembly.

Acceptance criteria:

[x] Equivalent supported absolute instants normalize consistently; missing/ambiguous civil-time input is rejected rather than resolved locally.
[x] Zodiac/ayanamsa, body/node, house/frame and aspect choices remain explicit; required observer/body facts are validated.
[x] Same-read admission compares expected per-operation origin/observer; cross-chart admission permits distinct birth instants/locations only under the selected origin/coordinate policy.
[x] Speed selection, elevation defaults and normalization metadata have defined identity behavior; leap-second strings are rejected consistently with the existing instant parser.
[x] No geometry, profile lookup, astronomy or clock call is part of normalization.
[x] Instant normalization reuses the existing parseInstant; unsupported leap-second/calendar strings preserve its rejection behavior.

C-09 — Implement calculation identity and evidence

HLD: precision/reproducibility, engine evidence. Depends on: C-01. Write scope: packages/chart-composer/**.

Implement the evidence exports, reusable by both rulebook registries and all response coordinators without importing them.

Acceptance criteria:

[x] Canonical object keys, ordered arrays, absent values and non-finite rejection are specified and covered by fixtures.
[x] Equal inputs/versions produce equal identity; a changed convention, rule hash or contributing provider version changes it.
[x] Changing position origin, speed selection, normalizer settings/version or semantics version changes identity even if a subset of numerical values happens to be equal.
[x] Evidence deduplication retains distinct position/house sources and never invents one common provider declaration.
[x] No storage/logging or wall-clock timestamp affects identity; result identity is not presented as a protected cache key.