@adcp/sdk 16.0.0-beta.7 → 16.0.0-beta.9

package/docs/guides/MEDIA-BUY-3.2-COMPATIBILITY.md

@@ -280,7 +280,7 @@ authoritative completion reconciliation after restart.
 
 ### Tokenless catalog and products-only legacy continuations
 
-An established 2.5, 3.0, or 3.1 seller may return purchasable catalog products
+An established 3.0 or 3.1 seller may return purchasable catalog products
 without a wholesale feed token, or answer a brief with products but no
 proposal. The SDK never invents a proposal, terms digest, or feed fence. When
 `principalScope`, an account, and stable seller-session binding are available,
@@ -301,7 +301,7 @@ invocation receives a fresh continuation even when the catalog is unchanged:
 const continuations = createInMemoryLegacyPurchaseContinuationStore();
 const lifecycle = await agent.negotiateMediaBuyLifecycle({
   principalScope: authenticatedPrincipalId,
-  // Required for established 2.5, 3.0, and 3.1 sellers that provide no server
+  // Required for established 3.0 and 3.1 sellers that provide no server
   // context ID. Persist this non-secret authenticated session ID across rehydration.
   legacyPurchaseSellerSessionScope: authenticatedSellerSessionId,
   legacyPurchaseContinuationStore: continuations,
@@ -331,9 +331,9 @@ after accepting the exact returned loss set. If the application requires an
 enforceable observed catalog/pricing fence, do not accept the continuation;
 the tokenless catalog is read-only for that policy.
 
-On 2.5 the loss set also includes `mutation_idempotency_not_guaranteed`. On 3.0
-and 3.1 it includes that loss whenever the seller does not advertise a usable
-replay TTL. All tokenless catalog continuations include
+On 3.0 and 3.1 the loss set includes `mutation_idempotency_not_guaranteed`
+whenever the seller does not advertise a usable replay TTL. All tokenless
+catalog continuations include
 `feed_version_not_atomic` and `pricing_version_not_atomic`.
 
 The in-memory store is a single-process reference implementation. Production
@@ -462,13 +462,12 @@ issued. It must be a stable, non-secret ID derived by the application from the
 authenticated seller/account session—not a bearer token. Persist and reuse it
 with the continuation store so a restarted coordinator can redeem or replay
 the same operation without making the token portable to another credentialed
-session. This applies to 2.5, 3.0, and 3.1; endpoint identity is not an
+session. This applies to 3.0 and 3.1; endpoint identity is not an
 authenticated session identity. URL userinfo and presigned URLs are rejected
 before the discovered payload can enter durable storage.
 
-Every 2.5 continuation declares `mutation_idempotency_not_guaranteed`.
-3.0/3.1 continuations declare the same loss whenever the seller does not
-advertise a usable replay TTL; accepting an idempotency key alone is not treated
+3.0/3.1 continuations declare `mutation_idempotency_not_guaranteed` whenever
+the seller does not advertise a usable replay TTL; accepting an idempotency key alone is not treated
 as evidence that a mutation can be replayed safely. Submitted completions are
 accepted only for the exact seller task ID recorded at dispatch. Unstructured
 or SDK-synthetic terminal errors remain ambiguous and retain the durable fence.
@@ -584,15 +583,17 @@ mutating prior state.
 
 ## Buyer projection policy
 
+All compatibility lanes require AdCP 3. AdCP 2 agents are rejected during discovery before a coordinator operation can dispatch; see the [AdCP 2 retirement guide](../migration-drop-adcp-2.md).
+
 | Coordinator operation | Compact tool | Established projection | Boundary |
 |---|---|---|---|
-| `listProducts` | `list_products` | `get_products(buying_mode='wholesale')` | Representable `criteria.offer_filters` map field-by-field through the negotiated legacy offer-filter schema; country remains `filters.countries` and is never recast as delivery targeting. Other structured criteria report their exact unsupported field before dispatch. Actual `wholesale_feed_version` is renamed to `feed_version`; no value is invented. An eligible tokenless catalog may expose the SDK-local `purchase_continuation` described above while `raw` remains the canonical SDK source object. The stable response exposes `next_cursor` and `unchanged` in both lanes. The established request includes `pagination` only when the caller supplies a cursor or `max_results`; the SDK does not fabricate a page-size default. v2.5 pagination/field selection, pre-3.1 conditional feed/pricing reads, and response-field names absent from the negotiated enum are typed unsupported. |
+| `listProducts` | `list_products` | `get_products(buying_mode='wholesale')` | Representable `criteria.offer_filters` map field-by-field through the negotiated legacy offer-filter schema; country remains `filters.countries` and is never recast as delivery targeting. Other structured criteria report their exact unsupported field before dispatch. Actual `wholesale_feed_version` is renamed to `feed_version`; no value is invented. An eligible tokenless catalog may expose the SDK-local `purchase_continuation` described above while `raw` remains the canonical SDK source object. The stable response exposes `next_cursor` and `unchanged` in both lanes. The established request includes `pagination` only when the caller supplies a cursor or `max_results`; the SDK does not fabricate a page-size default. Pre-3.1 conditional feed/pricing reads and response-field names absent from the negotiated enum are typed unsupported. |
 | `requestProposals` | `request_proposals` | `get_products(buying_mode='brief')` | Only offer-filter fields and metric values defined by the negotiated release map field-by-field, plus policy IDs. Compact catalog selection lacks the complete legacy catalog metadata and fails closed. Targeting-overlay requirements are forwarded only to a 3.2 established surface; 3.0/3.1 cannot represent them. Product-ID filters, compact-only offer prerequisites, `ext`, opportunity, and governance context fail preflight. |
 | `refineProposals` | `refine_proposals` | `get_products(buying_mode='refine')` | Ask and product include/omit map for revisions. Finalize maps only when it contains no additional refinement fields. Hard constraints, alternatives, criteria, amendment kinds, and finalize extras fail before dispatch. |
 | `declineProposals` | `decline_proposals` | proposal-scoped legacy omit | Rejected by default because omit is not a terminal decline and cannot carry the required compact reason/detail. Explicit opt-in reports `proposal_decline_not_terminal` and `proposal_decline_reason_not_forwarded`. |
-| `buyProducts` | `buy_products` | `create_media_buy` | Feed/pricing fencing is not atomic. Rejected by default; explicit opt-in names `feed_version_not_atomic` and, when present, `pricing_version_not_atomic`. A missing `feed_version` remains unsupported here; tokenless catalogs use the separate SDK-local `continueLegacyPurchase()` handoff. Shared package fields and nested targeting/reporting enums map against the negotiated schema, including 3.1+ `format_option_refs`; newer targeting, metric, and postal shapes fail closed. v2.5 also rejects non-empty compact targeting and push notification configuration. A direct compact `total_budget` and fields introduced on the 3.2 established surface—including allocation, budget-cap, bidding, governance, opportunity, and newer package controls—map only on a negotiated 3.2 established lane. Compact `catalog_ids` and resolved `pricing` remain typed unsupported. |
+| `buyProducts` | `buy_products` | `create_media_buy` | Feed/pricing fencing is not atomic. Rejected by default; explicit opt-in names `feed_version_not_atomic` and, when present, `pricing_version_not_atomic`. A missing `feed_version` remains unsupported here; tokenless catalogs use the separate SDK-local `continueLegacyPurchase()` handoff. Shared package fields and nested targeting/reporting enums map against the negotiated schema, including 3.1+ `format_option_refs`; newer targeting, metric, and postal shapes fail closed. A direct compact `total_budget` and fields introduced on the 3.2 established surface—including allocation, budget-cap, bidding, governance, opportunity, and newer package controls—map only on a negotiated 3.2 established lane. Compact `catalog_ids` and resolved `pricing` remain typed unsupported. |
 | `acceptProposal` | `accept_proposal` | `create_media_buy(proposal_id=...)` | A compact-shaped proposal retains strict digest, immutable-snapshot, account-scope, kind/status, and expiry checks. Caller values cannot override digest-bound budget, budget-cap, timezone, or purchase-order terms. An honest 3.0/3.1 proposal remains executable with its ordinary `proposal_id` semantics only after explicit opt-in to `proposal_terms_digest_not_enforced`, `proposal_terms_digest_unavailable`, and `proposal_snapshot_not_immutable` (plus `proposal_hold_not_verifiable` when it has no expiry). The caller supplies the original brand/flight as `established_fallback`; the SDK does not claim those values came from the seller or synthesize a digest. |
-| `controlMediaBuy` | `control_media_buy` | `update_media_buy` | Account, media-buy ID, and a positive revision are required. Revision and identically shaped fields present in the negotiated established schema map directly; `name` maps on the 3.2 established surface and fails closed on 3.0/3.1, whose update schemas do not define it. v2.5 requires explicit `revision_not_atomic` opt-in and rejects cancellation plus v3-only package controls. Pre-3.2 lanes reject the broader compact optimization-goal union and nested targeting/keyword shapes they cannot represent. Compact `catalog_ids` cannot be cast to established `catalogs` objects, so it fails closed in every established lane. |
+| `controlMediaBuy` | `control_media_buy` | `update_media_buy` | Account, media-buy ID, and a positive revision are required. Revision and identically shaped fields present in the negotiated established schema map directly; `name` maps on the 3.2 established surface and fails closed on 3.0/3.1, whose update schemas do not define it. Pre-3.2 lanes reject the broader compact optimization-goal union and nested targeting/keyword shapes they cannot represent. Compact `catalog_ids` cannot be cast to established `catalogs` objects, so it fails closed in every established lane. |
 | Readback | shared tools | `get_media_buys`, `get_media_buy_delivery` | Same public calls and canonical creative projection in every lane. Versioned request additions fail closed: webhook-activity and delivery-window/granularity options require 3.1+, while `indicator_types`, demographic breakdowns, and spot breakdowns require 3.2. Native postal reporting shapes require 3.1+. |
 
 Lossy mutations are fail-closed. An adopter may opt into only the exact named
@@ -735,8 +736,7 @@ trusted namespaces, never a buyer-supplied proposal ID alone.
 
 | Buyer surface | Seller surface | Expected path | Guarantee |
 |---|---|---|---|
-| Established `getProducts` / `createMediaBuy` / `updateMediaBuy` | AdCP 2.5–3.1 or a dual-surface 3.2 seller | Established tools are called directly | Existing application behavior remains unchanged; the compact coordinator is not involved. |
-| Compact-first coordinator | AdCP 2.5 | `list_products` → `get_products`; purchase → `create_media_buy`; supported control → `update_media_buy` | The direct common subset remains usable. Proposal objects/binding, media-buy readback, pagination, cancellation, v3-only top-level/package fields, and update reporting-webhook changes are typed unsupported rather than sent into v2.5's permissive additional-properties boundary. Feed fencing and optimistic revision enforcement require their named loss opt-ins. |
+| Established `getProducts` / `createMediaBuy` / `updateMediaBuy` | AdCP 3.0/3.1 or a dual-surface 3.2 seller | Established tools are called directly | Existing application behavior remains unchanged; the compact coordinator is not involved. |
 | Compact-first coordinator | AdCP 3.0, 3.1, or 3.2 legacy-only | `list_products` → `get_products`; proposal discovery/refinement → `get_products`; control → `update_media_buy`; purchase → `create_media_buy` only when its named loss policy permits it | Common-subset reads and control are lossless. Atomic feed/pricing fencing, digest enforcement, and terminal decline are not representable and fail before mutation by default. |
 | Compact-first coordinator | AdCP 3.2 dual-surface | Compact tools are preferred; `preferredLifecycle: 'established'` exercises the compatibility facade | Native by default; the forced established lane has the same explicit boundaries as older sellers. |
 | Compact-first coordinator | AdCP 3.2 compact-only | Compact lifecycle tools | Native compact guarantees. |
@@ -749,7 +749,7 @@ that a 3.0 seller can enforce a 3.2-only atomicity or digest guarantee. The SDK
 must reject that case or report the exact explicitly accepted loss; it must
 never label the weaker mutation as equivalent.
 
-The coordinator test matrix covers SDK 14 compact-first callers against v2.5,
+The coordinator test matrix covers compact-first callers against
 3.0, 3.1, 3.2 legacy-only, 3.2 dual-surface (compact preferred and established
 forced), and 3.2 compact-only discovery. The dual-surface MCP lane also holds
 the maximum at 3.2 while defaulting unversioned discovery and dispatch to 3.1,
@@ -761,9 +761,6 @@ validating every request and response against the corresponding cached wire
 bundle. Those lanes assert canonical format projection, pagination,
 feed/pricing provenance, account/brand/context/currency continuity, exact
 replay, changed-payload conflict, no duplicate mutation, control, and shared
-readback. The honest v2.5 fixture executes its complete representable direct
-subset, validates exact legacy wire, and asserts typed failures for pagination,
-proposals, cancellation, unsupported create/update fields, and media-buy
 readback. Versioned MCP fixtures also preserve submitted and input-required
 proposal states without inventing completed outcomes. A normal 3.2 server
 profile is exercised by 3.0 and 3.1 buyers through hidden established routes,

package/docs/guides/PROPERTY-LISTS.md

@@ -0,0 +1,264 @@
+# Property lists: matching, registry contribution, and serving
+
+## Buyer enforcement
+
+`validation.productPropertyPolicy` reads `get_products.filters.property_list`
+and the deprecated top-level `property_list`. When both are present they must
+have the same `agent_url`, `list_id`, and `auth_token`; conflicting references
+fail closed with `property_list_conflicting_references`. A malformed nested
+reference never falls back to the top-level field. The same reference is kept
+for polling, tracking, and webhook completions.
+
+These location and mixed-identifier fixes ship together. As before, request
+list enforcement defaults to enabled. Set `enforceRequestPropertyList: false`
+to disable local resolution, or `productPropertyPolicy: false` to disable the
+policy entirely. Resolution errors (including a non-MCP list URL) fail closed.
+
+Lists may mix domains, app bundles, and CTV store IDs. Non-domain types no
+longer cause an unconditional response failure. A product's
+`publisher_properties` contains publisher selectors, not app IDs: `property_ids`
+are opaque names scoped to a publisher. Supply complete catalogs to match
+their real identifiers:
+
+```typescript
+import { AdCPClient, type ProductPolicyResolvedProperty } from '@adcp/sdk';
+
+declare const loadPublisherCatalog: (
+  domain: string
+) => Promise<readonly ProductPolicyResolvedProperty[] | undefined>;
+
+const client = new AdCPClient(agents, {
+  validation: {
+    productPropertyPolicy: {
+      enforceRequestPropertyList: true,
+      unknownSelectorBehavior: 'flag',
+      resolvePublisherProperties: loadPublisherCatalog,
+    },
+  },
+});
+```
+
+The resolver receives normalized, untrusted publisher hostnames and an optional
+`{ signal }` argument. It returns the complete
+catalog of `{ property_id?, identifiers: [{ type, value }], tags? }` records
+from your publisher metadata store or discovery layer. Alternatively provide
+`publisherProperties: { [publisherDomain]: catalog }` directly. Keys use the exact
+normalized publisher hostname, including `www.` when present; catalogs are not
+shared across host aliases. When catalogs are configured, missing or failed
+lookups mean unknown metadata; `[]` means a known empty catalog. This hook does
+not initiate any additional registry or publisher lookups unless you implement
+them. Identifier type and value must match exactly for non-domain identifiers;
+bundle casing is preserved. `all`, `by_id`, and `by_tag` selectors are resolved
+against these records. Products with `property_targeting_allowed: true` may
+retain a proven eligible subset; other products must satisfy the policy for
+every selected property.
+
+Catalog loading is limited to 100 distinct lookups per response, 10 seconds
+per lookup, and a 10-second total budget by default (`maxPublisherLookups`,
+`publisherLookupTimeoutMs`, `publisherLookupBudgetMs`).
+Overflow and failed/timed-out lookups stay unknown even when a domain matches.
+Literal IP and localhost inputs do not reach the hook. For network discovery,
+use the SDK's SSRF-safe networking utilities to protect DNS resolution too;
+catalog identity/ownership verification remains the catalog provider's job.
+
+Products whose membership cannot be judged follow `unknownSelectorBehavior`
+(`allow`, `flag`, or `reject`). Request-derived policies remain strict by
+default, so the default unknown behavior is `reject`; choose `flag` explicitly
+to retain uncertain products. Known disallowed properties still reject even
+when another property is unknown. Diagnostics appear under
+`metadata.productPropertyPolicy`, including per-product
+`unresolved_property_identifiers` / `identifier_types` and
+`request_property_list.unsupported_identifier_types` for unrecognized types.
+
+## Identifier normalization and registration
+
+`normalizePropertyIdentifier(type, value)` (also exported as
+`validatePropertyIdentifier`) returns either `{ ok: true, value, rewrite? }`
+or `{ ok: false, error: IdentifierValidationError }`. Named normalizers cover
+domain, subdomain, iOS/Android bundles, Apple/Google/Roku/Samsung store IDs,
+Fire TV ASINs, and Apple TV/generic bundles. Each normalizer validates too.
+
+Domain normalization accepts HTTP(S) URLs and reports their reduction to a
+hostname, lowercases IDNs, and preserves wildcards. It preserves `www.` and
+`m.` because removing those labels would broaden an explicit allowlist.
+`subdomain` rejects wildcards. Platform names preserve case; numeric IDs stay
+strings without losing precision. Formats for app/store identifiers are SDK
+input hygiene rules, not assertions of registration, ownership, or existence.
+Opaque identifier families retain their spelling (including station names
+with spaces). Use these opt-in helpers before storing or matching values:
+
+```typescript
+import { normalizePropertyIdentifier } from '@adcp/sdk';
+
+const checked = normalizePropertyIdentifier('domain', submittedValue);
+if (!checked.ok) throw checked.error;
+await identifierStore.save({ type: 'domain', value: checked.value });
+// checked.rewrite, when present, records { from, to } for your review/audit UI.
+```
+
+`validatePublisherDomain(value)` is deliberately stricter: a publisher
+registration must already be a lowercase bare hostname. URLs, wildcards,
+ports, whitespace, trailing dots, malformed labels, and IP literals reject
+with `IdentifierValidationError.code === 'invalid_publisher_domain'`.
+`RegistryClient.saveProperty()` always performs this validation before HTTP.
+`saveProperties()` uses the same check for every record; failed records retain
+the existing `error` string and expose the typed error as `cause`.
+
+## Bulk catalog contribution
+
+`resolveIdentifiers()` in default `resolve` mode is the primary bulk catalog
+registration path: it contributes provenance, creates missing entries, and
+returns stable `property_rid` handles. Use `mode: 'lookup'` for read-only lookup.
+A RID is a join handle and does not grant advertising authorization.
+
+```typescript
+import { RegistryClient, isRegistryRequestError } from '@adcp/sdk';
+
+const registry = new RegistryClient({ apiKey: process.env.ADCP_REGISTRY_API_KEY });
+const outcomes = await registry.resolveIdentifiersAll({
+  identifiers,
+  provenance: { type: 'agency_allowlist', context: campaignId },
+  // Omit mode to register/contribute. Use mode: 'lookup' for a pure read.
+}, {
+  batchSize: 10_000,
+  maxRequestBytes: 1024 * 1024,
+  concurrency: 2,
+  maxRetries: 3,
+  maxRetryDelayMs: 60_000,
+});
+
+for (const outcome of outcomes) {
+  if (outcome.success) useCatalogHandle(outcome.identifier, outcome.result.property_rid);
+  else if (isRegistryRequestError(outcome.error)) {
+    reportRegistryFailure(outcome.index, outcome.error.status, outcome.error.retryAfterMs);
+  } else reportInputFailure(outcome.index, outcome.error);
+}
+```
+
+The helper caps each request at 10,000 identifiers and the configured UTF-8
+JSON byte limit, including provenance. It limits concurrency, honors
+`retryAfterMs` on HTTP 429, and returns an outcome for each input in input order,
+including duplicates. Oversized individual items, missing/malformed response
+entries, and failed batches become per-input errors; successful batches remain
+available. Inputs should already use canonical identifier spelling so registry
+results can be correlated by type and value. Empty input returns `[]`.
+
+Only rate limits are retried automatically. A server delay exceeding
+`maxRetryDelayMs` stops pending requests and returns the typed 429 (including
+its `retryAfterMs`) for callers to reschedule, without retrying early.
+Network and 5xx failures may have
+already contributed activity: identifier-to-RID resolution is idempotent, but
+the activity log is additive. The single-call API guards the 10,000-item limit;
+use the helper for byte-based splitting. `/api/registry/resolve` accepts responses
+up to 16 MiB by default; explicit `RegistryClientConfig.maxBodyBytes` still wins.
+
+Use `saveProperty()` when publishing or updating hosted publisher
+configuration (names, property identities, tags), rather than contributing a
+large identifier catalog. `saveProperties()` is a bounded client-side fan-out
+over that endpoint, intended for configuration updates. Its results are keyed
+by publisher domain; submit one configuration per domain.
+
+Registry HTTP failures use the exported `RegistryRequestError` /
+`isRegistryRequestError` contract, with `status`, `method`, `retryAfterMs`, and
+bounded untrusted `details`. Do not parse `error.message` for status or retry
+timing. Input validation and transport failures are separate errors.
+
+## Serve buyer-issued references over MCP
+
+`registerPropertyListTool` registers a real MCP `get_property_list` tool using
+the official MCP server. The reference's `auth_token` must authorize its exact
+`list_id`. It arrives in `Authorization: Bearer` or `x-adcp-auth`, never as a
+tool argument. The verifier runs before storage is read, on every page.
+
+```typescript
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { serve } from '@adcp/sdk';
+import { registerPropertyListTool } from '@adcp/sdk/server';
+
+serve(() => {
+  const server = new McpServer({ name: 'Buyer property lists', version: '1.0.0' });
+  registerPropertyListTool(server, {
+    verifyToken: ({ listId, token }) => listStore.verifyListToken(listId, token),
+    loadPage: (request, principal) => listStore.loadAuthorizedPage(request, principal),
+  });
+  return server;
+}, {
+  path: '/property-lists/mcp',
+  publicUrl: 'https://buyer.example/property-lists/mcp',
+  authenticate: listEndpointAuthenticator,
+});
+```
+
+Use your list endpoint's authenticator to validate list tokens globally and
+return `{ principal, token }`; the per-tool verifier still checks exact list
+access. Mount this read-only endpoint separately if your normal platform auth
+only accepts account bearers. Its proxy/auth middleware must allow the list
+token through. Ordinary MCP initialization needs no list ID. The helper also
+supports raw HTTP headers when a transport does not populate `authInfo`.
+It denies conflicting credentials and does not expose verifier/storage errors.
+
+`loadPage` receives a verified principal and the validated request, including
+`resolve` and `pagination`. Return `{ list, identifiers, pagination?,
+resolved_at?, cache_valid_until? }`. The list includes at least `list_id` and
+`name`; `identifiers` must be an array when resolving, including `[]` for an
+empty list. For `resolve: false`, return metadata without resolving identifiers.
+Honor the requested page limit (default 1,000; maximum 10,000). Provide a
+nonempty continuation cursor only when `has_more` is true, and bind cursors to
+the list, principal, and catalog revision. `list.property_count` is the total
+property count, not the current page's identifier count. Return coherent
+`cache_valid_until` timestamps across pages. The helper adds completion status
+and echoes request context on success and errors.
+
+Issue references whose `agent_url` points at this MCP endpoint. A plain REST
+URL returning JSON does not implement `get_property_list`.
+
+## Signed change notifications and certification
+
+Use your configured SDK `WebhookEmitter` (or the emitter from
+`createPostgresWebhookRuntime`) so signing, bounded retries, durable delivery
+bindings, and crash recovery use the same infrastructure as other webhooks:
+
+```typescript
+import { sendPropertyListChanged } from '@adcp/sdk/server';
+
+const result = await sendPropertyListChanged(
+  webhooks.emitter.forTenantScope(trustedTenantId),
+  {
+    url: subscriber.webhookUrl,
+    delivery_id: persistedDeliveryId,
+    notification: {
+      list_id: changedListId,
+      resolved_at: resolvedAt.toISOString(),
+      change_summary: { properties_added: added, properties_removed: removed, total_properties: total },
+    },
+  },
+);
+```
+
+Retain the same delivery ID and exact notification for retries. Each distinct
+event/subscriber delivery needs its own ID. The helper selects RFC 9421,
+includes the compatibility marker `signature: 'rfc9421'`, and lets the emitter
+bind a stable cryptographic `idempotency_key`. It sends a summary; receivers
+refresh through `get_property_list`. Configure production delivery storage,
+recovery, signing keys, and per-attempt subscription authorization on the
+emitter; see [the runtime reference](../TYPE-SUMMARY.md#postgresql-webhook-runtime).
+
+Before certifying a buyer, resolve references it actually issued:
+
+```typescript
+import { runPropertyListConformance, runConformance } from '@adcp/sdk/conformance';
+
+const report = await runPropertyListConformance(issuedReferences);
+if (report.totalFailures) throw new Error('Buyer-issued property lists are not resolvable');
+
+// Or include them in the main certification report/failure count:
+const fullReport = await runConformance(buyerAgentUrl, {
+  propertyListReferences: issuedReferences,
+});
+```
+
+Certification disables caches, validates each resolved page, checks list
+identity, rejects failure envelopes/oversized pages/cursor cycles, and uses
+the same MCP resolver as sellers. Reports identify inputs by index and never
+echo the reference token, URL, or remote exception. Empty lists are valid;
+unresolvable references fail the report rather than silently certifying.

package/docs/guides/SIGNING-GUIDE.md

@@ -503,6 +503,31 @@ app.post('/webhook', async (req, res) => {
 });
 ```
 
+Webhook-v1 uses unpadded Base64URL for `Signature` throughout AdCP 3.x,
+including 3.2. Its URL canonicalization follows AdCP 3.2 independently of
+that encoding. The 3.2 request-signing migration to padded standard Base64
+does not change the webhook-v1 profile. Python senders should use
+`adcp.signing.webhook_signer.sign_webhook` rather than a generic
+`sign_request` call with `signing_profile_version="3.2"` and the webhook tag.
+See the [protocol's binary-value encoding rules](https://github.com/adcontextprotocol/adcp/blob/v3.2.5/docs/building/by-layer/L1/security.mdx#adcp-rfc-9421-profile).
+
+When a known peer uses a generic RFC 9421 signer that emits standard padded
+Base64, configure that receiver route explicitly:
+
+```typescript
+await verifyWebhookSignature(req, {
+  jwks,
+  replayStore,
+  revocationStore,
+  signatureEncoding: 'rfc8941-base64',
+});
+```
+
+`createWebhookVerifier` accepts the same option. Each mode strictly parses
+its configured encoding; neither retries the other encoding. Select this
+option from trusted integration configuration, independently of incoming
+headers or webhook payloads.
+
 ## Step 6: Sign Outbound Webhooks (Seller)
 
 Configure `createAdcpServerFromPlatform` with a webhook signing key:

package/docs/guides/VALIDATE-YOUR-AGENT.md

@@ -835,3 +835,8 @@ Random seed on nightly broadens the surface; fixed seed on per-PR keeps reproduc
 - [`MULTI-INSTANCE-TESTING.md`](./MULTI-INSTANCE-TESTING.md) — horizontal scaling bug hunt
 - [`BUILD-AN-AGENT.md`](./BUILD-AN-AGENT.md) — server-side implementation
 - `skills/build-*-agent/SKILL.md` — per-specialism obligations and storyboard IDs
+
+
+For creative evaluator security fixtures, see
+[Creative evaluator build probes](CREATIVE-BUILD-PROBE.md) for valid route/input
+preparation, provisioned legacy selectors and explicit coverage gaps.

package/docs/llms.txt

@@ -1,7 +1,7 @@
 # Ad Context Protocol (AdCP)
 
-> Generated at: 2026-10-17
-> Library: @adcp/sdk v16.0.0-beta.7
+> Generated at: 2026-10-19
+> Library: @adcp/sdk v16.0.0-beta.9
 > AdCP major version: 3
 > Canonical URL: https://adcontextprotocol.github.io/adcp-client/llms.txt
 > Note: the `Library` stamp reflects the package.json version at doc-generation time. The narrative below describes the surface that lands on the next-published minor — including any 6.7 helpers documented here ahead of the release tag.

package/docs/migration-13-to-14.md

@@ -929,10 +929,12 @@ acceptance, caller-supplied budget,
 budget-cap, timezone, or purchase-order values must match any digest-bound
 seller terms; a conflict fails before `create_media_buy`.
 
-For v2.5 specifically, proposal operations, `get_media_buys`, pagination,
-cancellation, and v3-only package controls return typed unsupported errors.
-Supported pause/resume updates require explicit `revision_not_atomic` opt-in
-because v2.5 has no optimistic revision token.
+Historically, the SDK 14 v2.5 lane rejected proposal operations,
+`get_media_buys`, pagination, cancellation, and v3-only package controls with
+typed unsupported errors. Pause/resume updates required explicit
+`revision_not_atomic` opt-in because v2.5 has no optimistic revision token.
+SDK 16 removes that lane and rejects AdCP 2 agents before dispatch; see the
+[AdCP 2 retirement guide](./migration-drop-adcp-2.md).
 
 Run the same compact CLI storyboards against established sellers with
 `--media-buy-lifecycle-compat`. Use `--media-buy-compat-losses` only for the
@@ -1171,18 +1173,20 @@ configuration error; a tool or response variant absent from an installed
 bundle returns `undefined`. Neither case silently falls back to the current
 schema.
 
-Every `TaskResult.metadata` now exposes the selected seller wire generation as
-`serverVersion: 'v2' | 'v3'`. `serverVersionSynthetic` distinguishes an
-authoritative capability declaration (`false`) from the SDK's compatibility
-fallback (`true`). Both fields survive submitted/deferred continuations and
-durable restart recovery. `adcpVersion` remains the distinct, release-precision
-value echoed by a seller response.
-
-The v2.5 `get_products` response adapter also accepts explicitly zoned legacy
-forecast timestamps, including offset variants and single `$date`/`value`
-wrappers. It converts them to UTC RFC 3339 without losing fractional precision;
-ambiguous or unzoned values remain untouched, and the preserved seller wire
-object is not mutated.
+In SDK 14, every `TaskResult.metadata` exposed the selected seller wire
+generation as `serverVersion: 'v2' | 'v3'`. `serverVersionSynthetic`
+distinguishes an authoritative capability declaration (`false`) from the SDK's
+compatibility fallback (`true`). Both fields survive submitted/deferred
+continuations and durable restart recovery. `adcpVersion` remains the distinct,
+release-precision value echoed by a seller response. SDK 16 only dispatches
+AdCP 3 and rejects stored AdCP 2 continuations before resuming them; see the
+[AdCP 2 retirement guide](./migration-drop-adcp-2.md).
+
+The SDK 14 v2.5 `get_products` response adapter also accepted explicitly zoned
+legacy forecast timestamps, including offset variants and single `$date`/`value`
+wrappers. It converted them to UTC RFC 3339 without losing fractional precision;
+ambiguous or unzoned values remained untouched, and the preserved seller wire
+object was not mutated. That AdCP 2 adapter was removed in SDK 16.
 
 SDK 14 also adds semantic refinements to public object schemas. Behavior when
 composing a refined schema varies across supported Zod 4 releases: `.extend()`

package/docs/migration-14.x-rc-worksheet.md

@@ -16,18 +16,18 @@ pin using `ADCP_VERSION` inside that tarball.
 
 | Fact | Value |
 | --- | --- |
-| Checkout `package.json` version | `@adcp/sdk@16.0.0-beta.7` |
-| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@16.0.0-beta.7 dist.integrity` |
+| Checkout `package.json` version | `@adcp/sdk@16.0.0-beta.9` |
+| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@16.0.0-beta.9 dist.integrity` |
 | Node.js runtime | `^20.19.0 || >=22.12.0` |
 | Default AdCP wire release | `3.2.5` |
-| Maintained wire releases | `v2.5`, `v2.6`, `v3`, `3.0.0`, `3.0`, `3.0.1`, `3.0.2`, `3.0.3`, `3.0.4`, `3.0.5`, `3.0.6`, `3.0.7`, `3.0.8`, `3.0.9`, `3.0.10`, `3.0.11`, `3.0.12`, `3.0.13`, `3.0.14`, `3.0.15`, `3.0.16`, `3.0.17`, `3.0.18`, `3.0.19`, `3.0.20`, `3.0.21`, `3.0.22`, `3.0.23`, `3.0.24`, `3.0.25`, `3.1.0`, `3.1`, `3.1.1`, `3.1.2`, `3.1.3`, `3.1.4`, `3.1.5`, `3.1.6`, `3.1.7`, `3.1.8`, `3.1.9`, `3.1.10`, `3.1.11`, `3.1.12`, `3.1.13`, `3.1.14`, `3.1.15`, `3.1.16`, `3.1.17`, `3.1.18`, `3.1.19`, `3.1.20`, `3.1.21`, `3.1.22`, `3.1.23`, `3.1.24`, `3.1.25`, `3.1.26`, `3.1.27`, `3.1.28`, `3.1.29`, `3.2.1`, `3.2`, `3.2.2`, `3.2.3`, `3.2.4`, `3.2.5` |
+| Maintained wire releases | `v3`, `3.0.0`, `3.0`, `3.0.1`, `3.0.2`, `3.0.3`, `3.0.4`, `3.0.5`, `3.0.6`, `3.0.7`, `3.0.8`, `3.0.9`, `3.0.10`, `3.0.11`, `3.0.12`, `3.0.13`, `3.0.14`, `3.0.15`, `3.0.16`, `3.0.17`, `3.0.18`, `3.0.19`, `3.0.20`, `3.0.21`, `3.0.22`, `3.0.23`, `3.0.24`, `3.0.25`, `3.1.0`, `3.1`, `3.1.1`, `3.1.2`, `3.1.3`, `3.1.4`, `3.1.5`, `3.1.6`, `3.1.7`, `3.1.8`, `3.1.9`, `3.1.10`, `3.1.11`, `3.1.12`, `3.1.13`, `3.1.14`, `3.1.15`, `3.1.16`, `3.1.17`, `3.1.18`, `3.1.19`, `3.1.20`, `3.1.21`, `3.1.22`, `3.1.23`, `3.1.24`, `3.1.25`, `3.1.26`, `3.1.27`, `3.1.28`, `3.1.29`, `3.2.1`, `3.2`, `3.2.2`, `3.2.3`, `3.2.4`, `3.2.5` |
 | Canonical migration notes | [SDK 15 OAuth](./migration-oauth-issuer-bindings.md), [issuer-binding and storage](./guides/OAUTH-ISSUER-BINDING.md); historical [13.x → 14](./migration-13-to-14.md) |
 
 For a checkout at the published release commit, install the exact package version:
 
 ```bash
-npm install --save-exact '@adcp/sdk@16.0.0-beta.7'
-npm view '@adcp/sdk@16.0.0-beta.7' dist.integrity
+npm install --save-exact '@adcp/sdk@16.0.0-beta.9'
+npm view '@adcp/sdk@16.0.0-beta.9' dist.integrity
 ```
 
 ### Required and optional peers

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-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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adcp/sdk",
-  "version": "16.0.0-beta.7",
+  "version": "16.0.0-beta.9",
   "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",