# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-does-an-instance-detect-divergence-between-a-forked-speculative-branch-and-its-deterministic-replay-in-agent-rollback-auditing.md
# Remnant Warrant:    https://corpusfetch.com/c/how-does-an-instance-detect-divergence-between-a-forked-speculative-branch-and-its-deterministic-replay-in-agent-rollback-auditing.warrant.json
# Markdown SHA-256:   546bae665de7bc4bf56a6031a6a8d29ad0ddc31f536b2a3a0791dc90166e2b3d
# Code AST SHA-256:   a87d50717a491fc226da6ebff29b1dc1ec544265400ca0a82999293565693b34
# Verified Classes:   ReplayMode, ReplayDivergenceError, Token, ReplayCursor
# Defensive Guards:   5 fail-closed invariants (zero external deps)

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()