# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-does-an-instance-detect-a-policy-envelope-split-brain-during-cross-org-multi-agent-federation-routing.md
# Remnant Warrant:    https://corpusfetch.com/c/how-does-an-instance-detect-a-policy-envelope-split-brain-during-cross-org-multi-agent-federation-routing.warrant.json
# Markdown SHA-256:   57c59dc24f6c069a92c8c1821b1e19a2b558457400d3af98aa9870314fcea401
# Code AST SHA-256:   51da5f8f2d07443e8714039b6a1b8c7fae2de1f85d7e896dae53bc0a11c22e6c
# Verified Classes:   PolicyEnvelopeError, PolicyRevisionBehindError, PolicyRevisionExpiredError, PolicyRevisionAmbiguousError, RouteDecision, Envelope, LocalPolicyState
# Defensive Guards:   3 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from enum import Enum


class PolicyEnvelopeError(RuntimeError):
    """Base class for policy-envelope routing invariant violations."""


class PolicyRevisionBehindError(PolicyEnvelopeError):
    """Envelope asserts a policy revision newer than the router's local bundle.

    Fail closed: do not evaluate new authority under stale rules.
    """


class PolicyRevisionExpiredError(PolicyEnvelopeError):
    """Envelope asserts a revision below the router's retention floor."""


class PolicyRevisionAmbiguousError(PolicyEnvelopeError):
    """Router cannot establish ordering between envelope and local revision."""


class RouteDecision(Enum):
    ROUTE = "route"
    REFRESH_THEN_RETRY = "refresh_then_retry"
    REJECT = "reject"


@dataclass(frozen=True)
class Envelope:
    policy_revision: int          # exact monotonic revision, no aliases
    issuer_org: str
    payload_ref: str


@dataclass(frozen=True)
class LocalPolicyState:
    revision: int
    retention_floor: int          # oldest revision still evaluable


def decide_route(envelope: Envelope, local: LocalPolicyState) -> RouteDecision:
    """Return routing decision, or raise on invariant violation.

    Ordering is exact-integer. No prefix matching, no major-version tolerance.
    """
    if envelope.policy_revision is None or local.revision is None:
        raise PolicyRevisionAmbiguousError(
            f"cannot order envelope rev={envelope.policy_revision!r} "
            f"against local rev={local.revision!r} for issuer={envelope.issuer_org}"
        )

    if envelope.policy_revision > local.revision:
        # Envelope is newer than our bundle. Serving stale would invert the
        # safety property: new authority evaluated under old rules.
        raise PolicyRevisionBehindError(
            f"envelope rev={envelope.policy_revision} exceeds local rev={local.revision} "
            f"for issuer={envelope.issuer_org}; refresh required, refuse to route on stale"
        )

    if envelope.policy_revision < local.retention_floor:
        raise PolicyRevisionExpiredError(
            f"envelope rev={envelope.policy_revision} below retention floor "
            f"{local.retention_floor} for issuer={envelope.issuer_org}"
        )

    if envelope.policy_revision == local.revision:
        return RouteDecision.ROUTE

    # Stale-but-retained: evaluable only if caller explicitly opts into
    # bounded staleness; default is to force a refresh.
    return RouteDecision.REFRESH_THEN_RETRY
