# Overview & Player Promise

```mermaid
journey
  title From a mystery request to a fair solved case
  section Ask
    Request a mystery: 5: Player
    Select constraints and tone: 4: Player, Director
  section Forge
    Build the solvable skeleton first: 5: Loom
    Dress it with grounded narrative: 4: Loom
  section Prove
    Solve with all clues: 5: Solver
    Test withheld-clue fairness: 5: Gates
  section Play
    Investigate evidence: 5: Player
    Accuse the uniquely supported culprit: 5: Player
```

The journey begins with proof, not prose. Loom constructs a machine-solvable
case, generation gives it a readable surface, and the gate suite rechecks that
the evidence actually available to the player supports one fair conclusion.

V8 — codename **Ariadne** — is a self-authoring detective universe. Where V5
shipped twenty-five hand-authored cases, V8 turns the same open-world detective
game into one that _writes its own_: a player (or a director, or a creator) asks
for a mystery, and the system mints a complete one — a crime, a cast, a
timeline, a web of evidence and red herrings, and exactly one culprit — with
**no human authoring per case**. The labyrinth metaphor is deliberate and load-
bearing: a fair mystery _is_ a solvable maze, Ariadne's thread (the _clew_, the
etymological root of "clue") is the deduction chain that leads out of it, and
Theseus is the player who walks it. The single product promise underneath all of
that is not "infinite content" — anyone can generate infinite text. It is
**fairness you can trust**: every case Ariadne hands you _can_ be solved with
the clues it actually gives you, because the system proved that before it let
the case reach you. The part of the product that decides whether a mystery is
solvable is real code, not a prompt. The full feature inventory and the
subsystem ownership map live in the hub: [../V8_features.md](../V8_features.md).

## What ships, honestly

V8 is a **small product by surface area**, and the honest version of the player
promise is split cleanly down the middle. The half that has to be _provably
correct_ — "this case is solvable and fair" — is implemented, tested, and
verified against a known result today. The half that makes a case _feel_ like a
shipped AAA mystery — live voiced interrogation, generated art and music, the
persistent living city — is real machinery wired to provider-gated boundaries
that **fail loud** rather than fake their output. `V8_TODOS.md` tracks the build
at **87 of 90 tasks done** (three open, no partials), and there are two real,
tested code tracks expressing the same thesis at different scales.

- **The provable core is real today.** The focused symbolic packages under
  `libs/v8/*` (`@oshun/v8-case-csp`, `-case-bundle`, `-case-gates`) are a
  genuine constraint solver, a solve-first forge, and a seven-gate release
  suite. `case-csp` is ~1,100 lines including tests, and its correctness is
  anchored against the canonical Zebra (Einstein) puzzle — _"Norwegian drinks
  water, the Japanese owns the zebra"_
  (`libs/v8/case-csp/src/csp-solver.spec.ts:168`) — so the engine that decides
  fairness is checked against a result the world already agrees on, not just its
  own output.

- **The full pipeline runs offline, end to end.** The Loom service
  (`apps/v8/loom-service`) wires eleven `libs/yemaya/case-*` subsystem libraries
  into one `runPipeline` (`apps/v8/loom-service/src/pipeline.ts:127`), and the
  §12.4 acceptance test (`pipeline.test.ts:28`) **mints a case and publishes it
  offline, deterministically, with zero provider credentials and all eight
  `ReleaseDecision` gates green**, then runs the real `validate-cold-cases.py`
  build gate. The mint→publish path is genuinely executable and
  regression-tested — not a slide.

- **The realized surface is provider-gated, and refuses to fake.** The parts
  that need real models or money — the LLM proposer/prose writer, live media
  (Stability/Flux for portraits and documents, Hunyuan3D/Meshy for 3-D, Suno for
  music, ElevenLabs for VO, all via Isis), ACE/Inworld runtime interrogation,
  the live Palimpsest canon store, and the `V8/ue` client plugin — are typed
  boundaries the pipeline _injects_ and runs degraded without. A missing prose
  writer throws `CaseBundleNotConfiguredError`
  (`libs/v8/case-bundle/src/case-bundle.ts:115`); an absent media provider
  yields an honest `not-configured` asset slot, never a fabricated asset
  (`case-bundle.ts:260`). None of these stub a result.

So when this page describes the player experience below, it labels each promise
by which track backs it: **real today**, or **provider-gated remainder ([~])**.
The deeper architectural treatment is the companion page,
[../architecture/architectural-thesis-and-pipeline.md](../architecture/architectural-thesis-and-pipeline.md).

## What V8 is

V8's whole thesis fits in one sentence the product repeats everywhere: **the LLM
proposes; a constraint solver disposes.** A mystery has a _symbolic skeleton_
(who did it, the means/motive/opportunity, the clue logic, and a machine-proved
unique solution) and an _experienced surface_ (the prose, dialogue, art, and
voice an audience sees). V8 keeps them strictly apart. The skeleton is
authoritative and machine-checked; the surface is generated from it, graded, and
regenerated on failure. The part that _could_ hallucinate is never the part that
decides whether the case is solvable — which is exactly what separates V8 from
the freestyle-LLM whodunit that contradicts itself, hides the murderer behind a
fact it never showed you, or "solves" by authorial fiat.

