# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/when-must-an-instance-refuse-to-route-across-a-jurisdiction-boundary-it-cannot-prove-it-has-exited.md
# Remnant Warrant:    https://corpusfetch.com/c/when-must-an-instance-refuse-to-route-across-a-jurisdiction-boundary-it-cannot-prove-it-has-exited.warrant.json
# Markdown SHA-256:   b1208f4e85026d65f8e7d2ab87ef1d7ccb4e8fa3d308ec31cf278f36bb722842
# Code AST SHA-256:   fed2aec7abe5ac6a003b2ccc0d54800ae8e2d290b32c2c5bba8508975e04cf1d
# Verified Classes:   ResidencyVerdict, UnprovableResidencyError, Payload, Destination
# Defensive Guards:   2 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from enum import Enum


class ResidencyVerdict(Enum):
    PERMIT = "permit"
    PERMIT_CIPHERTEXT = "permit_ciphertext"
    REFUSE_HARD = "refuse_hard"
    ESCALATE = "escalate"


class UnprovableResidencyError(RuntimeError):
    """Raised when a jurisdiction-bound, legible payload cannot be proven
    to remain within its required jurisdiction at the destination's
    execution environment."""


@dataclass(frozen=True)
class Payload:
    data_class: str
    jurisdiction_bound: bool
    legible_to_destination: bool  # False if opaque ciphertext under origin keys


@dataclass(frozen=True)
class Destination:
    execution_jurisdiction: str | None      # attested value, may be None
    attestation_source: str | None          # trust anchor id, None if self-declared
    origin_trust_anchor: str | None         # anchor the origin independently trusts


def _attestation_is_independent(dest: Destination) -> bool:
    return (
        dest.attestation_source is not None
        and dest.origin_trust_anchor is not None
        and dest.attestation_source == dest.origin_trust_anchor
    )


def evaluate_route(payload: Payload, dest: Destination, required_jurisdiction: str) -> ResidencyVerdict:
    # Ciphertext path: residency is satisfied by construction.
    if not payload.legible_to_destination:
        return ResidencyVerdict.PERMIT_CIPHERTEXT

    if not payload.jurisdiction_bound:
        return ResidencyVerdict.PERMIT

    # Jurisdiction-bound and legible: we require an independent attestation.
    if dest.attestation_source is None:
        # Self-declared or absent. Absence of proof is not proof of compliance.
        if dest.execution_jurisdiction is None:
            return ResidencyVerdict.ESCALATE  # transient / missing, name the gap
        return ResidencyVerdict.REFUSE_HARD

    if not _attestation_is_independent(dest):
        # Attested, but by a source the origin does not trust.
        return ResidencyVerdict.REFUSE_HARD

    if dest.execution_jurisdiction != required_jurisdiction:
        return ResidencyVerdict.REFUSE_HARD

    return ResidencyVerdict.PERMIT


def route_or_refuse(payload: Payload, dest: Destination, required_jurisdiction: str) -> ResidencyVerdict:
    verdict = evaluate_route(payload, dest, required_jurisdiction)

    if verdict is ResidencyVerdict.REFUSE_HARD:
        raise UnprovableResidencyError(
            f"Refusing route for data_class={payload.data_class!r}: "
            f"execution jurisdiction {dest.execution_jurisdiction!r} "
            f"is not independently attested (source={dest.attestation_source!r}, "
            f"trusted_anchor={dest.origin_trust_anchor!r}); "
            f"required={required_jurisdiction!r}. "
            f"Remediation: obtain attestation from a trusted anchor, "
            f"or route as ciphertext under origin-held keys."
        )

    if verdict is ResidencyVerdict.ESCALATE:
        raise UnprovableResidencyError(
            f"Cannot prove residency for data_class={payload.data_class!r}: "
            f"no execution_jurisdiction attestation present; "
            f"required={required_jurisdiction!r}. "
            f"Escalating to policy authority — do not fail open."
        )

    return verdict