Varga Engine — High-Level Design

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

The varga engine maps one sidereal D1 (natal chart) longitude into each of the sixteen Shodasavarga signs, then builds the varga frame from the same mapping. It is pure arithmetic over a rulebook table: no binder call, no second position, and no varga computed from another varga.

1. Purpose

Divisional charts (vargas) are the most convention-sensitive layer in the composer.

The variants are real: D10 has at least three starting rules in use, D30 is not divided equally, and D16, D20, D40 and D45 differ between editions. If each screen encodes its own table, one birth yields two D9 charts — both “correct” under some convention — and the difference stays invisible.

The varga engine exists so that:

1. every varga is one total, deterministic mapping from a D1 longitude to a sign;
2. the variant scheme is a named rulebook entry, not a code branch;
3. the varga lagna (rising sign) and the varga bodies come from the same mapping function;
4. a response states which rulebook produced it, so two charts compare honestly.

2. Where it sits

chart core · D1 frame (lagna, longitudes, sign ids) ──┐
                                                      ├──▶ varga engine ──▶ varga charts
rulebook · varga tables (parts, start rules) ─────────┘

• Upstream: chart core supplies the D1 lagna, each body’s full longitude and its binder sign id. The facade supplies the requested varga ids and one rulebook handle.
• Downstream: the facade assembles the varga layer into POST /v1/charts; later varga-based strength readers consume the same signs.
• Never: no binder call, no D1 sign recomputation, no chaining one varga into another, no dasha, panchang or interpretation from a varga.

Input contract

Output contract

3. Responsibilities

4. Architecture

Diagram: reference design, not deployed behaviour.

The engine has no orchestration of its own. It is a mapping service with one rule: the same function turns a planet’s longitude and the lagna’s longitude into a varga sign. Otherwise one frame could mix two conventions.

5. Rules

1. From D1 only. A varga is never computed from another varga. Chaining divisions compounds rounding and yields charts no published table matches.
2. One mapping function. Bodies, the lagna and later points all use the same longitude → varga sign function. Varga houses then apply chart core’s whole-sign sign-distance rule to the resulting ids, never a second house rule.
3. The mapping is total. For every varga, each of the 30° of a sign maps to exactly one part and one sign. A gap, overlap or uncovered degree is a rulebook defect, caught at load.
4. Half-open parts. A longitude exactly on a part boundary belongs to the next part; exactly 30° is the next sign. No epsilon fudge hides a boundary.
5. No varga degree. A varga response carries a sign id and a part index, never a degree inside the varga sign; that would imply precision the division lacks.
6. Starting rules are data. Movable/fixed/dual, odd/even, elemental starts, reversed D2 halves and D30’s unequal spans live in the rulebook. A new scheme is a table row, not a branch.
7. D30 is asserted, not assumed. Its spans must sum to 30° and reverse in even signs; the rulebook load fails otherwise.
8. Vargottama is derived. “D1 sign equals D9 sign” falls out of the mapping and is reported as a flag. It is never stored as separate data or special-cased.
9. Sidereal only. The classical tables are defined on the sidereal zodiac. A tropical profile reports the varga layer unsupported rather than mapping tropical degrees.
10. D1 is passed through. The response’s D1 chart is the chart core chart, not a re-mapped copy, so a varga can never contradict the natal chart.
11. Unknown ids fail. An unserved varga id is a validation error, never skipped silently.
12. Deterministic order. Varga ids follow natural order (D1, D2 … D60) and bodies follow the chart’s canonical order, so two responses diff byte for byte.

6. Edge cases

7. Out of scope

• D1 frame, house placement, dignity and combustion (chart core).
• Vimshottari periods and the proportional division used by dashas (dasha engine).
• Varga strength, varga dignity and ashtakavarga scoring (later layers).
• Panchang, transits, matching and muhurta rules.
• Interpretation, remedies and chart drawing.
• Binder access, caching and provenance (facade and binder).

8. Planned code