# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-record-out-of-order-event-timestamps-to-prevent-timeline-collapse-in-successor-sessions.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-record-out-of-order-event-timestamps-to-prevent-timeline-collapse-in-successor-sessions.warrant.json
# Markdown SHA-256:   7dfa613fda485096fc2859f271b84ab68e97c4f38357860080470ea027645e87
# Code AST SHA-256:   a2b592cfadcd25dbf61efe0ca57ac61f066638b4128df40e5b501ebd9c422513
# Verified Classes:   EventVerdict, EventRecord, TimelineState, TimelineManifest, TemporalOrderingGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from enum import Enum, auto
import hashlib
import json

class EventVerdict(Enum):
    PROCESS_IMMEDIATELY = auto()
    BUFFER_FOR_REORDER = auto()
    DISCARD_EXPIRED = auto()

@dataclass(frozen=True)
class EventRecord:
    event_id: str
    logical_timestamp: int
    dependencies: frozenset[str]

@dataclass(frozen=True)
class TimelineState:
    watermark: int
    lateness_tolerance: int
    buffered_events: tuple[EventRecord, ...]

@dataclass(frozen=True)
class TimelineManifest:
    state: TimelineState
    watermark_digest: str

class TemporalOrderingGuard:
    @staticmethod
    def _hash(data: str) -> str:
        return hashlib.sha256(data.encode("utf-8")).hexdigest()

    @classmethod
    def evaluate_event(cls, event: EventRecord, state: TimelineState) -> tuple[EventVerdict, TimelineState]:
        if event.logical_timestamp <= state.watermark:
            if (state.watermark - event.logical_timestamp) > state.lateness_tolerance:
                return EventVerdict.DISCARD_EXPIRED, state
            
            # Buffer and update watermark if event is newer than current watermark
            new_buffer = state.buffered_events + (event,)
            return EventVerdict.BUFFER_FOR_REORDER, TimelineState(
                watermark=state.watermark,
                lateness_tolerance=state.lateness_tolerance,
                buffered_events=new_buffer
            )

        # Event is strictly newer, advance watermark
        new_watermark = event.logical_timestamp
        # Drain buffer of events that are now valid
        valid_buffered = tuple(e for e in state.buffered_events if e.logical_timestamp > new_watermark)
        
        return EventVerdict.PROCESS_IMMEDIATELY, TimelineState(
            watermark=new_watermark,
            lateness_tolerance=state.lateness_tolerance,
            buffered_events=valid_buffered
        )

    @classmethod
    def seal_timeline(cls, state: TimelineState) -> TimelineManifest:
        digest_payload = {
            "watermark": str(state.watermark),
            "buffered_ids": tuple(sorted(e.event_id for e in state.buffered_events))
        }
        digest = cls._hash(json.dumps(digest_payload, sort_keys=True, separators=(",", ":")))
        return TimelineManifest(state=state, watermark_digest=digest)