# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/when-must-an-instance-refuse-a-delegated-task-mid-lifecycle-the-a2a-v1-0-card-staleness-invariant-at-handshake-boundaries.md
# Remnant Warrant:    https://corpusfetch.com/c/when-must-an-instance-refuse-a-delegated-task-mid-lifecycle-the-a2a-v1-0-card-staleness-invariant-at-handshake-boundaries.warrant.json
# Markdown SHA-256:   c70388597fbf5ddb1e9488032a232496640a9a20c29091aaa0206605d75fd4cc
# Code AST SHA-256:   6ba03ec2a054f14767b384be9e29b38bb675635eb57f02758f5830cb0cc201ab
# Verified Classes:   CardStalenessError, AgentCard, DelegatedTask
# Defensive Guards:   2 fail-closed invariants (zero external deps)

import hashlib
from dataclasses import dataclass, field
from typing import FrozenSet


class CardStalenessError(RuntimeError):
    """Raised when a delegated task's required capabilities are not covered
    by the callee's live capability set at the submitted->working boundary."""


@dataclass(frozen=True)
class AgentCard:
    agent_id: str
    version: str
    skills: FrozenSet[str]
    capabilities: FrozenSet[str]

    def digest(self) -> str:
        payload = f"{self.agent_id}|{self.version}|{sorted(self.skills)}|{sorted(self.capabilities)}"
        return hashlib.sha256(payload.encode()).hexdigest()


@dataclass
class DelegatedTask:
    task_id: str
    required_skills: FrozenSet[str]
    required_capabilities: FrozenSet[str]
    resolved_card_digest: str
    state: str = "submitted"


def accept_delegation(task: DelegatedTask, live_card: AgentCard) -> DelegatedTask:
    """Callee-side gate: must run before any submitted->working transition.

    Refuses if the live capability set does not cover the task, OR if the
    caller resolved a card whose digest differs from the live card's digest
    AND the live card no longer covers the task (capability-set divergence,
    not mere version change).
    """
    missing_skills = task.required_skills - live_card.skills
    missing_caps = task.required_capabilities - live_card.capabilities

    if missing_skills or missing_caps:
        raise CardStalenessError(
            f"task {task.task_id} cannot enter 'working': live card "
            f"{live_card.agent_id}@{live_card.version} missing "
            f"skills={sorted(missing_skills)} capabilities={sorted(missing_caps)}"
        )

    if task.resolved_card_digest != live_card.digest():
        # Card was superseded, but live card still covers the task:
        # permitted, but the divergence must be recorded for audit.
        task.state = "working"
        task.metadata = getattr(task, "metadata", {})
        task.metadata["card_digest_mismatch"] = {
            "resolved": task.resolved_card_digest,
            "live": live_card.digest(),
        }
        return task

    task.state = "working"
    return task


def caller_check_before_dispatch(task: DelegatedTask, cached_card: AgentCard,
                                 fresh_card: AgentCard) -> None:
    """Caller-side gate: cancel rather than dispatch if the fresh card
    no longer covers a task justified by the cached card."""
    if cached_card.digest() == fresh_card.digest():
        return
    missing = (task.required_skills - fresh_card.skills) | (
        task.required_capabilities - fresh_card.capabilities
    )
    if missing:
        raise CardStalenessError(
            f"caller refusing to dispatch {task.task_id}: cached card "
            f"{cached_card.version} superseded by {fresh_card.version}, "
            f"no longer covers {sorted(missing)}; issue tasks/cancel"
        )
