# PROOF-002 evidence pack — semantic grounding at generation boundaries

> **Status: repository-complete / closed.** The named V1, V2, V6, V7, and V9
> generation boundaries require bounded retrieved passages and claim-level
> semantic proof, or they fail closed/fall back without claiming grounding. This
> status does not claim that live retrieval, match feeds, external entailment
> services, or production composition roots are deployed.

## Work-package charter

- **Task ID:** `PROOF-002`
- **Owner:** canonical contracts, V1 Sophia/BFF, V2 Iris commentary, V6 Clio, V7
  Mawu, and V9 Metis maintainers; implementation owner: Elikem Agudogo
- **Accountable product:** semantic grounding for the named V1–V9 content,
  commentary, narration, generated-asset, and lesson-generation boundaries
- **Priority:** P0
- **Target milestone:** 2026-07-15 SOTA gap-closure program
- **Risk tier:** Critical factual-integrity and release-grounding risk
- **Audit finding:** citation-shaped metadata could be accepted without actual
  retrieval, passage capture, or claim entailment
- **Dependencies:** PROOF-001 exact proof meanings, Sophia evidence reads,
  authoritative Iris match state, Ori event facts, Mawu source bundles, Metis
  approved lesson sources, and configured semantic-verifier ports
- **Affected schemas and content slots:** canonical bounded passages, factual
  claims, entailment assessments, proof bundles, V1 generated variants, V2 live
  commentary, V6 narrated story beats, V7 generated structured assets, V9 lesson
  prose/citations, and their release-gate envelopes. No rendered UI, media
  bytes, or database migration changed in the refresh.
- **Linked task IDs:** `PROOF-001`, `PROOF-002`, `PROOF-003`, `V1-002`,
  `PROMPT-001`, `PROMPT-002`, `MEDIA-001`, and `EVAL-005`
- **Rollout strategy:** shared additive semantic-grounding records followed by
  fail-closed enforcement at each affected generation and release boundary
- **Rollback strategy:** revert the original semantic-boundary commit and its
  current test/config remediations together. Partial rollback can leave
  consumers compiled against missing or weaker proof requirements.
- **Evidence-pack location:** this file

## Closure matrix

| Ledger requirement                                         | Repository closure proof                                                                                                                                                                                                                                                                                                                                                          |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| V1 Sophia retrieval, passage capture, and claim entailment | The production BFF resolves Sophia through the evidence-read adapter before writing. The writer receives bounded retrieved passages, emits atomic claims bound only to supplied citation IDs, and a separate semantic verifier produces canonical retrieval, passage-match, and claim-entailment proof. Unknown citations, unavailable retrieval, and non-entailment fail closed. |
| V1 bounded bundles and stable citation IDs                 | The BFF caps Sophia input at six passages and 1,200 characters per passage. Stable citation IDs come from Sophia results and survive variant generation. Prompt and runtime checks reject invented IDs or IDs outside the retrieved bundle.                                                                                                                                       |
| V2 authoritative live commentary                           | Iris accepts validated authoritative match state/facts plus a fact-verifier port. Generation and verification share the latency budget. Missing authority, mismatch, timeout, verifier error, or unsupported claims yield safe fallback commentary without factual proof; success carries the exact proof bundle.                                                                 |
| V6 Clio event-fact entailment                              | Narrated options convert cited Ori events into bounded passages and require a semantic decision for every free-prose claim. Citation membership alone cannot pass. Unsupported prose raises `ClioNarrationEntailmentError`; accepted beats retain the canonical proof envelope.                                                                                                   |
| V7 Mawu source-to-output grounding                         | Mawu verifies the actual generated tool-specific payload against source passages after generation. A missing verifier or semantic failure produces a typed non-artifact result. Pre-generation source metadata cannot create proof.                                                                                                                                               |
| V9 non-vacuous citation sufficiency                        | Non-empty factual output with no citations fails. The verifier requires claims, bounded passages, exact subjects, a semantic evaluator, exact claim/citation coverage, and canonical proof coverage. Empty or declared-only metadata cannot pass.                                                                                                                                 |
| V9 approved source retrieval and entailment                | Lesson generation requires a non-empty approved bundle whose bounded passages each carry upstream retrieval proof. Limits are eight passages, 4,000 characters per passage, and 16,000 total characters. Prompts require source markers on factual sentences; generated claims are verified against exact passages before G2 can pass.                                            |

## Canonical contract and boundary behavior

`libs/contracts/src/common/semantic-grounding.ts` owns the shared bounded
passage, factual-claim, entailment-assessment, proof-bundle, and coverage
contract. It composes PROOF-001 records instead of inventing a parallel proof
vocabulary:

- every passage has a stable citation ID and upstream retrieval proof for its
  exact source;
