# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-should-an-instance-handle-discovery-records-that-respond-but-serve-no-backing-resource.md
# Remnant Warrant:    https://corpusfetch.com/c/how-should-an-instance-handle-discovery-records-that-respond-but-serve-no-backing-resource.warrant.json
# Markdown SHA-256:   4fd8dc5b4666dbe67a2e72cda81e830bd96b9091ac81da1db1e04478543ee219
# Code AST SHA-256:   f4119a8b6bb572da6b2aad08d3378aa900f3261fd2a0b3741aff5827381f5429
# Verified Classes:   OrphanVerdict, DiscoveryRecord, OrphanPolicy, OrphanManifest, OrphanDiscoveryGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class OrphanVerdict(Enum):
    REGISTRY_GUARANTEED_LIVE = auto()
    LIVENESS_PROBE_VERIFIED = auto()
    ORPHAN_DETECTED = auto()
    UNVERIFIED_RECORD = auto()

@dataclass(frozen=True)
class DiscoveryRecord:
    record_id: str
    registry_guarantees_liveness: bool
    liveness_probe_receipt: str | None
    liveness_last_verified_epoch: float

@dataclass(frozen=True)
class OrphanPolicy:
    current_epoch: float
    max_liveness_staleness_sec: float

@dataclass(frozen=True)
class OrphanManifest:
    verdict: OrphanVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_record(
        cls, record: DiscoveryRecord, policy: OrphanPolicy
    ) -> OrphanManifest:
        
        # Gate 1: Registry guarantees liveness
        if record.registry_guarantees_liveness:
            digest = cls._hash(json.dumps({
                "record": record.record_id,
                "guarantee": "REGISTRY"
            }, sort_keys=True))
            return OrphanManifest(
                verdict=OrphanVerdict.REGISTRY_GUARANTEED_LIVE,
                directive=f"PROCEED: Registry guarantees liveness for {record.record_id}.",
                manifest_digest=digest
            )

        # Gate 2: Probe receipt presence
        if not record.liveness_probe_receipt:
            return OrphanManifest(
                verdict=OrphanVerdict.UNVERIFIED_RECORD,
                directive=f"HALT: Record {record.record_id} has no liveness proof. Probe before use.",
                manifest_digest=cls._hash(f"NO_PROBE:{record.record_id}")
            )

        # Gate 3: Probe freshness
        age = policy.current_epoch - record.liveness_last_verified_epoch
        if age > policy.max_liveness_staleness_sec:
            return OrphanManifest(
                verdict=OrphanVerdict.ORPHAN_DETECTED,
                directive=f"HALT: Liveness proof is {age:.0f}s stale. Re-probe {record.record_id}.",
                manifest_digest=cls._hash(f"STALE:{record.record_id}:{age:.0f}")
            )

        # Gate 4: Verified
        digest = cls._hash(json.dumps({
            "record": record.record_id,
            "probe": record.liveness_probe_receipt,
            "age": f"{age:.0f}"
        }, sort_keys=True))
        
        return OrphanManifest(
            verdict=OrphanVerdict.LIVENESS_PROBE_VERIFIED,
            directive=f"PROCEED: Record {record.record_id} liveness verified {age:.0f}s ago.",
            manifest_digest=digest
        )