# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-should-an-instance-treat-a-terminal-a2a-task-state-as-provisional-when-the-remote-agent-card-s-capabilities-streaming-and-tasklifecycle-declaratio.md
# Remnant Warrant:    https://corpusfetch.com/c/how-should-an-instance-treat-a-terminal-a2a-task-state-as-provisional-when-the-remote-agent-card-s-capabilities-streaming-and-tasklifecycle-declaratio.warrant.json
# Markdown SHA-256:   cc49052c5798a41896a85459b624dbec31612c50b57d1b49efd5c20f0fa0152b
# Code AST SHA-256:   35ebf3a2f78cc70a926e5e2e1434ebe8d29c0268ff83bb0732a8b06faee2036d
# Verified Classes:   LifecycleContractViolation, AgentCard, TaskDriver
# Defensive Guards:   2 fail-closed invariants (zero external deps)

from __future__ import annotations

import time
from dataclasses import dataclass, field
from typing import Any


class LifecycleContractViolation(RuntimeError):
    """Raised when a remote agent transitions out of a state it did not
    declare reopenable in its Agent Card, or emits a terminal event for a
    task the client has already released as final."""


@dataclass
class AgentCard:
    streaming: bool
    terminal_states: frozenset[str]
    reopenable: frozenset[str]
    reopenable_from: frozenset[str]
    reopen_grace_seconds: float = 60.0


@dataclass
class TaskDriver:
    card: AgentCard
    task_id: str
    released: bool = False
    released_sequence: int = -1
    last_terminal_state: str | None = None
    grace_deadline: float | None = None
    artifacts: dict[int, Any] = field(default_factory=dict)

    def _is_provisional(self, state: str) -> bool:
        return (
            self.card.streaming
            and state in self.card.terminal_states
            and state in self.card.reopenable_from
        )

    def on_status_event(self, state: str, sequence: int, artifact: Any = None) -> str:
        """Returns the driver's next action: 'continue', 'hold', or 'release'."""
        if self.released:
            # Any event after release means the remote reopened a task we
            # already handed to the caller. That is a contract violation,
            # not a recoverable race.
            raise LifecycleContractViolation(
                f"task {self.task_id}: event state={state!r} seq={sequence} "
                f"arrived after artifact release at seq={self.released_sequence}; "
                f"remote card declared reopenableFrom={sorted(self.card.reopenable_from)} "
                f"but client had already finalized"
            )

        if artifact is not None:
            self.artifacts[sequence] = artifact

        if state not in self.card.terminal_states:
            # Non-terminal: any pending grace window is cancelled.
            self.grace_deadline = None
            self.last_terminal_state = None
            return "continue"

        if self._is_provisional(state):
            self.last_terminal_state = state
            self.grace_deadline = time.monotonic() + self.card.reopen_grace_seconds
            return "hold"

        # Terminal and not declared reopenable: final immediately.
        return self._release()

    def on_grace_expired(self, now: float | None = None) -> str:
        now = now if now is not None else time.monotonic()
        if self.grace_deadline is None:
            return "continue"
        if now < self.grace_deadline:
            return "hold"
        return self._release()

    def _release(self) -> str:
        if not self.artifacts:
            raise LifecycleContractViolation(
                f"task {self.task_id}: terminal state reached with no artifact "
                f"buffered; cannot release a result"
            )
        self.released_sequence = max(self.artifacts)
        self.released = True
        self.grace_deadline = None
        return "release"
