Eve library

V9 — Systems Deep Dive

Guide

Revision 1

On this page

The libs/v9/ area: twelve Nx libraries that build Metis, the "ask a wonder → get a grounded, gated, explorable lesson" learning product — a solve-first lesson forge that composes the platform's existing real engines (Sophia retrieval, Mnemosyne psychometrics, Nyx/Kalika physics) rather than reinventing them.

What this area is#

V9 (codename Metis, the "Curious Ape's Guide to Reality") is a consumer learning product whose entry point is a single free-text wonder — a question — rather than a course catalog. Every library in libs/v9/ is a TypeScript Nx library tagged scope:v9, layer:domain, type:lib, and each carries a long description in its package.json that cites the section of V9_ARCHITECTURE.md it implements. The defining architectural stance, repeated in nearly every module header, is compose the real engines; add no new loop, no new physics, no new psychometrics, no new retrieval — V9's net-new code is the spine, the gates, and the orchestration, not the kernels.

The area decomposes into a few tiers. At the bottom sits the knowledge spine and the gate substrate: @oshun/v9-atlas (a unified ConceptNode/ConceptEdge graph merging the Metis/Sophia/Mnemosyne graphs) and @oshun/v9-lesson-gates (the seven-gate G1–G7 release suite built on the shared @oshun/content-release-gates). On top of that sit the composed evaluators: @oshun/v9-aletheia (the truth gate — grounding/accuracy/safety), @oshun/v9-lesson-explorables and @oshun/v9-hephaestus (real computed explorables from the Kalika symplectic integrator and the Nyx ephemeris), and @oshun/v9-mnemosyne-glue (the FSRS/IRT mastery loop). @oshun/v9-prometheus is the orchestrator — the Stage 0–8 HTN forge that wires all of the above into a single provenance-stamped V9LessonArtifact. Finally the delivery and platform tiers: @oshun/v9-chiron (tutor delivery + integrity modes), @oshun/v9-experience (consumer view-models), @oshun/v9-governance (agent-family registration + entitlements), @oshun/v9-cross-cutting (determinism / cost / accessibility / LMS interop), and @oshun/v9-theia (the Phase-2 "delight & depth" layer).

A recurring honest pattern runs through the area: the logic is real, but the model/runtime boundaries (the LLM writer, the live avatar/voice runtime, the Manim renderer, the dense embedder) are injected seams that fail loud when unconfigured rather than fabricating output. For example @oshun/v9-lesson-explorables throws LessonForgeNotConfiguredError when no writer is wired, and @oshun/v9-atlas throws WonderUnresolvedError rather than inventing a concept. None of the twelve projects is an empty scaffold — each has a populated src/ and a *.spec.ts suite (the test counts range from a handful in the smaller leaf libs to ~20 in aletheia and theia).

How it fits the wider system#

These libraries depend outward on the platform's shared engines and contracts, never the reverse. The shared dependencies that show up across the area are @oshun/contracts (the V9* schemas — V9ConceptNode, V9Lesson, V9LessonArtifact, V9GateVerdict, etc.), @mnemosyne/core (FSRS-v4 / IRT-2PL / KnowledgeGraph), @sophia/semantic-search (BM25), @nyx/ephemeris + @nyx/constants, @kalika/cosmology + @kalika/symplectic, and the shared @oshun/content-release-gates + @oshun/content-quality-judge gate framework.

Internally the v9 libraries form a dependency DAG that @oshun/v9-prometheus sits at the top of: Prometheus imports v9-aletheia, v9-atlas, v9-hephaestus, v9-lesson-explorables, and v9-mnemosyne-glue to run its pipeline; v9-experience composes v9-atlas and v9-governance (plus the @mnemosyne/core mastery types) into screen view-models; v9-theia composes v9-atlas plus the @mnemosyne/core engine for the P2 features, re-implementing the Chiron logic internally in chiron-full.ts rather than importing v9-chiron (v9-chiron and v9-mnemosyne-glue are declared in its package.json but not currently imported). The consumer app (the L6 client surface) binds to the tested view-models in v9-experience; institutional consumers reach a finished lesson through the SCORM/QTI/xAPI/LTI exporters in v9-cross-cutting. Walk the "used by" edges on any node below to see the exact consumers.

Entity reference#

@oshun/v9-atlas#

The unified knowledge spine (V9_ARCHITECTURE.md §2; libs/v9/atlas/src). It merges the Metis concept graph, the Sophia KG, and the Mnemosyne prerequisite graphs into one content-addressed ConceptNode/ConceptEdge store (atlas-store.ts), with each node parsed through V9ConceptNodeSchema at insert so an ungrounded fact node or a kernel-less STEM node is rejected at the door (the two Atlas invariants). Prerequisite reasoning is delegated to the real Mnemosyne KnowledgeGraph rather than reimplemented, and wonder-resolution.ts turns a free-text wonder into a mastery-scoped prerequisite frontier via Sophia BM25 (createBM25LexicalIndex) plus Mnemosyne identifyKnowledgeGaps, failing loud with WonderUnresolvedError when nothing matches. The graph-unifier.ts collapses same-named concepts to one cn:<sha256> id and honestly reports invariant-violating merges in a skipped list rather than fabricating grounding.

