v9 library

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.