# V2-001 — Invoked commentary and Hathor NPC safety evidence

- Owner: Codex implementation agent
- Accountable product: V2
- Priority: P0 product acceptance slice
- Linked task: V2-001, authoritative commentary and Hathor NPC output validation
- Source commits:
  - `89e16c774fd123b869b1de3989e38f988c03da8a`
  - `79d3c53c0407136c67eeded1a49f3c9a266cdfdc`
  - `0172b9c22b4a3b69ca9e446a918c708bd61ac324`
  - `4436396cc24e26b19abe5a3ba4d898ae97df5146`
  - `c0ad0010628dd9fadeba671320942216f05e7007`
- Evidence captured: 2026-07-24T17:50:46Z
- Host: Linux x86_64, kernel
  `6.8.0-110-generic #110-Ubuntu SMP PREEMPT_DYNAMIC Thu Mar 19 15:09:20 UTC 2026`
- Rollout: deploy the additive proto field and verifier dependency with the V2
  gRPC service, and deploy the Hathor response-contract/cache-schema update with
  the V2 NPC adapter; package the exact verified commentary banks with the V2
  content revision. Old/missing evidence fails validation instead of generating
  or returning.
- Rollback: revert the commentary source commit and generated Buf image
  together, revert the Hathor core and adapter source commit together, or revert
  the bank files, manifest, verifier, and Unreal mirror together. Do not deploy
  revisions whose proto, canonical Hathor types, adapter, cache schema, bank
  bytes, or recorded hashes disagree.

## Implemented boundary

The V2 commentary proto now transports the exact authoritative snapshot
reference, capture time, fact references, and fact text at the cue frame. The
gRPC adapter maps that snapshot into the Iris request and injects an
`IrisMatchCommentaryFactVerifier` supplied by service composition. A generated
line is released only when its semantic proof bundle passes inside the cue's
latency budget.

The wire contract distinguishes missing verifier, missing authoritative state,
failed fact verification, timeout, empty response, provider error, and missing
orchestrator. Contradictory generation therefore becomes a labeled
pre-recorded-bank fallback rather than an unsupported live claim. Requests with
no authoritative snapshot are rejected before provider invocation.

The gRPC service also owns a bounded measurement recorder. Every response
increments generated or fallback counts, every fallback is grouped by its
explicit wire reason, every rejected request is counted separately, and
successful/fallback response latency is accumulated into fixed buckets plus
sum/max. The server handle exposes the recorder so deployment composition can
export or inspect the snapshot without parsing response logs.

Both model-prompt boundaries use `@oshun/prompt-trust`. Live cue instructions
are branded authority, while request cue, rights, and authoritative-state fields
are rendered as bounded non-instruction data. The renderer neutralizes
literal/encoded delimiter smuggling and records renderer version, exact prompt
SHA-256, and typed trust labels in request metadata. The pre-existing V2
post-match writer and broadcast reviewer use the same renderer. Their
deterministic broadcast rules are evaluated independently and remain capable of
blocking generated prompt-control text when the model reviewer returns
`{"findings":[]}`.

The V2 NPC adapter now consumes Hathor's canonical response types through a
type-only package export instead of maintaining a weaker duplicated contract.
Hathor binds the selected personality ID to the requested NPC before provider
invocation and returns that persona identity with every answer or abstention.
Before V2 returns or caches dialogue, it validates persona, emotion, intent,
bounded action IDs, memory retrieval/use attribution, calibrated confidence,
threshold status, and abstention semantics. Triggered memories must exactly
equal validated attributed IDs; answered output must clear its threshold; and
abstentions cannot carry actions or triggered memories. Cached dialogue is
revalidated on read, and the cache schema is advanced so older weaker entries
fail closed.

