# V2 Rollback Isolation

Rollback simulation consumes only deterministic inputs and match-start payload
bytes. AI Director output, Psyche tendency profiles, Iris commentary, and any
Oshun-sourced data arrive through a behavior-hint side-channel that rollback
does not read, hash, predict, rewind, or replay as simulation authority.

## Behavior-Hint Channel

The side-channel carries non-authoritative hints for presentation, coaching, and
post-frame recommendations:

- AI Director pacing suggestions for camera, encounter dressing, tutorial
  prompts, and post-round presentation.
- Psyche tendency profile summaries for out-of-band coaching and opponent-read
  overlays.
- Iris commentary intents, translated captions, and highlight narration.
- Oshun-sourced recommendations from event bus, gRPC, dashboards, or companion
  apps.

## Determinism Rules

- Rollback frame simulation ignores behavior hints completely.
- Behavior hints are never included in rollback snapshots, deterministic frame
  hashes, hit resolution, input prediction, correction, or replay verification.
- A hint can affect gameplay only if it is baked into the deterministic
  match-start payload before frame `0`, byte-identical on every peer, and
  recorded into the replay container.
- If an Oshun service is unavailable, rollback simulation must produce identical
  frame hashes.
- Presentation systems can drop, delay, or reorder hints without changing match
  outcome.

## Message Envelope

Every behavior hint uses this envelope before reaching Unreal:

```json
{
  "channel": "v2.behavior_hint",
  "matchId": "match_01HYV2",
  "frameObserved": 1842,
  "producer": "iris.commentary",
  "determinism": "ignored_by_rollback",
  "expiresAtFrame": 2040,
  "payloadHash": "sha256:9b861...",
  "payload": {
    "intent": "commentary.reversal_callout"
  }
}
```

Required fields:

- `channel` is always `v2.behavior_hint`.
- `frameObserved` is the latest resolved frame the producer may reference; it is
  not an input to simulation.
- `producer` identifies the source domain, such as `ai-director`,
  `psyche.tendency`, `iris.commentary`, or `oshun.recommendation`.
- `determinism` is always `ignored_by_rollback`.
- `expiresAtFrame` prevents late hints from being applied to presentation after
  their window is gone.
- `payloadHash` is for audit and cache de-duplication only.

## Unreal Routing

- `V2Services` receives behavior hints from Oshun services.
- `V2AdaptiveAI` may consume live `@psyche/behavior-prediction` hints only in
  non-rollback modes. Rollback-with-CPU modes receive only a match-start
  snapshot.
- `V2Telemetry`, `V2Audio`, `V2Cinematics`, `V2UI`, and non-authoritative
  director systems may subscribe.
- `V2Combat`, `V2Gameplay`, `V2Input`, and `V2Netcode` rollback do not subscribe
  and do not include the side-channel headers.
- Replays may store behavior hints as optional presentation metadata, but replay
  verification ignores that metadata and hashes only deterministic streams.

## Test Contract

Golden replay tests must pass with behavior hints present, absent, delayed, and
reordered. The expected deterministic frame hashes are identical in all four
cases.

`V2/ue/Tools/check-rollback-determinism.py` runs in CI with a self-test fixture.
It fails if `V2Netcode` rollback frame code references `V2AdaptiveAI`,
`@psyche/behavior-prediction`, `V2Services`, gRPC, or HTTP service reads, and it
also fails if `V2AdaptiveAI` contains live Psyche RPC/client reads instead of
match-start snapshot consumption.