# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-happens-when-an-instance-is-replayed-against-a-trace-it-never-emitted-counterfactual-divergence-and-the-non-determinism-floor-in-otel-genai-postm.md
# Remnant Warrant:    https://corpusfetch.com/c/what-happens-when-an-instance-is-replayed-against-a-trace-it-never-emitted-counterfactual-divergence-and-the-non-determinism-floor-in-otel-genai-postm.warrant.json
# Markdown SHA-256:   c533521474e6a3db8b5771a9d393a2e0753ec562380b501a61063efb790b3803
# Code AST SHA-256:   f3188521d8d3ef8600c21416670ec6e93ff6292064c2330a1b801bbd28e94c6d
# Verified Classes:   ReplayPreconditionError, DecisionStep
# Defensive Guards:   2 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from typing import Sequence


class ReplayPreconditionError(RuntimeError):
    """Raised when counterfactual analysis is attempted on an unreproduced trace."""


@dataclass(frozen=True)
class DecisionStep:
    operation: str
    tool_name: str | None
    normalized_args: str
    finish_reason: str


def decision_projection(trace_steps: Sequence[DecisionStep]) -> tuple[DecisionStep, ...]:
    # The declared, versioned projection: decision-relevant only.
    return tuple(trace_steps)


def measure_reproduction_floor(
    original: Sequence[DecisionStep],
    replays: Sequence[Sequence[DecisionStep]],
) -> float:
    if not replays:
        raise ReplayPreconditionError("no replays supplied; cannot establish floor")
    target = decision_projection(original)
    diverging = sum(1 for r in replays if decision_projection(r) != target)
    return diverging / len(replays)


def run_counterfactual(
    original: Sequence[DecisionStep],
    replays: Sequence[Sequence[DecisionStep]],
    perturbed: Sequence[DecisionStep],
    max_floor: float = 0.0,
) -> int:
    floor = measure_reproduction_floor(original, replays)
    if floor > max_floor:
        raise ReplayPreconditionError(
            f"reproduction floor {floor:.3f} exceeds {max_floor:.3f}; "
            "trace is not a sufficient statistic, counterfactual is invalid"
        )
    target = decision_projection(original)
    cand = decision_projection(perturbed)
    for idx, (a, b) in enumerate(zip(target, cand)):
        if a != b:
            return idx
    if len(target) != len(cand):
        return min(len(target), len(cand))
    return -1  # no divergence


def attribute_incident(
    original: Sequence[DecisionStep],
    replays: Sequence[Sequence[DecisionStep]],
    perturbed: Sequence[DecisionStep],
) -> str:
    idx = run_counterfactual(original, replays, perturbed)
    if idx < 0:
        return "perturbation had no causal effect on decision sequence"
    step = decision_projection(original)[idx]
    return f"first causal divergence at decision {idx}: {step.operation}/{step.tool_name}"
