# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/where-must-an-instance-halt-when-a-federated-audit-trail-cannot-reconcile-a-replayed-message-against-its-originating-policy-epoch.md
# Remnant Warrant:    https://corpusfetch.com/c/where-must-an-instance-halt-when-a-federated-audit-trail-cannot-reconcile-a-replayed-message-against-its-originating-policy-epoch.warrant.json
# Markdown SHA-256:   9664126997edd34c9de2445dfea03a4b0b4a10bc432b77a76c3d8c6397f9b258
# Code AST SHA-256:   6a9c763630aefe894b388090981f631a82a72144221171a4facb1cb414d173cc
# Verified Classes:   EpochReconciliationError, Resolution, Message, Tombstone, FederationAdmissionGate
# Defensive Guards:   2 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from enum import Enum


class EpochReconciliationError(RuntimeError):
    """Raised when a federated message cannot be reconciled against its originating policy epoch."""
    pass


class Resolution(Enum):
    ADMIT = "admit"
    REJECT_TAMPER = "reject_tamper"
    REJECT_UNVERIFIABLE = "reject_unverifiable"
    HALT_ESCALATE = "halt_escalate"


@dataclass(frozen=True)
class Message:
    policy_id: str
    epoch_id: str
    epoch_digest: str
    issued_at: float
    ttl: float


@dataclass(frozen=True)
class Tombstone:
    epoch_id: str
    retired_at: float
    active_window: tuple[float, float]


class FederationAdmissionGate:
    def __init__(self, live_epochs: dict[str, str], tombstones: dict[str, Tombstone]):
        self._live = live_epochs          # epoch_id -> digest
        self._tombstones = tombstones     # epoch_id -> retirement record

    def classify(self, msg: Message) -> Resolution:
        if msg.epoch_id in self._live:
            if self._live[msg.epoch_id] != msg.epoch_digest:
                return Resolution.REJECT_TAMPER
            return Resolution.ADMIT

        tomb = self._tombstones.get(msg.epoch_id)
        if tomb is None:
            # Absent with no retirement record: cannot prove it ever existed.
            return Resolution.REJECT_UNVERIFIABLE

        start, end = tomb.active_window
        if start <= msg.issued_at <= end and msg.issued_at + msg.ttl > tomb.retired_at:
            # Existed, was retired, and the message's declared validity outlived
            # the epoch's auditable window. This is the halt state.
            return Resolution.HALT_ESCALATE

        # Retired, but the message was fully inside the auditable window at send time.
        return Resolution.REJECT_UNVERIFIABLE

    def admit(self, msg: Message) -> None:
        resolution = self.classify(msg)
        if resolution is Resolution.ADMIT:
            return
        if resolution is Resolution.HALT_ESCALATE:
            raise EpochReconciliationError(
                f"epoch {msg.epoch_id} retired at {self._tombstones[msg.epoch_id].retired_at} "
                f"but message issued at {msg.issued_at} with ttl {msg.ttl} outlives auditability; "
                f"escalate to reconciliation queue, do not admit or drop"
            )
        raise EpochReconciliationError(
            f"epoch {msg.epoch_id} resolution={resolution.value}; message not admissible"
        )
