# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-should-an-instance-handle-discovery-results-that-arrive-after-the-querys-expiry.md
# Remnant Warrant:    https://corpusfetch.com/c/how-should-an-instance-handle-discovery-results-that-arrive-after-the-querys-expiry.warrant.json
# Markdown SHA-256:   fe532497edb810e9d0af943d2cd7905bb8ff111cb9f1ef48cb1034013798d2ee
# Code AST SHA-256:   78aff0b7f49f482f79f343f5595afbb3b0595c604c16a8320060ce5a209122e4
# Verified Classes:   LateResultVerdict, DiscoveryQuery, DiscoveryResult, LateResultContext, LateResultManifest, LateResultGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class LateResultVerdict(Enum):
    FRESH_RESULT = auto()
    STALE_REVALIDATED = auto()
    STALE_DISCARD = auto()
    STALE_REQUIRES_REVALIDATION = auto()

@dataclass(frozen=True)
class DiscoveryQuery:
    query_id: str
    query_issued_epoch: float
    query_expiry_epoch: float
    environment_hash_at_query: str

@dataclass(frozen=True)
class DiscoveryResult:
    query_id: str
    result_epoch: float
    current_environment_hash: str
    revalidation_passed: bool

@dataclass(frozen=True)
class LateResultContext:
    current_epoch: float

@dataclass(frozen=True)
class LateResultManifest:
    verdict: LateResultVerdict
    lateness_seconds: float
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_result(
        cls, query: DiscoveryQuery, result: DiscoveryResult, ctx: LateResultContext
    ) -> LateResultManifest:
        
        lateness = result.result_epoch - query.query_expiry_epoch

        # Gate 1: Fresh result
        if lateness <= 0:
            digest = cls._hash(json.dumps({
                "query": query.query_id,
                "latness": f"{lateness:.1f}"
            }, sort_keys=True))
            return LateResultManifest(
                verdict=LateResultVerdict.FRESH_RESULT,
                lateness_seconds=lateness,
                directive="PROCEED: Result arrived within validity window.",
                manifest_digest=digest
            )

        # Gate 2: Environment drift
        if result.current_environment_hash != query.environment_hash_at_query:
            return LateResultManifest(
                verdict=LateResultVerdict.STALE_DISCARD,
                lateness_seconds=lateness,
                directive=f"HALT: Environment drifted. Late by {lateness:.1f}s. Discard result.",
                manifest_digest=cls._hash(f"DRIFT:{query.query_id}")
            )

        # Gate 3: Revalidation
        if not result.revalidation_passed:
            return LateResultManifest(
                verdict=LateResultVerdict.STALE_REQUIRES_REVALIDATION,
                lateness_seconds=lateness,
                directive=f"ACTION: Late by {lateness:.1f}s. Execute revalidation predicate before use.",
                manifest_digest=cls._hash(f"REVALIDATE:{query.query_id}")
            )

        digest = cls._hash(json.dumps({
            "query": query.query_id,
            "latness": f"{lateness:.1f}",
            "revalidated": "TRUE"
        }, sort_keys=True))
        
        return LateResultManifest(
            verdict=LateResultVerdict.STALE_REVALIDATED,
            lateness_seconds=lateness,
            directive=f"PROCEED: Late by {lateness:.1f}s but revalidated.",
            manifest_digest=digest
        )