The repository-local rollback-hashing portion of the commentary fallback path is
also closed. Each launch persona now has a source-controlled 24-line bank
covering every supported cue kind at least twice. The manifest and Unreal
defaults carry the exact-byte SHA-256 and line count, while the TypeScript cook
boundary and Python contract checker reject missing files, path escapes,
repeated-character digests, byte drift, identity drift, incomplete cue coverage,
and disagreement with the Unreal mirror. Fallback selection is deterministic
over the full `(cueKind,ruleset,commentatorId,seed)` identity and does not enter
rollback simulation state.

## Verification

All runnable commands ran at the source commit on 2026-07-24 UTC; the final row
records the attempted Unreal command and its host blocker:

| Command                                                                                                                                                                | Result                                                                                                                                                  |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pnpm --filter @v2/grpc-services test`                                                                                                                                 | PASS — 1 file, 18 tests                                                                                                                                 |
| `pnpm --filter @v2/grpc-services typecheck`                                                                                                                            | PASS                                                                                                                                                    |
| `pnpm --filter @v2/grpc-services lint`                                                                                                                                 | PASS                                                                                                                                                    |
| `pnpm --filter @v2/grpc-services build`                                                                                                                                | PASS                                                                                                                                                    |
| `pnpm exec vitest run --config libs/iris/conversation-orchestration/vitest.config.ts libs/iris/conversation-orchestration/src/match-commentary.spec.ts --maxWorkers=1` | PASS — 1 file, 7 tests                                                                                                                                  |
| `pnpm --filter @v2/iris-commentary-orchestration test`                                                                                                                 | PASS — 1 file, 9 tests                                                                                                                                  |
| `pnpm exec vitest run libs/calliope/match-commentary/src/match-commentary.test.ts --maxWorkers=1`                                                                      | PASS — 1 file, 9 tests                                                                                                                                  |
| Focused ESLint over the changed Iris and V2 service sources/specs                                                                                                      | PASS                                                                                                                                                    |
| `pnpm exec tsc --noEmit -p libs/iris/conversation-orchestration/tsconfig.lib.json`                                                                                     | PASS                                                                                                                                                    |
| `pnpm --filter @v2/iris-commentary-orchestration typecheck`                                                                                                            | PASS                                                                                                                                                    |
| `pnpm exec buf build --path src/oshun/v2/ai_commentary/commentary.proto` from `libs/proto`                                                                             | PASS                                                                                                                                                    |
| `pnpm codegen:proto && pnpm codegen:proto:check`                                                                                                                       | PASS — generated image current                                                                                                                          |
| `pnpm exec vitest run --config libs/hathor/llm-npc/vitest.config.ts --no-file-parallelism`                                                                             | PASS — 10 files, 110 tests                                                                                                                              |
| `pnpm exec vitest run --config apps/v2/hathor-npc-adapter/vitest.config.ts --no-file-parallelism`                                                                      | PASS — 1 file, 9 tests                                                                                                                                  |
| `pnpm --dir libs/hathor/llm-npc run typecheck`                                                                                                                         | PASS                                                                                                                                                    |
| `pnpm --dir apps/v2/hathor-npc-adapter run typecheck`                                                                                                                  | PASS                                                                                                                                                    |
| Strict ESLint over all Hathor and V2 NPC adapter TypeScript                                                                                                            | PASS — zero warnings                                                                                                                                    |
| `pnpm --dir libs/hathor/llm-npc run build`                                                                                                                             | PASS                                                                                                                                                    |
| `pnpm --dir apps/v2/hathor-npc-adapter run build`                                                                                                                      | PASS                                                                                                                                                    |
| `python3 V2/ue/Tools/check-v2-hathor-llm-npc.py`                                                                                                                       | PASS                                                                                                                                                    |
| `pnpm exec vitest run --config apps/v2/calliope-commentator-personas/vitest.config.ts --no-file-parallelism`                                                           | PASS — 1 file, 7 tests                                                                                                                                  |
| `pnpm --dir apps/v2/calliope-commentator-personas run typecheck`                                                                                                       | PASS                                                                                                                                                    |
| Strict ESLint over all `@v2/calliope-commentator-personas` TypeScript                                                                                                  | PASS — zero warnings                                                                                                                                    |
| `pnpm --dir apps/v2/calliope-commentator-personas run build`                                                                                                           | PASS                                                                                                                                                    |
| `python3 -m py_compile V2/ue/Tools/check-v2-calliope-commentator-personas.py`                                                                                          | PASS                                                                                                                                                    |
| `python3 V2/ue/Tools/check-v2-calliope-commentator-personas.py` with the committed source lockfile                                                                     | PASS                                                                                                                                                    |
| `UnrealEditor-Cmd V2.uproject -ExecCmds="Automation RunTests V2.Audio.Module; Quit" ...`                                                                               | HISTORICAL NOT RUN — the required engine path and `ueagent` were absent during the recorded 2026-07-24 attempt                                          |
| `pnpm proto:lint`                                                                                                                                                      | FAIL on the repository's pre-existing cross-portfolio Buf lint debt; the output contains thousands of unrelated package-layout and documentation errors |
| `pnpm exec buf lint --path src/oshun/v2/ai_commentary/commentary.proto` from `libs/proto`                                                                              | FAIL on pre-existing missing comments in the V2 proto; no syntax/build error                                                                            |

The value-asserting gRPC suite starts the actual `grpc-js` server and proves:

- an entailed provider line traverses the wire as generated commentary;
- a false submission claim against a knockout snapshot falls back with
  `FALLBACK_REASON_FACT_VERIFICATION_FAILED`;
- missing authoritative state returns `INVALID_ARGUMENT`;
- provider outage is a labeled deterministic fallback;
- provider outage increments the exact fallback-reason counter and cumulative
  latency histogram;
- invalid authoritative state increments rejection count without contaminating
  response-latency observations;
- rollback-frame calls return `FAILED_PRECONDITION`; and
- duplex streaming emits one governed result per request.
- a literal closing-delimiter injection is neutralized inside the live cue zone;
- live prompt metadata carries the canonical renderer version, exact SHA-256,
  and non-instruction trust label;
- post-match writer and reviewer prompts use the same typed renderer; and
- deterministic post-match rules block prompt-control text even when the model
  reviewer returns no findings.
- Hathor rejects a personality whose ID is not the requested NPC before the
  provider is called;
- V2 preserves the valid persona, intent, actions, attributed memories, response
  state, calibration version, score, and component evidence;
- foreign personas, unknown intents, path-like actions, fabricated memory
  triggers, uncalibrated scores, malformed responses, and action-bearing
  abstentions fail as `invalid_runtime_output`; and
- cached dialogue with drifted confidence evidence is rejected without calling
  the runtime.
- exact fallback-bank bytes, identities, locale, line counts, and complete cue
  coverage validate for all four launch personas;
- repeated-character or byte-drifted hashes fail closed; and
- identical full-key fallback selections return the same authored line.

## Artifact hashes

| Artifact                                                                 | SHA-256                                                            |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------ |
| `apps/v2/grpc-services/src/commentary-service.ts`                        | `8bef0ee49f53ca499839463cfcd12056278ab82dab7e08fcade3e1b1a5d3a883` |
| `apps/v2/grpc-services/src/server.ts`                                    | `3f68001752971d05937f414bba1fc4106f517ea0a8bd5611d1db81343adf8dd6` |
| `apps/v2/grpc-services/src/grpc-services.spec.ts`                        | `529dda907975581d1b4ac48a13fbc3e8a18cd897fb6bea973be06cfb315f3df6` |
| `libs/proto/src/oshun/v2/ai_commentary/commentary.proto`                 | `385808408f3067b99dbf39acc3573600f6a251cc567f91a880608b61b5620a7d` |
| `libs/proto/generated/buf-image.json`                                    | `7d718bf38337f2905650427f774bdf4cf00c04fbf23b0e27e3a2eac605297e4a` |
| `libs/iris/conversation-orchestration/src/match-commentary.ts`           | `d10827a471178bacb7d825bb4fd343fdc585e8d8f7a56eae0c680ab40790f5d6` |
| `libs/iris/conversation-orchestration/src/match-commentary.spec.ts`      | `1c122b7cc0a88a442580aa71d999cc17b1a58b58c3d7cb5663cc0a576ffaa0d6` |
| `libs/calliope/match-commentary/src/commentary-generator.ts`             | `be904d3a71595d0de864b2f0693b5df73e283fcd6d55dcaf1abd8e8ea72ef5e4` |
| `libs/calliope/match-commentary/src/match-commentary.test.ts`            | `a7e85b8b0e827e249598cea8ef3948018e0c5e097518cde174fe114f886f0e74` |
| `libs/hathor/llm-npc/src/types.ts`                                       | `136db3a4d72d041e298a7d4a6ed2c7649de2ace61ded67f71e248703caea4510` |
| `libs/hathor/llm-npc/src/dialogue/dialogue-generator.ts`                 | `6e8a7896ac6c814726b56280b522470ab4e9240b451b0183a1b47380fdcb18f9` |
| `libs/hathor/llm-npc/src/dialogue/dialogue-generator.spec.ts`            | `b0b23cff1ca57ed73961dbcd196199357b9b9d654b717ee2408ee226c877598b` |
| `apps/v2/hathor-npc-adapter/src/npc-bridge.ts`                           | `737eb8c21c883df510824481d532cf7b37d3cb01f464ee300d85094c8388c087` |
| `apps/v2/hathor-npc-adapter/src/npc-bridge.spec.ts`                      | `e01a2925bb103aa34bd1199a1b0d1878e5966294747c9092d3e80482e2d8aeff` |
| `apps/v2/hathor-npc-adapter/src/npc-dialogue-cache.ts`                   | `c4f9ccf1c32ccd69a3735a07be66dabb4bbdfad36a22898635d3684686316ba8` |
| `V2/ue/Tools/check-v2-hathor-llm-npc.py`                                 | `fe07d6529b71a1aac7be6fe86cac4c72928414e722406b03b968f56bb6716e40` |
| `apps/v2/calliope-commentator-personas/src/commentator-personas.ts`      | `a994bcfc5a159ed45fbb669ca227b452595fc05abb4a741c4e22f9d3f6fbbcc2` |
| `apps/v2/calliope-commentator-personas/src/commentator-personas.spec.ts` | `c1638c29fba50959d06ec2ea14bc5b52c1d6db4e88a33f78d2cb569b59aa00c2` |
| `V2/ue/Content/V2/Audio/Commentary/commentator-personas.json`            | `d58fe639ebc5c237305dd1f10de7fe8a839ef025e3108379d6515e845716da4c` |
| `V2/ue/Content/V2/Audio/Commentary/FallbackBanks/aria-voss.en-US.json`   | `89f0ca284d3afdc71edd2e8530a86585a9b502f90fd8cbbe52af75c215e2e792` |
| `V2/ue/Content/V2/Audio/Commentary/FallbackBanks/dante-cross.en-US.json` | `cb2f69078e7101a3bcd8989f776414c415d818781ba034b3396aba71864d6997` |
| `V2/ue/Content/V2/Audio/Commentary/FallbackBanks/marcus-knox.en-US.json` | `b3ceedb0e02053a1935178f833946bc6d3426fd15d64cee15599f14ce870bcba` |
| `V2/ue/Content/V2/Audio/Commentary/FallbackBanks/yuna-park.en-US.json`   | `8784c170096b9599b12c97b32aaea0df702992b3c1fe9b8265840fd062d39e76` |
| `V2/ue/Source/V2Audio/Private/V2AudioBlueprintLibrary.cpp`               | `fb53688e38b0384a63f38a7b73ce4d07f1a4f5f144dad344d037437e9886c6c3` |
| `V2/ue/Tools/check-v2-calliope-commentator-personas.py`                  | `e14709120fbe2b14ab7ac4850f4388cc5a97f8559fe1da8cfe8ee082383b5031` |

## Honest boundary

This evidence closes only the repository implementation and invoked gRPC/NPC
adapter proofs for authoritative-state verification and Hathor safety-output
validation. The commentary verifier, commentary provider, and NPC runtime used
in tests are controlled doubles. There is no claim of live provider traffic,
deployed V2 service operation, translation, TTS, face/lipsync rendering, live
provider NPC dialogue, consented voice, Unreal playback/cook, production
latency, player preference, or accessibility verification. Those real-path
V2-001/V2-002 gates remain open. In particular, source-controlled content hashes
do not prove in-engine playback, production rollback behavior, consent, latency,
disclosure, caption rendering, ducking, or accessibility. The targeted Unreal
automation could not run during the source-bound 2026-07-24 attempt because the
documented engine checkout and `ueagent` account were then absent; the current
host disposition is superseded below.

## Live-execution evidence gate

Evidence-gate source commit: `1d7142e76f29dc32fbf057329bb69584b423d00a`.

The two remaining V2-001 requirements now share a machine-verifiable, fresh-run
contract:

- `scripts/v2/verify-live-execution-evidence.mjs`
- `evidence/v1-v9/V2-001-live-execution-evidence.json`
- `evidence/v1-v9/V2-001-live-execution-readiness.json`

The gate requires live grounded commentary plus one immutable provider receipt
for translation, TTS, lipsync, and face animation; live validated NPC turns and
a service-operation receipt; exact source and fallback hashes; measured
generated and fallback latency tiers; active voice consent; an actually rendered
AI disclosure; rendered attributed captions; measured playback ducking;
accessibility automation; and healthy canary operations with costs, alerts, and
a verified rollback drill. URI-shaped placeholders such as `iris-voice://`,
controlled-double provider identifiers, package plans without rendered output,
and configuration flags without observed playback all fail closed.