@oshun/v9-aletheia#

The truth gate (V9_ARCHITECTURE.md §5.1; libs/v9/aletheia/src) — a thin policy layer that makes the existing rails a mandatory pass and owns gate semantics only. aletheia.ts runs three sub-gates in parallel and aggregates them: G1 grounding (every claim bound to a Sophia pin, in grounding-gate.ts), G2 accuracy (accuracy-gate.ts), and G6 safety (safety-gate.ts), plus the regenerate-with-direction fail-action routing. The G2 accuracy check is real: kernel-evaluators.ts holds a REGISTRY of ref → in-repo computation that recomputes STEM values on demand from @kalika/cosmology (ageTodayGyr, hubbleParameter, lookbackTimeGyr over PLANCK_2018_COSMOLOGY) and @nyx/constants (SPEED_OF_LIGHT), so a generated number is checked against ground truth rather than trusted.

@oshun/v9-lesson-gates#

The seven-gate release suite (ledger §J.1; libs/v9/lesson-gates/src). This is the smallest leaf in the area but the load-bearing one: it enforces V9's "no eighth loop" rule by registering the V9-lesson gates G1–G7 on the shared @oshun/content-release-gates ReleaseGateService instead of a bespoke checker. buildV9LessonGates composes each gate from the real platform primitives (gateFromManifestCheck, gateFromEvalScore, and createGroundingGate from @oshun/content-quality-judge): G1 truth (no false/unverified claims), G2 Sophia-pin grounding, G3 teachability, G4 safety, G5 ≥1 real computed explorable, G6 adaptive difficulty in [0,1], G7 a Mnemosyne retrieval checkpoint. evaluateV9Lesson runs the suite and reports cleared/blocked with the blocking gate ids; it defines the V9Lesson/V9LessonClaim/ V9LessonExplorable shapes the rest of the area gates against.

@oshun/v9-lesson-explorables#

The real computed explorables + adaptive layer (ledger §J.3; libs/v9/lesson-explorables/src). orbit-explorable.ts builds a two-body Kepler orbit by handing a separable Hamiltonian to @kalika/symplectic's integrateCanonical (velocity-Verlet) and reading back the trajectory plus the engine's analyzeEnergyBehavior energy-drift diagnostic — computed is true only when a finite multi-sample trajectory was actually produced. adaptive-difficulty.ts and retrieval-checkpoint.ts reuse the Mnemosyne IRT ability MLE and SM-2 scheduling; lesson-assembly.ts binds these into a provenance-bound lesson and lesson-forge.ts routes generation through an injectable LessonDraftWriter (the CognitionGateway boundary), grounding/truth-checking/gating the result and failing loud with LessonForgeNotConfiguredError when no writer is wired.

@oshun/v9-hephaestus#

The explorable runtime (V9_ARCHITECTURE.md §4; libs/v9/hephaestus/src): typed bindings from a ConceptNode to a real computed kernel, each with a demonstrably-reached success state for G4 completeness. nyx-sky-explorable.ts drives the Sun's true apparent position (RA/Dec) from @nyx/ephemeris's calculateSunPosition/dateToJd across a time-travel date slider, and asserts the measured fact that the Sun's right ascension sweeps ≈360° per year over the slider range rather than asserting it blind. kalika-orbit-explorable.ts wraps @oshun/v9-lesson-explorables's buildOrbitExplorable and validates symplectic energy conservation (relative drift below a default 1e-3 tolerance). It enforces the DoD that every P1 lesson ship ≥1 computed-kernel explorable; outputs validate against V9ExplorableSchema.

@oshun/v9-mnemosyne-glue#

The mastery-loop glue (V9_ARCHITECTURE.md §3 stage 6; libs/v9/mnemosyne-glue/src). knowledge-trace.ts turns each lesson concept into an FSRS-v4 card and reviews it via @mnemosyne/core's fsrsReview, scheduling the next retrieval at the forgetting frontier (where retrievability decays to the target retention — the testing effect). mastery-feedback.ts maps an active-recall score onto an FSRS ReviewGrade, projects the card to a MasteryLevel, and folds it back into the Atlas mastery map that resolveWonder consumes, so mastered concepts drop out of the prerequisite frontier and the loop closes. flow-channel.ts measures challenge-vs-skill as the IRT-2PL success probability and classifies the next item as boredom/flow/anxiety against a default [0.6, 0.85] band. Pure binding over the real engines — no new psychometrics.

@oshun/v9-prometheus#

