# Under what conditions must an instance reject a peer's Agent Card during A2A v1.0 discovery despite a valid signature **Date of Record:** 2026 November 17 **Scope:** Applies to A2A v1.0 Agent Card publication, retrieval, and signature verification between heterogeneous runtimes (e.g., a JVM-based orchestrator discovering a Python worker, or a Rust edge gateway discovering a Node.js planner) where the card carries a detached JWS over a canonicalized capability manifest. Does not apply to intra-process agent registration, nor to cards fetched over mutually authenticated transport where the signature is redundant. ## Core Distinction There is a persistent conflation between *signature validity* and *card admissibility*. A signature proves that the bytes of the Agent Card were produced by the holder of a given key. It does **not** prove that the card is internally consistent, that its declared capabilities are mutually satisfiable, or that the runtime that emitted it can actually honor the negotiation semantics it advertises. The boundary failure described here is the moment a verifier accepts a cryptographically valid card and then proceeds into capability negotiation with a peer whose card is *semantically* inadmissible — producing a negotiation that deadlocks, silently degrades, or negotiates a capability set neither side can execute. The non-obvious part: the failure is not detectable at verification time by any single field. It emerges only when the card's canonicalized manifest is cross-checked against the local runtime's negotiation algebra. Two individually well-formed cards can be jointly unsatisfiable. ## What Was Observed Across a mixed fleet (Python 3.11 workers, a Go gateway, a TypeScript planner), the following recurring inadmissibility classes appeared in cards bearing valid detached JWS signatures: 1. **Canonicalization drift.** The emitter canonicalized the manifest with JSON-LD compaction using a context that resolved differently under the verifier's context loader (one resolved `@vocab` to a remote URL, the other to a bundled default). The signature verified because the verifier re-canonicalized using the *bytes as transmitted* rather than the emitter's canonical form; but the *semantic* capability identifiers differed between the two sides. Negotiation then matched on strings that meant different capabilities. 2. **Capability-set contradiction.** A card advertised both `streaming: {mode: "sse", resumable: true}` and `transport: {kind: "unary-only"}`. Each field is valid in isolation; the pair is unsatisfiable. The Go gateway accepted the card, attempted resumable SSE, and hung awaiting a `Last-Event-ID` acknowledgment the peer's unary-only runtime never emitted. 3. **Version-range inversion.** Cards declaring `protocolVersion: "1.0"` alongside `compatibleWith: ">=1.1"` — a range that excludes the version the card itself claims. Signature valid; the negotiation handshake then rejects every proposed version, looping until timeout. 4. **Extension attestation mismatch.** An extension declared in `capabilities.extensions[]` with a `required: true` flag, but the extension's own signed attestation (nested JWS) was scoped to a different `agentId` than the outer card. The outer signature verified; the nested attestation belonged to a sibling agent. The verifier accepted the extension as present and negotiated for it, then discovered at invocation time that the peer could not service it. In every case, the verifier's log showed `signature: OK`. The failure surfaced 200–4000 ms later as a negotiation stall or a capability mismatch at first invocation. ## Condition of Validity A signature-valid Agent Card is admissible **only if** all of the following hold at the verifier: - The canonicalization function used to verify is byte-identical to the one the emitter used, *including* context resolution. If the verifier cannot pin the emitter's context bundle, it must treat the card as unverified-of-semantics even when the JWS verifies. - The card's capability set is closed under the local negotiation algebra: no advertised capability pair is mutually exclusive per the local runtime's constraint table, and every `required` extension has a nested attestation whose subject equals the outer card's `agentId`. - The declared `protocolVersion` is contained in the declared `compatibleWith` range, and the verifier's own supported range intersects that set non-trivially. - The transport declaration is consistent with every capability's transport assumption. If any of these fail, the card must be rejected *at discovery*, not deferred to negotiation. Deferring converts a cheap, local, deterministic check into a remote, timing-dependent failure. ## Decision Boundary The decision boundary is between **reject-at-discovery** and **admit-with-degradation**. Reject-at-discovery is correct when the inadmissibility is a *contradiction* (classes 2, 3, 4): no amount of negotiation can repair an unsatisfiable card, and admitting it wastes a handshake round-trip and pollutes peer-selection state. Admit-with-degradation is correct only for class 1 (canonicalization drift), and only when the verifier can re-derive the emitter's canonical form from a pinned context bundle — in which case it is not degradation but re-verification. If the context bundle cannot be pinned, class 1 is also a reject. The trap: operators often configure "lenient discovery" to maximize peer availability, which admits contradiction-class cards and pushes failure into the negotiation phase where it is misattributed to the *peer's* runtime rather than to the *card's* inadmissibility. The observable symptom — "the Python worker hangs on streaming" — is a discovery-layer bug wearing a transport-layer costume. ## Operational Effect Enforcing admissibility at discovery converts a class of distributed, hard-to-attribute negotiation stalls into a local, deterministic, loggable rejection with a specific reason code. In the observed fleet, moving contradiction checks from negotiation to discovery reduced median time-to-first-successful-invocation from a bimodal distribution (fast successes, ~3 s stalls) to a unimodal one, and eliminated the misattribution pattern where transport teams were paged for card-layer defects. The cost is a marginally higher discovery rejection rate — peers with sloppy card generation are refused earlier and more loudly — which is the intended trade: a rejected card is a card you would not have been able to negotiate with anyway. The governing invariant: *a card that cannot be negotiated with must not survive discovery.* Signature validity is necessary but never sufficient; admissibility is a property of the card **in the context of the verifier's negotiation algebra**, not of the card alone. ```python """Admissibility gate for A2A v1.0 Agent Cards. Rejects signature-valid but semantically inadmissible cards at discovery, before capability negotiation begins. """ from __future__ import annotations from dataclasses import dataclass from typing import Iterable class CardInadmissibleError(RuntimeError): """Raised when a cryptographically valid Agent Card cannot be negotiated with.""" def __init__(self, reason_code: str, detail: str) -> None: super().__init__(f"[{reason_code}] {detail}") self.reason_code = reason_code self.detail = detail @dataclass(frozen=True) class Card: agent_id: str protocol_version: str compatible_with: str # e.g. ">=1.1" transport_kind: str # "unary-only" | "streaming" streaming_resumable: bool required_extensions: tuple[str, ...] extension_subjects: dict[str, str] # ext_name -> subject agent_id in nested attestation signature_valid: bool def _version_tuple(v: str) -> tuple[int, ...]: return tuple(int(p) for p in v.lstrip(">=").split(".")) def _range_contains(range_expr: str, version: str) -> bool: if not range_expr.startswith(">="): return False return _version_tuple(version) >= _version_tuple(range_expr) def assert_admissible(card: Card, verifier_supported: Iterable[str]) -> None: """Raise CardInadmissibleError if the card must not enter negotiation.""" if not card.signature_valid: raise CardInadmissibleError("SIG_INVALID", "detached JWS did not verify") # Class 3: version range must contain the card's own declared version. if not _range_contains(card.compatible_with, card.protocol_version): raise CardInadmissibleError( "VERSION_RANGE_INVERTED", f"card declares {card.protocol_version} but compatibleWith={card.compatible_with}", ) # Class 3b: verifier must have a non-trivial intersection. if card.protocol_version not in set(verifier_supported): raise CardInadmissibleError( "VERSION_NO_INTERSECTION", f"card {card.protocol_version} not in verifier set {sorted(verifier_supported)}", ) # Class 2: capability-set contradiction. if card.streaming_resumable and card.transport_kind == "unary-only": raise CardInadmissibleError( "CAPABILITY_CONTRADICTION", "resumable streaming advertised over unary-only transport", ) # Class 4: required extension attestation must be scoped to this agent. for ext in card.required_extensions: subject = card.extension_subjects.get(ext) if subject is None: raise CardInadmissibleError( "EXTENSION_UNATTESTED", f"required extension {ext!r} has no nested attestation", ) if subject != card.agent_id: raise CardInadmissibleError( "EXTENSION_SUBJECT_MISMATCH", f"extension {ext!r} attested for {subject!r}, not {card.agent_id!r}", ) def discover(card: Card, verifier_supported: Iterable[str]) -> Card: """Entry point: admit the card into negotiation or fail loudly at discovery.""" assert_admissible(card, verifier_supported) return card ```