- each factual claim names citation IDs from the bounded passage set;
- a semantic evaluator records `entails`, `does_not_entail`, or `unknown` for
  that exact claim and citation set;
- accepted assessments produce exact `passage_match` and `claim_entailment`
  records;
- coverage passes only when every claim and cited passage has the current,
  passed, subject/evidence-bound proof required by policy.

Declared scores, source pins, citation syntax, citation membership, and
pre-generation source metadata never become semantic proof.

### V1 Sophia and BFF

Retrieval precedes writing and only the bounded Sophia bundle crosses the writer
boundary. The writer returns atomic factual claims and supplied citation IDs. A
separate strict LLM-NLI call assesses the claims; missing, neutral,
contradictory, or unknown assessments are rejected. Sophia judging and
publication readiness consume full proof coverage and score declared metadata as
zero.

### V2 Iris commentary

Live commentary validates authoritative state before generation. A fact verifier
checks proposed factual claims against that state within the remainder of the
same deadline. Failure to establish authority or finish verification takes the
safe fallback path without silently publishing an unverified assertion.

### V6 Clio and V7 Mawu

Clio binds cited event facts to narrated prose at claim granularity. Mawu binds
the generated structured output to its sources after generation. Both require an
explicit semantic verifier, retain proof only after success, and expose
missing-verifier/failed-grounding paths as non-releasable.

### V9 Metis lessons

V9 source bundles are approved, bounded retrieved passages rather than loose
metadata. Generation prompts expose stable IDs. Citation sufficiency builds
per-output factual claims, calls the configured entailment evaluator, and
evaluates the proof bundle. A `sourcePin`, non-empty reference array, or empty
citation scan cannot satisfy G2.

## Adversarial fixture matrix

| Fixture                       | Presented condition                                                          | Result                                             |
| ----------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------- |
| V1 invented citation          | Writer returns an ID absent from Sophia's bundle                             | Rejected before proof construction                 |
| V1 unsupported claim          | Citation exists but NLI returns neutral or contradiction                     | Rejected; no entailment proof                      |
| V1 missing retrieval          | Sophia adapter is absent or returns no usable passage                        | Generation fails closed                            |
| V2 missing authority          | Commentary request has no valid authoritative state or supported verifier    | Safe fallback, no factual proof                    |
| V2 verifier over budget       | Generation consumes the deadline or verification times out                   | Safe fallback within the shared budget             |
| V6 citation membership only   | Narration cites an existing Ori event but prose is unsupported               | Typed entailment failure                           |
| V7 pre-generation attribution | Source metadata exists but the generated payload does not preserve its facts | Artifact withheld as semantic-grounding failure    |
| V9 no citations               | Non-empty factual output contains no source markers                          | Citation sufficiency fails, never vacuously passes |
| V9 unproved passage           | A source passage lacks its exact upstream retrieval proof                    | Source bundle rejected before generation           |
| V9 partial coverage           | One claim or cited passage lacks exact semantic proof                        | G2 fails with coverage issues                      |

## Automated verification

### Current admitted value ledger

All rows below were rerun sequentially with `VITEST_MAX_WORKERS=1` from
published `origin/main` commit `734b7bd04105fc3e8c762c9c1451390f3ef0614e`.

| UTC interval                                      |  Files |        Result | Surface                                                             |
| ------------------------------------------------- | -----: | ------------: | ------------------------------------------------------------------- |
| 2026-07-29T14:17:44.511Z–2026-07-29T14:17:46.022Z |      2 |       **9/9** | canonical semantic-grounding contract and contract/Prisma alignment |
| 2026-07-29T14:17:46.022Z–2026-07-29T14:17:57.101Z |      2 |   **117/117** | full Iris conversation-orchestration package                        |
| 2026-07-29T14:17:57.101Z–2026-07-29T14:18:01.541Z |      1 |       **9/9** | V2 authoritative Iris commentary package                            |
| 2026-07-29T14:18:01.541Z–2026-07-29T14:18:06.897Z |      2 |     **16/16** | full Clio story/narration package                                   |
| 2026-07-29T14:18:06.897Z–2026-07-29T14:18:15.970Z |      5 |     **45/45** | full Mawu three-dimensional pipeline package                        |
| 2026-07-29T14:18:15.970Z–2026-07-29T14:18:21.609Z |      1 |       **9/9** | full V9 lesson-gates package                                        |
| 2026-07-29T14:18:21.609Z–2026-07-29T14:18:38.376Z |     24 |   **176/176** | full Metis verification package                                     |
| 2026-07-29T14:18:38.376Z–2026-07-29T14:19:14.372Z |     26 | **1328/1328** | full Metis LLM client package                                       |
| 2026-07-29T14:19:14.372Z–2026-07-29T14:19:34.219Z |      2 |     **46/46** | BFF autonomy bindings and end-to-end generation boundary            |
| 2026-07-29T14:19:34.219Z–2026-07-29T14:20:02.153Z |      2 |   **160/160** | V1 and V6/V7 prompt-injection boundaries                            |
| 2026-07-29T14:20:02.153Z–2026-07-29T14:20:03.483Z |      1 |     **14/14** | creative-variant citation preservation                              |
| **Unique total**                                  | **68** | **1929/1929** | no focused row or assertion is counted twice                        |

