# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-reference-expiry-invariants-must-survive-latency-induced-validity-gaps.md
# Remnant Warrant:    https://corpusfetch.com/c/what-reference-expiry-invariants-must-survive-latency-induced-validity-gaps.warrant.json
# Markdown SHA-256:   62c4297f14614698c4d7e1cd7bb57352f3d693370110a2278546acd1764fe8b0
# Code AST SHA-256:   599a9984823bbbaef72809aac52233041c2706acca4839332b8dc593b30786eb
# Verified Classes:   ExpiryVerdict, ReferenceTiming, ExpiryContext, ExpiryManifest, LatencyExpiryGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class ExpiryVerdict(Enum):
    IMMORTAL = auto()
    SUFFICIENT_VALIDITY = auto()
    INSUFFICIENT_VALIDITY = auto()
    ARRIVED_EXPIRED = auto()

@dataclass(frozen=True)
class ReferenceTiming:
    reference_id: str
    is_immortal: bool
    origin_issue_epoch: float
    origin_validity_sec: float
    transit_sec: float
    expected_use_sec: float

@dataclass(frozen=True)
class ExpiryContext:
    current_epoch: float
    min_useful_validity_sec: float

@dataclass(frozen=True)
class ExpiryManifest:
    verdict: ExpiryVerdict
    remaining_validity_sec: float
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_timing(
        cls, ref: ReferenceTiming, ctx: ExpiryContext
    ) -> ExpiryManifest:
        
        # Gate 1: Immortal
        if ref.is_immortal:
            digest = cls._hash(json.dumps({
                "reference": ref.reference_id,
                "immortal": "TRUE"
            }, sort_keys=True))
            return ExpiryManifest(
                verdict=ExpiryVerdict.IMMORTAL,
                remaining_validity_sec=float('inf'),
                directive=f"PROCEED: Reference {ref.reference_id} is immortal.",
                manifest_digest=digest
            )

        # Gate 2: Compute remaining validity
        arrival_epoch = ref.origin_issue_epoch + ref.transit_sec
        expiry_epoch = ref.origin_issue_epoch + ref.origin_validity_sec
        remaining = expiry_epoch - ctx.current_epoch

        # Gate 3: Already expired
        if remaining <= 0:
            return ExpiryManifest(
                verdict=ExpiryVerdict.ARRIVED_EXPIRED,
                remaining_validity_sec=remaining,
                directive=f"HALT: Reference {ref.reference_id} arrived {(-remaining):.1f}s after expiry.",
                manifest_digest=cls._hash(f"EXPIRED:{ref.reference_id}")
            )

        # Gate 4: Insufficient for use
        if remaining < ctx.min_useful_validity_sec:
            return ExpiryManifest(
                verdict=ExpiryVerdict.INSUFFICIENT_VALIDITY,
                remaining_validity_sec=remaining,
                directive=f"HALT: Reference {ref.reference_id} has {remaining:.1f}s remaining < {ctx.min_useful_validity_sec:.1f}s minimum.",
                manifest_digest=cls._hash(f"LOW_VALIDITY:{ref.reference_id}")
            )

        # Gate 5: Insufficient for expected use
        if remaining < ref.expected_use_sec:
            return ExpiryManifest(
                verdict=ExpiryVerdict.INSUFFICIENT_VALIDITY,
                remaining_validity_sec=remaining,
                directive=f"REFETCH: Reference {ref.reference_id} has {remaining:.1f}s remaining, use expects {ref.expected_use_sec:.1f}s.",
                manifest_digest=cls._hash(f"REFETCH:{ref.reference_id}")
            )

        # Gate 6: Sufficient
        digest = cls._hash(json.dumps({
            "reference": ref.reference_id,
            "remaining": f"{remaining:.1f}",
            "transit": f"{ref.transit_sec:.1f}",
            "expected_use": f"{ref.expected_use_sec:.1f}"
        }, sort_keys=True))
        
        return ExpiryManifest(
            verdict=ExpiryVerdict.SUFFICIENT_VALIDITY,
            remaining_validity_sec=remaining,
            directive=f"PROCEED: Reference {ref.reference_id} has {remaining:.1f}s remaining (transit {ref.transit_sec:.1f}s).",
            manifest_digest=digest
        )