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

context module

Validates explicit chart choices and decides when acquired facts or chart coordinates are compatible.

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.

Admission

normalizeChartContext reuses adapter-contract’s instant parser and request validation. It canonicalizes absolute time to epoch milliseconds and omitted elevation to zero, without timezone lookup, Terrestrial Time (TT) conversion, zodiac conversion or a clock. Speed selection is required. Invalid civil-time, calendar and leap-second strings retain the adapter’s rejection behavior.

validateChartRequirements admits requested bodies, speed selection, houses and sidereal nakshatra (lunar-mansion) support. Consumers still check actual optional facts such as a null returned speed.

assertCompatibleContexts(left, right, purpose) compares exact time and position request fields for position reads, or house observer/system for house reads. Cross-chart geometry allows different instants and house locations with the same zodiac/ayanamsa and position origin. Topocentric comparisons (positions seen from a surface observer) require the same position observer (including elevation); comparisons between different topocentric origins are unsupported. Cusp systems require the lagna frame.

Read the implementation

Read normalize-context.ts for input admission, then compatibility.ts for operation-specific comparison. validate-context.ts checks feature prerequisites against requested selections; it does not inspect acquired numerical results.

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