The former **608/608** ledger total was the correct unique total for the
historical suite set. Its evidence table displayed **615** because the final V9
citation-sufficiency **7/7** row was already included in the V9 package row.
This refresh removes that duplicated row and reports the larger current suites
once each.

Representative commands:

```text
pnpm exec vitest run --config libs/contracts/vitest.config.ts libs/contracts/src/common/semantic-grounding.test.ts libs/contracts/src/common/contract-prisma-alignment.test.ts
pnpm exec vitest run --config libs/iris/conversation-orchestration/vitest.config.ts
pnpm exec vitest run --config apps/v2/iris-commentary-orchestration/vitest.config.ts
pnpm exec vitest run --config libs/v6/clio-story/vitest.config.ts
pnpm exec vitest run --config libs/isis/three-d-pipelines/vitest.config.ts
pnpm exec vitest run --config libs/v9/lesson-gates/vitest.config.ts
pnpm exec vitest run --config libs/metis/verification/vitest.config.ts
pnpm exec vitest run --config libs/metis/llm-client/vitest.config.ts
pnpm exec vitest run --config apps/oshun/bff/vitest.config.ts <two autonomy files>
pnpm exec vitest run --config testing/prompt-injection/vitest.config.ts <V1 and V6/V7 files>
pnpm exec vitest run --config libs/oshun/creative-autonomy/vitest.config.ts libs/oshun/creative-autonomy/src/quality/llm.test.ts
```

### Type, lint, build, and compatibility gates

- library and spec TypeScript configurations passed for Iris, Mawu, Clio, Metis
  verification, and Metis LLM after both current remediations; contracts, V2
  commentary, V9 lesson gates, prompt injection, and creative autonomy also
  passed their task-scoped TypeScript gates during this refresh;
- exact ESLint with ignored test files included passed over all 16 changed
  library/test TypeScript files, and the final shared Vitest config passed exact
  ESLint; Prettier and `git diff --check` passed;
- an uncached targeted Iris production build and its three dependencies
  (`@oshun/contracts`, `@iris/types`, and `@oshun/prompt-trust`) passed;
- the BFF zero-new-error ratchet reported **0 known** app-owned backlog in the
  dependency-aware publication hook;
- Vitest 4's removed `test.poolOptions` was migrated to top-level `isolate`,
  `fileParallelism`, and `maxWorkers`. The current Clio run no longer emits the
  pool-options deprecation.

### Refresh-discovered regressions and bounded exclusions

The refresh preserved red gates and fixed every task-owned defect:

- Iris spec typechecking exposed stale imports/mock typing and a weighted
  factory that incorrectly required weights for every possible provider. The
  factory now accepts the configured-provider subset and its full **117/117**
  suite passes.
- Clio's spec config omitted Node types. Mawu's direct backend fixture omitted
  the now-required trust-rendered model prompt, and its spec config could not
  type its explicit `.ts` config import. The corrected packages pass **16/16**
  and **45/45**.
- Metis verification had three stale spec typings: a type imported from the
  wrong module, an asynchronous retriever cast as synchronous, and an unused
  refinement argument. Its full package passes **176/176**.
- Metis LLM spec typechecking reported 22 stale test-source errors, including
  unused fixtures, nullable request-system handling, factory tests that bypassed
  the factory, vacuous assertions, and a real-time 1 ms expiry fixture. The
  corrected full package passes **1,328/1,328**.
- the first combined prompt-boundary run at default parallelism had one
  multimodal Iris response failure out of 160. Each partition passed in
  isolation, and both the earlier sequential rerun and the current published
  sequential rerun pass **160/160**. No production semantic rule was weakened.
- the historical V2 selector referenced its former service path. The package now
  lives at `apps/v2/iris-commentary-orchestration`; the correct current package
  passes **9/9**.

The first publication hook for the source/test remediation evaluated 63
dependency-aware projects at repository-defined parallelism four. Directly
changed packages passed, as did the BFF ratchet, but the hook also reported
unrelated existing failures in `@yemaya/agents`,
`@oshun/v10-rail-channel-ori-presence`, and `@oshun/v10-case-files-cook`. Those
dependent failures are not represented as passing or repaired by PROOF-002.
`SKIP_TYPECHECK=1` was used only after the direct package typechecks above
passed. The shared-config commit used the same escape because it would otherwise
expand to a 236-project gate on this sub-32-GiB host; its ten directly affected
library/spec configs and all eleven value-suite surfaces passed.

