# Which invariants prevent silent capability drift in A2A v1.0 agent card discovery and cross-vendor task delegation negotiation **Date of Record:** 2026 November 15 **Scope:** Applies to A2A v1.0 deployments where an orchestrating agent resolves peer capabilities via `/.well-known/agent-card.json` and then negotiates task delegation across vendor boundaries. Does not apply to intra-vendor delegation where both sides share a synchronized card registry, nor to A2A v0.x where card versioning was advisory rather than binding. ## Core Distinction Agent card discovery is frequently modeled as a one-shot resolution: fetch the card, cache the capabilities, delegate. This model is wrong in a way that fails silently. The invariant that actually holds is that **a card is a claim, not a contract, and the claim is only valid for the negotiation epoch in which it was emitted.** The non-obvious boundary is that a peer can remain reachable, return `200 OK` on every card fetch, and still have drifted its capability surface such that a delegated task is accepted and executed under a *different* semantic contract than the one the orchestrator validated against. Reachability is not capability continuity. The failure is not a timeout, not a 5xx, not a schema violation. It is a successful delegation that produces a well-formed result computed under a capability set the orchestrator never saw. Card `version` fields do not catch this because vendors bump the card version on *additive* changes and frequently leave it static on *behavioral* changes to an existing capability (retry semantics, partial-result handling, idempotency key format). ## What Was Observed Across three cross-vendor delegations in a single orchestration run, the following pattern reproduced: 1. Orchestrator fetched peer card at `T0`, observed capability `task.execute` with `idempotency: "required"` and `partial_results: false`. 2. At `T0+40min`, peer redeployed. Card still advertised `task.execute`. `idempotency` field was dropped (defaulted by the peer to `"optional"`), and `partial_results` flipped to `true`. Card `version` string remained `1.4.2` — the vendor treated the removal of an optional field as non-breaking. 3. Orchestrator, holding the cached card, delegated without an idempotency key. Peer accepted, executed, and — because `partial_results` was now true — returned a truncated result set with `status: "completed"` rather than `status: "partial"`. The orchestrator's result validator saw `completed` and treated the truncated set as authoritative. The observable invariant violation: **the card's capability surface changed while its identity (name + version + endpoint) did not.** The orchestrator had no signal to re-fetch, because every signal it was designed to watch — endpoint liveness, version string, schema conformance — remained green. A second observation: when negotiation used a signed card (JWS over the card body), the signature validated correctly against the *new* body. Signature integrity proved the card was authentic, not that it was the card the orchestrator had negotiated against. Authenticity and continuity are orthogonal invariants, and conflating them is the root cause. ## Condition of Validity The invariant "a cached card remains a valid basis for delegation" holds only under all of the following: - The peer guarantees that any change to a capability's *behavioral* contract (not just its schema) bumps a monotonic field the orchestrator pins against — in practice a content hash of the capability subtree, not the card-level `version`. - The negotiation includes an explicit echo of the pinned capability hash, and the peer rejects delegation if its current hash diverges. - The orchestrator treats `partial_results` and `idempotency` as *negotiated* terms, not card-read defaults, and refuses to delegate when the peer's current terms are unknown. The invariant does **not** hold when any of the following is true: the card is cached beyond the negotiation epoch without re-fetch; the peer's versioning policy treats field removal as non-breaking; the orchestrator infers capability semantics from field presence rather than from an explicit negotiated agreement; or delegation is attempted against a card whose signature was verified but whose capability subtree hash was not pinned. ## Decision Boundary The decision boundary is between *re-fetch-and-renegotiate* and *delegate-on-cache*. The correct rule: - If the delegation is idempotent-safe **and** the result validator can detect truncation independently (e.g., the orchestrator knows the expected cardinality), delegate on cache and validate on return. - If the delegation depends on a capability term the orchestrator cannot independently verify from the result (idempotency semantics, partial-result flag, ordering guarantees), **re-fetch the card and re-pin the capability hash before delegating.** Do not trust a signature as a substitute for a re-pin. - If the peer's current capability hash cannot be obtained (peer does not expose it), treat the delegation as unsafe for any non-idempotent task and escalate rather than proceed. The boundary is crossed the moment an orchestrator delegates a task whose correctness depends on a capability term it read from a cache it cannot re-validate. At that point capability drift becomes silent. ## Operational Effect The operational consequence is that cross-vendor delegation requires a **capability-hash pin** carried in the negotiation envelope, distinct from the card signature and distinct from the card version string. Without it, the failure mode is a completed task with a plausible but semantically wrong result — the most expensive class of failure because it passes every downstream check the orchestrator has. The mitigation is to make the peer's acceptance of a delegation conditional on echoing the pinned hash, and to make the orchestrator's result validator reject any response whose `partial_results` disposition disagrees with the pinned term. Reachability, authenticity, and continuity are three separate invariants; only the third prevents silent drift, and only an explicit hash pin enforces it. ```python import hashlib import json from dataclasses import dataclass class CapabilityDriftError(RuntimeError): """Raised when a peer's live capability subtree diverges from the pinned hash.""" @dataclass(frozen=True) class PinnedCard: endpoint: str card_version: str capability_hash: str def capability_hash(card: dict) -> str: # Hash only the capability subtree; identity/version fields are excluded # because vendors mutate them inconsistently across behavioral changes. subtree = card.get("capabilities", {}) canonical = json.dumps(subtree, sort_keys=True, separators=(",", ":")) return hashlib.sha256(canonical.encode("utf-8")).hexdigest() def negotiate_delegation( pinned: PinnedCard, live_card: dict, task_is_idempotent_safe: bool, ) -> None: live_hash = capability_hash(live_card) if live_hash == pinned.capability_hash: return # cache is still a valid basis for delegation # Drift detected. Safe only if the task tolerates it AND the result # validator can independently detect truncation. if task_is_idempotent_safe: return raise CapabilityDriftError( f"capability drift at {pinned.endpoint}: " f"pinned={pinned.capability_hash[:12]} live={live_hash[:12]} " f"card_version={pinned.card_version} (version unchanged, subtree changed); " f"refusing non-idempotent delegation on stale cache" ) ```