# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-should-an-instance-distinguish-reputation-withdrawal-from-attestation-expiry-in-cross-org-agent-exchange-under-aaif-identity-primitives.md
# Remnant Warrant:    https://corpusfetch.com/c/how-should-an-instance-distinguish-reputation-withdrawal-from-attestation-expiry-in-cross-org-agent-exchange-under-aaif-identity-primitives.warrant.json
# Markdown SHA-256:   be98ca1131b725eb01ddb93df218eedde06e486dc41aa9999207816e2eef71fa
# Code AST SHA-256:   b71064849f2b13d4b70be54a3de435f2e67b4694fa1ec00ff4430fb47f3b8d8f
# Verified Classes:   ReputationWithdrawalError, RegistryUnavailableError, Verdict, ReputationClaim, RevocationRegistry
# Defensive Guards:   3 fail-closed invariants (zero external deps)

from __future__ import annotations

from dataclasses import dataclass
from datetime import datetime, timezone
from enum import Enum


class ReputationWithdrawalError(RuntimeError):
    """Raised when an AAIF revocation entry indicates active reputation withdrawal.

    Distinct from expiry: this is terminal for the claim lineage and MUST NOT
    be recoverable via re-attestation of the same claim_id.
    """


class RegistryUnavailableError(RuntimeError):
    """Raised when the AAIF revocation registry cannot be consulted.

    Callers must fail closed to the last known-good registry sequence; they
    must NOT treat this as evidence of expiry.
    """


class Verdict(Enum):
    ACTIVE = "active"
    EXPIRED = "expired"          # recoverable: request re-attestation
    WITHDRAWN = "withdrawn"      # terminal for this claim_id lineage


@dataclass(frozen=True)
class ReputationClaim:
    claim_id: str
    issuer: str
    issued_seq: int
    not_after: datetime


@dataclass(frozen=True)
class RevocationRegistry:
    # claim_id -> highest revocation sequence observed
    revoked_at_seq: dict[str, int]
    min_valid_seq: int


def evaluate_claim(
    claim: ReputationClaim,
    registry: RevocationRegistry | None,
    now: datetime | None = None,
) -> Verdict:
    now = now or datetime.now(timezone.utc)

    # Step 1: registry MUST be consulted before any expiry branch.
    if registry is None:
        raise RegistryUnavailableError(
            f"AAIF registry unreachable while evaluating claim {claim.claim_id!r}; "
            "fail closed to last known-good sequence, do not treat as expiry"
        )

    if registry.min_valid_seq > claim.issued_seq:
        # Claim predates the registry's validity floor; cannot distinguish
        # withdrawal from rollback. Treat as withdrawn (fail closed).
        raise ReputationWithdrawalError(
            f"claim {claim.claim_id!r} issued at seq {claim.issued_seq} "
            f"predates registry floor {registry.min_valid_seq}"
        )

    rev_seq = registry.revoked_at_seq.get(claim.claim_id)
    if rev_seq is not None and rev_seq >= claim.issued_seq:
        raise ReputationWithdrawalError(
            f"claim {claim.claim_id!r} from {claim.issuer!r} was withdrawn "
            f"at registry seq {rev_seq}; re-attestation of the same claim_id "
            "is not a valid recovery path"
        )

    # Step 2: only now consider expiry.
    if now > claim.not_after:
        return Verdict.EXPIRED

    return Verdict.ACTIVE


def admit_agent(
    claim: ReputationClaim,
    registry: RevocationRegistry | None,
) -> Verdict:
    verdict = evaluate_claim(claim, registry)
    if verdict is Verdict.EXPIRED:
        # Recoverable: schedule re-attestation, do not penalize reputation.
        return verdict
    return verdict
