# V9 Architecture Overview — A Curious Ape's Guide to Reality

V9 (codename **Metis**) is the version that points the entertainment machinery
of V1–V8 at _understanding_: a curious person types a wonder — "why is the night
sky dark?", "how old is the universe?" — and the system forges a grounded,
interactive, provenance-stamped lesson with no human authoring per lesson. The
defining architectural fact about V9 is that it is an **integration and
productization** version, not a from-scratch build. It adds exactly three
genuinely-new data structures and a generative pipeline that _composes_ the
real, already-shipped Oshun substrate (Sophia retrieval, Mnemosyne
spaced-repetition, the Nyx ephemeris, the Kalika physics kernels) rather than
reimplementing any of it. That choice is visible in the code: the entire net-new
surface is the typed vocabulary in `libs/contracts/src/v9/` (four files) plus
twelve focused packages under `libs/v9/` (`atlas`, `prometheus`, `aletheia`,
`hephaestus`, `mnemosyne-glue`, `lesson-explorables`, `lesson-gates`, `theia`,
`chiron`, `experience`, `governance`, `cross-cutting`), and almost every one of
them opens its module doc-comment with the same sentence — "composes the real
engines, no new graph store / retrieval / physics / psychometrics."

Why build it this way? Because trustworthiness and cost are the same problem. A
lesson is treated as a **reproducible artifact** with a hard separation between
a _verified skeleton_ (grounded claims and kernel-computed numbers —
authoritative and immutable once gated) and a _regenerable surface_ (the prose,
the Socratic dialogue, the media — re-skinnable over the same skeleton). That
split, encoded directly in the `V9LessonArtifact` contract as `skeletonHash` vs
`surfaceHash` (`libs/contracts/src/v9/lesson.ts:163`), is what lets V9 gate a
popular lesson once and serve it many times, and lets it swap a different
teacher persona over the same proven content without re-verifying the truth.
This page is the orientation companion to the architecture set; the monolith hub
is [../V9_ARCHITECTURE.md](../V9_ARCHITECTURE.md).

## What ships, honestly

V9's `V9_TODOS.md` tracks the build at 46 done / 11 partial / 0 open, and the
code backs a substantial, _tested_ core — but the monolith is in places
aspirational, so this section separates what is real from what is planned or
gated. Honest "planned/gated" beats fake "shipped."

**Implemented and tested (real today).** The three net-new contracts are real
Zod schemas with enforced invariants, exercised by
`libs/contracts/src/v9/__tests__/v9-contracts.spec.ts`. The **Atlas** store,
graph-unifier, source adapters, grounded-leaf binders, and wonder-resolver are
real and delegate prerequisite reasoning to the genuine `@mnemosyne/core`
`KnowledgeGraph` (`libs/v9/atlas/src/atlas-store.ts:113`). The **Prometheus**
pipeline composes Stages 0–8 end-to-end into a publishable `V9LessonArtifact`
(`libs/v9/prometheus/src/pipeline.ts:111`). **Aletheia**'s G1/G2/G6 gates are
real, and G2 recomputes STEM values from the genuine `@kalika/cosmology`
Friedmann solver and `@nyx/constants`
(`libs/v9/aletheia/src/kernel-evaluators.ts:33`). **Hephaestus**'s two
computed-kernel explorables are _actual computation_: the Nyx sky integrates the
real `@nyx/ephemeris` Sun position
(`libs/v9/hephaestus/src/nyx-sky-explorable.ts:13`) and the Kalika orbit runs
the real `@kalika/symplectic` velocity-Verlet integrator
(`libs/v9/lesson-explorables/src/orbit-explorable.ts:117`). The **experience**
view-models, **mnemosyne-glue** mastery loop, and the **lesson-gates** suite
over the shared platform release-gate service are all present with sibling
`*.spec.ts` files.

**Spec-described / planned.** The consumer _application_ — the rendered
wonder-front-door, lesson-player, and personal star-map screens — is **not**
shipped. `libs/v9/experience` ships the tested _view-models_ those screens would
bind to (`buildWonderFrontDoor`, `buildLessonPlayer`, `buildPersonalAtlasMap`),
and `apps/metis/{web,mobile}` exist but are "currently instructor/admin-shaped";
the consumer-first rebuild is, by the architecture's own admission
([../V9_ARCHITECTURE.md](../V9_ARCHITECTURE.md) §7), "the largest net-new
build," and it is not done. Of the three explorable _kinds_ in the contract,
only **computed-kernel** has a real builder; **generative-widget** and
**game-bridge** are typed but their runtimes (LLM widget generation, the Bellona
engine cook path) are deferred to P2/P3. "Browser WASM" delivery is the planned
packaging; the V9 explorable libs run the genuine Kalika integrator _in-process_
(Node/TS), not a wasm-bindgen build — the _computation_ is real, the in-browser
packaging is not what these libs exercise.

