Home / Engine / Chart and Pipeline Engine

C19 - Stored Natal Chart Basis (compute once, reuse) - build brief (v1, 2026-06-20)

Updated Jun 20, 2026 · Affirmology_StoredNatalChartBasis_C19_BuildBrief_v1.md

C19 - Stored Natal Chart Basis (compute once, reuse) - build brief (v1, 2026-06-20)

Jeff 2026-06-20: "Why would we run a complete new chart each time an audio is generated for someone we already pulled? That is inefficient and wasteful, especially at scale. All that info should be obtained once, stored, and used as the basis for all custom Sacred Audios. Progressions and transits get run on a need-by-need basis. But the chart should be there as the basis for all requests, analysis, and context."

Correct and important. The natal chart is IMMUTABLE (fixed at birth). Today the engine recomputes the full chart (placements, aspects, extended points, asteroids, HD, Gene Keys, numerology) on every audio render and every Hermes pull. That is redundant for the 4 test people and badly wasteful at scale. Fix: compute the natal chart ONCE per person, store it, and reuse it everywhere. Time-dependent layers (transits, progressions, the significant-events timeline) stay on-demand because "now" changes.

The model

• NATAL BASIS (immutable): the full natal Chart, computed once, serialized, stored, reused for every audio, reading, analysis, and Hermes context.
• TIMING LAYER (time-dependent): transits, secondary progressions, the significant-events timeline. Computed ON DEMAND from the current date, layered on top of the stored natal basis. Optional: cache per (person, date) with a 1-day TTL so repeated same-day pulls do not recompute.

What the stored basis MUST contain (verified against models.py 2026-06-20)

The cached natal basis must hold the COMPLETE blueprint Jeff named: western, Gene Keys, numerology, Human Design, Vedic, asteroids. Coverage check against the Chart Pydantic model: - COVERED by serializing the Chart object (already stored fields): western astrology (planets, angles), the full ASPECT grid (astrology.aspects), the EXTENDED POINTS (Lilith, Part of Fortune/Spirit, Vertex) and CHIRON + ASTEROIDS (astrology.extended_points), HUMAN DESIGN (human_design: type, authority, profile, channels, etc.), GENE KEYS (gene_keys: activation, Venus sequence, Pearl sequence), NUMEROLOGY (numerology: life path, and name-based numbers when name-confirmed). - THE ONE GAP - VEDIC: there is no vedic field on the Chart model today; the Vedic sidereal layer is derived at RENDER time via vedic_facts_text(chart). So caching only the Chart object would OMIT Vedic and re-derive it every pull. FIX (required): compute the Vedic layer ONCE into the stored basis. Preferred: add a vedic field to the Chart model, populated in compute_chart, so it serializes with everything else. Acceptable alternative: store the rendered Vedic facts alongside the cached Chart. Either way, the stored basis must return Vedic without recomputing. - TWO TIERS (Jeff 2026-06-20 "aspects, transits, all that... a summary of progressed"): - TIER 1 - IMMUTABLE NATAL BASIS: everything above (western incl. NATAL aspects, extended points, asteroids; HD; Gene Keys; numerology; Vedic). Cached forever, busted only by birth-data change or an engine-version bump. - TIER 2 - TIMING SNAPSHOT (date-dependent, so NOT in the immutable basis, but still stored/reused on a short clock): current major TRANSITS, a PROGRESSED SUMMARY (progressed Sun, progressed Moon + its phase, upcoming progressed sign changes), and the significant-events timeline. Computed on demand and cached per (person, date) with a TTL: transits ~daily, the progressed summary ~monthly (it moves ~1 degree/year). So it is reused within the window but always reflects the real "now," never frozen. - So the full picture is always available (natal blueprint + live timing), with each tier cached at the right cadence. Nothing recomputes needlessly; nothing goes stale.

Cache key (critical)

Key the stored natal chart on BOTH: 1. a hash of the birth data (name, date, time, location, name_confirmed) so editing birth data busts the cache, AND 2. a CHART_ENGINE_VERSION constant bumped whenever the chart engine changes (aspects, asteroids, new points, fixes). So key = sha1(birth_data_normalized + CHART_ENGINE_VERSION). When we upgrade the engine (as we just did), bumping the version recomputes every chart ONCE on next use, so nobody is frozen on an old engine. This is the safeguard that makes caching safe.

Storage

• A charts store: a chart_cache table in studio.db (or a small per-person JSON store / R2), columns: person_id, birth_hash, engine_version, chart_json, created_at. Look up by (person_id or birth_hash) + engine_version.
• KNOWN PEOPLE: precompute the natal charts for Jeff, Sol, Colin, Josh and commit them as JSON fixtures in the repo (e.g. verification/known_charts_computed/), so they are instant everywhere (laptop + cloud) with zero first-compute. Regenerate these fixtures whenever CHART_ENGINE_VERSION bumps (a small script).
• New users at scale: compute-once-then-store on first request; every later request reads the cache.
• Per-environment cache is fine (laptop and cloud each keep their own); the committed fixtures are shared via the repo.

Wiring

• Add compute_chart_cached(birth) (or a chart_store.get_or_compute(...)) that returns the natal Chart from cache or computes+stores it. Route the chart consumers through it:
• get_person_chart / compute_chart_from_birth (Hermes).
• script generation / audio render (script_generator, the --council path).
• any reading/analysis that needs the chart.
• render_all_facts natal sections read from the cached Chart; render_timing_facts stays computed live (date-dependent), layered on top.
• SERIALIZATION: ensure the Chart dataclass (placements, aspects, extended_points incl. Lilith/Lots/Vertex/Chiron/asteroids, HD, Gene Keys, numerology) round-trips to/from JSON faithfully. Add a test: compute -> serialize -> deserialize -> identical facts.

Guardrails

• IDENTICAL OUTPUT: caching is a pure performance optimization; the natal facts are byte-for-byte the same as a fresh compute (deterministic). It must not change any audio's content.
• DEMO LOCKED: the demo render output is unchanged (same natal chart). Adopt the cache on the demo path only if it is provably transparent; if there is any doubt, leave the locked demo path as-is (it is a single render, low cost) and apply caching to the Studio/Hermes paths.
• Engine-version key is mandatory (above), so upgrades always propagate.
• No em dashes. Vendor any engine changes into affirmology-studio/affirmology-agent/.

Payoff

• At scale: each person's chart math runs once, not once-per-audio. Big compute/cost saving.
• Consistency: the same natal basis underlies every audio and reading (no drift).
• Speed: faster renders and faster Hermes responses (no recompute).

Acceptance test

1. First pull for a person computes + stores the natal chart; a second pull reads from cache (no recompute) and returns identical facts.
2. Editing birth data, or bumping CHART_ENGINE_VERSION, busts the cache and recomputes once.
3. Timing (transits/progressions) still reflects the CURRENT date on every pull (not frozen by the cache).
4. The 4 known people load from committed fixtures with no compute.
5. A rendered audio's content is identical with caching on vs off (determinism preserved).