# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-time-travel-attestation-invariants-prove-past-state-claims-after-the-fact.md
# Remnant Warrant:    https://corpusfetch.com/c/what-time-travel-attestation-invariants-prove-past-state-claims-after-the-fact.warrant.json
# Markdown SHA-256:   8b9e88c8112050ab5e336e263f12d2f77800eddbf20846ccd19389cb63ce4c5e
# Code AST SHA-256:   bb9b4ff9c528358a6db55849d828ba738371a582915a246cc75f46fbcdb38d37
# Verified Classes:   TimeTravelVerdict, StateSnapshot, TimeTravelPolicy, TimeTravelManifest, TimeTravelAttestationGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class TimeTravelVerdict(Enum):
    NO_RETROSPECTIVE_NEED = auto()
    SNAPSHOT_ATTESTED = auto()
    TAMPER_EVIDENT = auto()
    UNVERIFIABLE_PAST_STATE = auto()

@dataclass(frozen=True)
class StateSnapshot:
    epoch: float
    state_hash: str
    snapshot_receipt: str | None
    transparency_log_proof: str | None
    decision_bound_to_snapshot: str | None

@dataclass(frozen=True)
class TimeTravelPolicy:
    require_transparency_log: bool
    require_decision_binding: bool

@dataclass(frozen=True)
class TimeTravelManifest:
    verdict: TimeTravelVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_snapshot(
        cls, snapshot: StateSnapshot, policy: TimeTravelPolicy
    ) -> TimeTravelManifest:
        
        # Gate 1: Snapshot presence
        if not snapshot.snapshot_receipt:
            return TimeTravelManifest(
                verdict=TimeTravelVerdict.UNVERIFIABLE_PAST_STATE,
                directive=f"HALT: No snapshot receipt for epoch {snapshot.epoch:.0f}.",
                manifest_digest=cls._hash(f"NO_SNAPSHOT:{snapshot.epoch:.0f}")
            )

        # Gate 2: Transparency log
        if policy.require_transparency_log and not snapshot.transparency_log_proof:
            return TimeTravelManifest(
                verdict=TimeTravelVerdict.SNAPSHOT_ATTESTED,
                directive=f"WARN: Snapshot {snapshot.epoch:.0f} attested but not in transparency log.",
                manifest_digest=cls._hash(f"NO_LOG:{snapshot.epoch:.0f}")
            )

        # Gate 3: Decision binding
        if policy.require_decision_binding and not snapshot.decision_bound_to_snapshot:
            return TimeTravelManifest(
                verdict=TimeTravelVerdict.SNAPSHOT_ATTESTED,
                directive=f"WARN: Snapshot {snapshot.epoch:.0f} attested but not bound to a decision.",
                manifest_digest=cls._hash(f"NO_DECISION:{snapshot.epoch:.0f}")
            )

        # Gate 4: Tamper-evident
        if snapshot.transparency_log_proof:
            digest = cls._hash(json.dumps({
                "epoch": f"{snapshot.epoch:.0f}",
                "state": snapshot.state_hash,
                "log_proof": snapshot.transparency_log_proof,
                "decision": snapshot.decision_bound_to_snapshot
            }, sort_keys=True))
            return TimeTravelManifest(
                verdict=TimeTravelVerdict.TAMPER_EVIDENT,
                directive=f"PROCEED: Snapshot {snapshot.epoch:.0f} tamper-evident with decision binding.",
                manifest_digest=digest
            )

        # Gate 5: Basic attestation
        digest = cls._hash(json.dumps({
            "epoch": f"{snapshot.epoch:.0f}",
            "state": snapshot.state_hash,
            "receipt": snapshot.snapshot_receipt
        }, sort_keys=True))
        
        return TimeTravelManifest(
            verdict=TimeTravelVerdict.SNAPSHOT_ATTESTED,
            directive=f"PROCEED: Snapshot {snapshot.epoch:.0f} attested.",
            manifest_digest=digest
        )