# V9 — Systems Deep Dive

> The `libs/v9/` area: twelve Nx libraries that build **Metis**, the "ask a
> wonder → get a grounded, gated, explorable lesson" learning product — a
> solve-first lesson forge that composes the platform's existing real engines
> (Sophia retrieval, Mnemosyne psychometrics, Nyx/Kalika physics) rather than
> reinventing them.

## What this area is

V9 (codename Metis, the "Curious Ape's Guide to Reality") is a consumer learning
product whose entry point is a single free-text _wonder_ — a question — rather
than a course catalog. Every library in `libs/v9/` is a TypeScript Nx library
tagged `scope:v9`, `layer:domain`, `type:lib`, and each carries a long
`description` in its `package.json` that cites the section of
`V9_ARCHITECTURE.md` it implements. The defining architectural stance, repeated
in nearly every module header, is **compose the real engines; add no new loop,
no new physics, no new psychometrics, no new retrieval** — V9's net-new code is
the _spine, the gates, and the orchestration_, not the kernels.

The area decomposes into a few tiers. At the bottom sits the **knowledge spine
and the gate substrate**: `@oshun/v9-atlas` (a unified
`ConceptNode`/`ConceptEdge` graph merging the Metis/Sophia/Mnemosyne graphs) and
`@oshun/v9-lesson-gates` (the seven-gate G1–G7 release suite built on the shared
`@oshun/content-release-gates`). On top of that sit the **composed evaluators**:
`@oshun/v9-aletheia` (the truth gate — grounding/accuracy/safety),
`@oshun/v9-lesson-explorables` and `@oshun/v9-hephaestus` (real computed
explorables from the Kalika symplectic integrator and the Nyx ephemeris), and
`@oshun/v9-mnemosyne-glue` (the FSRS/IRT mastery loop). `@oshun/v9-prometheus`
is the **orchestrator** — the Stage 0–8 HTN forge that wires all of the above
into a single provenance-stamped `V9LessonArtifact`. Finally the **delivery and
platform tiers**: `@oshun/v9-chiron` (tutor delivery + integrity modes),
`@oshun/v9-experience` (consumer view-models), `@oshun/v9-governance`
(agent-family registration + entitlements), `@oshun/v9-cross-cutting`
(determinism / cost / accessibility / LMS interop), and `@oshun/v9-theia` (the
Phase-2 "delight & depth" layer).

A recurring honest pattern runs through the area: the _logic_ is real, but the
_model/runtime boundaries_ (the LLM writer, the live avatar/voice runtime, the
Manim renderer, the dense embedder) are **injected seams that fail loud when
unconfigured** rather than fabricating output. For example
`@oshun/v9-lesson-explorables` throws `LessonForgeNotConfiguredError` when no
writer is wired, and `@oshun/v9-atlas` throws `WonderUnresolvedError` rather
than inventing a concept. None of the twelve projects is an empty scaffold —
each has a populated `src/` and a `*.spec.ts` suite (the test counts range from
a handful in the smaller leaf libs to ~20 in `aletheia` and `theia`).

## How it fits the wider system

These libraries depend _outward_ on the platform's shared engines and contracts,
never the reverse. The shared dependencies that show up across the area are
`@oshun/contracts` (the `V9*` schemas — `V9ConceptNode`, `V9Lesson`,
`V9LessonArtifact`, `V9GateVerdict`, etc.), `@mnemosyne/core` (FSRS-v4 / IRT-2PL
/ KnowledgeGraph), `@sophia/semantic-search` (BM25), `@nyx/ephemeris` +
`@nyx/constants`, `@kalika/cosmology` + `@kalika/symplectic`, and the shared
`@oshun/content-release-gates` + `@oshun/content-quality-judge` gate framework.

Internally the v9 libraries form a dependency DAG that `@oshun/v9-prometheus`
sits at the top of: Prometheus imports `v9-aletheia`, `v9-atlas`,
`v9-hephaestus`, `v9-lesson-explorables`, and `v9-mnemosyne-glue` to run its
pipeline; `v9-experience` composes `v9-atlas` and `v9-governance` (plus the
`@mnemosyne/core` mastery types) into screen view-models; `v9-theia` composes
`v9-atlas` plus the `@mnemosyne/core` engine for the P2 features,
re-implementing the Chiron logic internally in `chiron-full.ts` rather than
importing `v9-chiron` (`v9-chiron` and `v9-mnemosyne-glue` are declared in its
`package.json` but not currently imported). The consumer app (the L6 client
surface) binds to the tested view-models in `v9-experience`; institutional
consumers reach a finished lesson through the SCORM/QTI/xAPI/LTI exporters in
`v9-cross-cutting`. Walk the "used by" edges on any node below to see the exact
consumers.

