# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-does-an-instance-detect-a-trust-laundering-boundary-failure-when-federated-agent-capabilities-are-re-delegated-across-organizational-trust-domains.md
# Remnant Warrant:    https://corpusfetch.com/c/how-does-an-instance-detect-a-trust-laundering-boundary-failure-when-federated-agent-capabilities-are-re-delegated-across-organizational-trust-domains.warrant.json
# Markdown SHA-256:   bad702832d4582a25b9f76ac30364f7e4c350724cfabeedffe7515e23b8ac6d6
# Code AST SHA-256:   54d414b52bfd5cd6e94ccf0034159dd826edd08c3a27fd762505ac895cb3f8f4
# Verified Classes:   TrustLaunderingBoundaryError, Caveat, Capability
# Defensive Guards:   4 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from typing import Iterable


class TrustLaunderingBoundaryError(RuntimeError):
    """Raised when a capability crosses a trust boundary carrying caveats
    whose vocabulary the receiving domain cannot evaluate."""


@dataclass(frozen=True)
class Caveat:
    key: str
    value: str


@dataclass(frozen=True)
class Capability:
    root_domain: str
    audience: str
    caveats: tuple[Caveat, ...]


# Caveat keys whose semantics are load-bearing for delegation safety.
# These must never be silently ignored by a foreign domain.
DELEGATION_MARKERS = frozenset({"delegable", "may_delegate", "attenuable", "delegable_within"})


def admit_capability(
    cap: Capability,
    receiving_domain: str,
    lexicon: Iterable[str],
    provably_irrelevant: Iterable[str] = (),
) -> None:
    """Fail-closed admission check for a capability presented to a broker.

    Rejects if the capability's audience does not include the receiving
    domain, or if it carries a foreign-vocabulary caveat that is not
    provably irrelevant to the requested operation.
    """
    lexicon = frozenset(lexicon)
    irrelevant = frozenset(provably_irrelevant)

    if receiving_domain not in cap.audience.split(","):
        raise TrustLaunderingBoundaryError(
            f"capability from {cap.root_domain} presented to {receiving_domain} "
            f"but audience={cap.audience!r} does not include it"
        )

    for caveat in cap.caveats:
        if caveat.key in DELEGATION_MARKERS:
            # Domain-scoped delegability must name this domain explicitly.
            if caveat.key == "delegable_within" and caveat.value == receiving_domain:
                continue
            if caveat.key == "delegable_within":
                raise TrustLaunderingBoundaryError(
                    f"delegable_within={caveat.value!r} does not match "
                    f"receiving domain {receiving_domain!r}"
                )
            raise TrustLaunderingBoundaryError(
                f"capability from {cap.root_domain} carries delegation marker "
                f"{caveat.key!r} with no domain scoping; refusing to evaluate "
                f"in {receiving_domain!r}"
            )
        if caveat.key not in lexicon and caveat.key not in irrelevant:
            raise TrustLaunderingBoundaryError(
                f"foreign-vocabulary caveat {caveat.key!r} from {cap.root_domain} "
                f"is not in {receiving_domain!r} lexicon and is not provably "
                f"irrelevant to the requested operation"
            )