The retained readiness report is `blocked` with every check false. The
repository currently exposes package-level plans and controlled test adapters,
but no retained live provider, media-render, player-presentation, deployment, or
rollback-drill receipts.

The 2026-07-27 statement that this host lacked Unreal and `ueagent` is now
historical and superseded. Source-bound preflight on 2026-08-02 proves that the
UE 5.5.4 editor, `RunUAT.sh`, `ueagent`, V2 project descriptor, and enabled EOS
editor binary are present. It also proves that the retained V2 editor modules
have build ID `43c40849-16a9-4317-b4b9-c7a9a7e8b72d`, while the current engine
has build ID `9729efc9-d09a-46a2-bf07-036739f64d68`; the qualified editor and
cook invocations therefore remain blocked pending a resource-safe V2Editor
rebuild. This is a project-build freshness blocker, not engine unavailability,
and it does not supply any live-provider or runtime result. Machine evidence:
`evidence/v1-v9/V2-unreal-host-preflight.json`. No remaining V2-001 checkbox is
closed by this preflight.

Verification passed:

- Prettier and ESLint over the gate and adversarial suite.
- `node --check scripts/v2/verify-live-execution-evidence.mjs`.
- `node --test scripts/v2/verify-live-execution-evidence.test.mjs` — 9/9.
- `node --test scripts/v2/v2-unreal-host-preflight.test.mjs` — 6/6.
- `node scripts/v2/v2-unreal-host-preflight.mjs --verify=evidence/v1-v9/V2-unreal-host-preflight.json`
  — verified the retained `rebuild-required` disposition against the current
  host.
- The default CLI returned nonzero for the retained blocked evidence.
- `--report` reproduced the retained readiness JSON byte-for-byte after
  formatting.

To update the boundary after an authorized live run:

```sh
node scripts/v2/verify-live-execution-evidence.mjs \
  --evidence=evidence/v1-v9/V2-001-live-execution-evidence.json \
  --report
```

Only `status: "ready"` with all six checks true is sufficient to support closing
the two remaining V2-001 checklist items.