## Entity reference

### @oshun/v9-atlas

The **unified knowledge spine** (`V9_ARCHITECTURE.md` §2; `libs/v9/atlas/src`).
It merges the Metis concept graph, the Sophia KG, and the Mnemosyne prerequisite
graphs into one content-addressed `ConceptNode`/`ConceptEdge` store
(`atlas-store.ts`), with each node parsed through `V9ConceptNodeSchema` at
insert so an ungrounded fact node or a kernel-less STEM node is rejected at the
door (the two Atlas invariants). Prerequisite reasoning is _delegated_ to the
real Mnemosyne `KnowledgeGraph` rather than reimplemented, and
`wonder-resolution.ts` turns a free-text wonder into a mastery-scoped
prerequisite frontier via Sophia BM25 (`createBM25LexicalIndex`) plus Mnemosyne
`identifyKnowledgeGaps`, failing loud with `WonderUnresolvedError` when nothing
matches. The `graph-unifier.ts` collapses same-named concepts to one
`cn:<sha256>` id and honestly reports invariant-violating merges in a `skipped`
list rather than fabricating grounding.

### @oshun/v9-aletheia

The **truth gate** (`V9_ARCHITECTURE.md` §5.1; `libs/v9/aletheia/src`) — a thin
policy layer that makes the existing rails a mandatory pass and owns _gate
semantics only_. `aletheia.ts` runs three sub-gates in parallel and aggregates
them: G1 grounding (every claim bound to a Sophia pin, in `grounding-gate.ts`),
G2 accuracy (`accuracy-gate.ts`), and G6 safety (`safety-gate.ts`), plus the
`regenerate-with-direction` fail-action routing. The G2 accuracy check is real:
`kernel-evaluators.ts` holds a `REGISTRY` of ref → in-repo computation that
recomputes STEM values on demand from `@kalika/cosmology` (`ageTodayGyr`,
`hubbleParameter`, `lookbackTimeGyr` over `PLANCK_2018_COSMOLOGY`) and
`@nyx/constants` (`SPEED_OF_LIGHT`), so a generated number is checked against
ground truth rather than trusted.

### @oshun/v9-lesson-gates

The **seven-gate release suite** (ledger §J.1; `libs/v9/lesson-gates/src`). This
is the smallest leaf in the area but the load-bearing one: it enforces V9's "no
eighth loop" rule by registering the V9-lesson gates G1–G7 on the _shared_
`@oshun/content-release-gates` `ReleaseGateService` instead of a bespoke
checker. `buildV9LessonGates` composes each gate from the real platform
primitives (`gateFromManifestCheck`, `gateFromEvalScore`, and
`createGroundingGate` from `@oshun/content-quality-judge`): G1 truth (no
false/unverified claims), G2 Sophia-pin grounding, G3 teachability, G4 safety,
G5 ≥1 real _computed_ explorable, G6 adaptive difficulty in `[0,1]`, G7 a
Mnemosyne retrieval checkpoint. `evaluateV9Lesson` runs the suite and reports
`cleared`/`blocked` with the blocking gate ids; it defines the
`V9Lesson`/`V9LessonClaim`/ `V9LessonExplorable` shapes the rest of the area
gates against.

### @oshun/v9-lesson-explorables

The **real computed explorables + adaptive layer** (ledger §J.3;
`libs/v9/lesson-explorables/src`). `orbit-explorable.ts` builds a two-body
Kepler orbit by handing a separable Hamiltonian to `@kalika/symplectic`'s
`integrateCanonical` (velocity-Verlet) and reading back the trajectory plus the
engine's `analyzeEnergyBehavior` energy-drift diagnostic — `computed` is true
only when a finite multi-sample trajectory was actually produced.
`adaptive-difficulty.ts` and `retrieval-checkpoint.ts` reuse the Mnemosyne IRT
ability MLE and SM-2 scheduling; `lesson-assembly.ts` binds these into a
provenance-bound lesson and `lesson-forge.ts` routes generation through an
injectable `LessonDraftWriter` (the `CognitionGateway` boundary),
grounding/truth-checking/gating the result and failing loud with
`LessonForgeNotConfiguredError` when no writer is wired.

