# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/why-does-an-instance-of-a-federated-agent-boundary-silently-downgrade-trust-when-a-policy-mediated-route-traverses-two-or-more-federation-gateways.md
# Remnant Warrant:    https://corpusfetch.com/c/why-does-an-instance-of-a-federated-agent-boundary-silently-downgrade-trust-when-a-policy-mediated-route-traverses-two-or-more-federation-gateways.warrant.json
# Markdown SHA-256:   d2160ba159ea6622c3c287364a6f1fe64707dec2bd775df3f8a89e44a92d88bd
# Code AST SHA-256:   e3352eb1685323624b48d9a0c4105e822a75299b43c55aa5bc4662035d561e1d
# Verified Classes:   TrustLevel, TrustDowngradeError, Envelope
# Defensive Guards:   3 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from enum import IntEnum


class TrustLevel(IntEnum):
    UNTRUSTED = 0
    GUEST = 1
    PARTNER = 2
    PARTNER_V2 = 3


class TrustDowngradeError(RuntimeError):
    """Raised when a federated message's effective trust is lower than the
    asserted trust without a signed attenuation record explaining the gap."""


@dataclass(frozen=True)
class Envelope:
    asserted_trust: TrustLevel
    effective_trust: TrustLevel
    attenuation_record: str | None  # signed proof of a deliberate step-down


def admit_at_destination(env: Envelope, required_floor: TrustLevel) -> None:
    # Detect silent downgrade: effective < asserted with no signed reason.
    if env.effective_trust < env.asserted_trust and env.attenuation_record is None:
        raise TrustDowngradeError(
            f"silent trust downgrade: asserted={env.asserted_trust.name} "
            f"effective={env.effective_trust.name} with no attenuation record; "
            f"an intermediate gateway likely substituted a default for an "
            f"unrecognized trust level"
        )
    if env.effective_trust < required_floor:
        raise TrustDowngradeError(
            f"trust floor not met: effective={env.effective_trust.name} "
            f"required={required_floor.name}"
        )


def route_through_gateway(
    env: Envelope,
    gateway_vocabulary: set[TrustLevel],
    default_on_unknown: TrustLevel,
) -> Envelope:
    if env.asserted_trust not in gateway_vocabulary:
        # The dangerous case: defaulting to a permissive level forwards a
        # downgrade that the destination's floor check cannot detect.
        if default_on_unknown > TrustLevel.UNTRUSTED:
            raise TrustDowngradeError(
                f"gateway does not recognize {env.asserted_trust.name} and "
                f"would default to {default_on_unknown.name}; configure "
                f"REJECT-on-unknown or carry signed provenance before forwarding"
            )
    return env