# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-should-an-instance-treat-revocation-of-a-delegated-capability-when-the-revocation-token-has-not-yet-crossed-every-a2a-hop.md
# Remnant Warrant:    https://corpusfetch.com/c/how-should-an-instance-treat-revocation-of-a-delegated-capability-when-the-revocation-token-has-not-yet-crossed-every-a2a-hop.warrant.json
# Markdown SHA-256:   06f4f08df08de5efcf1391a8712b9dcb271118a2e2a073ef486b6373d1f1b977
# Code AST SHA-256:   a63e9001923a5406136102bb44dfa502e9bc5e1003d65b452e6dd32a4f0afed8
# Verified Classes:   StaleLivenessError, Capability, Hop
# Defensive Guards:   2 fail-closed invariants (zero external deps)

import time
from dataclasses import dataclass, field


class StaleLivenessError(RuntimeError):
    """Raised when a hop attempts to derive a child capability from a parent
    whose ancestor liveness has not been confirmed within the propagation budget."""
    pass


@dataclass
class Capability:
    token_id: str
    ancestor_id: str
    issued_at: float
    last_confirmed_live_at: float


@dataclass
class Hop:
    propagation_budget_s: float
    liveness_cache: dict = field(default_factory=dict)

    def confirm_live(self, ancestor_id: str, at: float | None = None) -> None:
        self.liveness_cache[ancestor_id] = at if at is not None else time.monotonic()

    def _ancestor_is_fresh(self, cap: Capability, now: float) -> bool:
        last = self.liveness_cache.get(cap.ancestor_id)
        if last is None:
            return False
        return (now - last) <= self.propagation_budget_s

    def admit_step(self, cap: Capability) -> None:
        # Execution of an already-admitted step is permitted on structural
        # validity alone; we do not fail closed here.
        return None

    def derive_child(self, cap: Capability, new_token_id: str) -> Capability:
        now = time.monotonic()
        if not self._ancestor_is_fresh(cap, now):
            raise StaleLivenessError(
                f"refusing to derive {new_token_id} from ancestor "
                f"{cap.ancestor_id}: liveness not confirmed within "
                f"{self.propagation_budget_s}s propagation budget"
            )
        # A child minted after its ancestor's last confirmation is suspect,
        # not fresh; reject rather than launder the propagation window.
        if cap.issued_at > cap.last_confirmed_live_at:
            raise StaleLivenessError(
                f"refusing to derive {new_token_id}: child issuance precedes "
                f"ancestor liveness confirmation"
            )
        return Capability(
            token_id=new_token_id,
            ancestor_id=cap.ancestor_id,
            issued_at=now,
            last_confirmed_live_at=cap.last_confirmed_live_at,
        )
