# V8 — Systems Deep Dive

> The `apps/v8/` area: three deployable Nx applications that expose the **V8
> Ariadne** self-authoring detective engine — a case-compiler CLI, the Loom
> orchestrator BFF, and the Minos ASP solver sidecar — as runnable processes.

## What this area is

V8 is "Ariadne", the self-authoring detective universe: a pipeline that mints
fair, solvable, machine-verified mystery cases with no human authoring. The
heavy lifting lives in the `@yemaya/case-*` libraries (`case-engine`,
`case-verifier`, `case-writers-room`, `case-compiler`, `case-eval`,
`case-pipeline`, `case-contracts`). The three projects under `apps/v8/` are the
**runtime shells** around that library core — they are
`projectType: "application"` nodes, each tagged `scope:yemaya`, `type:app`, and
`v8:ariadne`, that turn the libraries into a CLI, an HTTP BFF, and a solver
microservice.

The split follows the seven-gate case lifecycle. A `CaseSpec` is generated
(Clew, `@yemaya/case-engine`), verified for uniqueness/completeness/fair-play
(Minos, `@yemaya/case-verifier`, gates G1–G3), narratively realized (Anansesɛm,
`@yemaya/case-writers-room`), asset-realized, compiled to a V5 intermediate
representation (`@yemaya/case-compiler`), evaluated (Theseus,
`@yemaya/case-eval`, gates G4–G5), safety-scanned (Sekhmet, G6), and
canon-checked (G7) before a release decision publishes it. `v8-loom-service`
runs that whole chain; `v8-daedalus-compiler` runs the generate→verify→compile
prefix as a standalone tool; `v8-minos-asp-sidecar` extracts the G1 uniqueness
proof into its own scalable service.

All three are thin by design and honest about it: each `src/index.ts` documents
that the real algorithms live in the libraries and that the app is the "CLI +
runtime-relay wrapper" (`apps/v8/daedalus-compiler/src/index.ts`), the "Ariadne
orchestrator BFF" (`apps/v8/loom-service/src/index.ts`), or the "ASP solver
service" (`apps/v8/minos-asp-sidecar/src/index.ts`). None is an empty scaffold —
every project has a real `src/`, real tests (`cli.test.ts`, `pipeline.test.ts`,
`adversarial.test.ts`, `sidecar.test.ts`), and `tsc --noEmit` build/typecheck
targets plus Vitest test targets.

### How the projects relate

`v8-daedalus-compiler` and `v8-loom-service` are two entry points over the same
library stack: Daedalus is the developer/CI tool that stops at compile, Loom is
the production service that drives the full seven-gate pipeline to a publish
decision. `v8-minos-asp-sidecar` is the one that can be deployed independently —
it wraps only the verifier's ASP/clingo path so the uniqueness proof can be
offloaded to a clingo container, with an in-process DPLL fallback giving an
identical verdict when no clingo binary is present.

## How it fits the wider system

The UE5 client (V5/V6) is the ultimate consumer: per
`apps/v8/loom-service/src/server.ts` the client calls the Loom BFF to mint or
fetch compiled case packs on demand and **never holds provider keys** (sota §4).
Loom returns the compiled `manifest` only when `decision.publish` is true (all
seven gates green), answering `200` on publish and `422` with `blockingReasons`
otherwise. Daedalus is consumed by developers and CI as the `daedalus` bin to
compile a single case to disk for inspection or fixtures, and ships a sibling
`reproduce` CLI that proves the generated IR is bit-for-bit deterministic
(§11.5). The Minos sidecar is consumed by the verifier path (and operationally
by anything that wants to scale uniqueness solving) over `POST /solve`. The
boundary in every case is the `@yemaya/case-contracts` types (`CaseSpec`,
`CaseGroundTruth`, `CompiledCase`, `CaseBudget`, …): the apps own
process/transport concerns, the libraries own the domain logic.

## Entity reference

### v8-daedalus-compiler

The Daedalus case-compiler CLI app (`apps/v8/daedalus-compiler`, package
`@v8/daedalus-compiler`, bin `daedalus`). `src/cli.ts` runs the local
generate→verify→compile pipeline for a single case: `generateCaseSync` from
`@yemaya/case-engine` produces the session and ground truth, `verifyCase` from
`@yemaya/case-verifier` proves gates G1–G3 (uniqueness, completeness, fair-play,
balance), and on a green verdict `compileCase` from `@yemaya/case-compiler`
writes `<caseId>.compiled.json` and `<caseId>.manifest.json` to `--out`. It is
honest about scope: G4/G6/G7 are downstream, so a standalone compile is labelled
a draft and skips the Python all-gates-green build gate unless `--release` is
passed with every gate asserted. `src/index.ts` re-exports
`@yemaya/case-compiler` plus `runCli` and `DAEDALUS_VERSION = '0.1.0'`;
build/typecheck are `tsc -p tsconfig.json --noEmit`, covered by
`src/cli.test.ts`.

### v8-loom-service

The Loom orchestrator BFF (`apps/v8/loom-service`, package `@v8/loom-service`) —
the Ariadne runtime relay the UE5 client calls to mint cases. `src/pipeline.ts`
implements `runPipeline`, the §12.4 end-to-end acceptance flow that threads a
single `CaseSpec` through every stage behind the seven gates: ground-truth →
clue derivation → verify (G1–G3) → narrative realize → asset realize →
compile-IR → eval (G4–G5 via `checkInGameSolvable`/`judgeCase`) → safety (G6 via
`requireSafetyClear`) → canon-consistency (G7) → `decideRelease` (§9.6) →
compile-game/publish → provenance (§11.3) + telemetry, carrying a `CaseBudget`,
a `StageJournal`, and a `TelemetryAggregator`. `src/deps.ts` builds the
**offline** deps that run the whole pipeline with zero credentials
(deterministic Clew core, `KeywordSafetyScanner` for G6, in-memory
budget/journal/telemetry), with optional seams (`proposer`, `completionFn`,
`realizeAssets`, `canonChecker`) for the production swap-ins. `src/server.ts` is
a `node:http` BFF exposing `POST /v8/cases/mint`, `GET /v8/cases/:id`, and
`GET /health` (default port 4010, in-memory `minted` cache), returning the
compiled pack only when all seven gates pass. `src/reproduce-cli.ts` is the
§11.5 `reproduce` tool that regenerates a case twice and asserts the IR is
bit-for-bit identical, printing the reproducibility key. Tests:
`src/pipeline.test.ts` and `src/adversarial.test.ts`.

### v8-minos-asp-sidecar

The Minos ASP solver sidecar (`apps/v8/minos-asp-sidecar`, package
`@v8/minos-asp-sidecar`) — §3.1, the service that offloads the case-uniqueness
proof. `src/index.ts` exposes `handleSolve(req)`, the pure handler shared by the
server and tests, which calls `runUniquenessViaAsp` over the reachable clue set,
reports `clingoAvailable()`, and returns the emitted ASP program (via
`emitAspProgram`) for audit — all from `@yemaya/case-verifier`. `src/server.ts`
is a dependency-light `node:http` service with `POST /solve` (validates that the
body carries `groundTruth` and an `availableClueIds[]` array) and `GET /health`
(which reports whether a clingo backend is present), defaulting to port 4070.
The `Dockerfile` builds a `node:24-bookworm-slim` image with `gringo` and
`clingo` (Potassco) installed; when no clingo binary is available the underlying
verifier falls back to the in-process DPLL solver for an identical verdict. The
project adds a `docker:build` target and is covered by `src/sidecar.test.ts`.