**Provider-gated injected seams (fail-loud, not faked).** Several inputs are
typed boundaries the pipeline _injects_ rather than fakes: the LLM lesson writer
(the Iris boundary in Stage 3), the optional Nous dense reranker in wonder
resolution, the LLM-as-judge quality panel (G5 — the default is an honest
_deterministic structural proxy_, `libs/v9/prometheus/src/gates.ts:77`), the
Sophia contradiction checker, and the embodied Chiron live voice/avatar. These
refuse to fabricate: an absent writer falls back or fails loud; an unresolvable
wonder throws `WonderUnresolvedError`. One honesty note on G7: the provenance
gate verifies that the skeleton/surface/cacheKey hashes and a ledger entry are
_present_ (`libs/v9/prometheus/src/gates.ts:105`) — actual cryptographic C2PA
signing of every asset is the V3-inherited discipline the bundle is shaped for,
not a signature these libs produce (`c2paSigned` defaults to `false`).

**A real naming divergence worth knowing.** There are two gate modules with two
different G1–G7 mnemonics. The _canonical_ numbering (this page, the
architecture doc, and the Prometheus/Aletheia/Hephaestus composition) is **G1
grounding, G2 accuracy, G3 pedagogy, G4 completeness, G5 quality, G6 safety, G7
provenance**. The separate `@oshun/v9-lesson-gates` suite uses a _different_
order — **G1 truth, G2 grounding, G3 teachability, G4 safety, G5 explorable, G6
adaptive, G7 retrieval** (`libs/v9/lesson-gates/src/index.ts:12`). Both are
real, both run on the shared `@oshun/content-release-gates` service; they are
two framings of the same seven-gate discipline. Cross-linked detail lives in
[./seven-gates-and-aletheia.md](./seven-gates-and-aletheia.md).

## The six-layer reuse stack

V9 inherits the platform's recommended six-layer architecture (model plane →
agent runtime → capability tools → production orchestration → governance →
delivery) and specializes it for learning, consuming all six rather than adding
to them. Crucially, V9 spawns **no new agent loop** — Prometheus runs on the
existing Iris runtime, and the writer is an injected boundary, not a bespoke
orchestrator. The full layer-by-layer accounting, and the file-level reuse
ledger that shows which `libs/` surface each subsystem builds on, are their own
pages: [./six-layer-reuse-stack.md](./six-layer-reuse-stack.md) and
[./subsystem-map-and-reuse-ledger.md](./subsystem-map-and-reuse-ledger.md).

## The three net-new structures (the typed spine)

Everything V9 adds is anchored by three contracts in `libs/contracts/src/v9/`,
re-exported flat and under a `V9Contracts` namespace from the package root
(`index.ts:9`).

### ConceptNode / ConceptEdge — the Atlas vocabulary

`V9ConceptNodeSchema` (`concept-graph.ts:66`) carries a content-addressed `id`
(either `cn:<64-hex>` or a `<namespace>:<slug>` ref, `primitives.ts:17`), one of
seven **wonder axes**
(`cosmos, laws, mind, meaning, deep-time, living-world, made-world`,
`primitives.ts:42`), a discipline, a kind
(`topic|skill|fact|procedure|principle`), grounding pins, kernel refs, and a
required `epistemicStatus` (`established|contested|one-tradition|frontier`). Two
structural invariants are baked into the schema's `superRefine`, so a violating
node _fails to parse_:

1. **Every fact node carries ≥1 grounding pin** — no ungrounded fact may exist
   (`concept-graph.ts:67`).
2. **Every STEM fact/principle/procedure node carries a kernelRef** — its value
   is _computed_, not asserted. `v9NodeRequiresKernel` (`concept-graph.ts:36`)
   gates this against the STEM discipline set
   (`astronomy, physics, mathematics, chemistry, earth-science`,
   `primitives.ts:93`).

The same checks are also exposed non-throwing as `checkV9ConceptNodeInvariants`
(`concept-graph.ts:133`) so the Atlas build-time validator can _report_ every
violation across a whole graph instead of throwing on the first. Edges union the
Metis, Sophia, and Mnemosyne relation vocabularies plus a V9-specific `bridges`
edge for cross-axis threads (`concept-graph.ts:89`), and reject self-loops.