The product is layered as a myth cycle, and each layer maps to real code or to a
clearly-labelled seam:

- **Ariadne** — the product: the system that guarantees an unbreakable thread
  out of any labyrinth it builds.
- **Clew** — the generative case engine that builds the ground truth and derives
  clues _from_ the solution (solve-first), so a clue is never decorative.
- **Minos** — the verifier at the gate. `proveCaseUniqueness`
  (`libs/v8/case-csp/src/mystery-skeleton.ts:239`) compiles **only the player-
  visible clues** and demands two things at once: they must admit _exactly one_
  solution, **and** that solution must equal the intended ground truth. An
  under-determined case, an over-constrained one, or one whose visible clues
  prove a _different_ culprit than intended are all rejected — never fabricated
  as solved. This is the most real, most-tested thing in V8.
- **Theseus** — the autonomous playtester that solves each compiled case before
  release and calibrates its difficulty.
- **Daedalus** — the compiler that turns a verified case into V5 data.
- **Oracle** — the drama manager deciding which cases appear where, when, and
  for whom.

The forge ties the first three together. `forgeCaseBundle`
(`libs/v8/case-bundle/src/case-bundle.ts:236`) **proves solvability first** and
throws `CaseNotSolvableError` _before any generation_ if the case is not
uniquely solvable; only then does it generate prose and media through the
injected boundaries, C2PA-stamp every produced asset with the shared
`@oshun/content-signing` Ed25519 signer (`stampAsset`, `case-bundle.ts:184`),
and gate the assembled case. Tampering any signed field flips
`verifyCaseAssetManifest` (`case-bundle.ts:215`) to false. Provability is not a
late check bolted on — it is the precondition for spending a single token on the
surface.

### Built on V5, not instead of it

V8 does not rebuild the detective game. Daedalus compiles a verified case into
V5's _existing_ authored format — `FV5*` Mind-Palace structs plus a
`cold_cases_manifest.json` pack (via `libs/yemaya/case-compiler`) — so a
generated case drops into the shipping V5/V6 game with no rewrite, consumed by
the deduction UI, interrogation rig, and world streaming that already exist. The
familiar "Brilliant / Good / Doubtful / Wrong" accusation rating is V5's own
`EV5MindPalaceAccusationRating` (real, in the V5 Unreal source), now earned
against a solution the system can _defend_. A standalone Daedalus compile is
honestly labelled a draft and skips the all-gates-green Python build gate unless
`--release` is passed (`apps/v8/daedalus-compiler/src/cli.ts:55`).

## The player-facing experience

What the player actually meets is a Bureau of endless, fair cases. Six promises
make up that experience; each is mapped here to the pipeline that backs it and
labelled by how much of it ships today.

### The Endless Case Board

