# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-happens-when-an-instance-replays-a-trace-whose-side-effect-ordering-was-never-serialized.md
# Remnant Warrant:    https://corpusfetch.com/c/what-happens-when-an-instance-replays-a-trace-whose-side-effect-ordering-was-never-serialized.warrant.json
# Markdown SHA-256:   aa4bcccd527a7c8d204eb3adcd968dbcc6182b570bfb62969453ab30cf9373e2
# Code AST SHA-256:   050effd5a17837ee2f9b58aacd4edb0577e1f1313885174ab805c1034433bc35
# Verified Classes:   OrderIncompleteTraceError, TraceEvent
# Defensive Guards:   2 fail-closed invariants (zero external deps)

class OrderIncompleteTraceError(RuntimeError):
    """Raised when a trace lacks a recorded commit order for a dependent event pair."""
    pass


class TraceEvent:
    def __init__(self, event_id, kind, resource, commit_seq, recorded_result):
        self.event_id = event_id
        self.kind = kind                  # "write" | "read" | "delete"
        self.resource = resource
        self.commit_seq = commit_seq      # None if the trace never serialized it
        self.recorded_result = recorded_result


def assert_replay_is_evidentiary(events):
    """
    Refuse to re-derive results when a dependent pair lacks a recorded order.
    Dependent pair: same resource, at least one is a write or delete,
    and at least one is a read or delete that observes the other.
    """
    by_resource = {}
    for ev in events:
        by_resource.setdefault(ev.resource, []).append(ev)

    for resource, group in by_resource.items():
        if len(group) < 2:
            continue
        has_effect = any(e.kind in ("write", "delete") for e in group)
        has_observer = any(e.kind in ("read", "delete") for e in group)
        if not (has_effect and has_observer):
            continue
        seqs = [e.commit_seq for e in group]
        if any(s is None for s in seqs):
            raise OrderIncompleteTraceError(
                f"resource {resource!r} has a dependent event pair with no "
                f"recorded commit order: "
                f"{[(e.event_id, e.kind, e.commit_seq) for e in group]}. "
                f"Replay would be a simulation, not a reconstruction; "
                f"refusing to substitute re-derived results for recorded ones."
            )
        if len(set(seqs)) != len(seqs):
            raise OrderIncompleteTraceError(
                f"resource {resource!r} has duplicate commit_seq values; "
                f"order is ambiguous and cannot ground a forensic claim."
            )


def replay(trace):
    assert_replay_is_evidentiary(trace)
    # Order is proven; recorded results may now be trusted and re-derived
    # results are admissible because they are provably identical in order.
    return [ev.recorded_result for ev in sorted(trace, key=lambda e: e.commit_seq)]