# V9-004 V8 Metis detective-learning bridge

Date: 2026-07-27

## Outcome

V8 now has a governed player-learning boundary at
`libs/v8/metis-detective-learning-bridge`. It admits one exact released Metis
reasoning lesson through `@metis/game-bridge-contract` and combines it with one
already-released clue selected by Clew's existing `minimalProofTreeHint`.

Admission requires:

1. a case identity matching the authoritative proof-tree session;
2. an exact `G1` through `G8` `ReleaseDecision`, with every gate true, publish
   true, no blocker, and human-quality evidence present;
3. a non-empty, unique set of released clue IDs;
4. a valid consecutive proof tree with exactly one correct solution;
5. one available solve-path clue that has already been released; and
6. an exact released Metis lesson in `v8.detective-learning.proof-tree-hint`.

The bridge exposes `@yemaya/case-eval/release` as a narrow package subpath so it
can consume the authoritative release type without importing unrelated eval
surfaces.

## Critical authority and spoiler separation

The export contains the selected clue's ID, name, description, and step order,
plus generic grounded Metis reasoning guidance. It explicitly states that it
reveals exactly one already-released clue and does not reveal a conclusion,
culprit, deduction path, or unreleased evidence.

Case generation, repair, evidence release, interrogation runtime, accusation
resolution, canon writes, release pipeline calls, and director ticks are
rejected before hint selection or Metis reads. Ground truth, culprit,
conclusion, solution, deduction path, evidence-unlock, accusation, repair,
canon, release, placement, gameplay-outcome, and player-model mutation payloads
are likewise forbidden.

The complete hidden solution map and all release/human-quality evidence are
stripped from the serialized result. V8 retains sole authority over evidence,
investigation, accusation, case lifecycle, canon, placement, and adaptation.

## Provider admission

The shared contract requires exact released publication and lesson versions,
operator approval, cleared rights, verified provenance, approved
Sophia-source-of-record grounding, learner disclosure, accessibility and
fallback readiness, and safe labeled media.

## Automated verification

Focused verification passed:

- bridge production and test typechecks;
- bridge Vitest — 1 file, 21 tests;
- canonical fairness-validator tests — 54 tests;
- Clew proof-tree selector tests — 3 tests;
- Theseus/release-evaluation tests — 14 tests;
- bridge lint and build;
- canonical Metis contract generation check;
- V8 header/contract/package docs-drift verification;
- Nx project discovery and root module-boundary lint;
- exact lockfile importer parse/workspace-link validation; and
- targeted formatting validation.

Coverage includes deterministic selection, exact case and gate identity,
single-clue projection, hidden-data stripping, deterministic escalation,
regressed release rejection, twelve forbidden authority contexts/payloads before
I/O, failed releases, malformed proof trees, exhausted hints, unreleased Metis
packages, and cross-module lesson substitution.

TypeScript 6 required four missing `override` modifiers on the canonical
fairness validator's typed `EventEmitter`; that compatibility repair is included
and its 54 focused tests pass. The broader `@yemaya/agents` typecheck then
reached a pre-existing unrelated `libs/contracts` Zod/output-type failure set.
This increment does not alter or claim closure of that separate contract
baseline.

The repository-wide frozen-lockfile command also remains blocked by the
pre-existing root importer mismatch documented in the V7 evidence: removed
`@changesets/cli` and an `@fastify/cors` catalog-specifier mismatch. The new V8
importer is validated independently without rewriting unrelated user-owned
lockfile work.

## Scope boundary

This closes the repository-actionable V8 canonical-provider admission seam and
therefore the code-level V2–V8 bridge sequence. It does not claim a rendered V8
client, runtime authentication, a packaged game build, live provider delivery,
or recorded player learning. Those operational proofs keep the composite V9-004
launch checkbox open.
