From bd7433ea9c5f26611d5051d3864978f6ea0022fe Mon Sep 17 00:00:00 2001 From: garvitkaushik-123 Date: Mon, 24 Aug 2026 01:07:39 +0530 Subject: [PATCH 1/3] docs: complete reference test vector index --- docs/reference/test-vectors/index.mdx | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/docs/reference/test-vectors/index.mdx b/docs/reference/test-vectors/index.mdx index 0d8028c991..8a1dbe71a0 100644 --- a/docs/reference/test-vectors/index.mdx +++ b/docs/reference/test-vectors/index.mdx @@ -6,7 +6,7 @@ description: "Machine-readable fixtures SDKs and implementations diff against to --- **Status**: Request for Comments -**Last Updated**: April 20, 2026 +**Last Updated**: August 24, 2026 ## What these are @@ -18,9 +18,9 @@ Vectors are not the conformance specification — the [storyboards](/docs/buildi ## Versioning -Vector sets published under the compliance tree — `request-signing`, `webhook-signing`, `plan-hash`, `governance-authorization`, `webhook-receiver-envelope`, and `catalog-macro-substitution` — are versioned alongside the spec. The copy served at `/compliance/{version}/test-vectors/{set}/` is frozen at the GA release of that version; fixes that change a vector's bytes ship in the next AdCP minor release. `/compliance/latest/test-vectors/{set}/` tracks the most recent GA and moves under you between releases. +Vector sets published under `static/compliance/source/test-vectors/` are versioned alongside the spec. The copy served at `/compliance/{version}/test-vectors/{set}` is frozen at the GA release of that version; fixes that change a vector's bytes ship in the next AdCP minor release. `/compliance/latest/test-vectors/{set}` tracks the most recent GA and moves under you between releases. -The transport and response-extraction vectors served at `/test-vectors/{name}.json` are currently unversioned: each file is overwritten in place when it changes. SDKs that consume these fixtures SHOULD vendor a commit-pinned copy, for example fetching from `https://raw.githubusercontent.com/adcontextprotocol/adcp//static/test-vectors/.json` and recording `` in their lockfile, until these files are rolled into the versioned compliance tree. +Vector sets served under `/test-vectors/` are currently unversioned: each file is overwritten in place when it changes. SDKs that consume these fixtures SHOULD vendor a commit-pinned copy, for example fetching from `https://raw.githubusercontent.com/adcontextprotocol/adcp//static/test-vectors/.json` and recording `` in their lockfile, until these files are rolled into the versioned compliance tree. SDKs SHOULD fetch versioned paths where available and record the version under test. For pinned versions, the CDN copy at `/compliance/{version}/...` is the source of truth; `/compliance/latest/...` is a convenience alias, not a stable pin. @@ -34,6 +34,16 @@ SDKs SHOULD fetch versioned paths where available and record the version under t | [`governance-authorization`](https://github.com/adcontextprotocol/adcp/blob/main/static/compliance/source/test-vectors/governance-authorization.json) | Cross-role governed-payload JCS/SHA-256 hashes, authorization decisions, and 27 byte-exact Ed25519 compact-JWS fixtures. Signed cases cover critical headers, audience/caller/task/payload bindings, commitment currency and ceiling, time bounds, replay identifiers, signature tampering, and zero-cost authorization. The published private component is test-only and MUST NOT be installed as a production trust anchor. | `static/compliance/source/test-vectors/governance-authorization.json` | `/compliance/latest/test-vectors/governance-authorization.json` | | [`webhook-receiver-envelope`](https://github.com/adcontextprotocol/adcp/blob/main/static/compliance/source/test-vectors/webhook-receiver-envelope.json) | Receiver-side replay vectors for full MCP webhook POST envelopes: canonical delivery-report envelope acceptance, retry idempotency preservation, and rejection of bare result payloads or malformed envelopes | `static/compliance/source/test-vectors/webhook-receiver-envelope.json` | `/compliance/latest/test-vectors/webhook-receiver-envelope.json` | | [`catalog-macro-substitution`](https://github.com/adcontextprotocol/adcp/blob/main/static/compliance/source/test-vectors/catalog-macro-substitution.json) | Catalog-item macro substitution safety: NFC normalization, RFC 3986 percent-encoding, nested-expansion preservation, CRLF neutralization, bidi override neutralization, and URL-scheme injection neutralization | `static/compliance/source/test-vectors/catalog-macro-substitution.json` | `/compliance/latest/test-vectors/catalog-macro-substitution.json` | +| [`universal-macro-translation`](https://github.com/adcontextprotocol/adcp/blob/main/static/compliance/source/test-vectors/universal-macro-translation.json) | Producer-side universal-macro translation: RFC 3986 unreserved-whitelist value encoding, verbatim native insertion, unmapped-macro param dropping, privacy/consent macro advisory, suspect native-value detection, single-pass substitution, and control-character rejection in native mappings | `static/compliance/source/test-vectors/universal-macro-translation.json` | `/compliance/latest/test-vectors/universal-macro-translation.json` | +| [`attestations`](https://github.com/adcontextprotocol/adcp/tree/main/static/compliance/source/test-vectors/attestations) | Portable attestation trust and resolution: allowlist checks, delivery selection, validity windows, revocation, subject and digest comparison, stable outcomes, and the no-network rule for off-policy inputs. Uses a fictional proof format; cryptographic verification bytes are format-specific and tested by each format's own suite | `static/compliance/source/test-vectors/attestations/` | `/compliance/latest/test-vectors/attestations/` | +| [`rights-attestations`](https://github.com/adcontextprotocol/adcp/tree/main/static/compliance/source/test-vectors/rights-attestations) | Rights-grant profile composed with portable attestations: holder/claim/resolver policy, rights-subject checks, JWKS purpose binding, issuer-bound status evidence, constraint-digest comparison, and fail-closed outcomes for paused, revoked, stale, or untrusted grants | `static/compliance/source/test-vectors/rights-attestations/` | `/compliance/latest/test-vectors/rights-attestations/` | +| [`governance-runtime-attestations`](https://github.com/adcontextprotocol/adcp/tree/main/static/compliance/source/test-vectors/governance-runtime-attestations) | `check_governance` signal-activation with portable attestations: normalized outcome and governance verdict, binding-digest computation, deactivation negative-policy, and cache-reuse validity constraints | `static/compliance/source/test-vectors/governance-runtime-attestations/` | `/compliance/latest/test-vectors/governance-runtime-attestations/` | +| [`audience-evidence`](https://github.com/adcontextprotocol/adcp/tree/main/static/compliance/source/test-vectors/audience-evidence) | Population-level audience-evidence contract: product evidence snapshot validation, RFC 8785 content-digest recomputation, requirement-mode enforcement (`required` excludes, `preferred` ranks), `when_available` presence handling, and provider/methodology exclusion lists | `static/compliance/source/test-vectors/audience-evidence/` | `/compliance/latest/test-vectors/audience-evidence/` | +| [`brand-response-signing`](https://github.com/adcontextprotocol/adcp/tree/main/static/compliance/source/test-vectors/brand-response-signing) | Brand-authorization cross-check for `verify_brand_claim` and `verify_brand_claims` envelopes: advisory binding produces verifier-local untrusted results without hard-rejecting the response or rewriting signer-asserted `verification_status`. Mandatory cryptographic brand authorization is deferred to 4.0 | `static/compliance/source/test-vectors/brand-response-signing/` | `/compliance/latest/test-vectors/brand-response-signing/` | +| [`oauth-setup`](https://github.com/adcontextprotocol/adcp/tree/main/static/compliance/source/test-vectors/oauth-setup) | OAuth metadata-graph conformance: deterministic network fixtures for `oauth_metadata_graph` checks, redirect validation, graph-budget enforcement, and fail-closed behavior for missing fixture responses. No live network access permitted | `static/compliance/source/test-vectors/oauth-setup/` | `/compliance/latest/test-vectors/oauth-setup/` | +| [`trusted-match-context-merge`](https://github.com/adcontextprotocol/adcp/tree/main/static/compliance/source/test-vectors/trusted-match-context-merge) | Context Match targeting key-value merge: router attribution from publisher-controlled provider registration, bucket-key derivation, provider `signals.targeting_kvs` pass-through, shared-key multi-provider contribution, and dropped unmapped/case-mismatched tuples | `static/compliance/source/test-vectors/trusted-match-context-merge/` | `/compliance/latest/test-vectors/trusted-match-context-merge/` | +| [`products-only-brief-compatibility`](https://github.com/adcontextprotocol/adcp/tree/main/static/compliance/source/test-vectors/products-only-brief-compatibility) | Products-only brief flow across AdCP 2.5, 3.0, 3.1: compact projection without invented proposals, fail-closed legacy-create continuation with named fences, seller-fenced `listed_purchase` feed/pricing propagation, and 3.2 reverse-compatibility facades | `static/compliance/source/test-vectors/products-only-brief-compatibility/` | `/compliance/latest/test-vectors/products-only-brief-compatibility/` | +| [`relationship-scoped-indicators`](https://github.com/adcontextprotocol/adcp/blob/main/static/compliance/source/test-vectors/relationship-scoped-indicators.json) | Indicator snapshot semantics and invalidation lifecycle: scope containment validation, snapshot freshness, and relationship-scoped invalidation behavior | `static/compliance/source/test-vectors/relationship-scoped-indicators.json` | `/compliance/latest/test-vectors/relationship-scoped-indicators.json` | | [`transport-error-mapping`](https://github.com/adcontextprotocol/adcp/blob/main/static/test-vectors/transport-error-mapping.json) | Transport-layer error envelope shapes: the JSON-RPC (`error.code` / `data`) and A2A (task `status.message`) carriers for each documented AdCP transport error | `static/test-vectors/transport-error-mapping.json` | [`/test-vectors/transport-error-mapping.json`](https://adcontextprotocol.org/test-vectors/transport-error-mapping.json) | | [`mcp-response-extraction`](https://github.com/adcontextprotocol/adcp/blob/main/static/test-vectors/mcp-response-extraction.json) | Client extraction of the AdCP payload from MCP `tools/call` envelopes | `static/test-vectors/mcp-response-extraction.json` | [`/test-vectors/mcp-response-extraction.json`](https://adcontextprotocol.org/test-vectors/mcp-response-extraction.json) | | [`a2a-response-extraction`](https://github.com/adcontextprotocol/adcp/blob/main/static/test-vectors/a2a-response-extraction.json) | Client extraction of the AdCP payload from A2A task statuses and artifacts | `static/test-vectors/a2a-response-extraction.json` | [`/test-vectors/a2a-response-extraction.json`](https://adcontextprotocol.org/test-vectors/a2a-response-extraction.json) | @@ -42,10 +52,13 @@ SDKs SHOULD fetch versioned paths where available and record the version under t | [`webhook-hmac-sha256`](https://github.com/adcontextprotocol/adcp/blob/main/static/test-vectors/webhook-hmac-sha256.json) *(legacy)* | HMAC-SHA-256 signature computation and byte-equality invariants for the legacy HMAC webhook profile. Deprecated in 3.x, removed in 4.0 per [Webhook callbacks](/docs/building/by-layer/L3/webhooks#legacy-hmac-sha256-fallback-deprecated); new integrations use `webhook-signing` | `static/test-vectors/webhook-hmac-sha256.json` | [`/test-vectors/webhook-hmac-sha256.json`](https://adcontextprotocol.org/test-vectors/webhook-hmac-sha256.json) | | [`canonical-image-pixel-ratio`](https://github.com/adcontextprotocol/adcp/blob/main/static/test-vectors/canonical-image-pixel-ratio.json) | Canonical image logical-size versus intrinsic-pixel validation, top-level/slot density intersection, accepted and required rendition sets, mismatch failures, and parameterized legacy projection | `static/test-vectors/canonical-image-pixel-ratio.json` | [`/test-vectors/canonical-image-pixel-ratio.json`](https://adcontextprotocol.org/test-vectors/canonical-image-pixel-ratio.json) | | [`v1-canonical-mapping`](https://github.com/adcontextprotocol/adcp/blob/main/static/test-vectors/v1-canonical-mapping.json) | Literal v1 format-ID projection plus positive and negative vectors for the normative one-way v2-narrows-v1 relation | `static/test-vectors/v1-canonical-mapping.json` | [`/test-vectors/v1-canonical-mapping.json`](https://adcontextprotocol.org/test-vectors/v1-canonical-mapping.json) | +| [`adagents-discovery-redirects`](https://github.com/adcontextprotocol/adcp/blob/main/static/test-vectors/adagents-discovery-redirects.json) | `adagents.json` discovery redirect handling: same-registrable-domain following with eTLD+1 (including PSL private section), HTTPS preservation, per-hop SSRF revalidation, 3-hop cap, cross-registrable-domain refusal, and zero-redirect `authoritative_location` policy | `static/test-vectors/adagents-discovery-redirects.json` | [`/test-vectors/adagents-discovery-redirects.json`](https://adcontextprotocol.org/test-vectors/adagents-discovery-redirects.json) | +| [`canonical-format-classification`](https://github.com/adcontextprotocol/adcp/blob/main/static/test-vectors/canonical-format-classification.json) | Canonical format classification from realistic publisher-spec descriptions: classification follows creative payload and rendering responsibility, not placement behavior richness | `static/test-vectors/canonical-format-classification.json` | [`/test-vectors/canonical-format-classification.json`](https://adcontextprotocol.org/test-vectors/canonical-format-classification.json) | +| [`media-buy`](https://github.com/adcontextprotocol/adcp/tree/main/static/test-vectors/media-buy) | Media-buy lifecycle vectors: package-status targeting-overlay echo and `status_as_of` temporal query semantics | `static/test-vectors/media-buy/` | [`/test-vectors/media-buy/`](https://adcontextprotocol.org/test-vectors/media-buy/) | -**Start here**: every set's `README.md` in the source column documents file layout, key material, preconditions (e.g., runner state required for replay vectors), and how to wire the set into an SDK test loop. The README in the source tree is authoritative; the index on this page is a catalog, not an integration guide. +**Start here**: where a set includes a `README.md`, it documents file layout, key material, preconditions (e.g., runner state required for replay vectors), and how to wire the set into an SDK test loop. The source tree is authoritative; the index on this page is a catalog, not an integration guide. -Directory CDN paths (the three compliance-tree rows) are base paths for programmatic use — the CDN serves individual files, not directory listings. Browse the tree via the source column. +Directory CDN paths in the table are base paths for programmatic use — the CDN serves individual files, not directory listings. Browse the tree via the source column. ## Test keys are public From 05f2c49ed4833e53c69fd7ca1e9ca879fd0a7a23 Mon Sep 17 00:00:00 2001 From: garvitkaushik-123 Date: Mon, 24 Aug 2026 01:14:14 +0530 Subject: [PATCH 2/3] docs: fix test vector release guidance --- .changeset/complete-test-vector-index.md | 5 +++++ docs/reference/test-vectors/index.mdx | 4 ++-- 2 files changed, 7 insertions(+), 2 deletions(-) create mode 100644 .changeset/complete-test-vector-index.md diff --git a/.changeset/complete-test-vector-index.md b/.changeset/complete-test-vector-index.md new file mode 100644 index 0000000000..976dd0aa6b --- /dev/null +++ b/.changeset/complete-test-vector-index.md @@ -0,0 +1,5 @@ +--- +"adcontextprotocol": patch +--- + +Complete the reference test-vector index with every published compliance and unversioned set, accurate development-snapshot guidance, and direct links to the media-buy vector files. diff --git a/docs/reference/test-vectors/index.mdx b/docs/reference/test-vectors/index.mdx index 8a1dbe71a0..599998b5be 100644 --- a/docs/reference/test-vectors/index.mdx +++ b/docs/reference/test-vectors/index.mdx @@ -18,7 +18,7 @@ Vectors are not the conformance specification — the [storyboards](/docs/buildi ## Versioning -Vector sets published under `static/compliance/source/test-vectors/` are versioned alongside the spec. The copy served at `/compliance/{version}/test-vectors/{set}` is frozen at the GA release of that version; fixes that change a vector's bytes ship in the next AdCP minor release. `/compliance/latest/test-vectors/{set}` tracks the most recent GA and moves under you between releases. +Vector sets published under `static/compliance/source/test-vectors/` are versioned alongside the spec. The copy served at `/compliance/{version}/test-vectors/{set}` is frozen for that release; fixes that change a vector's bytes ship in a later AdCP release. `/compliance/latest/test-vectors/{set}` tracks the current development snapshot and may change before release. Vector sets served under `/test-vectors/` are currently unversioned: each file is overwritten in place when it changes. SDKs that consume these fixtures SHOULD vendor a commit-pinned copy, for example fetching from `https://raw.githubusercontent.com/adcontextprotocol/adcp//static/test-vectors/.json` and recording `` in their lockfile, until these files are rolled into the versioned compliance tree. @@ -54,7 +54,7 @@ SDKs SHOULD fetch versioned paths where available and record the version under t | [`v1-canonical-mapping`](https://github.com/adcontextprotocol/adcp/blob/main/static/test-vectors/v1-canonical-mapping.json) | Literal v1 format-ID projection plus positive and negative vectors for the normative one-way v2-narrows-v1 relation | `static/test-vectors/v1-canonical-mapping.json` | [`/test-vectors/v1-canonical-mapping.json`](https://adcontextprotocol.org/test-vectors/v1-canonical-mapping.json) | | [`adagents-discovery-redirects`](https://github.com/adcontextprotocol/adcp/blob/main/static/test-vectors/adagents-discovery-redirects.json) | `adagents.json` discovery redirect handling: same-registrable-domain following with eTLD+1 (including PSL private section), HTTPS preservation, per-hop SSRF revalidation, 3-hop cap, cross-registrable-domain refusal, and zero-redirect `authoritative_location` policy | `static/test-vectors/adagents-discovery-redirects.json` | [`/test-vectors/adagents-discovery-redirects.json`](https://adcontextprotocol.org/test-vectors/adagents-discovery-redirects.json) | | [`canonical-format-classification`](https://github.com/adcontextprotocol/adcp/blob/main/static/test-vectors/canonical-format-classification.json) | Canonical format classification from realistic publisher-spec descriptions: classification follows creative payload and rendering responsibility, not placement behavior richness | `static/test-vectors/canonical-format-classification.json` | [`/test-vectors/canonical-format-classification.json`](https://adcontextprotocol.org/test-vectors/canonical-format-classification.json) | -| [`media-buy`](https://github.com/adcontextprotocol/adcp/tree/main/static/test-vectors/media-buy) | Media-buy lifecycle vectors: package-status targeting-overlay echo and `status_as_of` temporal query semantics | `static/test-vectors/media-buy/` | [`/test-vectors/media-buy/`](https://adcontextprotocol.org/test-vectors/media-buy/) | +| [`media-buy`](https://github.com/adcontextprotocol/adcp/tree/main/static/test-vectors/media-buy) | Media-buy lifecycle vectors: package-status targeting-overlay echo and `status_as_of` temporal query semantics | `static/test-vectors/media-buy/` | [`package-status-targeting-overlay-echo.json`](https://adcontextprotocol.org/test-vectors/media-buy/package-status-targeting-overlay-echo.json), [`status-as-of.json`](https://adcontextprotocol.org/test-vectors/media-buy/status-as-of.json) | **Start here**: where a set includes a `README.md`, it documents file layout, key material, preconditions (e.g., runner state required for replay vectors), and how to wire the set into an SDK test loop. The source tree is authoritative; the index on this page is a catalog, not an integration guide. From e554089a6bad6a3bec72955d8140024a14644e6b Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Mon, 24 Aug 2026 22:21:37 +0100 Subject: [PATCH 3/3] docs: clarify reference vector scope --- docs/reference/test-vectors/index.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/test-vectors/index.mdx b/docs/reference/test-vectors/index.mdx index 599998b5be..c2c3e9d6cf 100644 --- a/docs/reference/test-vectors/index.mdx +++ b/docs/reference/test-vectors/index.mdx @@ -70,6 +70,6 @@ Production signers mint their own keypairs and publish under their own `jwks_uri ## Scope -The sets above exercise transport, signing, and canonicalization rules that cross every surface — the bytes-level pins that storyboards can't verify. Per-task request/response fixtures are intentionally not published here: the [conformance storyboards](https://adcontextprotocol.org/compliance/latest/) (wire behavior, error codes, lifecycle transitions) and [JSON Schemas](https://github.com/adcontextprotocol/adcp/tree/main/static/schemas/source) (request/response shapes) cover task-level conformance between them, and a parallel tree of frozen request/response pairs would drift against the storyboards it duplicates. +The sets above cover both cross-surface wire rules — transport, signing, canonicalization, and discovery — and selected protocol behaviors where deterministic fixtures add value, such as attestation resolution, compatibility projections, and media-buy readback semantics. They complement rather than duplicate the other machine authorities: vectors pin exact inputs, outputs, or edge-case decisions for SDK and library code; [conformance storyboards](https://adcontextprotocol.org/compliance/latest/) grade agent behavior end to end; and [JSON Schemas](https://github.com/adcontextprotocol/adcp/tree/main/static/schemas/source) define request and response shapes. -Implementers derive expected shapes from the schema and confirm wire behavior by running the storyboards against their agent. SDK authors that want machine-readable per-task fixtures should extract them from the relevant storyboard rather than expect a separate vector set. +The catalog does not aim to provide generic golden request/response pairs for every task. Implementers derive ordinary shapes from the schemas and confirm wire behavior by running the storyboards against their agent. Task-specific vectors are published only where a stable machine-readable fixture tests semantics that schemas alone cannot express or supports compatibility across SDKs.