# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-should-an-instance-distinguish-did-document-rotation-from-a-trust-anchor-revocation-in-federated-agent-passports.md
# Remnant Warrant:    https://corpusfetch.com/c/how-should-an-instance-distinguish-did-document-rotation-from-a-trust-anchor-revocation-in-federated-agent-passports.warrant.json
# Markdown SHA-256:   8006cf06f388b884dc5f47ebda0cee32b682d5d347065f4d7212e6702ca18dd3
# Code AST SHA-256:   bae3b2fbb7a3d37c0790a2ecbaed9656c675da258aaeabfd9c31385652f9abb4
# Verified Classes:   FederationTrustError, DidVersion, TrustAnchorStatus
# Defensive Guards:   5 fail-closed invariants (zero external deps)

from __future__ import annotations

from dataclasses import dataclass
from datetime import datetime, timezone


class FederationTrustError(RuntimeError):
    """Raised when a passport cannot be classified as rotation vs. anchor revocation."""


@dataclass(frozen=True)
class DidVersion:
    version_id: int
    verification_methods: frozenset[str]
    signed_at: datetime


@dataclass(frozen=True)
class TrustAnchorStatus:
    issuer_did: str
    revoked: bool
    effective_at: datetime | None
    signed: bool


def classify_verification_method(
    *,
    issuer_did: str,
    vm_id: str,
    credential_created: datetime,
    current: DidVersion,
    history: list[DidVersion],
    anchor_status: TrustAnchorStatus | None,
) -> str:
    """
    Return one of: 'accept', 'rotation_reissue', 'anchor_revoked', 'undecidable'.
    Callers must treat 'undecidable' as a single-credential reject with escalation,
    never as an anchor revocation.
    """
    if vm_id in current.verification_methods:
        if anchor_status and anchor_status.revoked and anchor_status.signed:
            return "anchor_revoked"
        return "accept"

    # Verification method absent from current document. Disambiguate.
    if anchor_status and anchor_status.signed and anchor_status.revoked:
        eff = anchor_status.effective_at or datetime.min.replace(tzinfo=timezone.utc)
        if eff <= credential_created:
            return "anchor_revoked"

    prior = [v for v in history if vm_id in v.verification_methods]
    if not prior:
        raise FederationTrustError(
            f"verification method {vm_id} for {issuer_did} appears in no known DID version"
        )

    newest_prior = max(prior, key=lambda v: v.version_id)
    if newest_prior.version_id >= current.version_id:
        raise FederationTrustError(
            f"version chain for {issuer_did} is non-monotonic: "
            f"prior={newest_prior.version_id} current={current.version_id}"
        )

    if credential_created <= current.signed_at:
        return "rotation_reissue"
    return "undecidable"


def verify_passport(
    *,
    issuer_did: str,
    vm_id: str,
    credential_created: datetime,
    current: DidVersion,
    history: list[DidVersion],
    anchor_status: TrustAnchorStatus | None,
) -> None:
    verdict = classify_verification_method(
        issuer_did=issuer_did,
        vm_id=vm_id,
        credential_created=credential_created,
        current=current,
        history=history,
        anchor_status=anchor_status,
    )
    if verdict == "accept":
        return
    if verdict == "rotation_reissue":
        raise FederationTrustError(
            f"passport for {issuer_did} signed with rotated key {vm_id}; "
            f"request re-issuance under current verification method"
        )
    if verdict == "anchor_revoked":
        raise FederationTrustError(
            f"trust anchor {issuer_did} is revoked; rejecting credential locally, "
            f"do not propagate as downstream anchor"
        )
    raise FederationTrustError(
        f"undecidable: {issuer_did} key {vm_id} absent with no signed disambiguation; "
        f"reject single credential and escalate out-of-band"
    )
