Dasha Engine — High-Level Design

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

The dasha engine turns the Moon’s position at birth into a Vimshottari timeline: mahadasha, antardasha and pratyantardasha (first-, second- and third-level planetary periods) as continuous UTC instants, plus the active chain at any asOf. It is pure time arithmetic over a rulebook sequence — no clock, no calendar, no binder.

1. Purpose

The birth balance is a fraction of one nakshatra (lunar mansion). One arcsecond of lunar longitude moves a period boundary by roughly two seconds. Year length is also a convention — 365.25, 360 and 365.2425 days all appear — and over 120 years those choices differ by months. Two implementations of one chart therefore produce two calendars for “when my Saturn period starts”.

The dasha engine exists so that:

1. one function produces every dasha boundary a product shows or notifies on;
2. periods tile the timeline exactly, at every requested level;
3. dates are absolute instants, independent of server timezone or locale;
4. the response names the sequence, year length, profile and rulebook behind it.

2. Where it sits

chart core · Moon longitude + nakshatra id ──┐
request · birth instant + depth ─────────────┼──▶ dasha engine ──▶ periods + lookup
profile · dasha year length ─────────────────┤
rulebook · nine lords, years, 120 total ─────┘

• Upstream: chart core supplies the binder’s full-precision Moon longitude and nakshatra id. The facade supplies the absolute birth instant, requested depth and one rulebook handle.
• Downstream: the facade assembles the dasha layer into POST /v1/charts; transit and notification features ask the same engine which period is active at an instant.
• Never: no binder call, no nakshatra re-derivation, no clock read, no calendar or timezone database.

Input contract

Output contract

3. Responsibilities

4. Architecture

Diagram: reference design, not deployed behaviour.

The engine reads one Moon position and one sequence table and returns a value object. It holds no calendar, clock or state between requests, so the same birth data reproduces the same boundaries on any JVM in any timezone.

5. Rules

1. The Moon alone decides. No other body, house, aspect or transit enters Vimshottari. The engine takes one longitude and one nakshatra id from the chart, nothing else.
2. The binder owns the nakshatra. The engine takes the binder’s nakshatra id for the first lord and computes only the fraction inside it. A computed index that disagrees is a boundary contract failure, not a rounding difference.
3. Full precision in, one rounding point out. Balance uses the binder’s unrounded longitude. Durations stay at full precision and are serialised to the second once, at assembly.
4. The year length is a profile field. Default 365.25 days; 360 and 365.2425 are supported by the rulebook. It is echoed in every response, and changing it is a profile version, never a per-request override.
5. Boundaries come from cumulative fractions. A child starts at parentStart + parentDuration × cumulativeYears / 120 and ends at the next cumulative boundary. Summed durations drift; the last child must end exactly where its parent ends.
6. Time is absolute. Dates are UTC instants. No timezone database, calendar month, local midnight or leap-second arithmetic; display formatting belongs to the client.
7. Nesting is an invariant. Every child lies inside its parent, siblings tile without gaps or overlaps, and the 120-year cycle repeats without drift. This is tested, not assumed.
8. The first period is partial. Its nominal start precedes birth. The response carries that start and partial: true with the balance at birth, so a client can show the full period or “balance at birth” without guessing.
9. Depth is explicit and capped. Default 3, maximum 4. Depth 4 never silently returns 3; depth 5 is rejected at validation.
10. Rulebook integrity is a load-time gate. Nine lords, each named once, years summing to 120. A failing table is not served.
11. Deterministic order and ids. Periods are emitted depth-first in mahadasha order with stable parent references, so two responses diff byte for byte.
12. There is no “now”. The engine never reads a clock. A caller wanting the current period supplies asOf; without it, the response is the timeline only.
13. One division primitive. KP sub-lord division, when it lands, reuses the same proportional splitter. A second “divide a segment by the Vimshottari years” implementation is a defect.

6. Edge cases

7. Out of scope

• Dasha interpretation, antardasha prose, remedies and predictions (product content).
• KP sub-lord and sub-sub-lord output (later KP profile; the division primitive is shared).
• Ashtakavarga, transits, Sade Sati and muhurta rules (their own designs).
• Chart frame, house placement, dignity and combustion (chart core).
• Divisional charts and vargottama (varga engine).
• Binder access, caching and provenance (facade and binder).
• Timezone display, locale formatting and calendar conversion (client).

8. Planned code