No full workspace sweep or AUD-003's separate 54-config refresh was attempted or
claimed.

## Artifact identity

These hashes were computed from the current implementation publication tip
`734b7bd04105fc3e8c762c9c1451390f3ef0614e`.

| Artifact                               | SHA-256                                                            |
| -------------------------------------- | ------------------------------------------------------------------ |
| Canonical semantic-grounding contract  | `3fcf69ab4593c17242316986ad3b7990089f0eca931d51606b62fdfb202efbf2` |
| V1 Sophia generation boundary          | `9e176ee4647d3d3c09f947c2ce24c6a7254ef33884ff69091801fd752fafd5b3` |
| V2 authoritative commentary boundary   | `69ad630c59c7c45e99b35d36a2cbb9fe87b24a3299ceadb282383d7fc88deac2` |
| Iris authoritative commentary boundary | `9e12a9e24438f1a84cfc5f6c91f4447b760d1be3ba5fbd590a960cc8bc1b3aff` |
| V6 Clio semantic boundary              | `b9e2876bfa286aaa292279749c7a8c677ed80264b532bd64b175cdfb804a12e3` |
| V7 Mawu semantic boundary              | `5b2e353a12f3f39d2a2d9b475b496bae1ee540019a1428526d362917dc5f57c5` |
| V9 citation-sufficiency verifier       | `e06399d875a741f0dfd99b8fa18196d01dfb8b49f19b8d23922cc6fa5cefd1b3` |
| V9 lesson source/claim generation      | `7d5d46a5b2362ca6e3c22767e4f34699c2d822d6e04a48d886993fbdc49776a0` |
| Iris weighted-provider compatibility   | `c547c3172a3818b18fcf14fcc77dc17c15e72d514b200db560326726f8ed1a0a` |
| Shared Vitest 4 worker configuration   | `58510ca1547ca65da4972f674ba40c56637080d6480bcfa2b24c17938338d0f3` |

## Human authority and external deployment boundary

Repository publication of these boundaries and fixtures requires no fabricated
human signoff, and none is claimed. A passing fixture proves deterministic
contract behavior; it is not a live retrieval event, authoritative match feed,
human approval, or production entailment decision.

- production verifier ports require real model/service configuration at their
  composition roots. Absence intentionally blocks or falls back;
- rights, consent, authenticated signature, byte-bound provenance, and C2PA
  receipt producers remain PROOF-003/external deployment scope;
- no live Sophia provider, match feed, third-party retrieval service, external
  NLI service, production credential, population outcome, or deployment was
  claimed.

## Resource-safe verification and UI scope

The refresh host was `app-dev-server`, Ubuntu 24.04.4 LTS, Linux
`6.8.0-134-generic` x86_64, with 15 GiB RAM, 31 GiB swap, and 16 GiB free disk.
The toolchain was Node.js `v24.15.0`, pnpm `10.25.0`, TypeScript `6.0.3`, and
Vitest `4.1.7`; `pnpm-lock.yaml` SHA-256 was
`08b055786e9b8a6104d5313601d7eef3205dedcf395066fd9a8264c9859d690f`.

An unrelated checkout's long-running Vitest worker and this checkout's Nx daemon
were active. Focused gates ran sequentially. A 236-project hook fan-out was
stopped early; the 63-project affected hook was supervised and remained above
the 2 GiB available-memory stop threshold. No full workspace gate was started.

This refresh changes backend library typing, tests, test configuration, and
evidence only. It does not change customer/admin/PWA/mobile/Unreal UI, so the
frontend skill, Playwright, mobile automation, screenshots, and Unreal
verification are inapplicable.

## Publication identity

- **Original semantic-boundary source commit:**
  `40d160fb7cf8941522a290682a781c80b2f2f9a6`
- **Historical evidence-pack commit on the current graph:**
  `630c479147b5b7058801c963f308142f64edae08`
- **Historical ledger closure commit:**
  `ff9933f202bc443fbe3edbccf3f3e717770590ae`
- **Historical declared closure evidence identity:**
  `09c1ea147df55a6eea5083b095eb8541f14743d1`
- **Current source/test remediation:**
  `7faca4cc67cb27534228053f104f533763ec67d4`
- **Current Vitest 4 compatibility and admitted verification tip:**
  `734b7bd04105fc3e8c762c9c1451390f3ef0614e`
- **Current evidence-refresh commit:** recorded by the task-scoped commit that
  contains this file.
