# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-prove-the-temporal-ordering-of-events-when-its-wall-clock-has-been-compromised.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-prove-the-temporal-ordering-of-events-when-its-wall-clock-has-been-compromised.warrant.json
# Markdown SHA-256:   7aad7abfbbdfd01ad53bbc0d2288235d83c09fc509c41f08c6909c720ca33958
# Code AST SHA-256:   2b5d7626830b0e0a04ecfde48a5656cb053771e06b4921ac158b20239dcc7ede
# Verified Classes:   TimelineVerdict, EventTrace, ClockCompromiseState, CausalManifest, CausalOrderingGuard
# Defensive Guards:   1 fail-closed invariants (zero external deps)

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

class TimelineVerdict(Enum):
    VERIFIED_CAUSAL_ORDER = auto()
    UNRECOVERABLE_TIMELINE = auto()
    PARTIAL_ANCHOR_COVERAGE = auto()

@dataclass(frozen=True)
class EventTrace:
    event_id: str
    logical_clock: int
    wall_clock: float
    causal_dependencies: frozenset[str]
    external_anchor_hash: str | None

@dataclass(frozen=True)
class ClockCompromiseState:
    compromise_detected: bool
    compromise_window_start: float
    compromise_window_end: float

@dataclass(frozen=True)
class CausalManifest:
    verdict: TimelineVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_timeline(
        cls, traces: tuple[EventTrace, ...], state: ClockCompromiseState
    ) -> CausalManifest:
        
        if not traces:
            raise ValueError("Cannot evaluate an empty timeline.")

        # Gate 1: No compromise detected
        if not state.compromise_detected:
            digest = cls._hash(json.dumps({
                "events": str(len(traces)),
                "compromise": "NONE"
            }, sort_keys=True))
            return CausalManifest(
                verdict=TimelineVerdict.VERIFIED_CAUSAL_ORDER,
                directive="PROCEED: No clock compromise detected. Timeline intact.",
                manifest_digest=digest
            )

        # Gate 2: Check logical clock uniqueness
        logical_clocks = [t.logical_clock for t in traces]
        if len(set(logical_clocks)) != len(logical_clocks):
            return CausalManifest(
                verdict=TimelineVerdict.UNRECOVERABLE_TIMELINE,
                directive="HALT: Logical clock collision detected. Causal ordering broken.",
                manifest_digest=cls._hash("LOGICAL_COLLISION")
            )

        # Gate 3: Verify causal dependencies precede their dependents
        clock_map = {t.event_id: t.logical_clock for t in traces}
        for trace in traces:
            for dep_id in trace.causal_dependencies:
                if dep_id in clock_map and clock_map[dep_id] >= trace.logical_clock:
                    return CausalManifest(
                        verdict=TimelineVerdict.UNRECOVERABLE_TIMELINE,
                        directive=f"HALT: Causal inversion: {dep_id} does not precede {trace.event_id}.",
                        manifest_digest=cls._hash(f"INVERSION:{trace.event_id}")
                    )

        # Gate 4: Check external anchors for events in compromise window
        unanchored_critical = [
            t.event_id for t in traces
            if state.compromise_window_start <= t.wall_clock <= state.compromise_window_end
            and not t.external_anchor_hash
        ]

        if unanchored_critical:
            digest = cls._hash(json.dumps({
                "events": str(len(traces)),
                "unanchored": tuple(sorted(unanchored_critical))
            }, sort_keys=True))
            return CausalManifest(
                verdict=TimelineVerdict.PARTIAL_ANCHOR_COVERAGE,
                directive=f"WARN: {len(unanchored_critical)} events in compromise window lack external anchors.",
                manifest_digest=digest
            )

        digest = cls._hash(json.dumps({
            "events": str(len(traces)),
            "anchored": "ALL"
        }, sort_keys=True))
        
        return CausalManifest(
            verdict=TimelineVerdict.VERIFIED_CAUSAL_ORDER,
            directive="PROCEED: Causal order reconstructed from logical clocks and external anchors.",
            manifest_digest=digest
        )