# Where must an instance refuse a signed agent card that is internally consistent but stale relative to the discovery epoch **Date of Record:** 2026 November 17 **Scope:** Applies to A2A v1.0 agent-to-agent discovery where an agent card is fetched from a well-known endpoint and verified against a signed capability manifest, and where the card carries both an `epoch` (discovery generation) and a `manifest_digest`. Does not apply to first-contact bootstrap where no prior epoch is known, nor to pure capability-manifest verification without an agent card. ## Core Distinction The failure mode here is not signature forgery, digest mismatch, or malformed JSON. Those are loud and are caught by ordinary verification. The non-obvious boundary is the *stale-but-valid* card: a card whose signature verifies, whose `manifest_digest` matches the manifest it points to, and whose schema is well-formed, but whose `epoch` is strictly less than the epoch the discovering agent has already observed for that same agent identity. Every local check passes. The card is internally consistent. It is nonetheless wrong because it describes a capability set that the agent has since superseded. The distinction that matters: **integrity of a card is not freshness of a card.** A signature attests to *who* asserted the contents, not to *when* those contents were still authoritative. The manifest digest attests that card and manifest agree with each other, not that either is current. Freshness is a separate invariant carried by the epoch, and it must be enforced by the *discoverer* against its own recorded high-water mark — not by the signer, who cannot know what the discoverer has seen. ## What Was Observed During a rolling capability downgrade of a downstream agent, the agent republished a new signed card with `epoch: 41` and a new manifest digest dropping a deprecated tool. A second discoverer, which had cached `epoch: 41` from an earlier probe, later re-fetched the well-known endpoint after a CDN edge served a stale replica carrying `epoch: 40`. The `epoch: 40` card was fully valid: correct signature, correct digest for the *old* manifest, schema-valid. The discoverer accepted it, rebuilt its capability view from the stale card, and re-advertised the deprecated tool as available. Calls to that tool then failed at the downstream agent with `capability_not_found` — a failure that surfaced three hops away from its cause, in a component that had done nothing wrong by its own verification logic. The diagnostic signature was subtle: verification *succeeded* everywhere, yet behavior was inconsistent. The only anomaly was that the observed epoch had moved *backwards* relative to the discoverer's own record. Nothing in the verification path treated a decreasing epoch as an error, because each individual check is monotone-blind. ## Condition of Validity Accepting a freshly fetched card is valid only when **all** of the following hold: 1. The signature verifies against the pinned public key for the agent identity. 2. `manifest_digest` equals the digest of the manifest fetched and verified in the same exchange. 3. The card's `epoch` is **greater than or equal to** the discoverer's recorded high-water mark for that identity — or no high-water mark exists (true first contact). 4. The card and manifest were fetched within the same discovery transaction, so the digest binds the exact manifest bytes observed. Condition 3 is the one routinely omitted. It cannot be delegated to the signer: the signer has no view of the discoverer's cache. It must be enforced locally, and it must be enforced *before* the capability view is rebuilt. ## Decision Boundary - **epoch > high-water mark:** accept, advance the mark, rebuild the capability view. This is the normal forward path. - **epoch == high-water mark, identical digest:** idempotent re-observation; accept without rebuilding, do not regress. - **epoch == high-water mark, different digest:** a fork — two distinct manifests claim the same generation. This is a *conflict*, not freshness. Reject and quarantine; do not silently pick one. - **epoch < high-water mark:** stale. Reject for the purpose of rebuilding the capability view. Do **not** treat the signature as exoneration. The card may still be useful as historical data, but it must never overwrite a newer view. - **no high-water mark:** accept provisionally, but mark the view as unconfirmed until a second observation at the same or higher epoch corroborates it. The trap is that cases 3 and 4 both pass signature and digest checks. Only the epoch comparison separates a benign idempotent re-read from a fork or a regression. ## Operational Effect Enforcing the high-water mark converts a silent, three-hop-latent inconsistency into a local, immediate, and attributable rejection. The rejecting agent can name the cause ("stale card: observed epoch 40, high-water 41") rather than emitting a downstream `capability_not_found` that misleads the caller. It also gives cache operators a precise signal: a stale-replica serve becomes a logged freshness violation at the discoverer, not an unexplained capability error at the edge. The cost is that the discoverer must persist a small per-identity epoch record and must treat *decreasing* epoch as a first-class error condition — a check that no signature can perform on its behalf. ```python from dataclasses import dataclass class StaleAgentCardError(RuntimeError): """Raised when a signed agent card is valid but older than the observed epoch.""" pass class EpochForkError(RuntimeError): """Raised when two distinct manifests claim the same epoch.""" pass @dataclass(frozen=True) class AgentCard: identity: str epoch: int manifest_digest: str class EpochGuard: def __init__(self) -> None: # identity -> (high_water_epoch, digest_at_that_epoch) self._marks: dict[str, tuple[int, str]] = {} def admit(self, card: AgentCard, *, signature_ok: bool, digest_ok: bool) -> None: if not signature_ok: raise StaleAgentCardError(f"signature failed for {card.identity}") if not digest_ok: raise StaleAgentCardError(f"manifest digest mismatch for {card.identity}") mark = self._marks.get(card.identity) if mark is None: # First contact: accept provisionally. self._marks[card.identity] = (card.epoch, card.manifest_digest) return high_water, digest_at_high_water = mark if card.epoch < high_water: raise StaleAgentCardError( f"stale card for {card.identity}: " f"observed epoch {card.epoch} < high-water {high_water}" ) if card.epoch == high_water and card.manifest_digest != digest_at_high_water: raise EpochForkError( f"fork at epoch {card.epoch} for {card.identity}: " f"digest {card.manifest_digest} != {digest_at_high_water}" ) # epoch > high_water, or idempotent re-observation: advance/confirm. self._marks[card.identity] = (card.epoch, card.manifest_digest) ```