### @oshun/v9-hephaestus

The **explorable runtime** (`V9_ARCHITECTURE.md` §4; `libs/v9/hephaestus/src`):
typed bindings from a `ConceptNode` to a real computed kernel, each with a
demonstrably-reached success state for G4 completeness. `nyx-sky-explorable.ts`
drives the Sun's true apparent position (RA/Dec) from `@nyx/ephemeris`'s
`calculateSunPosition`/`dateToJd` across a time-travel date slider, and asserts
the _measured_ fact that the Sun's right ascension sweeps ≈360° per year over
the slider range rather than asserting it blind. `kalika-orbit-explorable.ts`
wraps `@oshun/v9-lesson-explorables`'s `buildOrbitExplorable` and validates
symplectic energy conservation (relative drift below a default `1e-3`
tolerance). It enforces the DoD that every P1 lesson ship ≥1 computed-kernel
explorable; outputs validate against `V9ExplorableSchema`.

### @oshun/v9-mnemosyne-glue

The **mastery-loop glue** (`V9_ARCHITECTURE.md` §3 stage 6;
`libs/v9/mnemosyne-glue/src`). `knowledge-trace.ts` turns each lesson concept
into an FSRS-v4 card and reviews it via `@mnemosyne/core`'s `fsrsReview`,
scheduling the next retrieval at the _forgetting frontier_ (where retrievability
decays to the target retention — the testing effect). `mastery-feedback.ts` maps
an active-recall score onto an FSRS `ReviewGrade`, projects the card to a
`MasteryLevel`, and folds it back into the Atlas mastery map that
`resolveWonder` consumes, so mastered concepts drop out of the prerequisite
frontier and the loop closes. `flow-channel.ts` measures challenge-vs-skill as
the IRT-2PL success probability and classifies the next item as
`boredom`/`flow`/`anxiety` against a default `[0.6, 0.85]` band. Pure binding
over the real engines — no new psychometrics.

### @oshun/v9-prometheus

The **lesson forge** and area orchestrator (`V9_ARCHITECTURE.md` §3;
`libs/v9/prometheus/src`). `pipeline.ts` composes Stages 0–8 end-to-end: 0
resolve (Atlas) → 1 ground/solve-first (`ground-truth.ts` pulls a _verified
skeleton_ of grounded claims + recomputed STEM values from Atlas via the
Aletheia kernel evaluator, so the LLM never invents a fact or number) → 2 plan
(`plan.ts`, HTN) → 3 write (`write.ts`, an injected `LessonWriter` realizes the
skeleton with a misconception pass) → 5 explorable (Hephaestus) → 6
assess/schedule (Mnemosyne) → 7 gate (`gates.ts`: Aletheia G1/G2/G6 + Hephaestus
G4 + pedagogy/quality/ provenance, assembled into its own `@oshun/contracts`
G1–G7 verdicts) → 8 compile/cache (`compile.ts`: C2PA hashes, generation ledger,
profile-class cache). A lesson that fails any gate is blocked; a passing one
becomes an immutable `V9LessonArtifact`. The writer is the injected Iris-loop
boundary — absent ⇒ fail loud.

### @oshun/v9-chiron

**Chiron-lite**, the P1 delivery embodiment (`V9_ARCHITECTURE.md` §7;
`libs/v9/chiron/src`). `integrity-modes.ts` implements the four tutoring modes
(`teach`/`hint`/`practice`/`do-not-complete-for-me`) with a real
academic-integrity floor — `resolveTutorAction` refuses to complete a learner's
_graded_ work and redirects to a hint. `delivery.ts` resolves the live-avatar →
live-voice → text fallback order and _discloses_ every downgrade (a learner is
never silently given a lesser experience), and `lesson-delivery.ts` binds a
gated `V9LessonArtifact` into a `LessonDeliveryPlan` fronted by the
warm-generalist persona (`persona.ts`), refusing to deliver a lesson that did
not pass its gates (`isV9LessonPublishable`). The live tutoring/avatar runtimes
are the injected boundary; the integrity, fallback, and persona logic are real.

