Composer module specifications

The current package structure defines the workspace boundaries. The modules below share their owning domain’s package manifest and build. Their factories and helper exports are internal implementation contracts; application callers use the public package root or runtime assembly. Calculation task IDs and review gates remain unchanged.

Module inventory

Package roots expose named service contracts and supported entry points, without wildcard exports. Detailed module contracts below retain the calculation design and acceptance requirements; an internal export does not imply a public package export. Read development tasks for implementation and review status.

contracts

Files: src/context.ts, src/snapshot.ts, src/ports.ts, src/capabilities.ts, src/evidence.ts, src/errors.ts. Owner: C-01 agent.

Exports are types: ChartContextInput, ChartContext, ChartSnapshot, ChartFrame, BodyFacts, HouseRoster, ChartCapabilities, SnapshotIdentity, EvidenceReference, CalculationIssue, AstronomyReader, ComposerPort, GeometryPort, ProbePort, ProbeBudget, ProbeResult, SeriesRequest, RiseSetRequest, RiseSetResult and RulebookIdentity, plus GeometryChart, GeometryPoint, PointOrigin, MotionPolicy, AspectPolicy, ChartContact, CrossChartContact and HouseOverlay. The root module exports no factory, default registry or provider object.

The ports define position/house reads, snapshot composition, cross-chart geometry and bounded probes independently. An engine receives only the ports its operation needs. Snapshots carry resolved context, geometry exactly as returned by Binder, optional facts, source evidence and version identities. Context separates positionOrigin (geocentric/topocentric (measured from the observer’s place on Earth’s surface)), optional positionObserver and the houseObserver. Geocentric positions with local observer-based houses are a valid chart. Preserve the provider frame/origin and the non-zodiacal nature of ARMC; do not treat every angle as a zodiacal longitude. Include includeSpeed, normalization policy/version, semantics version and provider/binding/ephemeris/file identities in reproducibility inputs. Future event access is optional/capability-discriminated; an initial reader must not implement a fake rise/set method. Declaring its types never enables an operation. GeometryChart admits observed or technique-derived points with explicit origins, coordinate context and method identities. Derived harmonics/directions/composites must never masquerade as Binder-backed ChartSnapshot values just to call geometry.

Package acceptance: C-01’s two consumer fixtures compile; importing contracts runs no native, network, filesystem or clock code. Domain-specific scores, tables and output shapes are absent.

context

Files: src/normalize-context.ts, src/validate-context.ts, src/compatibility.ts. Owner: C-08 agent.

Exports: normalizeChartContext(input): ChartContext, validateChartRequirements(context, requirements): void, assertCompatibleContexts(left, right, purpose): void, and type ContextRequirements. Requires explicit absolute time, position origin/observer, house observer where needed, zodiac/ayanamsa (the angular offset between the tropical and sidereal zodiacs), body/node selection, speed, house/frame and orb policy. Same-read compatibility checks the expected declaration for each operation: observer-houses must not be rejected for being different from geocentric/topocentric. Cross-chart comparison permits distinct instants/ locations only under an explicit compatible coordinate/origin policy.

Returns canonical values or structured issues. It does not select a tradition/profile, resolve a civil timezone or perform zodiac/time-scale conversion. Acceptance: C-08 boundary/compatibility fixtures pass; canonical normalization never changes the requested calculation convention. Reuse adapter-contract’s parseInstant for accepted timestamp grammar and rejection behavior; do not introduce a second parser with different leap-second/calendar rules.

evidence

Files: src/canonicalize.ts, src/identity.ts, src/collect-evidence.ts. Owner: C-09 agent.

Exports: canonicalizeCalculation(value): string, hashCalculation(value): string, createSnapshotIdentity(context, sources, versions): SnapshotIdentity, collectEvidence(sources): readonly EvidenceReference[], and type CalculationVersions. Requires context, contributing declaration/version identities and exact input values; it returns stable hashes and a deduplicated evidence ledger without changing numerical results.

Hash rules specify ordered arrays, object keys, optional values and non-finite rejection. These are calculation identities, not privacy-safe cache keys; host cache storage/key protection stays outside the package. Acceptance: C-09 replay and version/context-change fixtures pass, while position/house evidence remains distinguishable. Binder already normalizes values (eight angle/speed decimal places by default); no consumer can recover raw provider digits from those results. Preserve returned values without another angular rounding step. Hash normalization settings/versions and semantics identity as well as provider versions; changing requested speed or position origin changes the calculation identity.

binder-client

Files: src/reader.ts, src/positions.ts, src/houses.ts, later src/rise-set.ts. Owner: C-07 agent; C-05 coordinates event support after B-01.

