# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/when-must-an-instance-refuse-an-a2a-v1-0-agent-card-whose-advertised-capabilities-diverge-from-the-task-lifecycle-it-can-actually-commit-to.md
# Remnant Warrant:    https://corpusfetch.com/c/when-must-an-instance-refuse-an-a2a-v1-0-agent-card-whose-advertised-capabilities-diverge-from-the-task-lifecycle-it-can-actually-commit-to.warrant.json
# Markdown SHA-256:   378a1c6f4c6a2db8c4e89c0d269e62152e6e295fda27dc81b2e65972ad9748d2
# Code AST SHA-256:   1823cdbb22ecac8060a4f45f1ce2188f6bde893328fb028b47d2fb9787f19694
# Verified Classes:   LifecycleState, NonConformingArtifactError, AgentCard, TaskRequest, LifecycleEvent
# Defensive Guards:   4 fail-closed invariants (zero external deps)

from __future__ import annotations

from dataclasses import dataclass
from enum import Enum
from typing import Iterable


class LifecycleState(str, Enum):
    SUBMITTED = "submitted"
    WORKING = "working"
    INPUT_REQUIRED = "input-required"
    COMPLETED = "completed"
    FAILED = "failed"
    CANCELED = "canceled"


class NonConformingArtifactError(RuntimeError):
    """Raised when a terminal artifact violates the negotiated output modes
    or contradicts a capability the Agent Card advertised as load-bearing."""


@dataclass(frozen=True)
class AgentCard:
    streaming: bool
    output_modes: frozenset[str]
    required_extensions: frozenset[str]


@dataclass(frozen=True)
class TaskRequest:
    accepted_output_modes: frozenset[str]
    requires_streaming: bool


@dataclass(frozen=True)
class LifecycleEvent:
    state: LifecycleState
    artifact_mode: str | None = None
    is_artifact_update: bool = False


def assert_conforming_completion(
    card: AgentCard,
    request: TaskRequest,
    events: Iterable[LifecycleEvent],
) -> None:
    """Enforce the discovery-vs-lifecycle boundary.

    Refuses only when a terminal-adjacent event positively contradicts a
    capability the request made load-bearing. Absence alone is not refusal
    grounds; a contradicting terminal artifact is.
    """
    saw_artifact_update = False
    for event in events:
        if event.is_artifact_update:
            saw_artifact_update = True

        if event.state is not LifecycleState.COMPLETED:
            continue

        # Terminal artifact must satisfy accepted output modes.
        if event.artifact_mode is not None and event.artifact_mode not in request.accepted_output_modes:
            raise NonConformingArtifactError(
                f"Agent '{card}' completed with artifact mode "
                f"{event.artifact_mode!r} outside accepted modes "
                f"{sorted(request.accepted_output_modes)}; card advertised "
                f"{sorted(card.output_modes)}. State machine has no reverse "
                f"edge from completed."
            )

        # Streaming was load-bearing but no incremental artifact update ever
        # arrived, and the agent did not offer input-required to renegotiate.
        if request.requires_streaming and card.streaming and not saw_artifact_update:
            raise NonConformingArtifactError(
                "Card advertised streaming: true and request required it, but "
                "no TaskArtifactUpdateEvent was observed before completion; "
                "agent dropped a load-bearing capability without offering "
                "input-required renegotiation."
            )


def discover_and_validate(card: AgentCard, request: TaskRequest) -> None:
    """Cheap discovery-time check: never refuse on shape alone, but reject
    requests whose load-bearing needs the card explicitly disclaims."""
    if request.requires_streaming and not card.streaming:
        raise NonConformingArtifactError(
            "Request requires streaming but Agent Card disclaims it; refusing "
            "before task submission (free refusal, no lifecycle cost)."
        )
    if not (request.accepted_output_modes & card.output_modes):
        raise NonConformingArtifactError(
            f"No intersection between accepted modes "
            f"{sorted(request.accepted_output_modes)} and advertised "
            f"{sorted(card.output_modes)}; refusal at discovery is free."
        )
