# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/under-what-conditions-must-an-instance-treat-a-cached-agent-identity-as-revoked-before-the-revocation-record-itself-propagates.md
# Remnant Warrant:    https://corpusfetch.com/c/under-what-conditions-must-an-instance-treat-a-cached-agent-identity-as-revoked-before-the-revocation-record-itself-propagates.warrant.json
# Markdown SHA-256:   2cb167ee2055d7853d2677f32922dacb8c962638b6e13f6200cf827cbcefcc56
# Code AST SHA-256:   69f6ec4acab918b7ff1eef191a033b61add960d3c9db27e72a3150fa84805119
# Verified Classes:   RevocationIndeterminateError, CachedValidation, FederationContract
# Defensive Guards:   2 fail-closed invariants (zero external deps)

from __future__ import annotations

from dataclasses import dataclass
from datetime import datetime, timedelta


class RevocationIndeterminateError(RuntimeError):
    """Raised when a cached identity cannot be proven non-revoked within the federation obligation bound."""


@dataclass(frozen=True)
class CachedValidation:
    agent_id: str
    cache_stamp: datetime
    root_domain: str


@dataclass(frozen=True)
class FederationContract:
    obligation_bound: timedelta      # Δ_obligation: max time to reject after revocation
    transit_bound: timedelta         # Δ_transit: worst-case revocation record transit
    clock_skew_allowance: timedelta  # ε


def assert_identity_usable(
    cached: CachedValidation,
    now: datetime,
    contract: FederationContract,
    has_freshness_assertion: bool,
) -> None:
    """Enforce the revocation-obligation boundary for a cached agent identity.

    Returns normally only if the cached validation is provably within the
    obligation window, or a positive freshness assertion covers it.
    """
    if has_freshness_assertion:
        return

    # The propagation bound must be tight enough that the cache stamp's age
    # is a sound proxy for "no revocation could be obligatory yet".
    if contract.transit_bound > contract.obligation_bound:
        raise RevocationIndeterminateError(
            f"federation contract is unsound: transit_bound={contract.transit_bound} "
            f"exceeds obligation_bound={contract.obligation_bound}; "
            f"no cache stamp can be trusted for agent {cached.agent_id!r}"
        )

    age = now - cached.cache_stamp
    usable_until = contract.obligation_bound - contract.clock_skew_allowance

    if age > usable_until:
        raise RevocationIndeterminateError(
            f"agent {cached.agent_id!r} (root={cached.root_domain!r}) cache stamp "
            f"age={age} exceeds usable window {usable_until}; "
            f"revocation state indeterminate — reject by default"
        )
