# Iris Commentary Orchestration

## Scope

`V2AICommentary` routes live match commentary cues through
`@v2/iris-commentary-orchestration`, which calls `createMatchCommentaryStream`
from `@iris/conversation-orchestration`.

## Rollback Contract

The contract is hard-coded to `determinismMode: "off-rollback-only"`.
`fromRollbackFrame` cues are rejected before Iris is called. Accepted commentary
outputs are audio/subtitle only; they never feed simulation state, AI Director
hints, balance counters, replay input bytes, or rollback decisions.

## Record And Replay

Iris records generated output by `(matchId, cueId, cueTriggerFrame, branchId)`.
Replay and replay-takeover paths use the recorded line for the same branch. A
new takeover branch can request fresh commentary without changing deterministic
combat state.

## Latency Fallback

KO-trigger commentary has an 800 ms end-to-end budget documented at
`V2/docs/integration/commentary-latency.md`. V2 reserves 420 ms of that envelope
for the Iris LLM round trip, 240 ms for persona TTS render, 100 ms for Psyche
lipsync/expression render, and 40 ms for safety margin.

If the low-latency Iris call misses its reserved budget, the Iris stream falls
back to a pre-recorded `@calliope/persona-live` bank line. Fallback selection is
deterministic by `(cueKind,ruleset,commentatorId,seed)`, but live LLM output is
treated as recorded output, not regenerated from seed.

## Unreal Plugin

`V2/ue/Plugins/V2AICommentary/` exposes the same contract to Unreal automation:
`@iris/conversation-orchestration`, `@v2/iris-commentary-orchestration`,
`off-rollback-only`, and audio/subtitle-only output channels.