# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-does-an-instance-detect-a-revoked-capability-peer-when-the-revocation-plane-and-the-data-plane-disagree-on-causal-order.md
# Remnant Warrant:    https://corpusfetch.com/c/how-does-an-instance-detect-a-revoked-capability-peer-when-the-revocation-plane-and-the-data-plane-disagree-on-causal-order.warrant.json
# Markdown SHA-256:   01cac43f2342df8951d029dfc73f7c6661ddcc7f33b5231d4329a1e15d092272
# Code AST SHA-256:   c8bb6546fb07a5fe6528dc898c7876e7a13020bad093ad99f3a2c22221b7069f
# Verified Classes:   RevocationCausalityError, Attestation, EpochWitness
# Defensive Guards:   1 fail-closed invariants (zero external deps)

import time
from dataclasses import dataclass


class RevocationCausalityError(RuntimeError):
    """Raised when an attestation is causally behind the receiver's epoch witness."""
    pass


@dataclass(frozen=True)
class Attestation:
    issuer: str
    capability: str
    authority_epoch: int
    signature: bytes


class EpochWitness:
    """Receiver-side causal witness. Persist high_water before accepting any invocation."""

    def __init__(self, persisted_high_water: int):
        self.high_water = persisted_high_water
        self.last_persist = time.monotonic()

    def observe(self, epoch: int) -> None:
        if epoch > self.high_water:
            self.high_water = epoch
            self._persist()

    def _persist(self) -> None:
        # Durability is load-bearing: a restart that loses the witness reopens the window.
        # Implementation omitted; must be synchronous and must not advance last_persist on failure.
        self.last_persist = time.monotonic()


def admit_invocation(att: Attestation, witness: EpochWitness) -> None:
    if att.authority_epoch < witness.high_water:
        raise RevocationCausalityError(
            f"attestation epoch {att.authority_epoch} is behind receiver witness "
            f"{witness.high_water}; issuer {att.issuer} capability {att.capability} "
            f"cannot be proven un-revoked"
        )
    # Signature and capability checks follow; they do not substitute for the epoch check.
    witness.observe(att.authority_epoch)
