Chart Core — High-Level Design

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

Chart core turns one binder snapshot plus one profile into the D1 chart: frame, houses, bodies and planet judgements. It is the only engine that picks the chart frame, and every other engine reads its output.

1. Purpose

The binder reports positions, signs, nakshatras (lunar mansions) and padas (quarter divisions). It does not:

• choose the chart reference (the lagna, or rising sign, by default);
• place bodies in houses;
• judge dignity, combustion (being burnt by the Sun) or planetary war (two planets close together).

Vargas (divisional charts), transits, matching and muhurta all depend on those decisions being made once. Chart core exists so that:

1. one lagna and one house convention produce one frame per response;
2. a body’s house comes from binder facts, never a second longitude-to-sign function;
3. dignity, combustion and planetary war come from rulebook tables, not scattered thresholds;
4. later engines read one stable, ordered chart object instead of the binder.

2. Where it sits

binder positions + houses ──┐
                            ├──▶ chart core ──▶ chart facts ──▶ varga · dasha · transit · matching
profile + rulebook handle ──┘

• Upstream: the composition facade supplies one binder read set, one profile and one rulebook handle. Chart core runs once per composition.
• Downstream: the varga engine takes the D1 longitudes, sign ids and lagna; the dasha engine takes the Moon facts; transit, matching and muhurta read the assembled chart.
• Never: no binder call, no HTTP parsing, no varga division, no dasha time arithmetic.

Input contract

Output contract

3. Responsibilities

4. Architecture

Diagram: reference design, not deployed behaviour.

Chart core is a set of pure functions, not a service. The facade owns every read and every field chart core does not produce. One shared chart context stops a body from being placed under a different lagna.

5. Rules

1. Longitudes are read, not derived. Only integer sign distance is computed, for whole-sign houses. A local floor(longitude / 30) is a defect.
2. Cusp placement stays binder-owned. Without per-body binder placement, a cusp profile reports the layer unsupported instead of walking cusps.
3. Whole sign means whole sign. Cusps never enter a whole-sign chart, even when the binder returned them for another layer.
4. One frame per chart. The reference body is resolved once, recorded in frame, and never re-chosen downstream.
5. Judgements are table lookups. Exaltation degrees, moolatrikona ranges, combustion orbs and war outcomes live in the rulebook; code holds no planet-specific threshold.
6. Half-open boundaries are inherited. A body exactly on a sign or cusp boundary belongs to the binder’s interval; chart core never re-opens it.
7. The profile’s body set is required. A missing body fails the request unless allowPartial is set, which marks affected judgements unavailable.
8. Aspects are consumed, not recomputed. Binder aspects are attached by reference; separation, orb and applying state are not recalculated.
9. Deterministic ordering. Bodies follow the profile’s canonical graha order, houses run 1–12, and no hash or map order reaches the response.
10. No clock, locale or storage. Chart core takes a canonicalised context and returns a value object; it reads no “now” and persists nothing.

6. Edge cases

7. Out of scope

• Divisional charts and vargottama (varga engine).
• Vimshottari periods and period lookup (dasha engine).
• Panchang, transits, matching and muhurta rules (their own designs).
• Aspect geometry, nakshatra and pada derivation (binder semantics).
• Provider calls, retries, caching and provenance (facade and binder).
• Chart drawing, glyph placement and interpretation copy (client and product content).

8. Planned code