Exports: createBinderReader(binder, options?): AstronomyReader, types BinderReaderOptions and BinderLike. BinderLike is the structural subset of already initialized Binder methods. Requires a host-created Binder with its tested TT (Terrestrial Time, the uniform clock used to evaluate planetary positions) resolver and routing configuration; it never calls createBinder, selects a provider or owns retries/storage.

Translates shared context into Binder requests and preserves declaration, decision, semantics, errors and provenance. Profile-specific aspects are evaluated in geometry using explicit policy, not assumed from the Binder’s construction-time aspect defaults. Acceptance: C-07 tests cover request translation, native-free import, capability refusal and unchanged failure/evidence. Supplying observer to Binder positions() means topocentric positions. Omit that field for an explicit geocentric profile even when houseObserver is present; pass the house observer only to houses(). For topocentric positions, use the explicit position observer. Verify returned origins and preserve armc unchanged, including for sidereal charts.

chart-core

HLD: neutral chart-core responsibilities. Files: src/frame.ts, src/placement.ts, src/rosters.ts, src/assemble.ts. Owner: C-02 agent.

Exports: resolveChartFrame(facts, framePolicy): ChartFrame, resolveWholeSignHouse(bodySign, referenceSign): number, resolveOccupancy(facts, frame): readonly BodyFacts[], buildHouseRosters(placements, frame): readonly HouseRoster[], assembleChartSnapshot(context, readSet, versions): ChartSnapshot, and type ChartReadSet. Requires already acquired position/house facts; uses the existing sign/house primitives where needed. This package is synchronous and pure. The facade acquires its read set.

Sign-distance/roster exports accept sign IDs and minimal body/house placements so varga can reuse them without fabricating astronomical degrees. Judgment fields belong to Vedic/Western results, not this snapshot. Acceptance: C-02 verifies frames, exact cusp/whole-sign boundaries, stable rosters, source preservation and input immutability.

geometry

Files: src/aspects.ts, src/cross-chart.ts, src/overlays.ts. Owner: C-03 agent.

Exports: toGeometryChart(snapshot): GeometryChart, evaluateChartAspects(chart, policy), evaluateCrossChartAspects(source, target, policy), evaluateHouseOverlays(source, target), createGeometryPort(): GeometryPort, and types AspectPolicy, ChartContact, CrossChartContact, HouseOverlay. Those types are defined by compose/contracts and re-exported here, so a pure consumer can accept contacts without a type dependency on the geometry implementation package. Requires context-tagged GeometryChart values, explicit orb rules and target cusps when overlays are requested. Results identify both charts/bodies, separation/orb/phase or target house and unavailable factors. Origin tags distinguish observed and transformed inputs; a derived chart may omit speed/house data and must not inherit those facts without an explicit technique policy.

All angular/cusp primitives reuse astrology-semantics. This package is pure and does not fetch charts or interpret patterns. Acceptance: C-03 checks wrap, direction, exact orb and unknown-speed cases. MotionPolicy declares the derivative used for applying/separating. Same-chart natal aspects use both returned speeds. For transits the reference is fixed with derivative zero, not its birth-time speed. Timeless synastry defaults to unknown phase unless an explicit technique defines a shared time parameter. Derived points need a defined transformed derivative or null; never copy an observed speed silently. These evaluation views retain original source evidence.

probes

Files: src/session.ts, src/budget.ts, src/series.ts, src/events.ts. Owner: C-04 agent; C-05 adds the events bridge.

Exports: createProbeSession(reader, context, limits): ProbePort, readPositionSeries(session, request): Promise<ProbeResult[]>, and types ProbeLimits, ProbeUsage. Port methods expose exact-instant evaluation and supported rise/set queries. Requires an injected reader, bounded window, maximum evaluations/concurrency and caller cancellation. Returns evaluated facts, usage and evidence; it does not decide what a tithi or return means.

No root solver is shared speculatively: panchang/transit/return packages own their conditions, convergence policy and search implementation. Acceptance: C-04 enforces bounds before reads; C-05 only enables events after B-01 provides real upstream support.

composer

Files: src/composer.ts, src/capabilities.ts, src/operations.ts. Owner: C-06 agent.

Exports: createChartComposer(options): ComposerPort, types ChartComposerOptions, ComposeChartRequest, ComposeChartResult, and constant COMPOSER_VERSION. Requires injected AstronomyReader, explicit context/policy and limits for operations needing probes. Facade methods are capabilities, compose, geometry and openProbeSession; C-01 freezes whether geometry is exposed as a property or methods before consumers start.

The facade sequences neutral packages and preserves failures; it exports no Vedic/Western rule or engine response. Acceptance: C-06 and S-02 show both engines using the same facade, while leaf chart-core/geometry tests run without Binder or native data.