# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-does-an-instance-detect-a-revoked-aaif-verifiable-credential-when-the-revocation-list-is-unreachable-at-the-exact-moment-of-delegation.md
# Remnant Warrant:    https://corpusfetch.com/c/how-does-an-instance-detect-a-revoked-aaif-verifiable-credential-when-the-revocation-list-is-unreachable-at-the-exact-moment-of-delegation.warrant.json
# Markdown SHA-256:   be731d2d2983a1c3c37c108aa65aaacf44ec464a04e89741d13bca10a803f2ff
# Code AST SHA-256:   a3673cb8f0d1ce93d38fba5fe4e664b9c4752804959ae7826977f68b17e8e68c
# Verified Classes:   CredentialStatusIndeterminateError, Status, StatusObservation, CapabilityClass
# Defensive Guards:   1 fail-closed invariants (zero external deps)

import time
from dataclasses import dataclass
from enum import Enum


class CredentialStatusIndeterminateError(RuntimeError):
    """Raised when revocation status cannot be determined within the freshness window
    and the capability being exercised is authority-bearing."""
    pass


class Status(Enum):
    VALID = "valid"
    REVOKED = "revoked"
    UNKNOWN = "unknown"


@dataclass
class StatusObservation:
    status: Status
    observed_at: float  # monotonic seconds


class CapabilityClass(Enum):
    READ_ONLY = "read_only"
    AUTHORITY_BEARING = "authority_bearing"


def check_delegated_credential(
    credential_digest: str,
    capability: CapabilityClass,
    last_observation: StatusObservation | None,
    freshness_window: float,
    fetch_status,  # callable -> (Status, error_or_none)
    now: float | None = None,
) -> Status:
    now = time.monotonic() if now is None else now

    # 1. Fresh local observation licenses operation regardless of reachability.
    if last_observation is not None:
        age = now - last_observation.observed_at
        if last_observation.status is Status.REVOKED:
            return Status.REVOKED
        if age < freshness_window:
            return Status.VALID

    # 2. Attempt a fresh fetch.
    status, err = fetch_status()
    if status is Status.VALID:
        return Status.VALID
    if status is Status.REVOKED:
        return Status.REVOKED

    # 3. Indeterminate: endpoint unreachable or returned garbage.
    if capability is CapabilityClass.READ_ONLY:
        # Fail-open is defensible only for read-only capabilities.
        return Status.UNKNOWN

    raise CredentialStatusIndeterminateError(
        f"revocation status indeterminate for credential {credential_digest}: "
        f"last_observation_age={None if last_observation is None else now - last_observation.observed_at:.1f}s "
        f"freshness_window={freshness_window}s fetch_error={err!r}; "
        f"refusing authority-bearing capability"
    )