Internal module guide. This module is now part of @astrology/chart-composer; use the public package README for application setup.

contracts module

The shared TypeScript vocabulary for chart inputs, snapshots, geometry and injected ports.

Start with the Composer reading guide for the complete request flow and glossary. Public imports use @astrology/chart-composer; implementation files are not cross-package APIs.

See the package specification and task plan.

Contract

The root exports types only. Both engine consumer examples live in test/fixtures/charts.ts; no tradition judgments enter this contract.

ChartContextInput requires an offset-bearing ISO instant or epoch milliseconds, an explicit position origin, ordered bodies, speed choice, zodiac, frame, house system (or null), and named aspect rules with their motion policy. Sidereal requires an ayanamsa. Lunar nodes require mean/true. positionObserver is required only for topocentric positions (seen from a point on Earth’s surface); houseObserver describes local houses independently. Geocentric positions (seen from Earth’s centre) with local houses are valid.

Snapshots retain ordered geometry, sign/nakshatra/motion facts, original Binder aspects, separate position/house evidence, degradation and reproducibility identity. Missing houses use null angles, empty rosters and null body houses; tropical nakshatra and unavailable speeds are null. Readonly contracts prevent mutation through typed consumers; callers must also treat retained references as immutable at runtime. Returned Binder values are already rounded and raw provider digits cannot be recovered.

ComposerPort.geometry is a property. AstronomyReader and ProbePort have optional event methods; their existence in the type system enables nothing. The bridge installs an event method only when the injected Binder has one; capabilities also require native definition support. Only Hindu solar events are implemented. They use the house observer, epoch milliseconds, a maximum 72-hour window and explicit null no-event results. Sunset is opt-in.

Read the implementation

Begin with context.ts, then snapshot.ts and ports.ts. The comments explain units, absent values, reference direction and which responsibilities belong to the host. evidence.ts defines the source records carried through those boundaries.

Run pnpm check:chart-composer and pnpm test:chart-composer from the repository root.