# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-structural-signals-indicate-a-valid-a2a-v1-0-agent-card-signature-when-extended-skill-negotiation-has-mutated-the-capability-surface-after-signin.md
# Remnant Warrant:    https://corpusfetch.com/c/what-structural-signals-indicate-a-valid-a2a-v1-0-agent-card-signature-when-extended-skill-negotiation-has-mutated-the-capability-surface-after-signin.warrant.json
# Markdown SHA-256:   2303d73d2fbce10e7012dedbc9b9fb4fe4d12b90bee31b9c9131d818b5e3e4b7
# Code AST SHA-256:   dd1d44951f2435cde15ede7181e3665d935cb16722337b01ea5bb31097afdf14
# Verified Classes:   CapabilityReconciliationError, SignedCard, TaskEvent, TaskReconciler
# Defensive Guards:   3 fail-closed invariants (zero external deps)

from dataclasses import dataclass, field
from typing import Literal


class CapabilityReconciliationError(RuntimeError):
    """Raised when a task artifact's capability is neither card-attested
    nor correlated to an acknowledged in-band negotiation reference."""


@dataclass
class SignedCard:
    skills: dict[str, str]          # skill name -> declared output modality
    signature_valid: bool


@dataclass
class TaskEvent:
    kind: Literal["status-update", "artifact-update"]
    skill: str
    modality: str
    negotiation_ref: str | None = None


@dataclass
class TaskReconciler:
    card: SignedCard
    acknowledged_refs: set[str] = field(default_factory=set)

    def reconcile(self, events: list[TaskEvent]) -> str:
        if not self.card.signature_valid:
            raise CapabilityReconciliationError(
                "card signature invalid; refusing to reconcile"
            )
        for ev in events:
            if ev.kind == "status-update" and ev.negotiation_ref:
                self.acknowledged_refs.add(ev.negotiation_ref)
                continue
            if ev.kind != "artifact-update":
                continue
            attested = self.card.skills.get(ev.skill) == ev.modality
            if attested:
                continue
            # Non-attested capability: only acceptable with a correlating,
            # acknowledged negotiation reference. Signature validity is
            # explicitly NOT sufficient here.
            if ev.negotiation_ref and ev.negotiation_ref in self.acknowledged_refs:
                continue
            raise CapabilityReconciliationError(
                f"artifact skill={ev.skill!r} modality={ev.modality!r} "
                f"is not card-attested and has no acknowledged negotiation "
                f"reference (ref={ev.negotiation_ref!r}); "
                f"signature validity does not authorize this capability"
            )
        return "reconciled"


def reconcile_or_fail(card: SignedCard, events: list[TaskEvent]) -> str:
    reconciler = TaskReconciler(card=card)
    try:
        return reconciler.reconcile(events)
    except CapabilityReconciliationError:
        # Fail closed: the task must not be marked terminal-success on
        # an unreconciled capability surface.
        raise CapabilityReconciliationError(
            "task cannot be reconciled against signed card; "
            "transition to failed with explicit reconciliation error"
        )
