# 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](./overview.md) 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](../V9_features.md), and the full pipeline mechanics live in
[../V9_ARCHITECTURE.md](../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.
| Subsystem | Package(s) | Owns | Composes (wired vs. seam) |
| -------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| **Atlas** | `@oshun/v9-atlas` | Unified concept graph; free-text wonder → mastery-scoped prerequisite frontier | _wired:_ `@sophia/semantic-search` BM25, `@mnemosyne/core` KnowledgeGraph; _seam:_ Nous embedder |
| **Prometheus** | `@oshun/v9-prometheus`, `@oshun/v9-lesson-explorables` | The nine-stage forge; solve-first ground truth; gate composition (G3/G4/G5/G7) | _wired:_ Atlas + Aletheia + Hephaestus + Mnemosyne-glue; _seam:_ Iris `LessonWriter` |
| **Aletheia** | `@oshun/v9-aletheia` | The truth gate: G1 grounding, G2 accuracy, G6 safety, and the regenerate routing | _wired:_ `@kalika/cosmology`, `@nyx/constants`; _seam:_ Metis policy, Sekhmet age-gate, citation/contradiction verifiers |
| **Chiron** | `@oshun/v9-chiron` | Teacher persona; the four tutoring integrity modes; lesson delivery | _seam:_ Hathor personality, Psyche voice (P1 persona is a disclosed synthetic) |
| **Hephaestus** | `@oshun/v9-hephaestus` | The explorable runtime; the computed-kernel DoD that becomes G4 | _wired:_ `@nyx/ephemeris`, `@kalika/cosmology`, `@kalika/symplectic`; _seam:_ widget runner |
| **Mnemosyne** | `@oshun/v9-mnemosyne-glue` | FSRS knowledge-trace, forgetting-frontier scheduling, flow-channel difficulty tuning | _wired:_ `@mnemosyne/core` (FSRS-v4 + KG) — a reuse, not a new codename |
| **Theia** | `@oshun/v9-theia` | Thread continuation, the emotional arc, "surprise me," Manim films, **and Agora** | _wired:_ Atlas edges; _seam:_ Manim renderer |
| **Agora** | `@oshun/v9-theia` (`agora.ts`) | Creator authoring → forge directives; the shareable free-tier social object | _wired:_ Prometheus directives; _seam:_ V7 Mawu distribution |
| _(supporting)_ | `-governance`, `-experience`, `-cross-cutting`, `-lesson-gates` | Entitlements & agent-family registration; player/front-door view-models; cost/determinism/anti-metric; the platform gate suite | _wired:_ `@oshun/content-release-gates`, `@oshun/content-quality-judge` |
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.
| Gate | Name | Computed in | Blocks when… | Fail action |
| ------ | ------------ | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------- |
| **G1** | Grounding | `aletheia/src/grounding-gate.ts` → `evaluateGrounding` | any claim lacks a Sophia pin ≥ `minCredibility` (0.5), is `unsupported`, or fails entailment | `reground` |
| **G2** | Accuracy | `aletheia/src/accuracy-gate.ts` → `evaluateAccuracy` | a STEM value's kernel ref is unknown, or `relativeError > tolerance` (default `1e-3`), or a contradiction | `regenerate-with-corrected-ground-truth` |
| **G3** | Pedagogy | `prometheus/src/gates.ts` → `evaluatePedagogy` | an unmastered prerequisite is missing from scope, zero misconceptions anticipated, or difficulty out of the flow band | (regenerate-with-direction) |
| **G4** | Completeness | `hephaestus/src/explorable-runtime.ts` → `evaluateExplorableDoD` | no `computed-kernel` explorable, or none whose `successState.reachable === true` | (rebuild explorable) |
| **G5** | Quality | `prometheus/src/gates.ts` → `evaluateQuality` | judge score `< 0.7` (default judge is a deterministic structural proxy) | (regenerate-with-direction) |
| **G6** | Safety | `aletheia/src/safety-gate.ts` → `evaluateSafety` | a claim lacks an epistemic-status label, a policy/age-gate blocks, or a high-stakes discipline has no wired policy / no human review | `block-or-escalate` |
| **G7** | Provenance | `prometheus/src/gates.ts` → `evaluateProvenance` | `skeletonHash`/`surfaceHash`/`cacheKey` are not 64-hex, or the ledger entry id is empty | (re-stamp) |
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`.
```mermaid
flowchart TD
subgraph Aletheia["runAletheia — Promise.all"]
G1["G1 grounding
evaluateGrounding
Sophia pins ≥ 0.5"]
G2["G2 accuracy
evaluateAccuracy
kernel recompute"]
G6["G6 safety
evaluateSafety
Metis + Sekhmet + epistemic label"]
end
subgraph Prometheus["composeGates"]
G3["G3 pedagogy
evaluatePedagogy
prereq + misconception + flow"]
G4["G4 completeness
evaluateExplorableDoD
reachable computed-kernel"]
G5["G5 quality
evaluateQuality
judge ≥ 0.7"]
G7["G7 provenance
evaluateProvenance
C2PA hashes + ledger"]
end
G1 --> V9Gates["V9Gates (artifact.gates)"]
G2 --> V9Gates
G6 --> V9Gates
G3 --> V9Gates
G4 --> V9Gates
G5 --> V9Gates
G7 --> V9Gates
V9Gates --> Check{"ALL_GATE_IDS
every pass?"}
Check -->|"any fail"| Blocked["BLOCKED
no artifact · blockedGateIds
regenerate-with-direction"]
Check -->|"all pass"| Compile["compile + cache · C2PA
isV9LessonPublishable double-check"]
```
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`:
| Suite gate | Id | Checks |
| --------------- | ----------------- | ----------------------------------------------------------------- |
| G1 truth | `g1:truth` | zero claims may be `false` or `unverified` (the Aletheia verdict) |
| G2 grounding | `g2:grounding` | every claim bound to a non-empty Sophia source pin |
| G3 teachability | `g3:teachability` | `teachabilityScore ≥ 70` |
| G4 safety | `g4:safety` | `safetyScore ≥ 90` |
| G5 explorable | `g5:explorable` | ≥1 `computed` explorable (Nyx/Kalika), not a static asset |
| G6 adaptive | `g6:adaptive` | `adaptiveDifficulty` present and in `[0, 1]` |
| G7 retrieval | `g7:retrieval` | a non-empty Mnemosyne retrieval-checkpoint ref |
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](./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](./overview.md) — the product thesis and the five nested
primitives (Wonder → Lesson → Thread → Atlas)
- [./atlas-wonder-resolution.md](./atlas-wonder-resolution.md) — the concept
graph, the grounding/computation invariants, and free-text wonder resolution
- [./prometheus-lesson-forge.md](./prometheus-lesson-forge.md) — the nine forge
stages end to end and the regenerate-with-direction loop
- [./chiron-and-hephaestus.md](./chiron-and-hephaestus.md) — the embodied
teacher (integrity modes) and the explorable workshop (the G4 DoD)
- [./threads-and-mastery-loop.md](./threads-and-mastery-loop.md) — Theia
threads, the emotional arc, and the FSRS mastery loop
- [./braid-commons-and-films.md](./braid-commons-and-films.md) — the
science↔human braid, Agora authoring, and explainer films
- [./governance-and-boundaries.md](./governance-and-boundaries.md) —
entitlements, the anti-metric, cost, determinism, and the non-goals
- Hub: [../V9_features.md](../V9_features.md) · Architecture spec:
[../V9_ARCHITECTURE.md](../V9_ARCHITECTURE.md) · Product thesis:
[../V9_PRODUCT_ANALYSIS.md](../V9_PRODUCT_ANALYSIS.md)