# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/under-what-conditions-must-an-instance-reject-an-a2a-v1-0-agent-card-whose-declared-capabilities-streaming-and-tasklifecycle-terminalstates-are-indivi.md
# Remnant Warrant:    https://corpusfetch.com/c/under-what-conditions-must-an-instance-reject-an-a2a-v1-0-agent-card-whose-declared-capabilities-streaming-and-tasklifecycle-terminalstates-are-indivi.warrant.json
# Markdown SHA-256:   2b29a7d801aa84eb19c483531a55cbf3cbc52f793d6cdd5fd09debdbfd09cd79
# Code AST SHA-256:   0f808099caae5b5d6037847ed62c5feb868d36d394d438864df01bf8b381ef0d
# Verified Classes:   IncoherentAgentCardError, CardLifecycle, DiscoveryVerdict
# Defensive Guards:   3 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from typing import Iterable


class IncoherentAgentCardError(RuntimeError):
    """Raised when an A2A v1.0 Agent Card is schema-valid but lifecycle-incoherent."""


INTERRUPT_STATES = frozenset({"input-required", "auth-required"})
DEFAULT_TERMINAL = frozenset({"completed", "failed", "canceled"})


@dataclass(frozen=True)
class CardLifecycle:
    streaming: bool
    terminal_states: frozenset[str]
    resumable: bool
    resumable_states: frozenset[str]
    has_explicit_lifecycle: bool


@dataclass(frozen=True)
class DiscoveryVerdict:
    accept: bool
    degraded: bool
    reason: str


def evaluate_card(card: CardLifecycle, *, allow_degraded: bool) -> DiscoveryVerdict:
    terminal = card.terminal_states
    resumable_set = card.resumable_states | (INTERRUPT_STATES if card.resumable else frozenset())

    if not card.streaming:
        return DiscoveryVerdict(True, False, "non-streaming; lifecycle invariant not applicable")

    if not card.has_explicit_lifecycle:
        # Implicit default terminal set excludes interrupt states; streaming is incoherent.
        if allow_degraded:
            return DiscoveryVerdict(True, True, "no taskLifecycle block; interrupt states unresumable")
        raise IncoherentAgentCardError(
            "streaming card omits taskLifecycle; interrupt states are neither terminal nor resumable"
        )

    stranded = INTERRUPT_STATES - terminal - resumable_set
    if stranded:
        raise IncoherentAgentCardError(
            f"streaming card strands interrupt states {sorted(stranded)}: "
            f"not in terminalStates {sorted(terminal)} and not resumable"
        )

    interrupt_terminal_only = INTERRUPT_STATES & terminal
    if interrupt_terminal_only and not (INTERRUPT_STATES & resumable_set):
        if allow_degraded:
            return DiscoveryVerdict(
                True, True, f"interrupt states {sorted(interrupt_terminal_only)} terminal-only; resume disabled"
            )
        raise IncoherentAgentCardError(
            "interrupt states are terminal-only; caller must opt in to degraded acceptance"
        )

    return DiscoveryVerdict(True, False, "coherent streaming lifecycle")


def register_cards(cards: Iterable[CardLifecycle], *, allow_degraded: bool) -> list[DiscoveryVerdict]:
    verdicts = []
    for card in cards:
        verdicts.append(evaluate_card(card, allow_degraded=allow_degraded))
    return verdicts
