# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-handle-reference-delegation-when-the-origin-cannot-be-directly-contacted.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-handle-reference-delegation-when-the-origin-cannot-be-directly-contacted.warrant.json
# Markdown SHA-256:   2e026b970570616bb71f636ae0a90ecee81fc7dab23cad9bee7daa19606e4c65
# Code AST SHA-256:   26b9a524b33bfb4f43956846a77216e4d5b85506cfed6d35753aa4c812a0d1d1
# Verified Classes:   DelegationVerdict, DelegationHop, DelegatedResolution, DelegationPolicy, DelegationManifest, DelegatedReferenceGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class DelegationVerdict(Enum):
    ORIGIN_DIRECT = auto()
    DELEGATED_VERIFIED = auto()
    DELEGATION_CHAIN_UNTRUSTED = auto()
    STALE_CACHE_DETECTED = auto()

@dataclass(frozen=True)
class DelegationHop:
    intermediary_id: str
    trust_attestation: str | None
    hop_epoch: float

@dataclass(frozen=True)
class DelegatedResolution:
    reference_id: str
    origin_reachable: bool
    delegation_chain: tuple[DelegationHop, ...]
    origin_signature_on_resource: str | None
    current_epoch: float
    max_acceptable_freshness_sec: float

@dataclass(frozen=True)
class DelegationPolicy:
    require_origin_signature: bool
    max_trusted_hops: int

@dataclass(frozen=True)
class DelegationManifest:
    verdict: DelegationVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_resolution(
        cls, resolution: DelegatedResolution, policy: DelegationPolicy
    ) -> DelegationManifest:
        
        # Gate 1: Origin reachable
        if resolution.origin_reachable:
            digest = cls._hash(json.dumps({
                "reference": resolution.reference_id,
                "status": "DIRECT"
            }, sort_keys=True))
            return DelegationManifest(
                verdict=DelegationVerdict.ORIGIN_DIRECT,
                directive=f"PROCEED: Resolve {resolution.reference_id} directly from origin.",
                manifest_digest=digest
            )

        # Gate 2: Chain length
        if len(resolution.delegation_chain) > policy.max_trusted_hops:
            return DelegationManifest(
                verdict=DelegationVerdict.DELEGATION_CHAIN_UNTRUSTED,
                directive=f"HALT: Delegation chain length {len(resolution.delegation_chain)} > {policy.max_trusted_hops}.",
                manifest_digest=cls._hash(f"CHAIN_LONG:{resolution.reference_id}")
            )

        # Gate 3: Intermediary trust
        for hop in resolution.delegation_chain:
            if not hop.trust_attestation:
                if policy.require_origin_signature:
                    return DelegationManifest(
                        verdict=DelegationVerdict.DELEGATION_CHAIN_UNTRUSTED,
                        directive=f"HALT: Intermediary {hop.intermediary_id} lacks trust attestation.",
                        manifest_digest=cls._hash(f"UNTRUSTED:{hop.intermediary_id}")
                    )

        # Gate 4: Origin signature
        if policy.require_origin_signature and not resolution.origin_signature_on_resource:
            return DelegationManifest(
                verdict=DelegationVerdict.DELEGATION_CHAIN_UNTRUSTED,
                directive=f"HALT: Resource lacks origin signature. Delegation substitution risk.",
                manifest_digest=cls._hash(f"NO_SIGNATURE:{resolution.reference_id}")
            )

        # Gate 5: Freshness
        latest_hop_epoch = max((h.hop_epoch for h in resolution.delegation_chain), default=0.0)
        age = resolution.current_epoch - latest_hop_epoch
        if age > resolution.max_acceptable_freshness_sec:
            return DelegationManifest(
                verdict=DelegationVerdict.STALE_CACHE_DETECTED,
                directive=f"HALT: Delegated resolution {age:.0f}s old > {resolution.max_acceptable_freshness_sec:.0f}s.",
                manifest_digest=cls._hash(f"STALE:{resolution.reference_id}")
            )

        # Gate 6: Verified
        digest = cls._hash(json.dumps({
            "reference": resolution.reference_id,
            "hops": tuple(h.intermediary_id for h in resolution.delegation_chain),
            "signature": resolution.origin_signature_on_resource,
            "age": f"{age:.0f}"
        }, sort_keys=True))
        
        return DelegationManifest(
            verdict=DelegationVerdict.DELEGATED_VERIFIED,
            directive=f"PROCEED: Delegated resolution verified via {len(resolution.delegation_chain)} hops.",
            manifest_digest=digest
        )