Transit Engine — High-Level Design

Status: Draft for review · Part of: Astro Composer · Updated: 2026-10-24

The transit engine compares a moving sky against an immutable reference chart: gochara (transit) positions from the natal Moon, Sade Sati phases and ashtakavarga scores, returned as occupancy segments, ingress events and phase intervals. It does pure comparison over binder positions and a verified snapshot: no natal recalculation, no provider call, no clock.

1. Purpose

A transit is not a new chart. It compares a fixed reference chart against a body’s position at an explicit instant. Every answer — which house Saturn occupies, when Sade Sati ends, how many bindus (score points) Jupiter carries — depends on that reference staying fixed. Mix references or conventions and two transit views disagree while both are arithmetically correct.

The transit engine exists so that:

1. one immutable reference supplies the Moon sign, lagna sign and natal ashtakavarga;
2. a window becomes segments and boundary events, not a row per day;
3. ingresses and Sade Sati phase changes are solved to instants;
4. gochara comes from the natal Moon, never the lagna;
5. responses name reference versions and boundary precision.

2. Where it sits

reference chart · Moon · lagna · BAV ──┐
window or asOf · bodies · step ────────┼──▶ transit engine ──▶ segments + events + phases
binder positions or timeseries ────────┤
profile + rulebook ────────────────────┘

• Upstream: the composition facade supplies a verified reference chart (usually a stored snapshot from the chart/account domain), an explicit asOf or window, the requested bodies, one profile and one rulebook handle; the binder client supplies transiting longitude, speed and sign id.
• Downstream: the facade builds POST /v1/transits; product views, notification jobs and strength readers consume the same segments and phases.
• Never: it does not compose a natal chart, call a provider, read a clock, store a chart or interpret a transit.

Input contract

Output contract

3. Responsibilities

Each area owns one comparison and one deterministic rule.

4. Architecture

Diagram: reference design, not deployed behaviour.

The engine holds one immutable reference and one immutable input series. Neither is composed or fetched here; both arrive through the facade. That split keeps a transit response reproducible while the sky moves.

5. Rules

1. A transit is a comparison. The reference chart is immutable; the engine never resolves a second reference, recomputes a natal position or uses the lagna for the Moon.
2. Gochara is from the natal Moon. House number is the sign distance from the Moon sign; lagna-based numbers are informational only.
3. Strict reference equality. Profile, rulebook hash and binder engine version must agree; a mixed pair is rejected with REFERENCE_VERSION_MISMATCH.
4. There is no “now”. A snapshot needs asOf, a scan needs from and to; server time is never an input or a cache key.
5. No natal recalculation. Moon sign, lagna sign, body signs and ashtakavarga come from the verified reference; birth data is never read.
6. Sign assignment is binder-owned. Each grid point carries the binder’s sign id; the engine compares ids, never longitudes.
7. Boundaries are solved, not grid-snapped. A segment starts at the ingress instant, belongs to the entering sign, and ends at the next ingress or the window edge.
8. A window is segments and events. The response is occupancy spans and boundary instants, not one row per day; a requested step stays bounded.
9. Timeseries is transport, not semantics. A grid with speeds and per-instant calls give the same result. Without timeseries the window layer is unsupported; the engine never interpolates.
10. Ashtakavarga is natal. A transiting planet scores the bindus the reference assigns to its sign. BAV is never computed from transits, and SAV must total 337 or the rulebook load gate fails.
11. Sade Sati has a pinned basis. The profile chooses Moon-sign phases or the 45° arc before the Moon; a retrograde re-entry is a new interval, never merged.
12. Vedha is visible. With vedha enabled, the response carries base verdict, effective verdict and cancelling pair; a cancellation never erases the original fact.
13. Limits are explicit. Maximum window, body count and minimum step are checked before binder work; exceeding one is LIMIT_EXCEEDED, not a truncated scan.
14. Deterministic order and precision. Bodies follow canonical order, segments sort by start, and boundaries round once to the second; no approximate boundary is silent.
15. No interpretation. The engine returns houses, verdicts, bindus and intervals; wording, ranking and remedies belong to the product.

6. Edge cases

Bad input fails loudly; nothing is silently approximated.

7. Out of scope

• Natal chart assembly, chart frame, dignity and vargas (chart core, varga engine).
• Vimshottari periods and dasha-based transit weighting (dasha engine).
• Panchang and muhurta windows (panchang engine).
• Ashtakoota matching (matching engine).
• Western transits, progressions, returns, synastry and composite charts.
• Transit interpretation, predictions, remedies and favourable-period prose.
• Eclipse, station and retrograde forecast products.
• Declination, parallels and aspect geometry (binder semantics, later profiles).
• Storing charts, snapshots or transit reports (chart/account domain).
• Binder access, caching, retries and provenance (facade and binder).

8. Planned code