### Explorable — a manipulable surface with a proven success state

`V9ExplorableSchema` (`explorable.ts:104`) binds a concept to one of three kinds
in increasing generative risk (`computed-kernel`, `generative-widget`,
`game-bridge`). The load-bearing field is the **success state**: `reachable` is
a boolean that, by contract comment and by the builders that set it, is true
_only_ when the target was actually demonstrated by a kernel result or a
headless verifier — "never asserted blind" (`explorable.ts:73`).
`isV9ExplorableShippable` (`explorable.ts:128`) is simply
`successState.reachable`, and a computed-kernel explorable that is grounded by a
pin instead of a kernelRef is rejected (`explorable.ts:115`). See
[./hephaestus-explorables.md](./hephaestus-explorables.md).

### Lesson — the cacheable, gated delivery artifact

`V9LessonArtifactSchema` (`lesson.ts:190`) is the compiled output. Its split is
the whole point: `groundTruth` (grounded `claims` each with ≥1 pin and a
`truth ∈ {true,false,unverified}` verdict, plus kernel-`computedValues`) is the
verified skeleton; `narrative`/`media` are the regenerable surface; and a
`superRefine` enforces referential integrity — every Socratic turn's `claimRef`,
every misconception correction, and the retrieval-check item must index a real
grounded claim (`lesson.ts:218`). `isV9LessonPublishable` (`lesson.ts:246`)
returns true only when all seven gate verdicts pass. The deeper anatomy is in
[./lesson-artifact.md](./lesson-artifact.md).

## Atlas: the knowledge spine, assembled not authored

Atlas is the one large new data structure, and it is _assembled_ by unifying
graphs that already exist. The `AtlasStore`
(`libs/v9/atlas/src/atlas-store.ts:55`) is a content-addressed `ConceptNode`/
`ConceptEdge` graph that validates every inserted node through
`V9ConceptNodeSchema` at the door (so the two invariants hold by construction),
and — critically — **delegates all prerequisite reasoning to the real Mnemosyne
engine**: `toMnemosyneGraph` (`atlas-store.ts:113`) projects the Atlas onto a
`@mnemosyne/core` `KnowledgeGraph`, and closure, topological sort, and
gap-analysis run there, not in V9. The graph-unifier
(`libs/v9/atlas/src/graph-unifier.ts:96`) merges per-source graphs by a
canonical content-hash of the slugged label (`canonicalId`, line 68), unioning
pins, kernel refs, and aliases. Its honesty discipline is explicit: a merged
node that _still_ violates an invariant after merge is not silently coerced into
validity — it is recorded in `skipped` with a reason and left out of the store
(`graph-unifier.ts:150`). Source adapters map the Metis concept graph, the
Sophia KG, and the Mnemosyne prerequisite graph into the shared vocabulary
(`source-adapters.ts`), and grounded-leaf binders attach real kernel callables
(`kalika:cosmology#ageTodayGyr`, `nyx:ephemeris#sun.position`) to STEM nodes
(`grounded-leaves.ts`).

**Wonder resolution** (`libs/v9/atlas/src/wonder-resolution.ts:86`) is the
front-door query. A free-text wonder is run through real **Sophia BM25** lexical
retrieval over the node text (`createBM25LexicalIndex`, line 96), optionally
blended 50/50 with an injected **Nous** dense embedder so a lexically-disjoint
wonder ("the beginning of everything") can still reach the right concept; the
chosen target's **Mnemosyne** prerequisite frontier is then filtered by the
learner's mastery (`identifyKnowledgeGaps`, line 141) to yield the _minimal_
teaching set in prerequisite order. A wonder that matches nothing throws
`WonderUnresolvedError` (line 56) rather than inventing a concept. Full detail:
[./atlas-knowledge-graph.md](./atlas-knowledge-graph.md).

## Prometheus: the lesson forge (the flow)

`forgeLesson` (`libs/v9/prometheus/src/pipeline.ts:111`) composes the stages
end-to-end. The governing rule is **solve-first**: the verified skeleton is
built from the _grounded Atlas nodes_ before any prose exists, and the writer is
constrained to realize that skeleton — "the LLM never invents a fact or a
number" (`ground-truth.ts:8`). `buildGroundTruth` (`ground-truth.ts:43`) refuses
to proceed if no grounded fact node is in scope (line 86), and recomputes every
STEM value through the real kernel evaluator rather than trusting a stored
literal.

