# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-persist-data-residency-constraints-across-cross-border-session-handoffs.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-persist-data-residency-constraints-across-cross-border-session-handoffs.warrant.json
# Markdown SHA-256:   49881cc03a715710ff96ce4b9fb15c9404e37748006c7932bdf43a4f05706fea
# Code AST SHA-256:   7b6d94a70d0c13fa78f87e5909bc3e6fc135ff7e850d87ae3a490623ef8f0d08
# Verified Classes:   ResidencyVerdict, DataResidencyState, HandoffManifest, DataResidencyGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class ResidencyVerdict(Enum):
    JURISDICTION_COMPLIANT = auto()
    JURISDICTION_VIOLATION = auto()
    UNKNOWN_JURISDICTION = auto()

@dataclass(frozen=True)
class DataResidencyState:
    data_origin_jurisdiction: str
    processing_jurisdiction: str
    permitted_processing_jurisdictions: frozenset[str]
    has_residency_receipt: bool

@dataclass(frozen=True)
class HandoffManifest:
    verdict: ResidencyVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_handoff(cls, state: DataResidencyState) -> HandoffManifest:
        
        # Gate 1: Receipt presence
        if not state.has_residency_receipt:
            return HandoffManifest(
                verdict=ResidencyVerdict.UNKNOWN_JURISDICTION,
                directive="HALT: No data residency receipt. Cannot verify jurisdiction.",
                manifest_digest=cls._hash("NO_RECEIPT")
            )

        # Gate 2: Processing jurisdiction allowed
        if state.processing_jurisdiction not in state.permitted_processing_jurisdictions:
            return HandoffManifest(
                verdict=ResidencyVerdict.JURISDICTION_VIOLATION,
                directive=f"BLOCKED: Processing in {state.processing_jurisdiction} is not permitted for data originating in {state.data_origin_jurisdiction}.",
                manifest_digest=cls._hash(f"VIOLATION:{state.processing_jurisdiction}")
            )

        # Gate 3: Compliant
        digest = cls._hash(json.dumps({
            "origin": state.data_origin_jurisdiction,
            "processing": state.processing_jurisdiction,
            "allowed": tuple(sorted(state.permitted_processing_jurisdictions))
        }, sort_keys=True))
        
        return HandoffManifest(
            verdict=ResidencyVerdict.JURISDICTION_COMPLIANT,
            directive="PROCEED: Processing jurisdiction is compliant with data residency constraints.",
            manifest_digest=digest
        )