# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/when-must-an-instance-refuse-an-a2a-task-acceptance-that-the-peer-s-agent-card-advertises-as-supported.md
# Remnant Warrant:    https://corpusfetch.com/c/when-must-an-instance-refuse-an-a2a-task-acceptance-that-the-peer-s-agent-card-advertises-as-supported.warrant.json
# Markdown SHA-256:   bae657b8e3fd547107e5dd9523d9d12d8259fdcae4da6c68f161d21209c52be0
# Code AST SHA-256:   424e7ee5e6931b188554b4e57a2834cc92526aa1b98e0df52009ff4ba48a0812
# Verified Classes:   CapabilityCorroborationError, TaskShape, AgentCardView, PeerTrustState
# Defensive Guards:   4 fail-closed invariants (zero external deps)

from __future__ import annotations

import time
from dataclasses import dataclass, field
from enum import Enum
from typing import Optional


class CapabilityCorroborationError(RuntimeError):
    """Raised when a peer's advertised capability cannot be trusted for a
    stateful, non-idempotent task and no prior corroboration exists."""


class TaskShape(Enum):
    SINGLE_SHOT = "single_shot"          # one request/response, no continuation
    STATEFUL = "stateful"                # requires input-required / streaming continuation


@dataclass
class AgentCardView:
    revision: str
    streaming: bool
    push_notifications: bool
    input_modes: set[str]
    output_modes: set[str]


@dataclass
class PeerTrustState:
    """Tracks whether a card revision has been corroborated by observed behavior."""
    corroborated_revisions: set[str] = field(default_factory=set)
    last_successful_task_at: Optional[float] = None

    def corroborate(self, revision: str) -> None:
        self.corroborated_revisions.add(revision)
        self.last_successful_task_at = time.monotonic()

    def is_corroborated(self, revision: str) -> bool:
        return revision in self.corroborated_revisions


def negotiate(
    card: AgentCardView,
    trust: PeerTrustState,
    task_shape: TaskShape,
    required_output_mode: str,
    side_effects_idempotent: bool,
    client_deadline_s: float,
) -> str:
    """Return one of 'accept', 'accept_degraded_poll', or raise.

    Raises CapabilityCorroborationError when the task is stateful,
    non-idempotent, and the card revision is uncorroborated.
    """
    # Hard incompatibility: never send a task whose required MIME is not
    # in the advertised output modes. This is not a stale-flag risk.
    if required_output_mode not in card.output_modes:
        raise CapabilityCorroborationError(
            f"peer card revision {card.revision} does not advertise "
            f"output mode {required_output_mode!r}; refusing to send task"
        )

    if task_shape is TaskShape.SINGLE_SHOT:
        return "accept"

    # Stateful task. Streaming/continuation claims are only trustworthy
    # if the revision has been corroborated by prior observed success.
    if trust.is_corroborated(card.revision) and card.streaming:
        return "accept"

    if side_effects_idempotent:
        # Cheap to retry; accept and rely on timeout + cancel + retry.
        return "accept"

    # Stateful, non-idempotent, uncorroborated, streaming advertised but
    # unproven. Do not accept the streaming continuation contract.
    if card.streaming and not trust.is_corroborated(card.revision):
        # Degrade to polling with a cadence well inside the peer's TTL.
        poll_cadence = min(5.0, client_deadline_s / 6.0)
        if poll_cadence <= 0:
            raise CapabilityCorroborationError(
                f"deadline {client_deadline_s}s too tight to poll peer "
                f"revision {card.revision} safely"
            )
        return "accept_degraded_poll"

    # Peer does not even advertise streaming for a stateful task.
    raise CapabilityCorroborationError(
        f"peer revision {card.revision} advertises streaming={card.streaming} "
        f"but task requires input-required continuation and side effects are "
        f"non-idempotent; refusing acceptance"
    )


def run_negotiation_example() -> str:
    card = AgentCardView(
        revision="rev-7",
        streaming=True,
        push_notifications=False,
        input_modes={"application/json"},
        output_modes={"application/json"},
    )
    trust = PeerTrustState()  # fresh peer, nothing corroborated
    try:
        return negotiate(
            card=card,
            trust=trust,
            task_shape=TaskShape.STATEFUL,
            required_output_mode="application/json",
            side_effects_idempotent=False,
            client_deadline_s=300.0,
        )
    except CapabilityCorroborationError:
        raise
