Metis · Architecture

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

A focused page within the Metis Architecture documentation. The full map and every sibling page live in the Architecture hub.

11sections14 minread1diagram
← Back to the Architecture hubMarkdown source
On this page

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.

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 §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.

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 and ./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.

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.

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.

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.

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 claimRefs 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.

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.

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.

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.

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.