astrology design library
Astrology8 MIN READ29 / 116

Astrology development plan

Status: Domain packages and runtime assembly are implemented. The calculation task lists retain their own acceptance and external-review gates; packaging does not certify draft numeric rules.

Selected package architecture

The current package structure is authoritative. Eight reusable workspace packages cover astronomy contracts, astrology primitives, Ephemeris, Composer, Vedic, Western, runtime assembly and logging. Drift validation is a separate tool. The earlier 35-library proposal is now represented by internal modules with domain-owned manifests and builds.

Domain Implementation Module specifications
Composer packages/chart-composer/src/; reader adaptation in runtime Composer modules
Vedic packages/vedic/src/ Vedic modules
Western packages/western/src/ Western modules

Calculations own their input/result shapes and rule tables. Profiles select conventions; registries verify supplied bundles. Engines plan registered features inside their domain. Shared house-placement primitives live in astrology-core, and neutral snapshot/context/evidence contracts belong to Composer. Neither tradition imports the other or a provider implementation.

Host assembly and required inputs

Application startup imports createAstrologyRuntime from @astrology/runtime and supplies tested Terrestrial Time (TT, the uniform clock used to evaluate planetary positions) resolution and provider configuration, or an initialized Binder/reader. Route handlers receive the public Vedic or Western service. They do not import or register individual calculators.

The runtime and domain factories perform this assembly internally:

  1. Initialize Binder when requested, then adapt it to one astronomy reader.
  2. Create one shared Composer with explicit probe limits, if configured.
  3. Build each tradition’s profile catalog and rulebook registry.
  4. Admit supplied rule families and register supported calculations within that domain.
  5. Expose named service requests/results and preserve capability, provenance and failure behavior.

Direct algorithm functions remain internal module APIs for domain maintainers and tests. They are not exported as separate installed libraries. Timezone resolution, transport, storage, logging configuration and production time conversion remain application responsibilities.

Task lists

Every task below links to its HLD, identifies its dependencies and write scope, and includes acceptance criteria. IDs are stable so agents and reviews can refer to one unit of work.

Task status is recorded in each domain plan. A design task is complete when its named specification and fixtures exist; it does not enable a runtime capability. An implementation task is complete only when its criteria pass and its package advertises precisely the supported operation/variant.

Shared prerequisite and integration tasks

S-01 — Register package families and incremental builds

HLD: module delivery boundaries, shared Composer contract. Owner: integration agent. Depends on: agreed package inventories and export names; no runtime implementation prerequisite. Files: pnpm-workspace.yaml, root package.json, lockfile; package manifests/build configurations as packages start.