```mermaid
sequenceDiagram
    participant L as Learner (a wonder)
    participant A as Atlas (Sophia BM25 + Mnemosyne)
    participant G as Ground-truth (kernels)
    participant W as Writer (Iris boundary)
    participant H as Hephaestus
    participant Al as Aletheia + gates
    participant C as Compile + cache

    L->>A: "why is the night sky dark?"
    A->>A: BM25 + dense rerank → target concept
    A->>A: Mnemosyne mastery-scoped prereq frontier
    A-->>G: minimal concept set (prereq-first)
    G->>G: grounded claims + RECOMPUTED kernel values
    G-->>W: verified skeleton (immutable)
    W->>W: realize skeleton (Socratic, misconception pass)
    W-->>H: chosen concept
    H->>H: build computed-kernel explorable; measure success state
    H-->>Al: narrative + explorable + skeleton
    Al->>Al: G1 grounding, G2 accuracy, G3 pedagogy, G4 completeness,<br/>G5 quality, G6 safety, G7 provenance
    alt any gate fails
        Al-->>L: BLOCKED (not delivered, not cached)
    else all seven pass
        Al->>C: compile V9LessonArtifact
        C->>C: skeletonHash/surfaceHash, ledger, (conceptSet,profileClass,seed) cache
        C-->>L: deliver lesson + Theia's next wonders
    end
```

**Worked example.** A learner asks "why is the night sky dark?" Stage 0 resolves
it to the Olbers'-paradox concept and its mastery-scoped prerequisites. Stage 1
pulls the grounded skeleton — including a kernel value such as the age of the
universe, recomputed as `ageTodayGyr(PLANCK_2018_COSMOLOGY)` from the real
Friedmann solver, never stored as "13.8 Gyr." Stage 3 writes Socratic prose
whose every assertion `claimRef`s back into that skeleton. Stage 5 binds a Nyx
sky explorable. Stage 7 runs the gates; Stage 8 emits the artifact, hashes it,
writes the ledger entry, and caches it by _profile class_ (not learner id), so
the next person who wonders the same thing is served the already-gated lesson.
The full stage table is in
[./prometheus-lesson-pipeline.md](./prometheus-lesson-pipeline.md).

## The seven gates and Aletheia

Stage 7 assembles the seven contract verdicts in `composeGates`
(`libs/v9/prometheus/src/gates.ts:132`): G1/G2/G6 come from Aletheia, G4 from
the Hephaestus computed-explorable DoD, and G3 (pedagogy), G5 (quality), G7
(provenance) are evaluated in Prometheus. Aletheia is deliberately a **thin
policy layer**, not a new grounding engine — G1 binds claims to Sophia pins, G2
recomputes numbers via Nyx/Kalika, and Aletheia owns only the "must pass or
block" semantics (`libs/v9/aletheia/src/index.ts`). G2 is the one part with no
home in Sophia: `evaluateAccuracy` (`accuracy-gate.ts:53`) recomputes each
asserted value and **blocks on an unknown kernel ref or a tolerance miss** —
"you cannot ship a number you cannot reproduce" (line 66). G3 fails a lesson
with a prerequisite-coverage gap or _zero_ anticipated misconceptions
(`gates.ts:36`). The block path is hard: when any gate fails, `forgeLesson`
returns early with `blocked: true` and the failing gate ids, and _no artifact is
compiled, delivered, or cached_ (`pipeline.ts:235`). See
[./seven-gates-and-aletheia.md](./seven-gates-and-aletheia.md).

## Hephaestus: explorables that compute, not animate

The Hephaestus DoD is that every P1 lesson ships ≥1 _computed-kernel_ explorable
whose success state was _measured_. `buildNyxSkyExplorable`
(`libs/v9/hephaestus/src/nyx-sky-explorable.ts:61`) samples the real
`calculateSunPosition` across a date slider and sets `reachable` only if the
Sun's right ascension actually sweeps ≈360°·days/year over the computed series
(line 81) — a real measured fact, with the swept degrees recorded as evidence.
`buildKalikaOrbitExplorable` (`kalika-orbit-explorable.ts:37`) wraps the genuine
velocity-Verlet integrator and sets `reachable` only when the symplectic
integrator's measured relative energy drift is below tolerance (line 44). The
DoD becomes the G4 verdict via `evaluateExplorableDoD`
(`explorable-runtime.ts:24`), which fails loudly if there is no computed-kernel
explorable or if one never reached its success state. More:
[./hephaestus-explorables.md](./hephaestus-explorables.md).

