@adcp/sdk 16.0.0-beta.8 → 16.0.0

package/docs/migration-4.x-to-5.x.md

@@ -882,13 +882,18 @@ steps for a 4.x upgrader and are omitted here:
 
 ## v2 sunset
 
-AdCP v2 went unsupported on 2026-04-20 as part of the 3.0 GA cutover
-([adcp#2220](https://github.com/adcontextprotocol/adcp/issues/2220)). The
-client still executes v2 code paths — no functional break — but emits a
-one-time `console.warn` the first time a client instance sees v2
-capabilities from an agent. Suppress with `ADCP_ALLOW_V2=1` or `adcp
---allow-v2` if you're knowingly running against a legacy holdout.
-Synthetic capabilities don't fire the warning.
+AdCP v2 became unsupported at the April 2026 3.0 GA cutover and reached
+full end of life on August 1, 2026; see the protocol's
+[v2 sunset policy](https://github.com/adcontextprotocol/adcp/blob/main/docs/reference/v2-sunset.mdx).
+In SDK 5.x, the client still executed v2 code paths and emitted a one-time
+`console.warn` when a client instance saw explicit v2 capabilities. That
+historical warning could be suppressed with `ADCP_ALLOW_V2=1` or
+`adcp --allow-v2`; synthetic capabilities did not fire it.
+
+**SDK 16 update:** AdCP 2 compatibility, `ADCP_ALLOW_V2`, and `--allow-v2`
+have been removed. Agents must support AdCP 3 discovery before business-tool
+dispatch. Follow the [AdCP 2 retirement guide](./migration-drop-adcp-2.md)
+for current behavior and the last supporting SDK pins.
 
 ## Webhook HMAC legacy deprecation
 

package/docs/migration-agent-identity-3.3.md

@@ -3,7 +3,7 @@
 The experimental identity rollout is tracked in
 [adcp-client#3233](https://github.com/adcontextprotocol/adcp-client/issues/3233).
 This release implements the rollout behind explicit experimental configuration.
-The SDK's default `ADCP_VERSION` remains **3.2.4**. Experimental client/server
+The SDK's default `ADCP_VERSION` remains **3.2.5**. Experimental client/server
 instances select the 3.3 carrier and apply the pinned draft overlays to the
 released bundle; they do not regenerate or replace the public 3.2 types.
 Upstream PRs remain open, so the experiment can change before graduation.
@@ -126,18 +126,42 @@ final UTF-8 body, covers the selected `Signature-Agent` member and digest,
 uses a fresh 64-byte nonce, and refuses automatic HTTP redirects. A request
 carries exactly one `web-bot-auth` signature and one `Signature-Agent` member:
 relays were removed from the profile, `signWebBotAuth` throws on `relay: true`
-and on a request that already carries signature fields, and the verifier
-answers a second signature (of any profile) or a second `Signature-Agent`
-member with 403. Signing keys are Ed25519 or RSA-PSS-SHA512 (2048 to 4096
-bits, e = 65537); ES256 stays on the AdCP RFC 9421 profile, and
+and on a request that already carries signature fields. The verifier reads
+only the `Signature-Input` member tagged `web-bot-auth` and ignores members
+with other tags, such as a CDN's own signature. It answers a second
+`web-bot-auth` signature or a second `Signature-Agent` member with 403.
+Signing keys are Ed25519 only; ES256 stays on the AdCP RFC 9421 profile, and
 `createWebBotAuthFetch`, `createWebhookEmitter` and `createAdcpServer` refuse
-a P-256 Web Bot Auth key at wire-up.
+a P-256 or RSA Web Bot Auth key at wire-up.
+
+This also changes two helpers outside the experiment. `verifySignature` and
+`verifySignatureAsync`, which `@adcp/sdk/signing/server` exports, no longer
+verify `rsa-pss-sha512`: they return `false` for it, as for any algorithm they
+don't support. Only Web Bot Auth used it, and the AdCP RFC 9421 profile allows
+only `ed25519` and `ecdsa-p256-sha256`. A caller that verifies RSA-PSS
+signatures with these helpers needs to verify them with `node:crypto` or
+WebCrypto instead.
+
+The covered `Signature-Agent` member must be exactly the canonical https origin
+string, compared as received: a lowercase host, no default port, and no path
+(not even `/`), query, fragment, or userinfo. Any other value, including an
+`http://` origin, is a 403 before any directory fetch. The signers apply the
+same rule: `signWebBotAuth`, `createSignedSignatureDirectory` and
+`createWebBotAuthFetch` canonicalize the agent origin they are given and throw a
+`TypeError` when it is not https, such as `http://localhost:3000`. There is no
+http opt-in. The member's `type`
+parameter is a Token (WBA section 5.2.1), and the verifier accepts
+`type=directory` as a Token or as a String. It ignores a member of any other
+type, which leaves no member to resolve (403).
 
 `SignatureDirectoryResolver` derives the directory from the covered canonical
 origin. Directories must be signed (WBA Appendix B.1): it validates a
-possession signature for every key, covering `"@authority";req` and
-`content-digest`, and the exact body digest before caching keys. An unsigned
-directory is a discovery failure. Its audit proof retains the signed body and
+possession signature for every key the profile can use, covering
+`"@authority";req` and `content-digest`, and the exact body digest before
+caching keys. It ignores keys the profile cannot use, such as a P-256 key, and
+any signature they made (RFC 7517 section 5). An unsigned directory, one
+with no usable key, or one that publishes private key material for any key,
+usable or not, is a discovery failure. Its audit proof retains the signed body and
 headers. Verification requires this resolver so context-free JWKS adapters cannot
 attribute a key to an arbitrary origin. Discovery uses HTTPS, DNS pinning, no redirects, a 256 KiB cap, a
 5-second connect bound and 10-second total bound, at most 64 keys, and bounded
@@ -155,8 +179,7 @@ Serve the exact JWS at `/.well-known/governance-revocations.json` and refresh it
 before `next_update` (the command defaults to five minutes). Pass `--snapshot`
 to sign a list of revoked key thumbprints and optional reasons/dates.
 `createSignedOriginRevocationList` provides the same authoring API. The SDK
-signs and verifies revocation lists with directory keys: EdDSA for Ed25519 keys
-and PS512 for RSA keys (a P-256 key cannot be published in a key directory). Observed key revocations are permanent;
+signs and verifies revocation lists with Ed25519 directory keys, as EdDSA. Observed key revocations are permanent;
 refresh failures use the last verified list only within the published grace
 window. Staleness follows the list's signed `next_update`, never the polling
 interval: the verifier re-polls at least every polling interval (at most 30
@@ -379,7 +402,7 @@ released schemas:
 
 | PR | Pinned head | Surface |
 | --- | --- | --- |
-| [7894](https://github.com/adcontextprotocol/adcp/pull/7894) | `e24eeb090c4365707641099cbbb45f9945c6d6e0` | WBA wire profile (`wba-profile.mdx`), profile selectors, directory and request vectors |
+| [7894](https://github.com/adcontextprotocol/adcp/pull/7894) | `e59294701d733b0ea2a004a2f0c091c8eccdcaae` | WBA wire profile (`wba-profile.mdx`), profile selectors, directory and request vectors |
 | [8121](https://github.com/adcontextprotocol/adcp/pull/8121) | `f5973ac0267b1b94d714c55fc4e3ad8fc2511350` | Origin identity and key-free trust v1 |
 | [8162](https://github.com/adcontextprotocol/adcp/pull/8162) | `5c9914c5c382cc32f3d2ad7842942e548c414705` | Ratified identity, coexistence, revocation |
 | [8168](https://github.com/adcontextprotocol/adcp/pull/8168) | `45540941dfd61e80ab8a463f780cb147c82a32f0` | Relationship and principal response arms |
@@ -388,7 +411,9 @@ released schemas:
 | [8177](https://github.com/adcontextprotocol/adcp/pull/8177) | `b663f8e4235fe4276c73fb9bac6db491b2252bbf` | Reporting authentication omission |
 
 The vectors in `test/fixtures/wba-profile/` are byte-identical to #7894 at that
-head and are all graded except the governance-token vectors (see `PINNED.json`).
+head (see `PINNED.json`). Every vendored request and directory vector is
+graded, and the interop harness (adcontextprotocol/adcp#8298) grades
+`scenarios.json`.
 
 Verification runs in Cloudflare's `http-message-sig` (signature base, coverage,
 window, algorithm and cryptographic checks); the SDK adds the profile rules in
@@ -413,7 +438,7 @@ so verification can run in a CDN or middleware in front of the AdCP server.
   reason is logged, never sent. A 429 for local load shedding (directory fetch
   limiter, replay-store `rate_abuse`) carries `Retry-After` instead.
 - Every signed request carries `created`, `expires` (at most 300 seconds
-  later), `keyid`, `alg` (`ed25519` or `rsa-pss-sha512`) and a `nonce` of 64
+  later), `keyid`, `alg` (`ed25519`) and a `nonce` of 64
   bytes, unpadded Base64URL or canonical padded Base64 (Cloudflare's default).
   The former 16-byte floor is gone: a shorter nonce is a 403. Replay state is
   keyed on the nonce bytes, so the two encodings of one nonce collide.
@@ -454,14 +479,14 @@ so verification can run in a CDN or middleware in front of the AdCP server.
   back off on 429 or 503.
 - `@target-uri` and `@authority` are taken from the target URI as received
   (RFC 9421 §2.2.2), never canonicalized; canonical origins identify the signer
-  only. Ed25519 and RSA-PSS-SHA512 keys are supported; RSA-PSS uses WebCrypto
-  where the runtime has it, so it also works on Cloudflare workerd.
+  only. Web Bot Auth is Ed25519 only, and it also works on Cloudflare workerd.
   `test/fixtures/wba-interop/` holds fixtures verified in both directions against
   Cloudflare's `web-bot-auth`; they already used signed directories and are
   unchanged.
-The #7894 governance-token vectors are vendored but not graded: ratified R4
-keeps the RFC 9421 discovery chain for governance through 3.3, and the profile
-page leaves document signing to a separate decision. `PINNED.json` records this.
+#7894 drops the governance-token checks and the `governance/` vectors from the
+WBA profile. Governance moves to the AdCP layer under a separate R4 erratum,
+which moves JWS artifacts, governance included, to the identity's WBA key
+directory in 3.3. This change leaves the SDK's governance code as it is.
 The buyer default onboarding field is `profiles.adcp.onboarding`, matching the
 schema; the design's `record_profiles` wording names the schema definition.
 

package/docs/migration-drop-adcp-2.md

@@ -0,0 +1,25 @@
+# Removing AdCP 2 compatibility
+
+AdCP 2.5 reached end of life on August 1, 2026. The SDK now supports AdCP 3 agents only. This is an SDK major release change. Integrations that still require AdCP 2 can pin the last supporting beta, `npm install @adcp/sdk@16.0.0-beta.8`, or stay on the stable SDK 15 line (`npm install @adcp/sdk@15.9.6`) while upgrading their agents.
+
+Upgrade agents to AdCP 3 before upgrading the SDK. An agent must expose `get_adcp_capabilities`. Its `adcp.supported_versions` determines its supported majors; `adcp.major_versions` is the legacy fallback. Omitting both fields no longer selects AdCP 2.
+
+Agents that declare only AdCP 2 and agents missing capability discovery fail with `VersionUnsupportedError` (`code: 'VERSION_UNSUPPORTED'`) before a business tool is dispatched. AdCP 2 constructor pins fail with `ConfigurationError`, even if an old schema cache remains on disk.
+
+The release removes:
+
+- `allowV2`, `ADCP_ALLOW_V2`, and the CLI `--allow-v2` flag.
+- `SingleAgentClient.isSyntheticV2()` and the v2 `buildSyntheticCapabilities()` helper.
+- The `2` argument to `SingleAgentClient.supportsVersion()` and `AgentClient.supportsVersion()`; the maintained query is `supportsVersion(3)`.
+- The `@adcp/sdk/types/v2-5` export and AdCP 2 schema bundles.
+- Outbound AdCP 2 adapters: `adaptGetProductsRequestForV2`, `adaptPricingOptionForV2`, `adaptProductPricingForV2`, `adaptSyncCreativesRequestForV2`, `adaptPackageRequestForV2`, `adaptCreateMediaBuyRequestForV2`, and `adaptUpdateMediaBuyRequestForV2`.
+- AdCP 2 creative/format/preview detectors: `usesV2CreativeIds`, `usesV2Dimensions`, and `usesV2RenderFields`, plus their v2-only structural types (`PackageRequestV2`, `PackageResponseV2`, `PackageAdapterContext`, `FormatV2`, and `PreviewRenderV2`).
+- The `sync-schemas:v2.5` and `generate-types:v2.5` scripts.
+
+Submit canonical AdCP 3 `creative_assignments`, format `renders`, and preview `render_id` / `role` fields. The maintained read helpers (`getCreativeIds`, `getCreativeAssignments`, `getFormatRenders`, `getPrimaryRender`, `getFormatDimensions`, `getRenderId`, `getRenderRole`, and preview URL/HTML accessors) still inspect valid AdCP 3 data. Their normalizers preserve that data; they no longer promote `creative_ids`, top-level format dimensions, or `output_id` into AdCP 3 fields.
+
+Seller applications using `createAdcpServer` or `createAdcpServerFromPlatform` must remove AdCP 2 from `capabilities.major_versions` and `capabilities.supported_versions`. Startup rejects a declaration such as `[2, 3]` because this SDK no longer implements the advertised AdCP 2 surface. A buyer can still call an external agent that genuinely implements both majors: when its discovery includes AdCP 3, the SDK negotiates AdCP 3.
+
+AdCP 3.0 and 3.1 compatibility remains available. Creative-model v2 projections and MCP v2 transport names refer to separate version schemes and remain supported.
+
+See the protocol's [v2 sunset policy](https://github.com/adcontextprotocol/adcp/blob/main/docs/reference/v2-sunset.mdx) and [FAQ](https://github.com/adcontextprotocol/adcp/blob/main/docs/faq.mdx).

package/docs/migration-reporting-storage-package.md

@@ -1,6 +1,6 @@
 # Reliable Reporting storage moved to `@adcp/reporting-storage`
 
-**Applies to:** SDK 16 beta. **Kind:** breaking, by design. There are no re-export shims: the moved subpaths are gone from `@adcp/sdk`.
+**Applies to:** SDK 16. **Kind:** breaking, by design. There are no re-export shims: the moved subpaths are gone from `@adcp/sdk`.
 
 The Reliable Reporting storage implementations now ship as their own package, `@adcp/reporting-storage`, on its own version line. `@adcp/sdk` keeps the protocol layer. If you import anything from `@adcp/sdk/reporting/gcs`, `/s3`, `/azure` or `/bigquery`, or the PostgreSQL store, row storage, managed delivery or notification activity from `@adcp/sdk/reporting/ledger`, or `createPostgresReliableReportingProductionService` from `@adcp/sdk/reporting/service`, change those imports. Nothing else changes on the wire, in the database schema, or in the ledger's behavior.
 
@@ -11,10 +11,10 @@ Why: storage keeps its own release cadence, as Auth.js, LangGraph and OpenTeleme
 1. Install the package next to the SDK. `@adcp/sdk` is a peer dependency of it, so the host keeps exactly one copy:
 
    ```bash
-   npm install @adcp/sdk@beta @adcp/reporting-storage@beta
+   npm install @adcp/sdk@^16.0.0 @adcp/reporting-storage@~0.1.0
    ```
 
-   Pin the storage package with `~` (`"@adcp/reporting-storage": "~0.1.0-beta.0"` while SDK 16 is in beta, `"~0.1.0"` after a stable release; a prerelease version is not matched by `~0.1.0`): it is pre-1.0 and every export is experimental. The cloud SDKs are optional peers of the new package, not of `@adcp/sdk` any more, so keep `@aws-sdk/client-s3`, `@azure/storage-blob` and `@google-cloud/storage` in your own dependencies for the providers you use.
+   Pin the storage package with `~` (`"@adcp/reporting-storage": "~0.1.0"`; this stable range does not match the earlier `0.1.0-beta.0` prerelease): it is pre-1.0 and every export is experimental. The cloud SDKs are optional peers of the new package, not of `@adcp/sdk` any more, so keep `@aws-sdk/client-s3`, `@azure/storage-blob` and `@google-cloud/storage` in your own dependencies for the providers you use.
 
 2. Change the imports using the table below, then run `tsc --noEmit`. A moved name on `@adcp/sdk/reporting/ledger` or `/service` is `TS2305: Module '"@adcp/sdk/reporting/ledger"' has no exported member 'PostgresReportingLedgerStore'`; a deleted subpath is `TS2307: Cannot find module '@adcp/sdk/reporting/gcs'`. At runtime the deleted subpaths fail with `ERR_PACKAGE_PATH_NOT_EXPORTED`, and a stale CommonJS `require` of a moved name on a kept subpath destructures to `undefined` and fails later as `X is not a constructor`, so grep JavaScript too (see [Self-grade](#self-grade)).
 

package/docs/releases/16.0.0.md

@@ -0,0 +1,20 @@
+# SDK 16.0.0
+
+SDK 16 is the stable AdCP 3.2 release line. Its default protocol pin is **3.2.5**, with maintained AdCP 3.0 and 3.1 compatibility. Install it with `npm install @adcp/sdk@^16.0.0`.
+
+## Upgrade from SDK 15
+
+- **AdCP 2 support is removed.** Sellers must support AdCP 3 capability discovery. Retired adapters, types, schema bundles and `allowV2` configuration are removed. See the [AdCP 2 retirement guide](../migration-drop-adcp-2.md).
+- **Reliable Reporting storage has its own package.** Install `@adcp/reporting-storage@~0.1.0` alongside the SDK and update the moved imports. The storage package remains experimental and pre-1.0 even though SDK 16 is stable. See the [package migration](../migration-reporting-storage-package.md) and [stability policy](../guides/REPORTING-STABILITY.md).
+- **Reporting row storage uses the protocol field names and source-timezone period dates.** Apply the migration and update custom object providers as described in the [row storage alignment guide](../migration-reporting-row-storage-alignment.md). Re-apply the warehouse sink migration when upgrading existing BigQuery sinks; see the [SDK changelog](https://github.com/adcontextprotocol/adcp-client/blob/main/CHANGELOG.md#1600).
+- **Compliance notice codes use the canonical names.** Replace `request_signing.required` with `request_signing_required_in_4_0` and `webhook_signing.legacy_hmac_fallback.removed` with `legacy_hmac_fallback_removed_in_4_0` in comparisons and dashboard keys.
+
+The [changelog](https://github.com/adcontextprotocol/adcp-client/blob/main/CHANGELOG.md#1600) includes the complete SDK 16 changes, including creative wire selection, account sync, property-list workflows and reporting fixes. Use the [release-bound upgrade worksheet](../migration-14.x-rc-worksheet.md) to check the exact package, runtime, peers and protocol bundle.
+
+SDK 16.0.0 also includes [#3350](https://github.com/adcontextprotocol/adcp-client/pull/3350): legacy creative delivery maps asset keys to the selected format's declared asset IDs, including image, click URL and tracker slots, while preserving occupied or ambiguous keys. See [creative delivery](../guides/CREATIVE-DELIVERY.md).
+
+## AdCP 3.3 preview
+
+The explicit `@adcp/sdk/identity-3.3` opt-in remains experimental. Promoting SDK 16 does not graduate that API or change the default wire pin to AdCP 3.3. See the [experimental identity guide](../migration-agent-identity-3.3.md).
+
+SDK 17 beta is the next release line for adopting the published AdCP 3.3 beta bundle. SDK 16 stays on AdCP 3.2 while that work proceeds. The `latest` channel stays on stable releases and `beta` carries the SDK 17 previews; a preview is published only once its protocol bundle is available and its integration passes validation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adcp/sdk",
-  "version": "16.0.0-beta.8",
+  "version": "16.0.0",
   "description": "AdCP SDK — client, server, and compliance harnesses for the AdContext Protocol (MCP + A2A)",
   "workspaces": [
     ".",
@@ -81,16 +81,6 @@
         "default": "./dist/lib/enums.js"
       }
     },
-    "./types/v2-5": {
-      "import": {
-        "types": "./dist/lib/types/v2-5/index.d.mts",
-        "default": "./dist/lib/types/v2-5/index.mjs"
-      },
-      "require": {
-        "types": "./dist/lib/types/v2-5/index.d.ts",
-        "default": "./dist/lib/types/v2-5/index.js"
-      }
-    },
     "./types/*": {
       "types": "./dist/lib/types/*.d.ts"
     },
@@ -448,9 +438,6 @@
       "types": [
         "dist/lib/types/index.d.ts"
       ],
-      "types/v2-5": [
-        "dist/lib/types/v2-5/index.d.ts"
-      ],
       "wholesale-feed-sync": [
         "dist/lib/wholesale-feed-sync/index.d.ts"
       ],
@@ -652,8 +639,7 @@
     "test:protocol-comparison": "node test/utils/comprehensive-protocol-comparison.js",
     "test:status-report": "node test/utils/final-status-report.js",
     "sync-schemas": "tsx scripts/sync-schemas.ts",
-    "sync-schemas:v2.5": "tsx scripts/sync-v2-5-schemas.ts",
-    "sync-schemas:all": "npm run sync-schemas && npm run sync-schemas -- 3.1.29 && npm run sync-schemas -- 3.0.25 && npm run sync-schemas:v2.5",
+    "sync-schemas:all": "npm run sync-schemas && npm run sync-schemas -- 3.1.29 && npm run sync-schemas -- 3.0.25",
     "sync:canonical-storyboard-fixtures": "tsx scripts/sync-canonical-storyboard-fixtures.ts --update",
     "check:canonical-storyboard-fixtures": "tsx scripts/sync-canonical-storyboard-fixtures.ts --check",
     "sync-registry-schemas": "tsx scripts/generate-registry-types.ts --sync",
@@ -662,8 +648,7 @@
     "generate-types": "tsx scripts/generate-types.ts && tsx scripts/generate-enum-arrays.ts && tsx scripts/generate-inline-enum-arrays.ts && tsx scripts/generate-manifest-derived.ts && tsx scripts/generate-entity-hydration.ts && tsx scripts/generate-media-buy-update-fields.ts && tsx scripts/generate-media-buy-action-metadata.ts",
     "generate-manifest-derived": "tsx scripts/generate-manifest-derived.ts",
     "generate-entity-hydration": "tsx scripts/generate-entity-hydration.ts",
-    "generate-types:v2.5": "tsx scripts/generate-v2-5-types.ts",
-    "generate-types:all": "npm run generate-types && npm run generate-types:v2.5",
+    "generate-types:all": "npm run generate-types",
     "generate-registry-types": "tsx scripts/generate-registry-types.ts",
     "generate-enum-arrays": "tsx scripts/generate-enum-arrays.ts",
     "generate-inline-enum-arrays": "tsx scripts/generate-inline-enum-arrays.ts",

package/skills/call-adcp-agent/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: call-adcp-agent
 description: Wire-level invariants for any AdCP buyer call — idempotency_key replay semantics, account `oneOf` variants, async `status:'submitted'`+`task_id` polling, error recovery from `adcp_error.issues[]`. Load before any per-protocol task skill (adcp-media-buy, adcp-creative, adcp-signals, adcp-governance, adcp-si, adcp-brand) when calling an AdCP agent as a buyer.
-adcp_version: "3.x"
+adcp_version: '3.x'
 type: cross-cutting
 ---
 
@@ -32,7 +32,7 @@ Walk these in order on first contact:
 
 1. **Agent card** (A2A) or **`tools/list`** (MCP): returns tool NAMES. Most AdCP MCP servers publish passthrough schemas in `tools/list` by default — everything shows `{type: 'object', properties: {}}`. Some servers opt into `exposeToolSchemas: true` and publish shallow top-level key hints there; treat those as call hints, not as the canonical schema.
 2. **`get_adcp_capabilities`**: returns supported protocols (`media_buy`, `signals`, `creative`, …), AdCP major versions, feature flags. Tells you WHICH tools this agent supports, not how to call them.
-3. **`get_schema(tool_name)`** *(when the agent exposes it — pending standardization in [#3057](https://github.com/adcontextprotocol/adcp/issues/3057), not yet universal)*: returns the JSON Schema for a tool's request/response. Preferred over reading bundled schemas when available.
+3. **`get_schema(tool_name)`** _(when the agent exposes it — pending standardization in [#3057](https://github.com/adcontextprotocol/adcp/issues/3057), not yet universal)_: returns the JSON Schema for a tool's request/response. Preferred over reading bundled schemas when available.
 4. **Bundled schemas** (offline, authoritative): every SDK ships the AdCP JSON Schemas locally. Path differs by SDK — spec repo source uses `dist/schemas/<version>/bundled/`, `@adcp/client` puts them at `schemas/cache/<version>/bundled/` after `npm run sync-schemas`, Python and Go SDKs use their own conventions. **Don't hardcode a path** — let the SDK's loader find them, or ask the developer. Each schema is `<protocol>/<tool>-{request,response}.json` once you locate the bundle. The canonical source for every SDK is `https://adcontextprotocol.org/protocol/<version>.tgz`.
 
 ## Non-obvious rules every buyer must follow
@@ -119,7 +119,7 @@ Every validation failure produces:
         "keyword": "oneOf",
         "message": "must match exactly one schema in oneOf",
         "variants": [
-          { "index": 0, "required": ["account_id"],        "properties": ["account_id"] },
+          { "index": 0, "required": ["account_id"], "properties": ["account_id"] },
           { "index": 1, "required": ["brand", "operator"], "properties": ["brand", "operator", "sandbox"] }
         ]
       },
@@ -226,9 +226,7 @@ Returns `{ signals: [{ signal_agent_segment_id, match_rate, pricing, ... }] }`.
 {
   "idempotency_key": "<uuid>",
   "signal_agent_segment_id": "sig_premium_ctv_sports",
-  "destinations": [
-    { "type": "platform", "platform": "the-trade-desk" }
-  ]
+  "destinations": [{ "type": "platform", "platform": "the-trade-desk" }]
 }
 ```
 
@@ -254,25 +252,25 @@ Both transports share: idempotency, error shape, schema enforcement, and handler
 
 Quick lookup before reading the full envelope. Match what you see in `adcp_error.issues[*]`, apply the fix:
 
-| Symptom | What it means | Fix |
-|---|---|---|
-| `keyword: 'oneOf'` with `variants[]` | Discriminated union — you sent fields from multiple variants, or none | Pick ONE variant from `variants[]`. Send only its `required` fields. |
-| `discriminator: [{field, value}]` on a `required` issue | Validator inferred which branch you targeted; you missed required fields IN that branch | Read the `discriminator` pair, fill the missing required fields at the same level (don't nest under the discriminator field name). |
-| `hint:` field present on the issue | SDK matched a curated shape-gotcha rule | Apply the hint directly — it's the validated fix path. |
-| 2-3 `additionalProperties` errors at the same pointer | You merged `oneOf` variants ({account_id, brand, operator, …}) | Drop to one variant. Don't keep "extra" fields "for completeness". |
-| `keyword: 'required'`, `pointer: '/idempotency_key'` | Mutating tool, no UUID | Generate fresh UUID per logical operation. Reuse it on retries. |
-| `keyword: 'type'` or `additionalProperties` at `/budget` | Sent `{amount, currency}` | `budget` is a number. Currency is implied by `pricing_option_id`. |
-| `additionalProperties` at `/format_id` (string passed) | Sent `"format_id": "video_..."` | `format_id` is `{agent_url, id}` — always an object. |
-| `keyword: 'enum'` at `/destinations/*/type` | Made-up destination type | Use `'platform'` (with `platform`) or `'agent'` (with `agent_url`). |
-| Response carries `status: 'submitted'` and `task_id` | Async — work is queued, NOT done | Poll via `tasks/get` (A2A) or the MCP async task extension using `task_id`. |
-| `recovery: 'transient'` (rate limit, 5xx, timeout) | Server-side, retry-safe | Retry with the **same** `idempotency_key`. |
-| `recovery: 'correctable'` | Buyer-side fix | Read `issues[]`, patch the pointers, resend. Most cases close in one attempt. |
-| `recovery: 'terminal'` (account suspended, payment required, …) | Requires human action | Don't retry. Surface to the user. |
-| `[adcp] Warning: agent … does not expose get_adcp_capabilities` (one-shot per client, `@adcp/client` only) | Seller didn't ship v3 discovery — routed through the v2 adapter with idempotency-TTL guarantee unknown | Branch on `client.isSyntheticV2()` before dispatch. Tighten retry policy (lower attempt cap, longer backoff) or fall back to natural-key recovery for these sellers. Same predicate also flags synthetic v3 caveat — see `isSyntheticV2()` JSDoc. |
-| `adcp_error.code: 'AUTH_MISSING'` | No credential was presented | Escalate by default. Retry only if you own a credential supply or refresh path; otherwise surface re-auth to a human. |
-| `adcp_error.code: 'AUTH_INVALID'` | Credential was presented but rejected or revoked | Do not retry blindly. Refresh once only if you own a valid refresh grant and the rejection is token-expiry-shaped; otherwise surface to a human to rotate credentials. |
-| `adcp_error.code: 'AUTH_REQUIRED'` | Legacy compatibility code; older sellers and some SDK helper paths still use it for missing or rejected credentials | Treat as auth escalation by default. Retry only if your agent owns a credential-refresh path; otherwise surface to a human. |
-| HTTP 401 with `WWW-Authenticate` header | Transport auth challenge; may be missing credentials, wrong scheme, rejected credentials, or required request signing | Follow the challenge scheme. `Bearer` means send/refresh an OAuth-style `Authorization: Bearer ...` token. `Basic` means configure basic auth (`auth: { type: 'basic', username, password }` or `--auth user:pass --auth-scheme basic`) — `Bearer` will never succeed against that gateway. `Signature` means enable RFC 9421 request signing with an AdCP signing key, not an `Authorization` retry. **Saved aliases**: if registered with `--auth-scheme basic`, the scheme persists in `~/.adcp/config.json` and auto-applies on every later invocation — don't redundantly repeat the flag on each call. |
+| Symptom                                                                    | What it means                                                                                                             | Fix                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `keyword: 'oneOf'` with `variants[]`                                       | Discriminated union — you sent fields from multiple variants, or none                                                     | Pick ONE variant from `variants[]`. Send only its `required` fields.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `discriminator: [{field, value}]` on a `required` issue                    | Validator inferred which branch you targeted; you missed required fields IN that branch                                   | Read the `discriminator` pair, fill the missing required fields at the same level (don't nest under the discriminator field name).                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `hint:` field present on the issue                                         | SDK matched a curated shape-gotcha rule                                                                                   | Apply the hint directly — it's the validated fix path.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| 2-3 `additionalProperties` errors at the same pointer                      | You merged `oneOf` variants ({account_id, brand, operator, …})                                                            | Drop to one variant. Don't keep "extra" fields "for completeness".                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `keyword: 'required'`, `pointer: '/idempotency_key'`                       | Mutating tool, no UUID                                                                                                    | Generate fresh UUID per logical operation. Reuse it on retries.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `keyword: 'type'` or `additionalProperties` at `/budget`                   | Sent `{amount, currency}`                                                                                                 | `budget` is a number. Currency is implied by `pricing_option_id`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `additionalProperties` at `/format_id` (string passed)                     | Sent `"format_id": "video_..."`                                                                                           | `format_id` is `{agent_url, id}` — always an object.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `keyword: 'enum'` at `/destinations/*/type`                                | Made-up destination type                                                                                                  | Use `'platform'` (with `platform`) or `'agent'` (with `agent_url`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| Response carries `status: 'submitted'` and `task_id`                       | Async — work is queued, NOT done                                                                                          | Poll via `tasks/get` (A2A) or the MCP async task extension using `task_id`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `recovery: 'transient'` (rate limit, 5xx, timeout)                         | Server-side, retry-safe                                                                                                   | Retry with the **same** `idempotency_key`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `recovery: 'correctable'`                                                  | Buyer-side fix                                                                                                            | Read `issues[]`, patch the pointers, resend. Most cases close in one attempt.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `recovery: 'terminal'` (account suspended, payment required, …)            | Requires human action                                                                                                     | Don't retry. Surface to the user.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `VersionUnsupportedError` / `code: 'VERSION_UNSUPPORTED'` from `@adcp/sdk` | Seller cannot meet the configured AdCP 3 version or required capability guarantees; read the error's `reason` and message | Stop and report the incompatibility before business-tool dispatch. For end-of-life AdCP 2 or missing discovery, upgrade the seller to AdCP 3 with `get_adcp_capabilities`; if the application must retain AdCP 2 temporarily, use the exact older SDK pins in the [AdCP 2 migration guide](https://github.com/adcontextprotocol/adcp-client/blob/main/docs/migration-drop-adcp-2.md). Retrying or changing idempotency keys cannot fix protocol incompatibility.                                                                                                                                             |
+| `adcp_error.code: 'AUTH_MISSING'`                                          | No credential was presented                                                                                               | Escalate by default. Retry only if you own a credential supply or refresh path; otherwise surface re-auth to a human.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `adcp_error.code: 'AUTH_INVALID'`                                          | Credential was presented but rejected or revoked                                                                          | Do not retry blindly. Refresh once only if you own a valid refresh grant and the rejection is token-expiry-shaped; otherwise surface to a human to rotate credentials.                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `adcp_error.code: 'AUTH_REQUIRED'`                                         | Legacy compatibility code; older sellers and some SDK helper paths still use it for missing or rejected credentials       | Treat as auth escalation by default. Retry only if your agent owns a credential-refresh path; otherwise surface to a human.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| HTTP 401 with `WWW-Authenticate` header                                    | Transport auth challenge; may be missing credentials, wrong scheme, rejected credentials, or required request signing     | Follow the challenge scheme. `Bearer` means send/refresh an OAuth-style `Authorization: Bearer ...` token. `Basic` means configure basic auth (`auth: { type: 'basic', username, password }` or `--auth user:pass --auth-scheme basic`) — `Bearer` will never succeed against that gateway. `Signature` means enable RFC 9421 request signing with an AdCP signing key, not an `Authorization` retry. **Saved aliases**: if registered with `--auth-scheme basic`, the scheme persists in `~/.adcp/config.json` and auto-applies on every later invocation — don't redundantly repeat the flag on each call. |
 
 If your symptom isn't here, fall through to the next section.
 

package/dist/lib/adapters/legacy/v2-5/create_media_buy.d.mts

@@ -1,3 +0,0 @@
-import type { CreateMediaBuyRequest, CreateMediaBuyResponse } from '../../../types/v2-5/index.mjs';
-import type { AdapterPair } from './types.mjs';
-export declare const createMediaBuyAdapter: AdapterPair<unknown, CreateMediaBuyRequest, CreateMediaBuyResponse, unknown>;

package/dist/lib/adapters/legacy/v2-5/create_media_buy.d.ts

@@ -1,3 +0,0 @@
-import type { CreateMediaBuyRequest, CreateMediaBuyResponse } from '../../../types/v2-5';
-import type { AdapterPair } from './types';
-export declare const createMediaBuyAdapter: AdapterPair<unknown, CreateMediaBuyRequest, CreateMediaBuyResponse, unknown>;

package/dist/lib/adapters/legacy/v2-5/create_media_buy.js

@@ -1,33 +0,0 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var create_media_buy_exports = {};
-__export(create_media_buy_exports, {
-  createMediaBuyAdapter: () => createMediaBuyAdapter
-});
-module.exports = __toCommonJS(create_media_buy_exports);
-var import_creative_adapter = require('../../../utils/creative-adapter.js');
-const createMediaBuyAdapter = {
-  toolName: "create_media_buy",
-  adaptRequest: import_creative_adapter.adaptCreateMediaBuyRequestForV2,
-  normalizeResponse: import_creative_adapter.normalizeMediaBuyResponse
-};
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  createMediaBuyAdapter
-});

package/dist/lib/adapters/legacy/v2-5/create_media_buy.mjs

@@ -1,9 +0,0 @@
-import { adaptCreateMediaBuyRequestForV2, normalizeMediaBuyResponse } from "../../../utils/creative-adapter.mjs";
-const createMediaBuyAdapter = {
-  toolName: "create_media_buy",
-  adaptRequest: adaptCreateMediaBuyRequestForV2,
-  normalizeResponse: normalizeMediaBuyResponse
-};
-export {
-  createMediaBuyAdapter
-};

package/dist/lib/adapters/legacy/v2-5/get_products.d.mts

@@ -1,8 +0,0 @@
-import type { GetProductsRequest, GetProductsResponse } from '../../../types/v2-5/index.mjs';
-import type { AdapterPair } from './types.mjs';
-/**
- * v3 ↔ v2.5 adapter pair for `get_products`. Wraps the existing scattered
- * adapter helpers so the registry pattern lands without behavior change;
- * a focused refactor of the underlying implementation can follow.
- */
-export declare const getProductsAdapter: AdapterPair<unknown, GetProductsRequest, GetProductsResponse, unknown>;

package/dist/lib/adapters/legacy/v2-5/get_products.d.ts

@@ -1,8 +0,0 @@
-import type { GetProductsRequest, GetProductsResponse } from '../../../types/v2-5';
-import type { AdapterPair } from './types';
-/**
- * v3 ↔ v2.5 adapter pair for `get_products`. Wraps the existing scattered
- * adapter helpers so the registry pattern lands without behavior change;
- * a focused refactor of the underlying implementation can follow.
- */
-export declare const getProductsAdapter: AdapterPair<unknown, GetProductsRequest, GetProductsResponse, unknown>;

package/dist/lib/adapters/legacy/v2-5/get_products.js

@@ -1,33 +0,0 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var get_products_exports = {};
-__export(get_products_exports, {
-  getProductsAdapter: () => getProductsAdapter
-});
-module.exports = __toCommonJS(get_products_exports);
-var import_pricing_adapter = require('../../../utils/pricing-adapter.js');
-const getProductsAdapter = {
-  toolName: "get_products",
-  adaptRequest: import_pricing_adapter.adaptGetProductsRequestForV2,
-  normalizeResponse: import_pricing_adapter.normalizeGetProductsResponse
-};
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  getProductsAdapter
-});

package/dist/lib/adapters/legacy/v2-5/get_products.mjs

@@ -1,9 +0,0 @@
-import { adaptGetProductsRequestForV2, normalizeGetProductsResponse } from "../../../utils/pricing-adapter.mjs";
-const getProductsAdapter = {
-  toolName: "get_products",
-  adaptRequest: adaptGetProductsRequestForV2,
-  normalizeResponse: normalizeGetProductsResponse
-};
-export {
-  getProductsAdapter
-};

package/dist/lib/adapters/legacy/v2-5/index.d.mts

@@ -1,34 +0,0 @@
-/**
- * Registry of legacy v2.5 adapter pairs, one per AdCP tool.
- *
- * The SDK's current pin (v3 today) is implicit — this module describes
- * what the buyer sends to and receives from a v2.5 seller, regardless of
- * which v3.x patch the SDK itself speaks. When the SDK pin moves to v4,
- * this directory continues to hold the v2.5 compat shim and a sibling
- * `legacy/v3/` would join for v3 sellers.
- *
- * Add a new tool by:
- *   1. Drop a per-tool module in this directory exporting an
- *      `AdapterPair<V3Req, V25Req, V25Res, V3Res>`.
- *   2. Register it below.
- *   3. Add a fixture to `test/lib/adapter-v2-5-conformance.test.js`.
- *
- * Naming intentionally matches `legacy/<seller-version>/`, NOT
- * `<sdk-version>-to-<seller-version>/`. Real ad-tech compat layers carry
- * N=1 active legacy shim with a deprecation runway (OpenRTB, Prebid, GAM
- * all behave this way) — the directory tree should reflect "exceptional,
- * time-boxed" rather than encoding a matrix nobody will staff.
- */
-import type { AdapterPair } from './types.mjs';
-export type { AdapterPair } from './types.mjs';
-/**
- * Look up the legacy adapter pair for a given AdCP tool when targeting
- * a v2.5 seller. Returns `undefined` for tools without a registered pair
- * — caller should pass the request through unchanged.
- */
-export declare function getV25Adapter(toolName: string): AdapterPair | undefined;
-/**
- * Names of tools registered for v2.5 adaptation. Used by the conformance
- * test suite as the authoritative list.
- */
-export declare function listV25AdapterTools(): string[];

package/dist/lib/adapters/legacy/v2-5/index.d.ts

@@ -1,34 +0,0 @@
-/**
- * Registry of legacy v2.5 adapter pairs, one per AdCP tool.
- *
- * The SDK's current pin (v3 today) is implicit — this module describes
- * what the buyer sends to and receives from a v2.5 seller, regardless of
- * which v3.x patch the SDK itself speaks. When the SDK pin moves to v4,
- * this directory continues to hold the v2.5 compat shim and a sibling
- * `legacy/v3/` would join for v3 sellers.
- *
- * Add a new tool by:
- *   1. Drop a per-tool module in this directory exporting an
- *      `AdapterPair<V3Req, V25Req, V25Res, V3Res>`.
- *   2. Register it below.
- *   3. Add a fixture to `test/lib/adapter-v2-5-conformance.test.js`.
- *
- * Naming intentionally matches `legacy/<seller-version>/`, NOT
- * `<sdk-version>-to-<seller-version>/`. Real ad-tech compat layers carry
- * N=1 active legacy shim with a deprecation runway (OpenRTB, Prebid, GAM
- * all behave this way) — the directory tree should reflect "exceptional,
- * time-boxed" rather than encoding a matrix nobody will staff.
- */
-import type { AdapterPair } from './types';
-export type { AdapterPair } from './types';
-/**
- * Look up the legacy adapter pair for a given AdCP tool when targeting
- * a v2.5 seller. Returns `undefined` for tools without a registered pair
- * — caller should pass the request through unchanged.
- */
-export declare function getV25Adapter(toolName: string): AdapterPair | undefined;
-/**
- * Names of tools registered for v2.5 adaptation. Used by the conformance
- * test suite as the authoritative list.
- */
-export declare function listV25AdapterTools(): string[];