# V8 — Systems Deep Dive

> The `libs/v8/` area: three Nx libraries that turn a generated detective case
> into a **machine-proven, gated, and provenance-stamped** content bundle — V8
> (Ariadne)'s "the LLM proposes; a constraint solver disposes" pipeline.

## What this area is

V8 is the **Ariadne self-authoring detective universe**. Its design principle,
repeated verbatim in every package's header, is _"the LLM proposes; a constraint
solver disposes"_: a language model may draft a mystery, but a real symbolic
solver — not the model — decides whether that mystery is fair and solvable, and
a shared release-gate suite — not a bespoke per-product checker — decides
whether it may ship. The three libraries here are the deterministic, verifiable
spine of that pipeline; the live generative providers (image/3-D/music/voice
models) sit behind injected boundaries and are the honest `[~]` remainder.

The three projects form a clean dependency chain keyed to the V8 ledger
sections. `@oshun/v8-case-csp` (ledger §I.2) is the bottom: a domain-agnostic
finite-domain constraint solver plus a mystery-skeleton compiler that proves a
case admits **exactly one** solution. `@oshun/v8-case-gates` (ledger §I.1) is
the release-gate layer: seven gates (G1–G7) built on the platform-shared
`@oshun/content-release-gates`, one of which consumes the CSP's uniqueness flag.
`@oshun/v8-case-bundle` (ledger §I.3) is the top: a forge that proves
solvability first, then drafts prose and generates media through injectable
provider seams, C2PA-signs every produced asset, and runs the whole case through
the gate suite.

The honesty posture is built into the code, not just the docs. An unsolvable
skeleton is **rejected before any generation** (`CaseNotSolvableError`); a
missing prose writer **fails loud** (`CaseBundleNotConfiguredError`); and an
absent media provider yields a `not-configured` asset slot rather than a
fabricated asset. What is real here is the solver, the uniqueness proof, the
gates, the C2PA stamping, and the provenance binding. What is deferred (and
labelled as such) is the roster of live media models named in the boundary
interfaces (Stability/Flux for images, Hunyuan3D/Meshy for 3-D, Suno for music,
ElevenLabs for voiceover) and the real LLM behind the prose-writer seam.

## How it fits the wider system

These three libraries are tagged `scope:v8`, `layer:domain`, `type:lib` and
compose **platform-shared infrastructure** rather than reinventing it:
`@oshun/content-signing` (Ed25519 signing + `sha256Hex`),
`@oshun/content-release-gates` (the `ReleaseGateService` and its
`gateFromEvalScore` / `gateFromManifestCheck` builders), and
`@oshun/content-quality-judge` (the §7.2 grounding gate reused for clue
grounding). The boundary V8 owns is the _detective-case domain logic_: what
"fair," "solvable," and "grounded" mean for a mystery, expressed as CSP
constraints and gate definitions over those shared primitives.

The consumer of the whole area is the case-bundle forge's caller — the V8
authoring service or agent loop that supplies a `MysterySkeleton`, a
`CaseProseWriter`, and zero or more `CaseMediaGenerator`s. Because the heavy
dependencies (LLM, media models, signing key) are all injected at the call site,
the libraries themselves are pure and testable: the CSP solver is anchored
against the canonical **Zebra (Einstein) puzzle** in its spec, and the bundle
forge runs end-to-end against in-test provider doubles without touching a real
model. Note the deliberate non-edge between the two lower libraries:
`@oshun/v8-case-gates` does **not** import `@oshun/v8-case-csp`; the CSP proof
is reduced to a boolean (`uniqueSolutionProven`) and composed at the call site
so the gate suite stays dependency-light, with the wiring demonstrated in
`mystery-skeleton.ts`'s `provenUniquenessFlag` helper and the case-bundle forge.

## Entity reference

### @oshun/v8-case-csp

The deterministic core (`libs/v8/case-csp`, ledger §I.2) — a genuine
finite-domain constraint solver, not a boolean stub. `src/csp-solver.ts`
implements backtracking search with node consistency, minimum-remaining-values
(MRV) variable ordering, and forward checking (`solveCsp`,
`proveUniqueSolution`) over a first-class constraint algebra (`equals`,
`not-equals`, `in`, `all-different`, `implies`, and a general n-ary `relation`
predicate). The search is complete and exact — its spec anchors correctness
against the canonical Zebra puzzle (`csp-solver.spec.ts` asserts "Norwegian
drinks water, Japanese owns the zebra"). `src/mystery-skeleton.ts` is the domain
layer on top: it compiles a generated case's **player-visible** clues into a
`CspModel` (`compileMysteryToCsp`) and `proveCaseUniqueness` verifies the
presented clues admit exactly one solution _and_ that it equals the intended
`groundTruth` — rejecting under-determined, unsatisfiable, or wrong-answer cases
instead of fabricating a "solved" flag.

### @oshun/v8-case-gates

The release-gate suite (`libs/v8/case-gates`, ledger §I.1, Phase 0).
`src/index.ts` registers seven V8-case gates — G1 fairness, G2 solvability, G3
clue-grounding, G4 voice, G5 misdirection, G6 prose, G7 safety — as real
`GateDefinition`s **composed onto the shared `@oshun/content-release-gates`
service**, not a forked per-product checker. G1 is a manifest check that every
clue the solution depends on (`solutionClueIds`) is presented before the reveal;
G2 consumes the CSP's `uniqueSolutionProven` boolean; G3 reuses the §7.2
grounding gate from `@oshun/content-quality-judge` to confirm every cited clue
actually exists; G4/G6/G7 are eval-score gates with tunable thresholds
(`V8CaseGateConfig` defaults voice/prose 70, safety 90); G5 enforces fair
misdirection (at least one red herring, but at most `maxRedHerrings`, default
5). `evaluateV8Case` runs the suite and returns `cleared` only when all seven
required gates pass, with the blocked gate ids surfaced.

### @oshun/v8-case-bundle

The forge at the top of the chain (`libs/v8/case-bundle`, ledger §I.3).
`src/case-bundle.ts`'s `forgeCaseBundle` orchestrates the full pipeline: it
**proves solvability first** via `@oshun/v8-case-csp` (throwing
`CaseNotSolvableError` before any generation if the case is not uniquely
solvable), fails loud if no `CaseProseWriter` is wired
(`CaseBundleNotConfiguredError`), drafts prose + clue logic through that
injected writer, then walks the draft's asset requests through injected
`CaseMediaGenerator`s. Every produced asset is C2PA-stamped — `stampAsset`
hashes the bytes with `sha256Hex` and Ed25519-signs a canonical manifest via
`@oshun/content-signing` — while any unsupported asset kind becomes an honest
`not-configured` slot rather than a fabricated asset. The assembled `V8Case` is
then run through `@oshun/v8-case-gates`, and the result carries a
`CaseBundleProvenance` (solution hash, generated-asset count, not-configured
kinds, signer key id/public key). `verifyCaseAssetManifest` recomputes and
checks each signature, so tampering any signed field flips it to false. The
named live providers (Stability/Flux, Hunyuan3D/Meshy, Suno, ElevenLabs) and the
real LLM prose writer are the injectable `[~]` boundaries; the proof, stamping,
gating, and provenance binding are fully implemented.