## Delivery (L6) and cross-cutting

V9's P1 delivery is **web-first and deliberately does not depend on the Bellona
Unreal cook path** — the two heaviest surfaces (the Nyx sky and Kalika physics)
are computed surfaces, and only the _game-bridge_ explorables need the engine
bridge, which is why they are scoped to P2/P3. The `experience` package supplies
the tested view-models the consumer screens bind to — `buildWonderFrontDoor`
(`libs/v9/experience/src/wonder-front-door.ts:43`, which catches an unresolved
wonder and returns an `unresolved: true` state rather than throwing at the UI),
`buildLessonPlayer` (with a show-your-sources transparency panel), and the
personal Atlas star-map — but, as noted above, the rendered application is the
open net-new build. Governance, determinism, cost discipline, localization, and
accessibility are handled by the `governance` and `cross-cutting` packages and
the shared platform plane (every forge is an AgentRun under the V1 Agentic AI
Studio envelope; nothing runs ungoverned). The full delivery and cross-cutting
account is in
[./delivery-and-cross-cutting.md](./delivery-and-cross-cutting.md).

## Failure modes and edge cases

The system is built to _refuse_ rather than fabricate, and the refusals are
specific:

- **Unresolvable wonder** → `WonderUnresolvedError` (`wonder-resolution.ts:56`);
  the front door degrades to an `unresolved` state.
- **Nothing to ground** → `buildGroundTruth` throws "refusing to forge an
  ungrounded lesson" when no grounded fact node is in scope
  (`ground-truth.ts:86`).
- **Invariant-violating merged node** → recorded in `skipped`, left out of the
  Atlas, with a logged reason (`graph-unifier.ts:150`) — a logged truncation,
  not a fabricated grounding.
- **Unreproducible number** → G2 blocks on an unknown kernel ref or a value
  mismatch (`accuracy-gate.ts:66`).
- **Unreachable explorable** → G4 fails (`explorable-runtime.ts:33`); a
  generated-but-unverified explorable never ships.
- **Any gate failure** → the lesson is blocked, _not_ delivered and _not_ cached
  (`pipeline.ts:235`); the contract's own `isV9LessonPublishable` must agree
  with the gate sum, with a defensive throw if they ever disagree
  (`pipeline.ts:257`).
- **Cyclic prerequisite graph** → topological ordering falls back to the input
  order instead of throwing (`wonder-resolution.ts:159`).

## Configuration and determinism

A forge is parameterized by a `seed`, a caller-supplied clock (`nowUnixMs`, "no
fabricated time"), a `learnerProfileClass`, and a set of optional injected
boundaries (`writer`, `embedder`, `qualityJudge`, `safetyOptions`,
`learnerMastery`, `cache`, `ledger`) — see `ForgeLessonInput`
(`pipeline.ts:53`). Determinism is both a provenance and a cost lever: the same
inputs and seed yield the same artifact and hashes, and the cache key is the
`(conceptSet, learnerProfileClass, seed)` digest, so a popular lesson is
generated and gated once per profile class and served many times. Numeric
tolerances are explicit (G2 defaults to a 1e-3 relative match; kernel results
carry their own 1e-6 tolerance, `lesson.ts:51`), which is what makes "computed,
not asserted" a checkable claim rather than a slogan.

## Related

- Section hub: [../V9_ARCHITECTURE.md](../V9_ARCHITECTURE.md), and the product
  framing in [../README.md](../README.md)
- [./subsystem-map-and-reuse-ledger.md](./subsystem-map-and-reuse-ledger.md) and
  [./six-layer-reuse-stack.md](./six-layer-reuse-stack.md) — the reuse
  accounting
- [./atlas-knowledge-graph.md](./atlas-knowledge-graph.md) — the knowledge spine
- [./prometheus-lesson-pipeline.md](./prometheus-lesson-pipeline.md) — the forge
  stages in depth
- [./seven-gates-and-aletheia.md](./seven-gates-and-aletheia.md) — the gate
  semantics and the two gate framings
- [./hephaestus-explorables.md](./hephaestus-explorables.md) — computed-kernel
  explorables
- [./lesson-artifact.md](./lesson-artifact.md) — the delivery contract anatomy
- [./delivery-and-cross-cutting.md](./delivery-and-cross-cutting.md) — L6,
  governance, determinism, cost