The lesson forge and area orchestrator (V9_ARCHITECTURE.md §3; libs/v9/prometheus/src). pipeline.ts composes Stages 0–8 end-to-end: 0 resolve (Atlas) → 1 ground/solve-first (ground-truth.ts pulls a verified skeleton of grounded claims + recomputed STEM values from Atlas via the Aletheia kernel evaluator, so the LLM never invents a fact or number) → 2 plan (plan.ts, HTN) → 3 write (write.ts, an injected LessonWriter realizes the skeleton with a misconception pass) → 5 explorable (Hephaestus) → 6 assess/schedule (Mnemosyne) → 7 gate (gates.ts: Aletheia G1/G2/G6 + Hephaestus G4 + pedagogy/quality/ provenance, assembled into its own @oshun/contracts G1–G7 verdicts) → 8 compile/cache (compile.ts: C2PA hashes, generation ledger, profile-class cache). A lesson that fails any gate is blocked; a passing one becomes an immutable V9LessonArtifact. The writer is the injected Iris-loop boundary — absent ⇒ fail loud.

@oshun/v9-chiron#

Chiron-lite, the P1 delivery embodiment (V9_ARCHITECTURE.md §7; libs/v9/chiron/src). integrity-modes.ts implements the four tutoring modes (teach/hint/practice/do-not-complete-for-me) with a real academic-integrity floor — resolveTutorAction refuses to complete a learner's graded work and redirects to a hint. delivery.ts resolves the live-avatar → live-voice → text fallback order and discloses every downgrade (a learner is never silently given a lesser experience), and lesson-delivery.ts binds a gated V9LessonArtifact into a LessonDeliveryPlan fronted by the warm-generalist persona (persona.ts), refusing to deliver a lesson that did not pass its gates (isV9LessonPublishable). The live tutoring/avatar runtimes are the injected boundary; the integrity, fallback, and persona logic are real.

@oshun/v9-experience#

The consumer experience-layer view-models (V9_ARCHITECTURE.md §8, L6; libs/v9/experience/src) — the tested data/logic the rendered consumer screens bind to. wonder-front-door.ts projects resolveWonder into the "ask a wonder" entry (disambiguation candidates, scaffolding depth, and "surprise me" frontier suggestions). lesson-player.ts projects a gated artifact into the grounded explanation, the "show your sources" transparency panel (every claim with its Sophia pins + epistemic label), the explorable canvas, and the retrieval checkpoint — and refuses to build a player for an ungated lesson. mastery-map.ts renders the personal Atlas star-map with mastery as brightness (mastered = bright, frontier = the next star to light), and billing-gating.ts layers a free-tier quota over the @oshun/v9-governance entitlement check.

@oshun/v9-governance#

Platform governance (V9_ARCHITECTURE.md §9, V9 Phase 0; libs/v9/governance/src). agent-family.ts registers V9 as an agent family in the V1 Agentic AI Studio, building the AgentRun envelope deterministically from the real Prometheus stage graph — a visible DAG, per-stage budget inheritance, kill switches, and a replay manifest. gate-suite.ts attests (via confirmSevenGateSuite) that the seven gates run on the shared @oshun/v9-lesson-gates / ReleaseGateService rather than a forked checker; iris-loop.ts confirms V9 adds no eighth agentic loop and files an F2/A2 gap report if the platform Iris substrate isn't yet single. entitlements.ts is a real deny-by-default access decision over age band / region / subscription tier plus cross-product grants (a V2 racing achievement unlocking an applied-physics lesson). The platform graphs are injected boundaries; the V9 gating/grant logic is implemented here.

@oshun/v9-cross-cutting#

The cross-cutting concerns library (V9_ARCHITECTURE.md §9, P3; libs/v9/cross-cutting/src). determinism.ts runs a forge twice and compares artifact hashes (skeletonHash/surfaceHash/cacheKey/groundTruth), blocking promotion on any mismatch. anti-metric.ts encodes V9's north star as durable-understanding and throws BannedOptimizationTargetError if an engagement metric (time-on-app, session-length, …) is ever set as the optimization target. champion-challenger.ts ramps a challenger variant only on a statistically significant two-proportion z-test (a real normal-CDF Abramowitz-&-Stegun approximation) behind a min-trials guard. cost-discipline.ts enforces per-stage budget caps and logs every coverage truncation so none is silent; accessibility.ts, localization.ts, and lms-interop.ts add a captions/transcript/alt-text completeness check, a local/cloud inference-tier routing plan, and spec-conformant SCORM 1.2 / QTI 3 / xAPI / Caliper / OneRoster / LTI 1.3 / Open Badges 3.0 exporters.

@oshun/v9-theia#

The Phase-2 "delight & depth" layer (V9_ARCHITECTURE.md §3 P2; libs/v9/theia/src). theia.ts is the wonder-director — thread continuation (nextWonders walks Atlas edges in an enables→bridges→specializes→related priority to open the next, better question), an emotional arc, and "surprise me" frontier picks. generative-widgets.ts verifies an LLM-generated web widget compiles and reaches its declared success state under a headless predicate before it can clear G4/G5 — an unverified widget never ships. manim.ts drives a STEM explainer-film render from a verified Kalika derivation with a bounded self-repair retry loop and C2PA stamping. hitl.ts is the real pause/redirect/ resume HitlSession state machine with per-step budget and checkpoint recovery; agora.ts maps creator authoring directives onto Prometheus; chiron-full.ts adds cross-session memory and bounded, reconstruction-labeled, Sekhmet-gated historical personas. The avatar/emotion/render runtimes are injected boundaries.