The Vice Squad case-desk and the cross-cell Mind Palace stop being a fixed set
of authored cases. The **Bureau Case Board** offers fresh, themed,
difficulty-tuned cases: daily drops, player-requested commissions (_"a 1947
arson case in the warehouse district, hard, two suspects"_), and ambient
open-world mysteries. **Today:** the offline mint→publish path that produces
such a case deterministically from a `CaseSpec` is real and tested. **Gated
([~]):** the on-demand runtime minting that turns a live in-game request into a
streamed case is spec-described — the Oracle director and runtime relay are the
remainder.

### Cases that fit the world, and remember

Generated cases are **canon-consistent**: they reuse the persistent city's
districts, recurring NPCs, factions, and the _outcomes of the player's prior
cases_. Accuse the wrong man in case #7 and he can resurface — freed and
vengeful — in case #19. The G7 canon-consistency gate is a real injected seam in
the pipeline (a `canonChecker` whose hard contradictions block release,
`pipeline.ts:208`); the offline run uses a fresh world with no prior canon to
contradict. **Gated ([~]):** the full live Palimpsest knowledge graph
(Postgres + pgvector + Neo4j) that stores and resurfaces outcomes across a real
campaign. The proof-and-canon mechanics have their own page:
[./case-generation-proof-and-canon.md](./case-generation-proof-and-canon.md).

### Living suspects you interrogate

Suspects are not branching dialogue trees. Each carries an **Ori** (the V6
portable agent identity — memory, personality, secrets, a stake in the case) and
is driven by Hathor LLM-NPC plus ACE/Inworld for live, lip-synced interrogation.
They hold consistent alibis, crack under correctly-presented evidence, and **lie
_fairly_** — every lie is catchable with a clue the game actually gives you,
which is the same fair-play invariant Minos enforces on the skeleton. **Gated
([~]):** the live in-engine interrogation runtime is the external remainder; the
suspect-mind seam and the per-suspect interrogation-tree realization are
described in
[./realization-and-living-suspects.md](./realization-and-living-suspects.md).

### Fully realized, not text-only

Every generated case is meant to ship with crime-scene environment art and 3-D
props, suspect portraits and document/photo evidence, case music and stings, and
full voice-over — all produced by the Isis fabric, keyed to the case, and
provenance-stamped. **Today:** the C2PA stamping and verification machinery is
real (`stampAsset` / `verifyCaseAssetManifest`), and the offline pipeline emits
a text-only _degraded_ asset pack honestly rather than faking media. **Gated
([~]):** the live media providers themselves. V8 adds no new providers — it
orchestrates Isis's existing ones.

### Fairness you can feel

Because Minos proves uniqueness and Theseus plays the case first, players never
hit an unsolvable wall or a "gotcha" solution. Difficulty is honest: harder
cases have more suspects and subtler clue chains, never _hidden_ information.
The subtle cheat fair-play exists to forbid — "a case solvable only with
withheld clues" — is exactly what `proveCaseUniqueness` rejects, and the spec
exercises that rejection directly. This is the part of the promise that is
**most real today**, and it is what makes the accusation rating meaningful
rather than cosmetic.

### Co-op and creator cases

A **Co-op Bureau** lets a party work one generated case together (shared Mind
Palace, divided legwork), and a **Commission Studio** lets creators steer
Ariadne — set era, tone, cast, constraints — and publish vetted cases through
the V7 Mawu distribution and Sekhmet safety regime. **Gated ([~]):** both are
spec-described forward motions layered on the runtime and the live
safety/distribution planes.

## The GA promise

V8 is GA-complete when, with **zero human authoring per case**, a player
requests or is offered a case and the system delivers a mystery that is provably
solvable, fully realized, live to interrogate, canon-consistent, and
reproducible. The seven-point Definition of Done in the hub is the contract;
here it is, mapped honestly to what the code does today.

| GA promise                                                           | Backed by                                                                           | Status                                          |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------- |
| 1. Generate a requested case within budget                           | `runPipeline` over a `CaseSpec`, per-case token/asset budget                        | **Real offline**; live on-demand minting is [~] |
| 2. Minos _proves_ the unique, fair culprit                           | `proveCaseUniqueness` + G1–G3 (uniqueness, completeness, Knox/Van-Dine)             | **Real, tested** (Zebra-anchored)               |
| 3. Theseus _solves_ the compiled case to a "Brilliant"-eligible path | in-game solvability check on the compiled IR (`checkInGameSolvable`)                | **Real offline**; live in-engine solve is [~]   |
| 4. Full env/props/portraits/docs/music/VO, provenance-stamped        | C2PA `stampAsset` / `verifyCaseAssetManifest`; Isis seam                            | **Provenance real**; live media is [~]          |
| 5. Suspects interrogate live with fairly-catchable lies              | Ori + Hathor + ACE/Inworld seam                                                     | **[~]** external runtime                        |
| 6. Canon-consistent + writes its outcome back                        | G7 `canonChecker` seam                                                              | **Seam real**; live Palimpsest store is [~]     |
| 7. Reproducible from a seed, auditable, refuses the unsafe           | `seed` + canon snapshot + `StageJournal`; `decideRelease` blocks + journals reasons | **Real, tested**                                |

The two rows that carry the whole promise — **#2 (provable fairness)** and **#7
(reproducible refusal)** — are the ones that are fully real today, and that is
by design. The release decision takes the conjunction of all eight gates
(`decideRelease`, `pipeline.ts:212`); G6 safety is fail-loud by construction
(`requireSafetyClear` throws on flagged _or unscanned_ content, leaving the gate
red); and a blocked case journals its reasons and produces _no_ published pack.
A run is parameterized by a seed and a canon snapshot, so the same case mints
identically — which is both the provenance guarantee and the cost lever (a
popular case is minted and gated once). Nothing unsolvable, unfair, unsafe, or
canon-breaking can reach a player, because the system is built to **refuse**
rather than fabricate.

## Non-goals

V8 is deliberately narrow, and the non-goals are part of the honesty:

- **It does not replace authored cases.** V5's twenty-five hand-made cases
  remain the golden corpus and the Theseus/judge calibration fixtures.
- **It does not rebuild V5.** No new deduction UI, interrogation rig, or world
  streaming — V8 emits `FV5*` data those systems already consume.
- **It does not add asset providers.** It orchestrates Isis's existing fabric.
- **It does not let an LLM freestyle a mystery.** The symbolic ground truth plus
  the constraint solver are authoritative; the LLM only realizes a skeleton that
  has already been proved fair.

V8 is, in the end, a small net-new footprint on a large shared platform: it
reuses the platform's release-gate service, content-signing, and grounding gate
rather than re-implementing them, and reuses V5 (the game), V6 (the Ori), and V7
(Sekhmet safety, Mawu distribution) wholesale. What is genuinely new is the
provable core — and that core is real.

## Related

- The feature hub: [../V8_features.md](../V8_features.md)
- The architecture companion (thesis + pipeline):
  [../architecture/architectural-thesis-and-pipeline.md](../architecture/architectural-thesis-and-pipeline.md)
- [./case-generation-proof-and-canon.md](./case-generation-proof-and-canon.md) —
  the solve-first engine, the uniqueness/fair-play proof, and canon continuity
- [./realization-and-living-suspects.md](./realization-and-living-suspects.md) —
  the writers' room, asset realization, and living-suspect interrogation