# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/which-invariants-prevent-silent-task-state-divergence-during-a2a-v1-0-agent-card-re-resolution-and-cross-vendor-artifact-handoff.md
# Remnant Warrant:    https://corpusfetch.com/c/which-invariants-prevent-silent-task-state-divergence-during-a2a-v1-0-agent-card-re-resolution-and-cross-vendor-artifact-handoff.warrant.json
# Markdown SHA-256:   b2b98675d0b2d9c59afaef939eed7383b9380b0343ff88b0e70b7687fbf9f959
# Code AST SHA-256:   4335f42f404b855a6cabd320638920eff3b9a836e4710f30670b639b98aead2c
# Verified Classes:   TaskStateDivergenceError, PinnedTask
# Defensive Guards:   2 fail-closed invariants (zero external deps)

from dataclasses import dataclass, field
from typing import Literal

TaskState = Literal["submitted", "working", "input-required", "completed", "failed", "canceled"]
TERMINAL = {"completed", "failed", "canceled"}


class TaskStateDivergenceError(RuntimeError):
    """Raised when a pinned-snapshot task observes a state or artifact
    inconsistent with the Agent Card version that admitted it."""


@dataclass
class PinnedTask:
    task_id: str
    admitted_card_version: str
    admitted_output_modes: frozenset[str]
    admitted_streaming: bool
    local_state: TaskState = "submitted"
    server_state: TaskState | None = None
    artifacts_seen: list[str] = field(default_factory=list)


def validate_artifact(task: PinnedTask, artifact_kind: str, server_state: TaskState) -> None:
    # Server terminal state is authoritative for task state; never overwrite it.
    task.server_state = server_state
    if artifact_kind not in task.admitted_output_modes:
        raise TaskStateDivergenceError(
            f"task {task.task_id}: artifact kind {artifact_kind!r} not in "
            f"admission-time outputModes {sorted(task.admitted_output_modes)} "
            f"(card {task.admitted_card_version}); do NOT mark failed — record divergence"
        )
    task.artifacts_seen.append(artifact_kind)


def reconcile_terminal(task: PinnedTask) -> None:
    if task.local_state in TERMINAL and task.server_state in TERMINAL:
        if task.local_state != task.server_state:
            raise TaskStateDivergenceError(
                f"task {task.task_id}: local={task.local_state} server={task.server_state} "
                f"under card {task.admitted_card_version}"
            )
    elif task.server_state in TERMINAL:
        task.local_state = task.server_state  # adopt authoritative terminal


def on_card_refresh(task: PinnedTask, new_version: str, new_streaming: bool) -> str:
    if new_version == task.admitted_card_version:
        return "noop"
    if task.admitted_streaming and not new_streaming and task.local_state not in TERMINAL:
        # Capability withdrawn mid-flight: drain, do not reconfigure.
        return "drain"
    return "adopt-for-new-tasks"