Add packages/chart-composer/src/*, packages/vedic/src/*, packages/western/src/*, ESM exports, package-local build/check/test commands and root aggregate commands. Follow existing Binder conventions; do not generate empty implementations for all future packages.

Acceptance criteria:

  • [ ] Each started package resolves through its inventory name; no consumer uses another package’s src imports.
  • [ ] Contracts and pure leaf packages import without native providers or ephemeris files, including transitive runtime imports.
  • [ ] Package declarations match the specified direct/type-only dependencies; topological builds do not require every advanced technique to exist.
  • [ ] Build/check/test commands and test type checks work per package and per family; package graph is acyclic and installation produces one consistent lockfile.

S-02 — Verify the first working slice

HLD: Vedic assembly/delivery, Western assembly/delivery. Owner: integration agent. Depends on: S-01, C-01–C-04, C-06–C-09, V-01–V-03, V-05, V-15–V-18, W-01, W-02 and W-11–W-13. Files: cross-family integration harness under tests/astrology/; root aggregate commands.

Wire one host-owned Binder/Composer into both engines. Deliver Vedic D1 (birth chart) judgments, the D9 divisional chart and Vimshottari periods, plus Western natal judgments. Later HLD operations remain gated by their tasks.

Acceptance criteria:

  • [ ] A real Binder/Composer path passes reviewed sidereal (star-anchored) and tropical (equinox-anchored) reference fixtures with recorded tolerances.
  • [ ] Fixtures distinguish geocentric positions (seen from Earth’s centre) with local houses from explicitly topocentric positions (seen from the observer’s place on the surface), retain upstream rounding/semantics versions and exercise fixed-reference transit motion when delivered.
  • [ ] Each engine returns its profile/rulebook/engine identity, Composer version and contributing Binder evidence.
  • [ ] Identical pinned inputs replay identically; neither engine mutates the shared snapshot.
  • [ ] Missing required facts and upstream errors produce the specified failure; partial output requires opt-in and names missing dependencies.
  • [ ] All packages in the first slice build, type-check and pass tests. Real Swiss integration requires pinned files and a tested TT resolver; unavailable prerequisites are reported as blocked, never passed.
  • [ ] Package READMEs contain executable host-wiring examples and list only implemented capabilities.
  • [ ] Direct dasha and natal-only engine consumers succeed without unrelated feature implementations or native runtime imports; V-11 separately proves direct matching use.

B-01 — Supply the Binder rise/set prerequisite

Status: Implemented for the Hindu definition, with native/reference tests and a real Composer test.

HLD: proposed rise/set contract, panchang sunrise requirements. Owner: integration agent acting as Binder owner, or an explicitly assigned upstream agent. Depends on: agreed rise/set definition before native implementation. Files: affected contract, Swiss adapter, normalization, routing and Binder surfaces under packages/ephemeris/, their tests and Binder documentation; no engine code.

Acceptance criteria:

  • [x] In-process API defines observer, absolute search window, event types, horizon/refraction policy, no-event result and provenance; Composer C-05 can consume its published types.
  • [x] Hindu sunrise (rising of the Sun under the Hindu definition) and any other advertised definition have explicit semantics and match independent native/reference event fixtures within a stated tolerance.
  • [x] Ordinary sunrise/next sunrise, optional sunset, polar no-event and coverage-edge cases are tested; unsupported providers/definitions fail capability admission.
  • [x] Native calculations remain inside the Swiss adapter; no approximation is introduced in Binder, Composer or either engine.
  • [x] Affected Binder packages build, type-check and pass tests; the existing position/house/routing behavior still passes regression checks.

Parallel assignment and merge order

Use package-level assignments. Four agents can work concurrently; additional agents can take ready packages without changing the boundaries. Each running assignment owns one package or an explicitly named package set. The family labels below are queues, not one large shared edit.

Wave Integration agent Composer agent Vedic agent Western agent Exit gate
0 S-01 C-01 shared contracts Prepare V-16 contract examples Prepare W-12 contract examples Shared contracts merged; package manifests created as needed
1 C-07 Binder bridge C-08 context, C-09 evidence V-16 contracts, V-01 profiles W-12 contracts, W-01 profiles Contracts, canonical context and evidence APIs fixed
2 V-17/W-13 registries after C-09 C-02 core, C-03 geometry, C-04 probes V-02 judgments or V-03 varga W-02 natal Leaf fixtures/exports pass; V-05 dasha and V-18 drishti are also independent ready work
3 S-02 harness C-06 facade Complete V-05/V-18, then V-15 W-11 First working slice S-02 passes
4 B-01 upstream events C-05 after B-01 V-04, V-06/V-07, V-09/V-10, V-11, V-12 W-03/W-04, per-technique W-05 designs Accept each feature package independently
5 Integrate elected capabilities New-port regressions V-08, V-13/V-14, V-19 after gates W-06–W-10 independently after gates Delivered features pass package and cross-family checks

For more parallelism after Wave 1, assign separate agents to V-03 varga, V-05 dasha, V-11 matching and W-02 natal: their calculator packages have no runtime dependency on each other. Likewise geometry and core can proceed from shared fixtures without waiting for real Binder reads. Respect every task’s listed dependencies; the wave is not permission to bypass a gate.

Package agents own the full assigned package’s source, unit tests, tables/fixtures and README, including its internal module entry point. The integration agent alone edits root files, lockfile, manifests, build setup and tests/astrology/. Family documentation has one designated editor at a time; other agents submit task-status/API notes. Contract owners coordinate consumer changes before merging. Cross-package edits require explicit handoff, not an unannounced shared-file change.

Acceptance required for every package

  • [ ] HLD/task criteria and the package’s specified exports are implemented; the README documents inputs, outputs, conventions and unsupported cases.
  • [ ] Public-root imports work from a consumer test. No private-path import or hidden dependency on an engine/provider appears in a leaf package.
  • [ ] Owned rule tables have sources, schema validation, stable identity and independent numerical/boundary fixtures.
  • [ ] Build, source/test type checks and behavioral tests pass for the package and affected consumers.
  • [ ] No clock, locale, mutable registry state or hidden astronomy call affects a pure calculation; injected asynchronous ports have bounded behavior.
  • [ ] One package can be assigned and reviewed without editing another calculator’s implementation, fixtures or export file.

Implementation handoff template

For each assignment, record package path/npm name, task IDs, HLD/spec links, predecessor API versions, exact exports to implement, allowed files, direct/type-only dependencies, required injected ports/data and command names. Attach changed files, acceptance results, fixture sources and any unresolved design gate. A design-only task must not create a successful runtime stub. Review the diff and run relevant build/type/test checks after integration. For documentation-only task outputs, check links and rendered Markdown instead.