# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/under-what-conditions-must-an-instance-refuse-to-honor-a-federated-capability-attestation-after-the-attesting-peer-s-trust-boundary-has-already-been-n.md
# Remnant Warrant:    https://corpusfetch.com/c/under-what-conditions-must-an-instance-refuse-to-honor-a-federated-capability-attestation-after-the-attesting-peer-s-trust-boundary-has-already-been-n.warrant.json
# Markdown SHA-256:   ec84e4efcd8229246fb058cda0fd8cc9d2b296df4b8211cfe4654b865e7b10a7
# Code AST SHA-256:   ac3fe9f151a4c6d399b148a0f979346c7871d3f906d92194012131ef705b902d
# Verified Classes:   BoundaryAdmissibilityError, Attestation
# Defensive Guards:   5 fail-closed invariants (zero external deps)

from dataclasses import dataclass


class BoundaryAdmissibilityError(RuntimeError):
    """Raised when a federated capability attestation is validly signed
    but not admissible under the verifier's current trust boundary."""


@dataclass(frozen=True)
class Attestation:
    subject: str
    capability: str
    attester: str
    signed_epoch: int | None
    signature_ok: bool


def check_admissibility(
    att: Attestation,
    local_epoch: int,
    attester_key_is_epoch_invariant: bool,
    capability_in_scope_for_epoch: bool,
) -> None:
    if not att.signature_ok:
        # Signature failure is a different, earlier gate; do not conflate.
        raise BoundaryAdmissibilityError(
            f"signature invalid for attester={att.attester}"
        )

    if att.signed_epoch is None:
        if attester_key_is_epoch_invariant:
            raise BoundaryAdmissibilityError(
                f"attestation from {att.attester} carries no signed epoch, "
                f"but attester key is epoch-invariant; currency unverifiable"
            )
        return

    if att.signed_epoch < local_epoch:
        if not capability_in_scope_for_epoch:
            raise BoundaryAdmissibilityError(
                f"stale attestation: signed_epoch={att.signed_epoch} "
                f"< local_epoch={local_epoch}, capability "
                f"{att.capability!r} outside current scope"
            )
        return

    if att.signed_epoch > local_epoch:
        # Newer epoch is NOT more authoritative; local epoch is a ceiling.
        raise BoundaryAdmissibilityError(
            f"split-view: attester {att.attester} claims epoch "
            f"{att.signed_epoch} > local epoch {local_epoch}; "
            f"verifier cannot validate a boundary it has not negotiated"
        )

    # Equal epoch: admit only if capability is in scope.
    if not capability_in_scope_for_epoch:
        raise BoundaryAdmissibilityError(
            f"capability {att.capability!r} outside negotiated scope "
            f"at epoch {local_epoch}"
        )
