# V9 — Architecture (Metis: A Curious Ape's Guide to Reality) Status: technical design that realizes `V9_features.md` under the constraints in `V9_PRODUCT_ANALYSIS.md` and the external grounding in `V9_SOTA_RESEARCH.md`. Date: 2026-06-13. Audience: architecture, generative-AI, learning-science, science-kernel, gameplay, platform, and trust-and-safety leads. V9 is an **integration architecture**: it adds three genuinely-new pieces (the **Atlas** knowledge graph, the **Hephaestus** explorable runtime, and the consumer experience layer) and otherwise _composes and binds_ existing Oshun domains behind seven release gates. Every "build on X" below cites the real in-repo surface; absence-of-implementation gaps are in `V9_GAP_ANALYSIS.md`. --- > **This architecture reference has been decomposed into focused pages under > [`architecture/`](./architecture/README.md).** This file remains the canonical > hub (every section heading is preserved, so existing `arch§"…"` anchors keep > resolving); the in-depth, code-grounded companion pages live under > [`architecture/`](./architecture/README.md). Start at the > [architecture page index](./architecture/README.md). The product feature map > is in [`V9_features.md`](./V9_features.md) / > [`features/`](./features/README.md). ## 1. The six-layer reuse stack V9 inherits the target SOTA architecture from `AGENTIC_CONTENT_GENERATION_SOTA_REPORT_2026-06-12.md` §5 (the platform's own recommended stack) and specializes it for learning. One stack, six layers; V9 is a consumer of all six. ``` L6 Delivery & Experience Consumer web/mobile app; Nyx WebGL + Kalika WASM in the browser; Chiron embodied teacher (Psyche); on-demand explainer films; the personal Atlas map. (NO Bellona/UE dependency for P1 — see §8.) L5 Governance plane V1 Isis control plane + Agentic AI Studio: AgentRun envelopes, budget inheritance, approval gates, kill switches, ProvenanceBundle + C2PA, immutable generation ledger. The seven gates (§5) are enforced here. L4 Production orchestration Prometheus (lesson forge) on Yemaya HTN-planned dynamic pipelines with mid-pipeline HITL; failure recovery; cost caps; determinism + caching. L3 Capability tools Domain tool servers on the shared catalog (MCP-shaped): sophia.ground, nyx.ephemeris/render, kalika.cas/solve, mnemosyne.schedule/trace, isis.generate.*, psyche.speak, hathor.persona, euterpe.score, themis/sekhmet.adjudicate, approval.request, handoff. L2 Agent runtime Iris: THE agentic loop (tool-call iteration with max-iteration guard), normalized cross-provider tool protocol, sub-agent spawn with budget inheritance, memory tiers. V9 spawns NO new agent loop. L1 Model plane Iris model-orchestrator + Nous: provider gateway, routing, fallback, caching, cost metering; Nous local inference for privacy/cost where feasible. ``` Design rules that make this SOTA rather than merely consolidated (inherited from the platform report and specialized): **everything generated passes mandatory grounding + accuracy + policy + canon gates before a human gate where required; agents are products with visible DAGs, cost ledgers, and replay; determinism where it matters (a lesson is a reproducible artifact); champion-challenger everything.** --- ## 2. The Atlas of Reality (the knowledge spine — NEW) The one large new data structure. Atlas is the unified knowledge graph that makes "start from a wonder, pull the thread" possible. It is assembled, not authored from scratch, by unifying surfaces that already exist: - **Metis concept graph** — directed graph of educational concepts with node types (topic/skill/fact/procedure/principle) and edge types (prerequisite, related, part_of, generalizes, specializes, enables, conflicts, complements), plus validation/repair (`services/metis/src/metis/services/source_concept_graph_helpers.py`). - **Sophia knowledge graph** — 15 entity types, 27 relationship types, traversal - shortest-path, citation-credibility scoring (`libs/sophia/knowledge-graph/`). - **Mnemosyne prerequisite reasoning** — knowledge graphs with prerequisite closure and adaptive sequencing (`libs/mnemosyne/core`, `.../knowledge-graph`). - **Domain data** as grounded leaves — Nyx catalogs/ephemeris, Kalika physics constants/kernels, Nisaba canonical references, Demeter plant DB, etc. ### 2.1 Atlas node & edge contract ``` ConceptNode { id: ConceptId // stable, content-addressed label, aka[] // "Olbers' paradox", aliases for wonder-matching wonderAxis: cosmos|laws|mind|meaning|deep-time|living-world|made-world discipline: // Metis taxonomy placement (headline vs scaffolding) kind: topic|skill|fact|procedure|principle groundingPins: SophiaPin[] // ≥1 vetted source per fact node (G1 invariant) kernelRefs: { nyx?, kalika?, ... } // a node whose values are COMPUTED, not asserted epistemicStatus: established|contested|one-tradition|frontier safetyPolicyRef: MetisCurriculumPolicyId } ConceptEdge { from, to, type: prerequisite|related|enables|generalizes|...|bridges, weight } ``` Two design invariants: 1. **Every fact node carries ≥1 grounding pin** (no ungrounded node may exist). 2. **STEM nodes carry kernelRefs** — the node does not _store_ "the age of the universe = 13.8 Gyr"; it references the computation/source that yields it, so the value is reproducible and current. ### 2.2 Wonder resolution A learner's free-text wonder → embedding (Nous) → candidate ConceptNodes (Sophia hybrid retrieval) → disambiguation → the node's **prerequisite closure** filtered by the learner's mastery state (Mnemosyne). Output: the minimal concept set to teach now (cognitive-load discipline, `V9_SOTA_RESEARCH.md` §5). --- ## 3. The lesson-generation pipeline (Prometheus) Solve-first, grounded, gated — the V8 "propose/dispose" discipline retargeted from _fair mystery_ to _true explanation_. Runs as a Yemaya HTN-planned pipeline on the Iris runtime, under the V1 governance envelope. Stages (each emits a durable, replayable artifact): | Stage | Owner | Action | Reuses | | --------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | | **0. Resolve** | Atlas + Theia | Wonder → concept set + learner-scoped prerequisite frontier; decide answer/scaffold/thread. | Metis concept-graph, Sophia retrieval, Mnemosyne mastery state | | **1. Ground (solve-first)** | Aletheia | Pull the verified ground truth: grounding pins from Sophia for every claim; **compute** every STEM value via the kernels (Nyx ephemeris/render params, Kalika CAS/physics). This is the authoritative skeleton. | `libs/sophia/*`, `libs/nyx/ephemeris`, `libs/kalika/cas-engine` | | **2. Plan** | Prometheus (Yemaya planner) | HTN plan: narrative beats, the explorable(s), the assessment, the Chiron persona, the score brief. | `libs/yemaya/agents/planning`, `libs/yemaya/autonomous-pipelines` | | **3. Write** | Prometheus (Hathor + Iris) | LLM realizes the skeleton into Socratic prose/dialogue — **constrained to the grounded claims**; misconception-anticipation pass. | `libs/hathor/llm-npc`, `libs/iris/conversation-*` | | **4. Realize media** | Prometheus (Isis + Euterpe + Psyche) | Generate visuals/diagrams (Isis), the score (Euterpe), the Chiron face/voice (Psyche); for math/physics, compile a precise Manim-style animation from the _verified_ Kalika derivation. | `libs/isis/*`, `DOMAINS/euterpe`, `DOMAINS/psyche` | | **5. Build explorable** | Hephaestus | Bind a computed kernel (Nyx sky / Kalika sim) or generate a verified interactive widget; define its success state. | §4 | | **6. Assess & schedule** | Mnemosyne | Build the retrieval checkpoint + spaced schedule; register concepts in the learner's knowledge-trace. | `libs/mnemosyne/core`, Metis assessment | | **7. Gate** | Governance plane | Run G1–G7 (§5); on failure, regenerate-with-direction (mid-pipeline HITL) or route to human review for high-stakes disciplines. | V1 Agentic AI Studio, Yemaya HITL, Sekhmet | | **8. Compile & cache** | Prometheus | Emit the `Lesson` artifact (§6), C2PA-stamp it, write the generation-ledger entry, cache by `(conceptSet, learnerProfileClass, seed)`. | V3 C2PA, V1 generation ledger | | **9. Deliver** | L6 experience | Stream the lesson into the consumer app; Chiron runs live; telemetry + evals feed champion-challenger. | §8 | **Cost discipline:** Stage 8's cache key is _learner-profile-class_, not learner-id — a popular lesson ("how do black holes work?") is generated and gated once per profile class, served many times. Determinism (same inputs + seed → same artifact + hashes) is both a provenance and a cost lever. --- ## 4. The Hephaestus explorable runtime (NEW) The second new piece. Three explorable kinds, in increasing generative risk: 1. **Computed-kernel explorables (P1, highest trust).** A typed binding between a ConceptNode and a real kernel exposed to the browser: - **Nyx** — WebGL planetarium (`libs/nyx/renderer-*`, 10M+ stars at 60fps), ephemeris (`libs/nyx/ephemeris`, VSOP87/ELP), "time-travel," exoplanets. A cosmology slider drives _real_ sky state. - **Kalika** — the Rust CAS/numerical kernels compiled to **WASM** (`libs/kalika/cas-engine` has a `wasm-bindgen` build) + reactive notebooks (`libs/kalika/notebooks`): a physics parameter recomputes the actual solution, not an animation. These are correct by construction (PhET-grade), and are V9's P1 default. 2. **Generative-widget explorables (P1/P2).** For ideas without a kernel, Prometheus generates a runnable web widget (the Claude-Artifacts primitive, `V9_SOTA_RESEARCH.md` §4), then **verifies** it: it must compile, hit its defined success state under a headless check, and pass an accuracy review before G4/G5. Generated-but-unverified widgets never ship. 3. **Game-bridge explorables (P2/P3).** Existing Oshun games as labs — e.g., the **V2** racing mode's vehicle dynamics become an applied-physics surface; a strategy loop becomes game theory. This path depends on the engine bridge (Bellona cook path), which is currently types-only (`AGENTIC_CONTENT_GENERATION_SOTA_REPORT_2026-06-12.md` §2.4), so it is deferred and rides the same fix V8 needs — it does **not** block P1. Every explorable declares: `{ conceptId, kind, params[], successState, groundingOrKernelRef, provenance }`. --- ## 5. The seven gates (governance-plane enforcement) Enforced at Stage 7 by the V1 Agentic AI Studio governance plane; modeled on V8's seven-gate discipline. Each gate is an eval suite in the platform's single **content release gate** (the `AGENTIC_CONTENT_GENERATION_SOTA_REPORT` D3 consolidation target), not a bespoke per-product checker. | Gate | Mechanism | Fail action | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | | **G1 Grounding** | Every claim node has ≥1 Sophia pin; ungrounded → block. | Re-ground or drop claim | | **G2 Accuracy** | STEM values recomputed and matched to kernel output; Sophia-grounded contradiction pass. | Regenerate with corrected ground truth | | **G3 Pedagogy** | Prerequisite-coverage check (Atlas); cognitive-load heuristic; misconception coverage; difficulty in flow band (Mnemosyne). | Re-scope / re-plan | | **G4 Completeness** | Every exercise/explorable has a reachable success state (automated solver, the V8 "Theseus" pattern applied to learning tasks). | Fix or remove task | | **G5 Quality** | LLM-as-judge panel (clarity/narrative/beauty/engagement), aggregated; correlates with the Yemaya 76-validator suite. | Regenerate-with-direction | | **G6 Safety** | Sekhmet age/sensitivity + Metis per-discipline curriculum safety policy; epistemic-status labels present. | Block / escalate to human | | **G7 Provenance** | C2PA signatures on all assets; seed-reproducibility check; ledger entry. | Block until signed | High-stakes disciplines (religion, psychology, health-adjacent) additionally require a human review checkpoint per the Metis curriculum safety policy — the gate routes to the Studio editorial lifecycle rather than auto-publishing. ### 5.1 Aletheia is a gate, not a grounding engine G1/G2 (owned by **Aletheia**) are deliberately a **thin policy layer over capabilities that already exist**, not a new grounding system: - **G1** calls **Sophia** (`libs/sophia/*`) to bind every claim to a vetted source pin. Sophia already does retrieval, citation, the knowledge graph, and faithfulness evaluation — Aletheia **reuses** it and must **not** reimplement RAG. - **G2** recomputes every STEM value via the **Nyx/Kalika** kernels and checks the generated text matches. This is the one part with no home in Sophia (Sophia retrieves _text_; it does not compute an ephemeris or solve an ODE). Aletheia itself owns only the **gate semantics**: the "every claim node must have ≥1 grounding pin" invariant, the pass/fail rule, the epistemic-status labelling, and the regenerate-with-direction routing on failure. The division of labour: **textual grounding → Sophia; numeric/derivational accuracy → Nyx/Kalika; the "must pass or block" policy → Aletheia.** This mirrors V8 exactly — its **Minos** gate _enforced_ the fairness validators, it did not rebuild them — and it is the concrete answer to the platform report's finding **F6** (`AGENTIC_CONTENT_GENERATION_SOTA_REPORT_2026-06-12.md`: "grounding exists but is not a mandatory pass on generated content"). Aletheia is the act of making Sophia's existing rail a **mandatory pass**, nothing more. --- ## 6. The Lesson artifact (delivery contract) The compiled, cacheable, provenance-stamped output of the pipeline: ``` Lesson { id, seed, conceptSet: ConceptId[], learnerProfileClass groundTruth: { claims: GroundedClaim[], computedValues: KernelResult[] } // the verified skeleton narrative: { beats[], socraticTurns[], misconceptions[] } mentor: ChironPersonaRef // voice/face/personality binding media: { visuals: IsisAssetRef[], score: EuterpeRef, film?: ExplainerFilmRef } explorables: Explorable[] // ≥1 required (DoD) assessment: { retrievalCheck, masterySignal } schedule: MnemosyneSchedule gates: { G1..G7: pass, evidence[] } provenance: C2PABundle thread: { nextWonders: ConceptId[] } // Theia's continuation } ``` `groundTruth` is authoritative and immutable post-gate; `narrative`/`media` are regenerable realizations of it. This is the same separation V8 uses (verified symbolic skeleton vs. generated surface), which is what makes the artifact both trustworthy and cheap to re-skin (e.g., a different Chiron persona over the same verified content). --- ## 7. Subsystem → existing-code map | Subsystem | New code | Builds on (real in-repo surface) | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Atlas** | Graph unifier + wonder-resolver + personal-map renderer | `services/metis/.../source_concept_graph_helpers.py`, `libs/sophia/knowledge-graph`, `libs/mnemosyne/core`, Nyx/Kalika/Nisaba data | | **Prometheus** | Lesson HTN templates + the realize-skeleton constraint layer | `libs/yemaya/{agents,autonomous-pipelines,orchestration}`, `libs/iris/agents-core`, `services/metis/.../source_generation_service.py` | | **Aletheia** | The grounding+accuracy **gate** — a thin policy over Sophia + the kernels, **not** a new RAG/grounding engine (binds claims to Sophia pins, recomputes STEM values, applies pass/fail + regenerate; see §5.1) | `libs/sophia/*`, `libs/nyx/ephemeris`, `libs/kalika/cas-engine`, V3 C2PA | | **Chiron** | Teacher-persona system + integrity-mode dialogue + cross-session memory glue | `DOMAINS/psyche` (avatar/voice/Conductor), `libs/hathor/llm-npc`, `services/metis/.../tutoring_service.py` (live-voice already real), `libs/isis`, `DOMAINS/euterpe` | | **Hephaestus** | Kernel→browser bindings, generative-widget verifier, game-bridge adapters | `libs/nyx/renderer-*`, `libs/kalika/{cas-engine(wasm),notebooks}`, V2–V8 substrates | | **Mnemosyne** | Lesson↔trace glue (mostly reuse) | `libs/mnemosyne/core` (FSRS/SM-2, BKT/DKT, IRT/CAT), `services/metis/.../adaptive_*`, assessment | | **Theia** | Wonder director + emotional-arc + science↔human braid | `services/metis/.../analytics/discovery`, game hooks, `libs/meditation/*` | | **Agora** | Creator authoring + publish/distribute glue | V7 Mawu distribution, `services/metis` authoring, Sekhmet | | **Experience (L6)** | The consumer web/mobile app | `apps/metis/{web,mobile}` (currently instructor/admin-shaped — the largest net-new build) | --- ## 8. Delivery & the deliberate non-dependency on Bellona V9's P1 experience is **web-first and does not depend on the Unreal cook path.** The two heaviest "wow" surfaces are already web-native: - **Nyx** ships a WebGL/Three.js renderer and TS client — the live cosmos runs in the browser. - **Kalika** ships a `wasm-bindgen` build of its Rust kernels — computed physics runs in the browser. Embodied teaching (Chiron) runs through Psyche's real-time avatar/voice runtime, which the Metis live-voice tutoring service already provisions. The model plane (Iris + Nous) handles routing, fallback, caching, and — where feasible — **local inference (Nous)** for cost and privacy. The **game-bridge explorables** (learn-by-playing inside V2–V8) are the one surface that needs the Bellona headless-cook path (`AGENTIC_CONTENT_GENERATION_SOTA_REPORT_2026-06-12.md` §2.4, §6 A1). That work is shared with V8 and is sequenced as a **P2/P3** motion; V9's P1 ships fully without it. This is a deliberate scoping decision to avoid inheriting the portfolio's single biggest blocker. --- ## 9. Cross-cutting concerns - **Governance:** every lesson generation is an AgentRun under the V1 Agentic AI Studio envelope (budget inheritance, kill switches, anomaly quarantine, visible DAG, replay). V9 registers as an agent family; it does not run ungoverned. - **Safety & age-gating:** Sekhmet (V7) + the Metis per-discipline curriculum safety policy are the floor; the shared block/mute and age/region attributes come from the single Oshun account profile graph (`V_SERIES_PLATFORM_CONSOLIDATION.md` §"Problem 2"). - **Provenance:** C2PA on every generated asset (V3's "C2PA on every export" discipline), seed-reproducible lessons, immutable generation ledger. - **Determinism + caching:** the (conceptSet, profileClass, seed) cache + the verified-skeleton/regenerable-surface split keep per-lesson cost bounded. - **Localization & accessibility:** Metis lecture packages already do multi-language dubbing/subtitles and SCORM; V9 reuses that for lesson localization, and the meditation offline engine is the model for offline/low- bandwidth support. - **Identity & entitlements:** one Oshun account; cross-product grants (a V2 racing achievement → the physics lesson; a meditation streak → the neuroscience thread) flow through the shared entitlement graph. --- ## 10. What is genuinely new vs. composed **New (V9 must build):** the Atlas unified knowledge graph + wonder-resolver; the Hephaestus explorable runtime (kernel bindings + generative-widget verifier); the consumer experience layer (`apps/metis/{web,mobile}` rebuilt consumer-first); the Theia wonder-director; the lesson HTN templates and the "realize the verified skeleton" constraint layer in Prometheus; the seven-gate suite specialized for learning. **Composed (V9 reuses, does not rebuild):** the Metis education backend; Nyx; Kalika; Sophia; Nous; Mnemosyne; Isis; Yemaya; Hathor; Psyche; Euterpe; the Iris runtime; the V1 governance plane; V3 C2PA; V7 Sekhmet; the meditation engine; the V2–V8 game substrates. The ratio is the whole point: V9 is ~20% new connective tissue over ~80% existing, verified capability — which is why it is a _productization_ version, not a from-scratch build. See `V9_DEPENDENCIES.md` for the full reuse DAG and `V9_GAP_ANALYSIS.md` for the file-level evidence of what is real today.