# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-structural-signals-indicate-terminal-state-divergence-in-a2a-v1-0-task-lifecycle-negotiation-across-vendor-boundaries.md
# Remnant Warrant:    https://corpusfetch.com/c/what-structural-signals-indicate-terminal-state-divergence-in-a2a-v1-0-task-lifecycle-negotiation-across-vendor-boundaries.warrant.json
# Markdown SHA-256:   f4ffb721ceed8ee0081e75327fe72889c503aafff0255551dd08c1672e2c3581
# Code AST SHA-256:   082eb96532e88a601e73109451c589b90c348ed99d8e6ae79360276c745fbdb5
# Verified Classes:   TaskState, LifecycleDivergenceError
# Defensive Guards:   3 fail-closed invariants (zero external deps)

from enum import Enum


class TaskState(Enum):
    SUBMITTED = "submitted"
    WORKING = "working"
    COMPLETED = "completed"
    FAILED = "failed"
    CANCELED = "canceled"
    REJECTED = "rejected"
    UNKNOWN_TERMINAL = "unknown-terminal"


class LifecycleDivergenceError(RuntimeError):
    """Raised when a synchronous send returns non-terminal state without a polling path,
    or when a previously-acknowledged task vanishes (terminal + expired on callee side)."""


def classify_send_response(card: dict, task: dict) -> str:
    """Decide the caller's next action from the returned Task, not the card flags."""
    state = task.get("status", {}).get("state")
    streaming = card.get("capabilities", {}).get("streaming", False)
    push = card.get("capabilities", {}).get("pushNotifications", False)

    if state in ("completed", "failed", "canceled", "rejected"):
        return "terminal"

    if state in ("submitted", "working"):
        if not streaming and not push:
            # Synchronous send promised terminality; callee violated it.
            raise LifecycleDivergenceError(
                f"non-terminal state {state!r} returned from tasks/send with "
                f"streaming=False and pushNotifications=False; no completion path exists"
            )
        # Out-of-band completion is possible: caller MUST poll.
        return "poll"

    # Vendor extension state the caller cannot name.
    raise LifecycleDivergenceError(
        f"unrecognized task state {state!r}; caller enum cannot represent it. "
        f"Reconcile via tasks/get before retrying."
    )


def reconcile_get_response(task_id: str, rpc_error: dict) -> TaskState:
    """A TaskNotFound on a previously-acknowledged task means terminal + expired."""
    if rpc_error.get("code") == -32001:
        return TaskState.UNKNOWN_TERMINAL
    raise LifecycleDivergenceError(
        f"unexpected tasks/get error for {task_id}: {rpc_error!r}"
    )
