Subsystem Map, Substrate Reuse, and the Seven Gates

V9 (Metis — A Curious Ape's Guide to Reality) is deliberately an integration architecture, not a green-field engine: it forges true, interactive lessons on demand by composing engines the monorepo already shipped, and it holds every generated lesson behind seven gates so nothing untrue, unsafe, ungrounded, or pedagogically broken reaches a learner. This page is the canonical reference the product overview points to for two things it only sketches: the subsystem ownership ledger (which of the eight named subsystems lives in which of the twelve @oshun/v9-* packages, and what each one actually composes) and the gate mechanics (where each gate is computed, what it blocks on, and what failing it triggers). It is the features-side companion to the architecture catalogue; the hub for the set is ../V9_features.md, and the full pipeline mechanics live in ../V9_ARCHITECTURE.md.

The reason V9 is buildable rather than aspirational is the same reason this page is worth reading carefully: the trust model is enforced by contracts and composed evaluators, not by prose. The seven contract gate verdicts live on the V9LessonArtifact itself (libs/contracts/src/v9/lesson.ts:149), and isV9LessonPublishable() (lesson.ts:246) is true only when all seven pass. The forge (libs/v9/prometheus/src/pipeline.ts) assembles those verdicts from the subsystems and refuses to compile an artifact that disagrees with its own gate sum. So "the subsystems" and "the gates" are not two topics — the gates are the contract by which the subsystems hand work to each other.

What ships, honestly#

The connective tissue is real and tested. All twelve libs/v9/* packages (@oshun/v9-atlas, -prometheus, -aletheia, -chiron, -hephaestus, -mnemosyne-glue, -theia, -governance, -experience, -cross-cutting, -lesson-gates, -lesson-explorables) plus the libs/contracts/src/v9 contract package are implemented and exercised by 18 spec files, and V9_TODOS.md carries 46 [x], 11 [~], and zero open [ ] items. The gates are wired into the forge for real: runAletheia and composeGates are both called inside forgeLesson (pipeline.ts:225), and a blocked lesson returns with no artifact (pipeline.ts:236).

Three honesty notes a careful reader needs, all grounded in what is actually in the tree rather than in the design doc:

• There are two different "seven gates," and they are numbered differently. The README / V9_features.md / contract numbering is G1 Grounding, G2 Accuracy, G3 Pedagogy, G4 Completeness, G5 Quality, G6 Safety, G7 Provenance — this is the V9Gates block stamped onto the artifact. The separate platform release-gate suite (@oshun/v9-lesson-gates) registers a different decomposition — G1 truth, G2 grounding, G3 teachability, G4 safety, G5 explorable, G6 adaptive, G7 retrieval. Both are real, both are tested, both are "seven gates"; they are not the same seven by number. Conflating them is the single easiest mistake to make here, so this page keeps them visibly separate.
• Four substrates are wired; the rest are fail-loud seams. The only non-@oshun engine imports anywhere under libs/v9 are @mnemosyne/core (×17), @kalika/cosmology / @kalika/symplectic (×3), @sophia/semantic-search (×1), and @nyx/ephemeris / @nyx/constants (×2). The other substrates the design doc names as owners — Psyche (voice/face), Hathor (LLM-NPC), Isis (assets), Euterpe (music), Metis (curriculum-safety policy), Sekhmet (age-gating), Iris (the agent loop), Nous (the dense embedder) — are present as injected typed interfaces that throw when unwired, not as wired dependencies. libs/urania and libs/sekhmet do not exist as directories on this branch at all; libs/psyche exists but is not imported by any V9 package. Refusing to fabricate an absent integration is the opposite of a stub, but it does mean the ownership ledger below is partly "owns the seam," not "ships the engine."
• Two gate evaluators are deliberately scoped. The G2 kernel registry computes six cosmology / physical-constant refs today (libs/v9/aletheia/src/kernel-evaluators.ts, extensible via an injected KernelEvaluator), and the default G5 quality judge is a deterministic structural proxy standing in for the injected LLM-judge panel — it is honest about being a proxy and is overridable, not a fake LLM.

The genuinely external [~] work is what you would expect to be gated on the world: the rendered consumer app and closed beta, the provider-gated Psyche avatar embodiment, the Bellona Unreal cook path (a P2/P3 motion), the Agora creator-payout rails, and the multi-week efficacy study.

The subsystem ownership ledger#

V9's design names eight subsystems under the Promethean "gift of fire" metaphor. They map onto the twelve packages as follows. The "Composes" column is the load-bearing one — it distinguishes a wired engine from an injected seam.

Two mismatches between the design doc and the code are worth stating outright, because the overview flags them and an adversarial reader will check them: Agora is not its own package — it is agora.ts inside @oshun/v9-theia. And Mnemosyne is reuse, not a new subsystem — @oshun/v9-mnemosyne-glue is the thin lesson↔trace binding over the pre-existing @mnemosyne/core engine (17 import sites across V9), which is exactly why the doc tags it (reused). The four "supporting" packages (-governance, -experience, -cross-cutting, -lesson-gates) do not appear in the eight-name list at all; they carry the cross-cutting concerns — governance, view-models, cost/determinism, and the platform gate registration — that every subsystem leans on.

Substrate reuse: what is wired versus what is a seam#

The defining engineering choice of V9 is "no new agent loops, no new asset providers, no reinvented kernels" — it consumes the platform. In code that splits cleanly into two categories.

Wired engines (a real import that runs in-process):

• @mnemosyne/core — FSRS-v4 review (fsrsReview) and the knowledge-graph / prerequisite reasoning, used by Atlas resolution and the whole mastery loop.
• @sophia/semantic-search — BM25 lexical retrieval over each concept node's label + aliases + discipline + axis, the first pass of wonder resolution.
• @nyx/ephemeris (sun position for the sky explorable) and @nyx/constants (the physical constants behind G2 accuracy, e.g. SPEED_OF_LIGHT).
• @kalika/cosmology — the Friedmann solver (ageTodayGyr, hubbleParameter, lookbackTimeGyr over PLANCK_2018_COSMOLOGY) behind both the orbit/cosmology explorables and G2's recomputed STEM values; @kalika/symplectic integrates the orbit explorable.

Injected seams (a typed interface that throws a named error when unwired, so the product fails loud instead of fabricating): the Iris LessonWriter and misconception anticipator (Stage 3 generation), the Nous WonderEmbedder (the optional dense rerank), the Metis CurriculumSafetyEvaluator and Sekhmet SekhmetAgeGate (G6), the Sophia CitationVerifier and ContradictionChecker (the optional entailment / contradiction passes inside G1/G2), the G5 QualityJudge (the LLM-judge panel), and Hephaestus's Manim renderer and headless widget runner. Each refuses to invent output. This is the honest core of "substrate reuse": V9 owns the gate semantics and the orchestration, and it borrows everything that computes or generates — either as a wired engine or as a boundary that fails loud when the engine is absent.

The seven gates — the canonical contract gates#

These are the seven the README, V9_features.md, and the V9Gates contract all agree on (V9GateIdSchema = ['G1'..'G7'], lesson.ts:138). Each is a V9GateVerdict — { pass: boolean, evidence: string[] } — and the forge stamps all seven onto the artifact's gates block.

A few gate internals reward a closer look:

• G2 recomputes; it never trusts a stored number. evaluateAccuracy resolves each claim's ref through the kernel registry and computes a relativeError = |asserted − computed| / max(|computed|, 1e-12). An unknown ref blocks outright — "you cannot ship a number you cannot reproduce" — and so does any mismatch beyond tolerance. The registry (kernel-evaluators.ts) binds six real refs: kalika:cosmology#ageTodayGyr, #hubble0, #lookbackTimeGyr, #hubbleParameter, and nyx:constants#speedOfLight / #speedOfLightKmS. Each is an actual in-repo computation, so the age of the universe is derived from the Friedmann integral, not a literal pasted into a prompt.
• G6 fails loud on high-stakes ignorance. HIGH_STAKES_DISCIPLINES = {religion, psychology, neuroscience}. For those, a missing curriculum-safety policy is a blocker, not a pass, and a missing human-review checkpoint forces block-or-escalate (route to editorial, do not auto-publish). G6 also requires an epistemicStatus label on every claim, which is how the "established / contested / one-tradition" labelling promise is enforced rather than hoped for.
• G5 is honest about its default. defaultQualityJudge scores structure (≥3 beats → 0.4, ≥1 Socratic turn → 0.3, ≥1 misconception → 0.2, a "next question" beat → 0.1) against a 0.7 threshold. It is explicitly a proxy for the injected LLM-judge panel and is replaced by passing a real judge.
• G4 is demonstrated, not asserted. isV9ExplorableShippable is true only when successState.reachable is true, and the contract's own superRefine forces a computed-kernel explorable to be grounded by a kernelRef rather than a stored value. The Nyx sky explorable, for instance, sets reachable only after its computed samples show the Sun's RA sweeping ≈360° over a year.

How the gates are composed in the forge#

The forge does not run a monolithic gate function. Aletheia owns the three truth-shaped gates and runs them in parallel; Prometheus composes the other four; composeGates stitches all seven into the contract V9Gates.

Concretely, runAletheia (aletheia.ts:47) runs G1/G2/G6 under Promise.all and de-duplicates their distinct fail actions for routing; composeGates (gates.ts:132) injects the Hephaestus DoD as G4 and folds in the pedagogy, quality, and provenance verdicts. The forge then computes blockedGateIds = ALL_GATE_IDS.filter(id => !gates[id].pass) (pipeline.ts:232). If anything is blocked it returns without an artifact. If nothing is blocked it compiles, and then runs a defensive check: if isV9LessonPublishable(compiled.artifact) disagrees with the gate sum, it throws rather than ship (pipeline.ts:257). The contract and the pipeline must agree, or the build fails.

The other seven gates — the platform release-gate suite#

Separately from the contract gates, V9 satisfies the repo's "no eighth loop" rule: a lesson is also gated by the same shared @oshun/content-release-gates service every other Oshun product uses, not a bespoke per-product checker. That suite lives in libs/v9/lesson-gates/src/index.ts (buildV9LessonGates, evaluateV9Lesson), and @oshun/v9-governance's confirmSevenGateSuite (gate-suite.ts) attests that it registers exactly seven gates on the platform service (gateCount === 7, usesPlatformReleaseGate: true, bespokeChecker: false).

The catch a reader must internalize: this suite's seven gates are numbered differently from the contract gates above. Each is built from the platform primitives gateFromManifestCheck / gateFromEvalScore / createGroundingGate:

So the platform suite splits truth and grounding into G1/G2 (where the contract merges grounding into its G1 and makes its G2 accuracy), lifts safety to G4, makes explorable G5, and replaces quality/provenance with explicit adaptive and retrieval gates. Both representations are genuine and tested. The way to read them is: the contract V9Gates is the per-lesson trust object stamped into the artifact; the @oshun/v9-lesson-gates suite is the platform-conformance attestation that V9 runs on the shared release-gate engine. They are complementary, not a contradiction — but they are emphatically not the same numbering, and the design doc's single seven-row table papers over that.

Block semantics, fail actions, and regenerate-with-direction#

Gates block; they do not warn. A blocked forge returns { blocked: true, blockedGateIds, gates, aletheia, conceptSet } with no artifact, so a failing lesson is never delivered and never cached. The AletheiaFailAction union (aletheia/src/verdict.ts) is what makes the retry intelligent rather than a blind re-roll: reground (G1 — re-ground or drop the claim), regenerate-with-corrected-ground-truth (G2 — the kernel value is authoritative, the text is wrong), and block-or-escalate (G6 — a safety failure routes to editorial, it does not silently regenerate). runAletheia collects the distinct actions across the failed gates so the orchestrator can apply each correction once. The pedagogy, quality, and provenance failures feed the more general "regenerate-with-direction" loop described in ./prometheus-lesson-forge.md.

How the map connects to the rest of V9#

The subsystem map and the gates are bracketed by the supporting packages:

• Governance registers V9 as an agent family in the V1 Agentic AI Studio (governance/src/agent-family.ts): the forge stages become a governable DAG with kill switches (ks:v9-family → pause, ks:v9-provider → text-only), budget inheritance (per-stage caps must sum to ≤ the inherited ceiling, validateBudgetInheritance), and a replay manifest keyed on cacheKey / skeletonHash / ledgerEntryId. confirmConsumesSharedLoop (iris-loop.ts) declares V9 owns zero agent loops and files a Phase-A2 gap (finding F2) rather than papering over an incomplete platform.
• Entitlements (governance/src/entitlements.ts) gate access deny-by-default over age / region / tier, with adult-gating and region blocks taking precedence over the paywall, and cross-product grants that turn a V2 racing podium into the applied-physics lesson, a meditation streak into the neuroscience-of-attention thread, and a V8 detective case into the logic-and-deduction lesson (CROSS_PRODUCT_GRANTS).
• Chiron consumes a gated artifact for delivery; its integrity modes (chiron/src/integrity-modes.ts, resolveTutorAction) are the academic-honesty floor — in practice or do-not-complete-for-me mode a request for the full answer to graded work is refused and redirected to a hint.
• Cross-cutting carries the cost ledger, the determinism verifier (same (inputs, seed) ⇒ same artifact + hashes), and the anti-metric guard that throws if time-on-app is ever set as the optimization target.

For the deep dives, follow the siblings below; this page is the index that ties the subsystems to the gates they feed.

Related pages#

• ./overview.md — the product thesis and the five nested primitives (Wonder → Lesson → Thread → Atlas)
• ./atlas-wonder-resolution.md — the concept graph, the grounding/computation invariants, and free-text wonder resolution
• ./prometheus-lesson-forge.md — the nine forge stages end to end and the regenerate-with-direction loop
• ./chiron-and-hephaestus.md — the embodied teacher (integrity modes) and the explorable workshop (the G4 DoD)
• ./threads-and-mastery-loop.md — Theia threads, the emotional arc, and the FSRS mastery loop
• ./braid-commons-and-films.md — the science↔human braid, Agora authoring, and explainer films
• ./governance-and-boundaries.md — entitlements, the anti-metric, cost, determinism, and the non-goals
• Hub: ../V9_features.md · Architecture spec: ../V9_ARCHITECTURE.md · Product thesis: ../V9_PRODUCT_ANALYSIS.md