Metis — A Curious Ape's Guide to Reality (Product Overview)

Metis (V9) turns the actual question a person has about reality — "why do we dream?", "what is a black hole made of?", "what did the first writing say?" — into a true, interactive, memorable lesson, generated on demand rather than pulled from a course catalog. It is deliberately one coherent product for curious apes, not a tool and not an LMS. Its defining engineering decision is that an LLM never gets to freestyle the facts: every factual claim is bound to a vetted source, every STEM number is recomputed from a real in-repo kernel, and the whole artifact is held behind seven gates (G1–G7) so that nothing untrue, unsafe, ungrounded, or pedagogically broken reaches a learner. That discipline is inherited from V8 — "the LLM proposes, the verifier disposes" — and retargeted from fairness to truth. The data structure that makes it concrete is the V9LessonArtifact (libs/contracts/src/v9/lesson.ts), which splits a lesson into a verified groundTruth skeleton (authoritative, immutable post-gate) and a regenerable narrative/media surface, fingerprinted as two separate hashes (skeletonHash vs surfaceHash) so the same gated truth can be re-skinned with a different teacher persona without re-verifying.

What makes V9 buildable rather than aspirational is that it is an integration architecture. The monorepo already shipped the two halves it needs — a production learning backend (the Metis domain at services/metis/ and libs/metis/) and the kernels that compute reality (@nyx/ephemeris, @kalika/cosmology) — but they were never wired into a delightful consumer product with a single "map of reality" to navigate by. V9 builds exactly that missing connective tissue: twelve packages under libs/v9/ plus the shared contract package libs/contracts/src/v9/, every one of which composes the real engines (@sophia/semantic-search BM25 retrieval, @mnemosyne/core FSRS and the knowledge-graph, @nyx/*, @kalika/*) instead of reinventing graph stores, psychometrics, or kernels. This page is the features-side companion to the architecture catalogue; the hub for the set is ../V9_features.md, and the full mechanics live in ../V9_ARCHITECTURE.md.

What ships, honestly#

The connective tissue is real and tested. All twelve libs/v9/* packages plus libs/contracts/src/v9 are implemented and exercised by 18 spec files (~160 test cases), and they compose the real substrates rather than mocking them — resolveWonder actually runs Sophia BM25 and the Mnemosyne knowledge graph; the G2 accuracy gate actually recomputes cosmology from @kalika/cosmology's Friedmann solver; the Nyx sky explorable actually calls calculateSunPosition from @nyx/ephemeris. The end-to-end Prometheus forge (libs/v9/prometheus/src/pipeline.ts) runs "ask a wonder → grounded, gated, provenance-stamped lesson" as a single async function. V9_TODOS.md carries 46 [x], 11 [~], and zero open [ ] items — no in-repo task is left unimplemented.

Three things are honest seams, not stubs. V9 owns no agent loop and runs no model itself (the repo's "no new agent loops" rule); instead it exposes typed injected boundaries that fail loud when unwired: the LLM LessonWriter is the shared Iris loop, the dense WonderEmbedder is the Nous model, the CurriculumSafetyEvaluator/SekhmetAgeGate are the Metis/Sekhmet policy seams, the ManimRenderer and HeadlessWidgetRunner are render/verify boundaries. Each throws a named error (e.g. ManimNotConfiguredError, WidgetRunnerNotConfiguredError) rather than fabricating output — refusing to fake is the opposite of a stub. Two pieces are real-but-deliberately-scoped: the default kernel registry (libs/v9/aletheia/src/kernel-evaluators.ts) computes six cosmology/physical-constant refs today (extensible via an injected KernelEvaluator), and the default G5 quality judge is a deterministic structural proxy standing in for the injected LLM-judge panel.

The genuinely external [~] work is what you would expect to be gated on the world: the rendered consumer web/mobile app and its closed beta, the provider-gated Psyche avatar face + emotion recognition (Chiron's embodiment), the Bellona Unreal cook path for in-game lessons (a P2/P3 motion), a Genie-class world model, the Agora creator-payout rails, and the multi-week efficacy study. Where a promise is planned or provider-gated, this page says so.

The product, layered — and the contracts beneath it#

V9 has five nested primitives, and unusually for a design doc, each one is a real typed contract you can point at.

• A Wonder is the atom of input: a real free-text question, entering on one of seven wonder axes (V9WonderAxisSchema: cosmos, laws, mind, meaning, deep-time, living-world, made-world, libs/contracts/src/v9/primitives.ts). Wonders are the front door, not syllabi.
• A Lesson is what V9 generates from a wonder + the learner's model — the V9LessonArtifact.
• A Thread is the chain of next, better questions one wonder unspools into (the good version of a rabbit hole), carried by the artifact's thread.nextWonders.
• The Atlas is the learner's personal, growing map of reality — the concept-cosmos they have lit up.
• The connective spine under all of it is the Atlas concept graph (ConceptNode/ConceptEdge).

Two invariants make the Atlas a map, not a bag of facts#

libs/contracts/src/v9/concept-graph.ts bakes two structural rules into the V9ConceptNodeSchema via superRefine, so a node that violates them fails to parse:

• Invariant 1 — grounding. Every fact node carries ≥1 vetted Sophia source pin (V9SophiaPinSchema, a real source id + locator + credibility in [0,1]). No ungrounded fact exists in the graph.
• Invariant 2 — computation. Every STEM fact/principle/procedure node (the disciplines in V9_STEM_DISCIPLINES = astronomy, physics, mathematics, chemistry, earth-science) carries a kernelRef instead of a stored literal. A node does not store "age of the universe = 13.8 Gyr"; it carries a callable ref like kalika:cosmology#ageTodayGyr, so the value is reproduced — never silently drifting — by v9NodeRequiresKernel(discipline, kind).

Edges unify the source graphs into nine relationship types (V9ConceptEdgeTypeSchema: prerequisite, related, part_of, generalizes, specializes, enables, conflicts, complements, bridges), where bridges is the cross-axis thread V9 adds (cosmology ↔ deep-time). Self-loops are rejected. The build-time validator path is the non-throwing checkV9ConceptNodeInvariants, which the separate Atlas validator aggregates over the whole graph — see ./atlas-wonder-resolution.md.

The Lesson artifact: a verified skeleton under a regenerable surface#

The split in lesson.ts is the whole trust model. groundTruth holds V9GroundedClaims (each: text, ≥1 pin, an epistemicStatus, and an Aletheia truth verdict where only 'true' clears G1) and V9KernelResults (a computed scalar with a tolerance the generated text must match within, plus a contentHash). The narrative is regenerable — beats, socraticTurns, and anticipated misconceptions — and crucially, every Socratic turn and misconception references its grounding claim by index: the artifact's own top-level superRefine rejects any claimRef that does not point at a real claim. So the teacher's words cannot drift off the verified skeleton. The artifact also requires ≥1 explorable (explorables: z.array(...).min(1)), an assessment, a Mnemosyne schedule, all seven gates, and a C2PA provenance bundle. isV9LessonPublishable() is true only when all seven gate verdicts pass.

The flow: ask a wonder, get a forged lesson#

forgeLesson() in libs/v9/prometheus/src/pipeline.ts runs nine stages (0–8) end to end. A lesson that fails any gate is blocked (not delivered, not cached); only a fully passing lesson is compiled into an immutable artifact.

A worked trace for "why is the night sky dark?" (Olbers' paradox): Stage 0 resolves the wonder via resolveWonder — Sophia BM25 over each node's label+aliases+discipline+axis picks candidates, an optional Nous embedder reranks 50/50 (so "the beginning of everything" can reach the Big Bang with zero lexical overlap), and Mnemosyne's identifyKnowledgeGaps plus a topologicalSort return the minimal prerequisite-first teaching set. A wonder that matches nothing throws WonderUnresolvedError rather than inventing a concept. Stage 1 assembles the grounded skeleton. Stage 5 builds the explorable: buildNyxSkyExplorable computes the Sun's true RA/Dec across a "time-travel" date slider from @nyx/ephemeris, and sets successState.reachable only after the computed samples demonstrate the Sun's RA sweeps ≈ 360°·days/yr — never asserted blind. Stage 6 turns the target concept into an FSRS card and schedules the next retrieval at the forgetting frontier. Stage 7 gates; Stage 8 compiles. Full mechanics: ./prometheus-lesson-forge.md.

The subsystems#

V9's eight named subsystems (the Promethean "gift of fire" naming) map onto the twelve packages. The detailed ownership ledger and the gate mechanics live in ./subsystem-map-and-gates.md; in brief:

Two things to read carefully against the design doc: Agora is not its own package — it lives inside @oshun/v9-theia as agora.ts. And Mnemosyne is a reuse, not a new codename: @oshun/v9-mnemosyne-glue is the lesson↔trace binding over the existing @mnemosyne/core engine.

Aletheia — the truth gate (G1/G2/G6)#

runAletheia (libs/v9/aletheia/src/aletheia.ts) runs three gates in parallel. G1 grounding checks every claim has ≥1 pin and a true verdict. G2 accuracy is the part with no home in Sophia: evaluateAccuracy recomputes each asserted STEM value through the real kernel registry and blocks on either an unknown kernel ref ("you cannot ship a number you cannot reproduce") or a relative-error mismatch beyond tolerance. The registry binds, e.g., kalika:cosmology#ageTodayGyr to ageTodayGyr(PLANCK_2018_COSMOLOGY) and nyx:constants#speedOfLight to SPEED_OF_LIGHT — actual in-repo computations. G6 safety (safety-gate.ts) requires an epistemic-status label on every claim, evaluates the Metis curriculum-safety policy and the Sekhmet age gate, and fails loud for a high-stakes discipline (religion, psychology, neuroscience) that has no policy wired or no human-review checkpoint recorded — it routes to editorial rather than auto-publishing. The remaining gates are composed in libs/v9/prometheus/src/gates.ts: G3 pedagogy (prerequisite + misconception + flow-band coverage), G4 completeness (the Hephaestus explorable DoD), G5 quality, G7 provenance. See ./governance-and-boundaries.md.

Chiron and Hephaestus — the teacher and the workshop#

Chiron's integrity modes are the academic-honesty floor, and they are real policy, not vibes. resolveTutorAction (integrity-modes.ts) enforces that 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 — a tutor must not do the learner's assessed work. The P1 persona is a single, disclosed synthetic teacher (WARM_GENERALIST_PERSONA, a Hathor personality bound to a Psyche voice ref, synthetic: true with a disclosureLabel); full embodied face, cross-session memory, and grounded historical personas are P2 and partly provider-gated. Hephaestus enforces that every P1 lesson ships ≥1 computed-kernel explorable whose success state was demonstrably reached (evaluateExplorableDoD → explorableDoDToGateVerdict = G4); a generated-but-unverified explorable never ships. Both are covered in ./chiron-and-hephaestus.md.

Threads and the mastery loop#

Theia turns every answer into the next question. nextWonders walks the Atlas edges in priority order (enables → bridges → specializes → related); orchestrateEmotionalArc labels lesson beats along the awe → curiosity → understanding → anticipation arc; surpriseMe surfaces the highest-readiness unexplored concept (the one whose prerequisites are most mastered). The mastery loop reuses real FSRS-v4: reviewConcept delegates to @mnemosyne/core's fsrsReview, atForgettingFrontier schedules retrieval right as recall gets hard (the testing effect), and conceptMastery projects a card's stability onto a MasteryLevel that feeds back into Atlas wonder-scoping. The personal star map (buildPersonalAtlasMap) renders mastery as brightness and the frontier as inviting dark. See ./threads-and-mastery-loop.md.

The braid, the commons, and the films#

The "soulful braid" places the scientific beside the human; Agora lets a creator steer Prometheus. validateJourneySpec rejects an over-deep journey for a kids audience; toPrometheusDirectives maps a creator's tone/depth/audience onto forge directives (depth deep → 12 concepts, a slightly harder flow target); buildShareableObject mints the free-tier growth object. On-demand explainer films go through renderExplainerFilm (theia/manim.ts), which refuses an empty (unverified) derivation, runs a bounded self-repair retry loop, and C2PA-stamps a success. See ./braid-commons-and-films.md.

Edge cases, failure modes, and configuration#

V9's correctness story is mostly about what it refuses to do:

• Unresolvable wonders fail loud. resolveWonder throws WonderUnresolvedError rather than inventing a concept; the front-door view-model (buildWonderFrontDoor) catches it and returns unresolved: true so the UI can ask for a rephrase instead of hallucinating.
• Unwired seams fail loud. Every injected boundary throws a named error when absent (the Iris writer, the Manim renderer, the widget runner). The product never silently degrades a generation into a fabrication.
• Gates block, they don't warn. forgeLesson returns { blocked: true, blockedGateIds, gates, aletheia } with no artifact when any gate fails; the contract's own isV9LessonPublishable must agree with the gate sum, and a disagreement throws defensively.
• Determinism is verified, not assumed. verifyForgeDeterminism (cross-cutting/determinism.ts) runs a forge twice and assertDeterministic blocks promotion on any field mismatch — same (inputs, seed) ⇒ same artifact + hashes, which is both a provenance guarantee and the cost lever (gate once, serve from the profile-class cache many times).
• No silent overspend. CostLedger.spend refuses (returns false) an attempt that would exceed a per-stage cap or the inherited ceiling, and logTruncation records any coverage drop explicitly.
• The north star cannot be engagement. assertNorthStarTarget (cross-cutting/anti-metric.ts) throws BannedOptimizationTargetError if time-on-app, session-length, watch-time, etc. is ever set as the optimization target; the instrumented metric is computeDurableUnderstanding — concepts still held at ≥ floor mastery after a retention delay.

Configuration is mostly the set of injected dependencies on ForgeLessonInput: the writer and misconceptionAnticipator (Iris), the embedder (Nous), the explorableBuilder (Hephaestus), the qualityJudge and safetyOptions (the G5/G6 boundaries), the caller-supplied clock (nowUnixMs, no fabricated time), the seed, the learnerProfileClass (lessons cache by profile class, not learner id, so a popular lesson is gated once), and optional cache/ledger.

How it connects to the rest of Oshun#

V9 is a consumer of the platform, by design (the non-goals are explicit in ../V9_features.md): it adds no new agent loop (confirmConsumesSharedLoop files a Phase-A2 gap rather than papering over an incomplete platform), adds no new asset providers, runs under the V1 identity / billing / governance plane, and inherits the V7 Sekhmet safety regime. Access is a deny-by-default decision over age/region/tier with cross-product grants — applyCrossProductGrant turns a V2 racing podium into the applied-physics lesson, a meditation streak into the neuroscience-of-attention thread, a V8 detective case into the logic-and-deduction lesson (governance/entitlements.ts). The kernels and content factory are reused wholesale; the only genuinely net-new structures are the three this page is built around — the Atlas graph, the Hephaestus explorable, and the Lesson artifact.

Related pages#

• ./subsystem-map-and-gates.md — the full ownership ledger and the seven-gate mechanics
• ./atlas-wonder-resolution.md — the concept graph, invariants, and free-text wonder resolution
• ./prometheus-lesson-forge.md — the nine forge stages, end to end
• ./chiron-and-hephaestus.md — the embodied teacher and the explorable workshop
• ./threads-and-mastery-loop.md — Theia threads, the emotional arc, and FSRS mastery
• ./braid-commons-and-films.md — the science↔human braid, Agora, and explainer films
• ./governance-and-boundaries.md — entitlements, the anti-metric, cost, determinism, and the non-goals
• Hub: ../V9_features.md · Architecture spec: ../V9_ARCHITECTURE.md · Product thesis: ../V9_PRODUCT_ANALYSIS.md