# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-does-an-instance-detect-a-stale-trust-attestation-during-cross-org-capability-negotiation-without-breaking-federated-liveness.md
# Remnant Warrant:    https://corpusfetch.com/c/how-does-an-instance-detect-a-stale-trust-attestation-during-cross-org-capability-negotiation-without-breaking-federated-liveness.warrant.json
# Markdown SHA-256:   8603b988327dde067a20168624b41a7d83195acfa1ee8db0d5faa668dc5be20a
# Code AST SHA-256:   7b522c08200992593de86a634fd5a00ae3496c5ee3b8970af63ffc422a4542fd
# Verified Classes:   StaleTrustAttestationError, EpochRollbackError, FederationBroker
# Defensive Guards:   3 fail-closed invariants (zero external deps)

class StaleTrustAttestationError(RuntimeError):
    """Raised when a cached trust attestation's policy epoch is behind the issuer's observed epoch."""
    pass


class EpochRollbackError(StaleTrustAttestationError):
    """Raised when an issuer serves an epoch below the broker's high-water mark."""
    pass


class FederationBroker:
    def __init__(self, gossip_epochs: dict[str, int], high_water: dict[str, int]):
        # gossip_epochs: issuer_id -> latest epoch observed via gossip
        # high_water:    issuer_id -> highest epoch this broker has ever accepted
        self.gossip_epochs = gossip_epochs
        self.high_water = high_water

    def check_attestation(self, issuer: str, attestation_epoch: int, capability: str,
                          has_side_effects: bool) -> None:
        observed = self.gossip_epochs.get(issuer)
        if observed is None:
            # No gossip view: fail closed for side-effecting capabilities.
            if has_side_effects:
                raise StaleTrustAttestationError(
                    f"no gossip epoch for issuer {issuer}; cannot validate {capability}"
                )
            return

        hw = self.high_water.get(issuer, -1)
        if attestation_epoch < hw:
            raise EpochRollbackError(
                f"attestation epoch {attestation_epoch} for {issuer} is below "
                f"high-water {hw}; possible issuer rollback"
            )

        if attestation_epoch < observed:
            if has_side_effects:
                raise StaleTrustAttestationError(
                    f"attestation epoch {attestation_epoch} for {issuer} is stale "
                    f"(gossip epoch {observed}); re-negotiation required for {capability}"
                )
            # Non-side-effecting: tolerate, but surface for audit.
            return

        # Accept and advance high-water mark.
        if attestation_epoch > hw:
            self.high_water[issuer] = attestation_epoch
