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
factnode 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/procedurenode (the disciplines inV9_STEM_DISCIPLINES=astronomy, physics, mathematics, chemistry, earth-science) carries akernelRefinstead of a stored literal. A node does not store "age of the universe = 13.8 Gyr"; it carries a callable ref likekalika:cosmology#ageTodayGyr, so the value is reproduced — never silently drifting — byv9NodeRequiresKernel(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.
This picture is wider than it can be shown here. Move across it, or read it as text.
Drawn from its Mermaid source.
As text
Parts: - Wonder (free text) - Stage 0 — resolve Atlas: BM25 + dense rerank + Mnemosyne prereq frontier - Stage 1 — ground / solve-first verified groundTruth skeleton - Stage 2 — plan (HTN) - Stage 3 — write (injected Iris writer; fail-loud) - Stage 5 — explorable Hephaestus: Nyx sky / Kalika sim - Stage 6 — assess & schedule Mnemosyne FSRS retrieval checkpoint - Stage 7 — gate G1..G7 - BLOCKED regenerate-with-direction - Stage 8 — compile & cache C2PA hashes, ledger, profile-class cache - V9LessonArtifact Connections: - Wonder (free text) to Stage 0 — resolve Atlas: BM25 + dense rerank + Mnemosyne prereq frontier - Stage 0 — resolve Atlas: BM25 + dense rerank + Mnemosyne prereq frontier to Stage 1 — ground / solve-first verified groundTruth skeleton - Stage 1 — ground / solve-first verified groundTruth skeleton to Stage 2 — plan (HTN) - Stage 2 — plan (HTN) to Stage 3 — write (injected Iris writer; fail-loud) - Stage 3 — write (injected Iris writer; fail-loud) to Stage 5 — explorable Hephaestus: Nyx sky / Kalika sim - Stage 5 — explorable Hephaestus: Nyx sky / Kalika sim to Stage 6 — assess & schedule Mnemosyne FSRS retrieval checkpoint - Stage 6 — assess & schedule Mnemosyne FSRS retrieval checkpoint to Stage 7 — gate G1..G7 - Stage 7 — gate G1..G7 to BLOCKED regenerate-with-direction: any fail - Stage 7 — gate G1..G7 to Stage 8 — compile & cache C2PA hashes, ledger, profile-class cache: all pass - Stage 8 — compile & cache C2PA hashes, ledger, profile-class cache to V9LessonArtifact
Show source
flowchart TD
W["Wonder (free text)"] --> S0["Stage 0 — resolve<br/>Atlas: BM25 + dense rerank<br/>+ Mnemosyne prereq frontier"]
S0 --> S1["Stage 1 — ground / solve-first<br/>verified groundTruth skeleton"]
S1 --> S2["Stage 2 — plan (HTN)"]
S2 --> S3["Stage 3 — write<br/>(injected Iris writer; fail-loud)"]
S3 --> S5["Stage 5 — explorable<br/>Hephaestus: Nyx sky / Kalika sim"]
S5 --> S6["Stage 6 — assess & schedule<br/>Mnemosyne FSRS retrieval checkpoint"]
S6 --> G["Stage 7 — gate G1..G7"]
G -->|any fail| B["BLOCKED<br/>regenerate-with-direction"]
G -->|all pass| S8["Stage 8 — compile & cache<br/>C2PA hashes, ledger, profile-class cache"]
S8 --> A["V9LessonArtifact"]
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:
| Subsystem | Package(s) | Owns |
|---|---|---|
| Atlas | @oshun/v9-atlas |
Unified concept graph; free-text wonder → mastery-scoped frontier |
| Prometheus | @oshun/v9-prometheus, @oshun/v9-lesson-explorables |
The 9-stage lesson forge; explorable selection; gate composition |
| Aletheia | @oshun/v9-aletheia |
The truth gate: G1 grounding, G2 accuracy, G6 safety |
| Chiron | @oshun/v9-chiron |
Teacher persona; the four tutoring integrity modes |
| Hephaestus | @oshun/v9-hephaestus |
Explorable runtime; the computed-kernel DoD → G4 |
| Mnemosyne | @oshun/v9-mnemosyne-glue |
FSRS knowledge-trace, forgetting-frontier scheduling, flow tuning |
| Theia | @oshun/v9-theia |
Thread continuation, emotional arc, "surprise me", Manim, Agora |
| Agora | @oshun/v9-theia (agora.ts) |
Creator authoring → forge directives; shareable social objects |
| (supporting) | @oshun/v9-governance, @oshun/v9-experience, @oshun/v9-cross-cutting, @oshun/v9-lesson-gates |
entitlements, view-models, the cross-cutting DoD, gate suite |
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.
resolveWonderthrowsWonderUnresolvedErrorrather than inventing a concept; the front-door view-model (buildWonderFrontDoor) catches it and returnsunresolved: trueso 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.
forgeLessonreturns{ blocked: true, blockedGateIds, gates, aletheia }with noartifactwhen any gate fails; the contract's ownisV9LessonPublishablemust agree with the gate sum, and a disagreement throws defensively. - Determinism is verified, not assumed.
verifyForgeDeterminism(cross-cutting/determinism.ts) runs a forge twice andassertDeterministicblocks 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.spendrefuses (returnsfalse) an attempt that would exceed a per-stage cap or the inherited ceiling, andlogTruncationrecords any coverage drop explicitly. - The north star cannot be engagement.
assertNorthStarTarget(cross-cutting/anti-metric.ts) throwsBannedOptimizationTargetErroriftime-on-app,session-length,watch-time, etc. is ever set as the optimization target; the instrumented metric iscomputeDurableUnderstanding— 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