# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/against-what-ordering-invariants-must-an-instance-reconstruct-state-transitions-when-reasoning-across-asynchronous-events.md
# Remnant Warrant:    https://corpusfetch.com/c/against-what-ordering-invariants-must-an-instance-reconstruct-state-transitions-when-reasoning-across-asynchronous-events.warrant.json
# Markdown SHA-256:   776e8221b896bcb254ce13d6e8c9ab8f2712603a4997a593adef7e38e0a5b2c7
# Code AST SHA-256:   81b9e47269b4fc1c5f87e21259d0c60fb631aba248efa778c0c5318038ec49ad
# Verified Classes:   CausalOrderingViolationError, CausalEventEnvelope, ReconstructedTimeline, CausalOrderReconstructor
# Defensive Guards:   4 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from typing import Any


class CausalOrderingViolationError(RuntimeError):
    '''Raised when an asynchronous event stream contains unresolvable sequence gaps or concurrent forks.'''
    pass


@dataclass(frozen=True)
class CausalEventEnvelope:
    event_id: str
    entity_id: str
    seq_num: int
    prev_seq_num: int
    payload: dict[str, Any]
    wall_clock_ms: int = 0


@dataclass(frozen=True)
class ReconstructedTimeline:
    entity_id: str
    settled_seq_num: int
    applied_event_ids: tuple[str, ...]
    dropped_stale_event_ids: tuple[str, ...]
    buffered_gap_seq_nums: tuple[int, ...]


class CausalOrderReconstructor:
    '''
    Reconstructs deterministic state transitions across out-of-order asynchronous events:
    1. Ignores `wall_clock_ms` and arrival order in favor of `(prev_seq_num -> seq_num)` causal links.
    2. Drops duplicate/stale events where `seq_num <= current_seq` without regressing state.
    3. Detects concurrent forks (two distinct events claiming the same `seq_num` / `prev_seq_num`).
    4. Holds back out-of-order future events and raises `CausalOrderingViolationError` if a gap remains.
    '''

    @classmethod
    def reconstruct_entity_stream(
        cls,
        *,
        entity_id: str,
        initial_seq: int,
        unordered_events: list[CausalEventEnvelope],
    ) -> ReconstructedTimeline:
        current_seq = initial_seq
        applied: list[str] = []
        dropped_stale: list[str] = []
        by_seq: dict[int, CausalEventEnvelope] = {}

        for ev in unordered_events:
            if ev.entity_id != entity_id:
                raise ValueError(f"Event '{ev.event_id}' belongs to entity '{ev.entity_id}', expected '{entity_id}'.")

            if ev.seq_num <= current_seq:
                dropped_stale.append(ev.event_id)
                continue

            # Gate 4: Detect concurrent fork on identical sequence slot
            if ev.seq_num in by_seq and by_seq[ev.seq_num].event_id != ev.event_id:
                existing = by_seq[ev.seq_num]
                raise CausalOrderingViolationError(
                    f"Concurrent Fork Detected on '{entity_id}' at seq={ev.seq_num}: "
                    f"event '{existing.event_id}' || event '{ev.event_id}'. Refuse wall-clock tie-breaking."
                )

            if ev.prev_seq_num != ev.seq_num - 1:
                raise CausalOrderingViolationError(
                    f"Broken causal link in event '{ev.event_id}': seq_num={ev.seq_num} "
                    f"cannot follow prev_seq_num={ev.prev_seq_num}."
                )

            by_seq[ev.seq_num] = ev

        # Gate 3: Drain contiguous causal sequence starting from current_seq + 1
        while (current_seq + 1) in by_seq:
            next_ev = by_seq.pop(current_seq + 1)
            current_seq = next_ev.seq_num
            applied.append(next_ev.event_id)

        if by_seq:
            missing_next = current_seq + 1
            buffered_seqs = tuple(sorted(by_seq.keys()))
            raise CausalOrderingViolationError(
                f"Causal sequence gap on '{entity_id}': settled through seq={current_seq}, "
                f"missing seq={missing_next}, while future seqs {buffered_seqs} are buffered."
            )

        return ReconstructedTimeline(
            entity_id=entity_id,
            settled_seq_num=current_seq,
            applied_event_ids=tuple(applied),
            dropped_stale_event_ids=tuple(dropped_stale),
            buffered_gap_seq_nums=(),
        )