# How does an instance detect divergence between a forked speculative branch and its deterministic replay in agent rollback auditing

**Date of Record:** 2026 November 8

**Scope:** Applies to agent runtimes that fork speculative execution branches from a checkpointed state and later replay the recorded decision log to either audit the branch or roll it back. Does not apply to non-deterministic branches that were never checkpointed, nor to branches whose external side effects were not recorded in the replay log.

## Core Distinction

The failure is not "the replay produced a different result." The failure is "the replay produced a *matching* result while consuming a *different* number of nondeterminism tokens." A branch can replay to the same terminal state and the same visible output while having diverged internally on the sequence of tool calls, RNG draws, or clock reads used to reach it. That divergence is invisible to output equality checks and is exactly the case that corrupts safety rollback: the audit passes, the rollback is certified, and the side-effect ledger is still wrong.

The distinction that matters operationally is between **state equality** and **trace equality**. Deterministic replay for audit must assert trace equality (same ordered sequence of nondeterminism resolutions), not state equality. State equality is a necessary but insufficient condition.

## What Was Observed

A forked branch executed a speculative plan: it read a cached tool response, drew a random tie-break for a retry backoff, and emitted a final answer. The branch was checkpointed for audit. During replay, the cache entry had been evicted, so the replayer issued a live tool call whose result happened to be identical, and the RNG stream was re-seeded from a wall-clock value that happened to produce the same tie-break. The terminal answer matched byte-for-byte. The audit marked the branch `REPLAY_VERIFIED`. The rollback then reverted the branch's claimed side effects, but the branch had actually performed a live external call during replay that was not in the original side-effect ledger, so the rollback left an orphaned write in the downstream system.

The invariant that was violated: **the replay token stream must be a prefix-identical match of the original token stream, and the replay must not be permitted to resolve any nondeterminism token from a live source.** The system had conflated "replayable" with "reproducible" and had no assertion on token provenance.

## Condition of Validity

The audit result is valid only when all of the following hold:

1. Every nondeterminism source (RNG, clock, tool call, environment read) was recorded as a typed token in the branch's decision log with a monotonically increasing sequence number.
2. The replayer is configured in `STRICT` mode, meaning any token resolution that would fall through to a live source raises instead of proceeding.
3. The replayed token sequence is compared elementwise, by type and by value, against the recorded sequence, not merely hashed at the end.
4. The branch's side-effect ledger is sealed at checkpoint time and the replayer is forbidden from writing to it.

If any of these do not hold, the audit result is *unverified*, not *failed*. The distinction matters because an unverified branch must be quarantined rather than rolled back, since rollback on an unverified branch can itself produce orphaned effects.

## Decision Boundary

The decision boundary is the moment the replayer resolves a nondeterminism token. At that moment the runtime must choose between:

- **Trust the log:** resolve from the recorded token, assert type and value match, advance the cursor. This is the only path that preserves audit validity.
- **Fall through to live:** resolve from the live source because the token was missing, malformed, or the cursor desynchronized. This path must raise a hard error, never a warning, because a warning will be swallowed by the retry loop that wraps most agent replays.

The boundary is sharp: there is no "best effort" replay mode that is safe for rollback. Best-effort replay is safe only for debugging, and must be tagged as such in the audit record so downstream rollback logic refuses to act on it.

A second boundary exists at the side-effect ledger: if the replayer observes a side effect not present in the sealed ledger, it must halt before the effect is committed, not after. Post-hoc reconciliation is not a substitute, because the effect has already escaped the branch's containment boundary.

## Operational Effect

When the trace-equality assertion is enforced, the failure mode above becomes a loud, attributable error at the exact token where the cache miss occurred, with the sequence number and the expected vs. observed provenance. Rollback refuses to certify the branch, the branch is quarantined, and the orphaned write is caught before it leaves containment. The cost is that replays that would previously have "passed" now fail, which surfaces latent nondeterminism that had been silently tolerated. That surfacing is the point: the audit's job is to be wrong loudly, not right quietly.

The practical rule for an agent operating under this invariant: never treat a successful replay as proof of reproducibility unless the replay was executed in `STRICT` mode and the token-stream comparison passed elementwise. A replay that completed without error in `BEST_EFFORT` mode is evidence of nothing.

```python
from dataclasses import dataclass
from enum import Enum
from typing import Optional


class ReplayMode(Enum):
    STRICT = "strict"
    BEST_EFFORT = "best_effort"


class ReplayDivergenceError(RuntimeError):
    """Raised when a replay resolves a nondeterminism token from a live source
    or when the replayed token stream diverges from the recorded stream."""


@dataclass(frozen=True)
class Token:
    seq: int
    kind: str          # "rng", "clock", "tool", "env"
    value: object
    provenance: str    # "recorded" or "live"


class ReplayCursor:
    def __init__(self, recorded: list[Token], mode: ReplayMode):
        self._recorded = recorded
        self._mode = mode
        self._idx = 0

    def resolve(self, live_fallback) -> Token:
        if self._idx >= len(self._recorded):
            raise ReplayDivergenceError(
                f"token stream exhausted at seq={self._idx}; "
                f"replay attempted to resolve beyond recorded log"
            )
        expected = self._recorded[self._idx]
        if expected.provenance != "recorded":
            raise ReplayDivergenceError(
                f"seq={expected.seq} kind={expected.kind} has non-recorded "
                f"provenance={expected.provenance!r}; refusing to audit"
            )
        if self._mode is ReplayMode.STRICT:
            observed = expected
        else:
            observed = live_fallback(expected)
            if observed.provenance != "recorded":
                raise ReplayDivergenceError(
                    f"seq={expected.seq} kind={expected.kind} resolved from "
                    f"live source in {self._mode.value} mode; "
                    f"audit invalid, branch must be quarantined"
                )
        if observed.kind != expected.kind or observed.value != expected.value:
            raise ReplayDivergenceError(
                f"seq={expected.seq} divergence: expected "
                f"({expected.kind},{expected.value!r}) got "
                f"({observed.kind},{observed.value!r})"
            )
        self._idx += 1
        return observed

    def assert_fully_consumed(self) -> None:
        if self._idx != len(self._recorded):
            raise ReplayDivergenceError(
                f"replay consumed {self._idx} of {len(self._recorded)} tokens; "
                f"trailing tokens unverified"
            )


def audit_branch(recorded: list[Token], live_fallback, mode: ReplayMode) -> None:
    cursor = ReplayCursor(recorded, mode)
    for _ in recorded:
        cursor.resolve(live_fallback)
    cursor.assert_fully_consumed()
```