# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-referential-integrity-invariants-must-survive-when-agents-propagate-uris-peer-to-peer.md
# Remnant Warrant:    https://corpusfetch.com/c/what-referential-integrity-invariants-must-survive-when-agents-propagate-uris-peer-to-peer.warrant.json
# Markdown SHA-256:   06ad9cbcaa3e1a10157cad0dba2f4bdee4a6e48ef1dc77913710581a296a9680
# Code AST SHA-256:   8fd5130d1faa28f5df84214087d06e88e44bef476c1544fc99bb1f1d2d81a4a6
# Verified Classes:   ReferentialVerdict, PropagatedURI, URIReceiver, URIReferentialPolicy, URIReferentialManifest, PeerToPeerReferentialGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class ReferentialVerdict(Enum):
    SELF_RESOLVED = auto()
    ATTESTED_SAME_DOMAIN = auto()
    ATTESTED_CROSS_DOMAIN = auto()
    UNVERIFIED_PROPAGATION = auto()

@dataclass(frozen=True)
class PropagatedURI:
    uri: str
    resolution_attestation: str | None
    attestation_epoch: float
    sender_trust_domain: str
    chain_depth: int

@dataclass(frozen=True)
class URIReceiver:
    receiver_trust_domain: str
    current_epoch: float
    freshness_window_sec: float

@dataclass(frozen=True)
class URIReferentialPolicy:
    require_attestation: bool
    max_chain_depth: int

@dataclass(frozen=True)
class URIReferentialManifest:
    verdict: ReferentialVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_uri(
        cls, uri: PropagatedURI, receiver: URIReceiver, policy: URIReferentialPolicy
    ) -> URIReferentialManifest:
        
        # Gate 1: Attestation presence
        if policy.require_attestation and not uri.resolution_attestation:
            return URIReferentialManifest(
                verdict=ReferentialVerdict.UNVERIFIED_PROPAGATION,
                directive=f"HALT: URI {uri.uri} lacks resolution attestation after {uri.chain_depth} hops.",
                manifest_digest=cls._hash(f"NO_ATTEST:{uri.uri}")
            )

        # Gate 2: Chain depth
        if uri.chain_depth > policy.max_chain_depth:
            return URIReferentialManifest(
                verdict=ReferentialVerdict.UNVERIFIED_PROPAGATION,
                directive=f"HALT: URI {uri.uri} chain depth {uri.chain_depth} > {policy.max_chain_depth}. Re-resolve from origin.",
                manifest_digest=cls._hash(f"DEPTH:{uri.uri}")
            )

        # Gate 3: Freshness
        age = receiver.current_epoch - uri.attestation_epoch
        if age > receiver.freshness_window_sec:
            return URIReferentialManifest(
                verdict=ReferentialVerdict.UNVERIFIED_PROPAGATION,
                directive=f"HALT: URI {uri.uri} attestation {age:.0f}s stale > {receiver.freshness_window_sec:.0f}s.",
                manifest_digest=cls._hash(f"STALE:{uri.uri}")
            )

        # Gate 4: Same domain
        if uri.sender_trust_domain == receiver.receiver_trust_domain:
            digest = cls._hash(json.dumps({
                "uri": uri.uri,
                "attestation": uri.resolution_attestation,
                "epoch": f"{uri.attestation_epoch:.0f}",
                "domain": uri.sender_trust_domain
            }, sort_keys=True))
            return URIReferentialManifest(
                verdict=ReferentialVerdict.ATTESTED_SAME_DOMAIN,
                directive=f"PROCEED: URI {uri.uri} attested in same trust domain.",
                manifest_digest=digest
            )

        # Gate 5: Cross domain
        return URIReferentialManifest(
            verdict=ReferentialVerdict.ATTESTED_CROSS_DOMAIN,
            directive=f"RESOLVE_LOCALLY: URI {uri.uri} attested in {uri.sender_trust_domain}, receiver is {receiver.receiver_trust_domain}.",
            manifest_digest=cls._hash(f"CROSS_DOMAIN:{uri.uri}")
        )