### @oshun/v9-experience

The **consumer experience-layer view-models** (`V9_ARCHITECTURE.md` §8, L6;
`libs/v9/experience/src`) — the tested data/logic the rendered consumer screens
bind to. `wonder-front-door.ts` projects `resolveWonder` into the "ask a wonder"
entry (disambiguation candidates, scaffolding depth, and "surprise me" frontier
suggestions). `lesson-player.ts` projects a gated artifact into the grounded
explanation, the "show your sources" transparency panel (every claim with its
Sophia pins + epistemic label), the explorable canvas, and the retrieval
checkpoint — and refuses to build a player for an ungated lesson.
`mastery-map.ts` renders the personal Atlas star-map with mastery as brightness
(mastered = bright, frontier = the next star to light), and `billing-gating.ts`
layers a free-tier quota over the `@oshun/v9-governance` entitlement check.

### @oshun/v9-governance

**Platform governance** (`V9_ARCHITECTURE.md` §9, V9 Phase 0;
`libs/v9/governance/src`). `agent-family.ts` registers V9 as an agent family in
the V1 Agentic AI Studio, building the AgentRun envelope deterministically from
the real Prometheus stage graph — a visible DAG, per-stage budget inheritance,
kill switches, and a replay manifest. `gate-suite.ts` _attests_ (via
`confirmSevenGateSuite`) that the seven gates run on the shared
`@oshun/v9-lesson-gates` / `ReleaseGateService` rather than a forked checker;
`iris-loop.ts` confirms V9 adds no eighth agentic loop and files an `F2`/`A2`
gap report if the platform Iris substrate isn't yet single. `entitlements.ts` is
a real deny-by-default access decision over age band / region / subscription
tier plus cross-product grants (a V2 racing achievement unlocking an
applied-physics lesson). The platform graphs are injected boundaries; the V9
gating/grant logic is implemented here.

### @oshun/v9-cross-cutting

The **cross-cutting concerns** library (`V9_ARCHITECTURE.md` §9, P3;
`libs/v9/cross-cutting/src`). `determinism.ts` runs a forge twice and compares
artifact hashes (`skeletonHash`/`surfaceHash`/`cacheKey`/`groundTruth`),
blocking promotion on any mismatch. `anti-metric.ts` encodes V9's north star as
`durable-understanding` and throws `BannedOptimizationTargetError` if an
engagement metric (`time-on-app`, `session-length`, …) is ever set as the
optimization target. `champion-challenger.ts` ramps a challenger variant only on
a statistically significant two-proportion z-test (a real normal-CDF
Abramowitz-&-Stegun approximation) behind a min-trials guard.
`cost-discipline.ts` enforces per-stage budget caps and logs every coverage
truncation so none is silent; `accessibility.ts`, `localization.ts`, and
`lms-interop.ts` add a captions/transcript/alt-text completeness check, a
local/cloud inference-tier routing plan, and spec-conformant SCORM 1.2 / QTI 3 /
xAPI / Caliper / OneRoster / LTI 1.3 / Open Badges 3.0 exporters.

### @oshun/v9-theia

The **Phase-2 "delight & depth" layer** (`V9_ARCHITECTURE.md` §3 P2;
`libs/v9/theia/src`). `theia.ts` is the wonder-director — thread continuation
(`nextWonders` walks Atlas edges in an
`enables`→`bridges`→`specializes`→`related` priority to open the next, better
question), an emotional arc, and "surprise me" frontier picks.
`generative-widgets.ts` verifies an LLM-generated web widget compiles and
reaches its declared success state under a headless predicate before it can
clear G4/G5 — an unverified widget never ships. `manim.ts` drives a STEM
explainer-film render from a _verified_ Kalika derivation with a bounded
self-repair retry loop and C2PA stamping. `hitl.ts` is the real pause/redirect/
resume `HitlSession` state machine with per-step budget and checkpoint recovery;
`agora.ts` maps creator authoring directives onto Prometheus; `chiron-full.ts`
adds cross-session memory and _bounded, reconstruction-labeled_, Sekhmet-gated
historical personas. The avatar/emotion/render runtimes are injected boundaries.