# 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](../V9_features.md), and the full mechanics live in
[../V9_ARCHITECTURE.md](../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](./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
`V9GroundedClaim`s (each: text, ≥1 pin, an `epistemicStatus`, and an Aletheia
`truth` verdict where only `'true'` clears G1) and `V9KernelResult`s (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.

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