@adcp/sdk 16.4.0 → 16.6.0

package/docs/guides/COLLECTION-FIXTURE-FOUNDATION.md

@@ -69,6 +69,36 @@ schema-validated catalog is enumerated first. Discovery, schema, transport and
 pagination errors stay terminal; a complete no-match is still an explicit
 `fixture_unsatisfied` coverage gap, never a pass.
 
+Paginated discovery uses one stable `(cache_scope, wholesale_feed_version,
+pricing_version)` identity. Tokens are opaque, and appearing or disappearing
+also changes the identity. A change discards the partial catalog and restarts
+without a cursor; fixture selection and capture publication wait for a complete
+walk. The runner permits three restarts within its cumulative 1,000-page limit
+and honors the caller's abort signal. Continuous churn exhausts runner coverage:
+full and standalone execution skip with the bounded-observation `not_applicable` reason, while preparation
+returns `status: 'unsupported', reason: 'not_applicable'`. This reports neither
+seller nonconformance nor a complete no-match. Producer evidence remains available. Resolution records carry `unavailable_reason: runner_budget_exhausted`; their failed resolution status is not a seller verdict.
+
+Capability discovery errors also precede optional capability gates. Native full
+and standalone execution retain a `discovery_failed` result with the actual
+capability probe and redacted response evidence when available. Validated MCP
+OAuth requirements appear on the failed step's `authorization_required` for
+interactive prompting. Successful discovery that omits an optional capability
+still skips normally. Schema-invalid success bodies remain available to ungated diagnostic storyboards with their original schema notices; capability gates require valid evidence. Explicitly supplied profiles remain the caller's trusted
+scope boundary; failed or malformed evidence cannot establish capability absence.
+
+### Canonical format matching
+
+The `canonical_format_satisfies` fixture predicate uses the same comparison as
+the `canonical_format_satisfaction` storyboard validation. A selector may omit
+the option's `asset_source`, `buyer_asset_acceptance`, `composition_model`,
+`slots`, and `ssl_required`; the product keeps those production, manifest, and
+delivery declarations. Omission supplies no defaults, and explicit conflicting
+values still fail. Dimensions, duration, encoding limits, and unknown product
+constraints remain required. Selecting an option does not validate a creative
+manifest or prove buyer-upload support: fixtures that need a particular
+production policy must also match the relevant declared policy.
+
 ### Independent scopes
 
 `minimum_pairs: 1` and `minimum_pairs: 2` qualify **independently**. A seller
@@ -514,6 +544,86 @@ guarantees:
   tell the two apart. That is not a leak — the authorizer is the host, and
   the store it would be learning about is its own. What is closed is the
   oracle available to the caller, who sees only the refusal.
+- **Fresh preparation has its own optional authorization hook.** Pass
+  `prepared_fixtures_preparation_authorizer` in `PrepareStoryboardFixturesOptions`
+  to `prepareStoryboardFixtures`. The SDK asks it exactly once, after local
+  caller-metadata and misuse screens and before client creation, initialization,
+  capability discovery, controller reset/seeding, or catalog reads.
+
+  Its `PreparedFixturesPreparationLookup` contains `gate: 'prepare'` and a
+  locally computed `current` binding. There is no stored `binding`, `reference`,
+  or `step_id`: no state exists yet. The proposed identity includes the actual
+  routes, credential fingerprints, schema artifact, storyboard digest, account,
+  brand, principal, sandbox, and run scope. No seller profile is fabricated.
+  The authorized binding must still match before contact and before state is
+  minted; a changed scope is refused with `binding_mismatch`. Authorized
+  dispatch uses detached account, brand, credential, route, and storyboard data
+  across discovery awaits. Runtime services such as transport and OAuth storage
+  retain their host-owned identity. A drift refusal after contact cannot undo
+  earlier calls; their evidence goes only to the private audit sink.
+
+  The existing `PreparedFixturesLookup.binding` stays required and its gate
+  union stays `run | pass | step`. Existing reuse authorizers need no migration.
+  A host can explicitly share one implementation between the two options:
+
+  ```ts
+  import type {
+    PreparedFixturesLookup,
+    PreparedFixturesPreparationLookup,
+    PreparedFixturesDecision,
+  } from '@adcp/sdk/testing';
+
+  const authorize = async (
+    lookup: PreparedFixturesLookup | PreparedFixturesPreparationLookup
+  ): Promise<PreparedFixturesDecision> => {
+    const allowed = lookup.gate === 'prepare'
+      ? await hostMayPinAGraph(lookup.current)
+      : await hostGrantStillValid(lookup.binding, lookup.current);
+    return allowed ? { authorized: true } : { authorized: false, detail: 'denied' };
+  };
+
+  const prepared = await prepareStoryboardFixtures(agentUrl, storyboard, {
+    ...options,
+    prepared_fixtures_preparation_authorizer: authorize,
+  });
+  await runStoryboard(agentUrl, storyboard, {
+    ...options,
+    ...withPreparedFixtures(prepared, authorize),
+  });
+  ```
+
+  | Hooks supplied to preparation | Preparation hook calls | Reuse hook calls |
+  | --- | --- | --- |
+  | Neither | 0 | 0 |
+  | `prepared_fixtures_authorizer` only | 0 | 0 |
+  | Preparation hook only | 1 | 0 |
+  | Both | 1 | 0 |
+
+  **The reuse hook never authorizes preparation.** Passing it alone retains
+  legacy behavior, including seller contact. Hosts requiring a precontact
+  decision must adopt the new preparation option explicitly; invoking it is
+  not fulfilment of a different supplied hook. A preparation grant does not
+  authorize reuse: run/pass/step lookups still require the existing hook.
+
+  Only literal `authorized: true` grants. Denied, absent, malformed, throwing,
+  and rejecting decisions throw `PreparedFixturesDeniedError` with
+  `refusalCode: 'authorizer_denied'`, produce no state, and make zero seller
+  calls. Host-provided detail is never echoed at this gate. Canonical private
+  evidence goes to `prepared_fixtures_audit_sink`; a failing sink cannot grant
+  access or disclose its own error. A hook that never settles stalls the call;
+  the host must bound its authorization lookup.
+
+  The option belongs only to `PrepareStoryboardFixturesOptions`. Untyped use
+  on `runStoryboard`, `runStoryboardStep`, or `comply` throws before seller
+  contact rather than silently ignoring it. To gate a fresh run's catalog
+  reads, prepare explicitly with this hook, then reuse that state with the
+  reuse authorizer. Inline fresh resolution in those other entry points has
+  no preparation-hook contract.
+
+  The existing reserved-key asymmetry remains: preparation returns an invalid
+  caller body as a failed disposition; run/step deny it. Those local screens
+  run before the preparation authorizer and make no seller calls.
+
 - **A refusal is an access-control error, not a grading outcome.** When a
   gate refuses, `runStoryboard` / `runStoryboardStep` **throw**
   `PreparedFixturesDeniedError` and return nothing. The error carries
@@ -703,7 +813,7 @@ third-party runner cannot infer them:
 | The second parent-selection exclusion | `storyboard-schema.yaml` pins deterministic selection as "exclude candidates already pinned to non-reusable handles, sort by UTF-8 bytewise seller identity, select the first" — one exclusion. Skipping a parent that cannot satisfy a dependent discover-only pricing spec is a second, and it changes which product a conformant seller is tested on. |
 
 `collection_set` and `minimum_pairs` are zero-occurrence in
-`schemas/cache/3.2.5/` — they are SDK-local storyboard DSL, not wire
+`schemas/cache/3.2.7/` — they are SDK-local storyboard DSL, not wire
 objects, and the amendment should say so or a reader will take
 `collection_set_equals_context` to assert a wire shape.
 
@@ -717,6 +827,17 @@ Until a companion `adcontextprotocol/adcp` PR lands all six, no *published*
 storyboard can legally use any of this. That is a merge dependency, not an
 implementation gap — and it is why the downgrade story below matters.
 
+When a prepared fixture graph failed discovery, authorized reuse retains its
+producer phase as `fixture_preparation` and its handle records as
+`fixture_resolutions`. The producer phase is diagnostic history outside graded
+`phases`, so it does not add JUnit failures or change consumer grading counts.
+Protected capture keys are stripped from its public step contexts; a private
+audit sink receives the complete failed producer record after a denial. Failed
+discovery responses retain the official client's protocol response when available;
+successful-page evidence retains parsed SDK data. HTTP-only A2A evidence includes
+its status and an extraction note when the bounded capture was truncated. SDK
+connection diagnostics never stand in for a seller response.
+
 ### Output inventory for the amendment
 
 Everything a report consumer can newly observe, with where it is emitted and
@@ -733,7 +854,7 @@ Line numbers rot; these find the sites in any revision.
 | --- | --- | --- |
 | synthesized — capture | 3 | `grep -n "check: 'fixture_capture_unbuildable'" src/lib/testing/storyboard/{seeding,runner}.ts` — the seed/discovery step, the funnel's own commit refusal, and a standalone step reusing a failed preparation |
 | synthesized — protection | 2 | `grep -n "check: 'protected_context_violation'" src/lib/testing/storyboard/runner.ts` — the shared graded-commit helper (covering four funnel call sites) and the ordinary step's context patch |
-| synthesized — authority | 3 | `grep -n "check: 'prepared_fixtures_authorization'" src/lib/testing/storyboard/runner.ts` — the per-step gate, the run and pass gates, and the standalone step entry gate |
+| synthesized — authority | 3 | `grep -n "check: 'prepared_fixtures_authorization'" src/lib/testing/storyboard/runner.ts` — the per-step gate, the shared run/pass refusal helper (also used by the fresh-preparation gate), and the standalone step entry gate |
 | **authored — separate** | 1 | `grep -n "collection_set_equals_context" src/lib/testing/storyboard/validations.ts` — dispatch and implementation |
 
 `schema_id` and `schema_url` are `required_on_failure` for every check and

package/docs/guides/DELIVERY-WEBHOOK-PARSING.md

@@ -0,0 +1,135 @@
+# Parsing media-buy delivery webhooks
+
+Use `parseMediaBuyDeliveryWebhook` from `@adcp/sdk/webhooks` after your receiver
+has authenticated the original HTTP body and enforced replay protection. It
+validates delivery content without requiring an `AgentClient`, an SDK callback
+registry, or a signature-verification strategy. It performs no authentication
+itself; `ok: true` means the payload is valid, not that its sender is trusted.
+
+```typescript
+import { parseMediaBuyDeliveryWebhook } from '@adcp/sdk/webhooks';
+
+// Call only after signature verification. Load the version from the registered
+// seller/buy record, rather than trusting a version claim in the request body.
+function parseAuthenticatedDelivery(verifiedRawBody: Uint8Array, negotiatedVersion: string) {
+  const parsed = parseMediaBuyDeliveryWebhook(verifiedRawBody, {
+    adcpVersion: negotiatedVersion,
+  });
+  if (!parsed.ok) {
+    // Suitable for a 400 response: paths are readable and omit report values (map key names can appear in paths).
+    // e.g. result.media_buy_deliveries[0].by_package is required
+    return { status: 400, error: parsed.message, errors: parsed.errors };
+  }
+  return { status: 200, report: parsed.result };
+}
+```
+
+Pass the exact bytes you authenticated to avoid parsing a different body from
+JSON middleware. The parser also accepts a parsed JSON object or a JSON string. It returns
+a detached copy of validated data and preserves the seller's fields. It does
+not add a task status, operation ID, currency, package breakdown, or other
+missing data. Bodies are limited to 16 MiB and 64 nesting levels before schema
+validation. Schema diagnostics use fail-fast validation and readable paths.
+Invalid bodies return one of:
+
+| Code | Meaning |
+| --- | --- |
+| `webhook_envelope_invalid` | Malformed JSON, invalid envelope metadata, or a missing result. |
+| `webhook_result_invalid` | The nested delivery report fails the selected release's schema. |
+| `webhook_unsupported_payload` | Another task type, or an unenveloped report without explicit opt-in. |
+
+An invalid or unbundled `adcpVersion` is a caller configuration error and throws
+`ConfigurationError`. Omission selects the SDK's protocol pin. The body does not
+select its own validation release.
+
+## Select the release used for the buy
+
+A reporting webhook does not provide a trustworthy negotiated-version field.
+Keep that release with the callback/buy registration and supply it for every
+report. Stable patch pins select their bundled minor contract; preview pins
+remain exact.
+
+| Release | Report validation | Envelope details |
+| --- | --- | --- |
+| 3.0 | `get-media-buy-delivery-response.json`; report-wide currency is required. | `operation_id` is optional and remains absent when omitted. The parser accepts the documented `media_buy_delivery` discriminator even though the old task enum omits it. |
+| 3.1 | `media-buy-delivery-webhook-result.json`; report-wide currency is required. | `operation_id` is required. |
+| 3.2 | Dedicated webhook-result schema; report-wide currency is optional. | `operation_id` is required. |
+
+All releases require `by_package` on each delivery row. The SDK's schema loader
+handles both relative and absolute schema IDs. No external `$ref` traversal or
+network fetch is needed.
+
+On SDK 16, the standalone parser is additive. Existing `verifyAndParseWebhook`
+contracts remain unchanged; receivers needing per-buy release selection can pass
+already-authenticated bytes to this parser.
+
+## Bare-report compatibility is explicit
+
+The default rejects a body with top-level `media_buy_deliveries` and no MCP
+envelope. For a temporary migration, opt in explicitly:
+
+```typescript
+const parsed = parseMediaBuyDeliveryWebhook(verifiedRawBody, {
+  adcpVersion: savedBuy.adcpVersion,
+  acceptBareDeliveryReport: true,
+});
+if (parsed.ok && parsed.wireFormat === 'bare_delivery_report') {
+  // Record the seller's protocol violation and repair its callback format.
+  // parsed.envelope is undefined; no transport identity has been invented.
+}
+```
+
+The report still undergoes release-specific validation. A poll-shaped report
+with only a task `status` and no envelope identity is also bare; any such field
+is preserved when the selected report schema permits it. An incomplete or invalid
+envelope never falls back to bare-report acceptance. A normal envelope returns
+`wireFormat: 'mcp_envelope'` and the validated `envelope`. Authentication and
+sender, account, media-buy authorization, and deduplication remain the receiver's
+responsibility in either format.
+
+## A shared delivery body for polling and pushing
+
+`MediaBuyDeliveryReport` imports from `@adcp/sdk/types` or `@adcp/sdk/webhooks`.
+`MediaBuyDeliveryReportSchema` imports from `@adcp/sdk/schemas` and
+`@adcp/sdk/schemas/browser`. This payload-only shape accepts a polled report or a
+webhook result without requiring a task-level `status`. The shared TypeScript type and these Zod schemas describe
+the SDK's current pin; use the parser above for older release-specific checks.
+
+`GetMediaBuyDeliveryResponseSchema` still requires task status through its
+referenced `core/protocol-envelope.json`. The absence of `status` from the
+response document's own `required` list does not remove that inherited
+requirement. Use the shared body schema for ingestion, and the full response
+schema for a poll's protocol envelope. `MediaBuyDeliveryWebhookResultSchema`
+now retains the canonical required row fields, including `by_package`.
+
+## Envelope status and notification type are independent
+
+The parser accepts the selected release's task-status enum; it does not require
+`completed` for all reporting messages. For example, `notification_type:
+'delayed'` may accompany `status: 'working'` when a valid report is present.
+`delayed` itself is not a task status. A progress-only message without a report
+is not a delivery-data webhook.
+
+`notification_type: 'final'` concerns report scheduling; envelope `completed`
+does not mean the media buy has finished. Per-buy state remains in
+`media_buy_deliveries[].status`. This follows the protocol's
+[envelope/result distinction](https://github.com/adcontextprotocol/adcp/blob/v3.3.0-beta.0/docs/building/by-layer/L3/webhooks.mdx#payload-anatomy-envelope-vs-result).
+
+The protocol also requires receivers to ignore `aggregated_totals` in pushed
+reports as an authority source. The parser preserves that field for auditing
+when supplied; reconcile authoritative totals through a poll or per-delivery
+rows instead.
+
+For offline tooling that needs all raw JSON Schema diagnostics,
+`@adcp/sdk/schemas` also exports `getSchemaValidatorByRef`. Its default is
+fail-fast; complete diagnostics are an explicit option:
+
+```typescript
+import { getSchemaValidatorByRef } from '@adcp/sdk/schemas';
+const validate = getSchemaValidatorByRef(
+  'media-buy/media-buy-delivery-webhook-result.json',
+  '3.1',
+  undefined,
+  { allErrors: true },
+);
+```

package/docs/guides/DISCOVERY-CACHE-AND-SESSION-REUSE.md

@@ -5,7 +5,7 @@ A server-side caller that makes one AdCP call per incoming request, building a `
 Two independent mechanisms remove that cost:
 
 1. an **opt-in shared discovery cache** so client instances for the same agent and principal reuse one endpoint / `tools/list` / capabilities observation, and
-2. **reusable MCP connections** that per-call correlation headers, `AbortSignal`s and timeouts no longer split, plus a public **connection scope** to run a whole workflow on one session.
+2. **reusable MCP connections** inside a caller-owned connection scope, or with an explicit principal partition or process reuse opt-in. Per-call correlation headers, `AbortSignal`s and timeouts do not split these sessions.
 
 ## Shared discovery cache
 
@@ -54,6 +54,7 @@ The key is a SHA-256 over:
 | credential kind (anonymous, bearer, OAuth or header) | Keeps anonymous and authenticated discovery separate while allowing token rotation                                     |
 | configured `adcpVersion` / `wireAdcpVersion`         | negotiated version                                                                                                     |
 | every non-correlation, non-credential header         | unknown `x-*` tenant / routing / policy headers can select a different upstream view, so they fail closed into the key. This includes `baggage`, **ambient OpenTelemetry baggage included** |
+| `transport.connectionPartition` | Local caller principal partition; never sent on the wire |
 | request-signing identity and policy                  | `kind`, `kid`, `alg`, agent URL and signing policy; never the private key                                              |
 | configured `allowPrivateIp`, `maxResponseBytes`      | the transport policy the evidence was gathered under (per-call `transport` overrides included). These are the values the caller *configured*, not the effective ones: an unset `maxResponseBytes` keys as "unset" rather than as the 4 MiB default, so entries written before the default landed stay reusable. The MCP connection cache keys the *resolved* cap instead — see [Reusable MCP connections](#reusable-mcp-connections) |
 
@@ -97,11 +98,40 @@ const ok = await client.primeDiscoveryCache({
 
 Unlike [`primeCapabilities`](../TYPE-SUMMARY.md) — which stays client-bound and scope-keyed — seeded evidence outlives the instance. It returns `true` only once the backing cache accepted the entry, and `false` (seeding nothing) for synthetic, malformed, uncloneable or foreign-origin evidence. When the cache rejects the write or does not answer within the 2 second deadline, `false` means *not confirmed*, not *empty*: a write already handed to the backend may still land later, while one still queued behind earlier operations is dropped. After such a `false`, seed again or invalidate rather than assuming nothing was stored. Without `endpoint` the first call of a cold client still runs the endpoint probe once.
 
+## Multi-tenant intermediaries
+
+A shared seller credential cannot identify the end customer on whose behalf you call. An account ID in tool arguments does not isolate an MCP session. Use a caller-owned `connectionPartition` to reuse sessions for one principal without disclosing that principal in a header:
+
+```ts
+const client = new AgentClient(seller, {
+  transport: { connectionPartition: request.customerAuthorizationScopeId },
+  accountRegistryScope: request.customerAuthorizationScopeId,
+  discoveryCache: {
+    cache: discoveryCache,
+    authIdentity: request.customerAuthorizationScopeId,
+  },
+});
+```
+
+The partition is local configuration. It is hashed into MCP connection, discovery, and signing-policy cache keys and never sent in headers or tool arguments. Keep it stable for the same authorization scope, and use distinct values for different principals even when they share a seller token. Partitions also separate sessions within a single `withMCPConnectionScope` workflow.
+
+Outside a connection scope, calls now open and close their own MCP sessions by default. To retain process-wide reuse, provide a nonempty `connectionPartition`, or set `transport: { connectionReuse: 'process' }` when every caller with the same credentials and routing headers represents one principal. A supplied `trustedFetchFn` continues to use one-shot sessions outside an explicit scope, including with a partition or process opt-in.
+
+Successful calls and ordinary errors terminate one-shot sessions. When a call throws because it was cancelled or timed out, the SDK closes its client without sending DELETE, so it does not terminate work still running on the seller; remaining server session state follows the seller's TTL.
+
+Per-call `transport` replaces the constructor's complete transport object. Repeat `connectionPartition` (and any other settings) when passing an override; omitting it returns that call to one-shot behavior. Shared discovery still requires an explicit `authIdentity` and cache; the partition additionally separates entries, and a per-call partition change bypasses both the client's locally cached evidence and shared discovery for that call.
+
+The low-level `callMCPTool` request options and `MCPCallOptions` for `callMCPToolWithOAuth` accept `connectionPartition` and `connectionReuse` directly. Native task helpers accept a trailing connection-options argument with the same policy fields, `headers`, and `signingContext`. Repeat the creation call's routing headers and signing context on follow-up calls. Public low-level calls install their own policy, so calling them from an SDK callback does not inherit another principal. `checkGovernance()` calls without an explicit connection scope use one-shot sessions.
+
+For native MCP Tasks whose seller binds task ownership to the session, keep creation, polling, result retrieval, and cancellation inside the same connection scope, or use the same principal partition on every call. Generated agent and governance calls without a transport option use scopes for session continuity.
+
+Reuse a bounded set of principal partitions. Process sessions remain subject to the connection cache's LRU bound and have no idle expiry. Call `closeConnections()` from `@adcp/sdk/advanced` during shutdown, or use `withMCPConnectionScope` for sessions that close at workflow completion. These session options apply to MCP; they do not create A2A sessions. The local partition also separates shared discovery and signing-capability evidence for A2A. A low-level `connectMCP()` result remains caller-owned and must be closed by its caller.
+
 ## Reusable MCP connections
 
-This behavior applies by default, including calls that pass a signal or timeout outside a connection scope. The process-wide legacy/OAuth session cache retains at most 20 connections per cache with LRU eviction and has no idle expiry. For request workflows with many distinct credentials, use a scope to bound session lifetime. At process shutdown, `closeConnections()` from `@adcp/sdk/advanced` closes the process-wide connections.
+This reuse applies inside an explicit scope, or with `connectionPartition` or `connectionReuse: 'process'`. Other unscoped calls own one-shot sessions, including when they pass a signal or timeout. The process-wide legacy/OAuth session cache retains at most 20 connections per cache with LRU eviction and has no idle expiry. For request workflows with many distinct credentials, use a scope to bound session lifetime. At process shutdown, `closeConnections()` from `@adcp/sdk/advanced` closes the process-wide connections.
 
-A reusable session is keyed only by what changes the _connection_: endpoint, credential, tenant / routing headers, signing identity, `allowPrivateIp`, `maxResponseBytes`, a caller-injected fetch, and the workflow scope. These no longer choose or split a session:
+A reusable session is keyed only by what changes the _connection_: endpoint, credential, tenant / routing headers, signing identity, `allowPrivateIp`, `maxResponseBytes`, a caller-injected fetch, the local principal partition, and the workflow scope. These no longer choose or split a session:
 
 - **Correlation headers**: `traceparent`, `tracestate`, `x-request-id`, `x-correlation-id`, `x-trace-id`, `x-span-id`, `x-debug-id`, `x-client-request-id`, `x-b3-*`, `x-amzn-trace-id`, `x-cloud-trace-context`, `x-datadog-*`, `sentry-trace`, and vendor-prefixed `x-<vendor>-request-id` / `-correlation-id` / `-trace-id` / `-span-id` / `-debug-id`. Names suggesting credentials or tenant/routing identity (including `auth`, `token`, `tenant`, `account`, `workspace`, `seat`, `advertiser`, `publisher`, `buyer` and `seller`) are never treated as correlation. **`baggage` stays in the key**: it can carry tenant or routing members. Any header outside the list above also stays in the key (fail closed).
 - **`AbortSignal`** and **`requestTimeoutMs`**: they bound a call.
@@ -132,6 +162,21 @@ Await every operation before the scope callback returns; the callback owns the s
 
 Inside a scope the endpoint probe, capability discovery, `tools/list` and tool calls share one negotiated session per identity. `closeScopedConnections()` closes the current MCP scope's sessions early and does nothing when no MCP scope is active (A2A connections are not scoped). Nested `withMCPConnectionScope` calls join the outer scope unless you pass `{ isolate: true }`.
 
+An implicit high-level task scope closes local transports without sending session
+`DELETE` when its final result is accepted `submitted`, `working`, `input-required`,
+`auth-required`, or `deferred` work. (`deferred` is a task/HITL result, not an MCP
+wire status.) The owning task's final result decides; an earlier nested result
+cannot change a completed owner's cleanup. Completed tasks keep normal session
+termination.
+
+An explicit `withMCPConnectionScope` workflow remains caller-owned: its final
+cleanup terminates its sessions even if a call inside returned `submitted` or
+`working`. End that callback only when you intend to relinquish those sessions.
+Implicit preservation means avoiding termination, not retaining a connection for
+resumption: local clients are closed and evicted, later calls open fresh sessions,
+and the seller owns expiration of its retained sessions. A preserved implicit
+scope can include discovery sessions as well as the dispatch session.
+
 ### One exception: the first legacy handoff
 
 For a seller on the pre-2026 MCP protocol era, the SDK negotiates with the v2 client first and then hands the call to the v1 client so 2025 Tasks keep working. That handoff is a cold cost the SDK cannot avoid: the first scope against such a seller opens one classification handshake plus one shared v1 session. Within the scope everything after that (probe aside) shares the v1 session, including `tools/list`, and the classification is remembered across scopes for five minutes, so a later scope opens only its own session. Modern-era sellers need a single negotiation per scope.

package/docs/guides/REPORTING-LEDGER.md

@@ -103,6 +103,14 @@ buyer's orders out of another buyer's report. `mediaBuyIds` is always derived
 from the returned constituents, so a buyer-named order ID can never reach
 `fetchSlice`. `expectedCurrency`, `expectedSourceTimezone`, and
 `expectedMediaBuyIds` are optional assertions and fail closed on conflict.
+For products created per brief or buy, source offerings may declare
+`applicability.products: { kind: 'host_attested' }`. In that mode,
+`resolveCoverage` must also verify each product declares the selected offering
+in `reporting_capabilities.reporting_delivery_offering_ids`. The SDK retains
+constituent-kind and product-binding checks, and freezes the returned
+denominator for each configuration generation. Existing `productIds` lists
+keep their allowlist behavior. See [source offering applicability](./REPORTING-SOURCE-EXECUTOR.md#products-created-per-brief-or-buy)
+for the new shapes and reader compatibility requirements.
 The service rejects credential-shaped keys and `ctx_metadata` anywhere in the
 returned `sourceScope`, then applies the source contract and existing ledger
 immutability checks. Return the resulting secret-free configuration state from
@@ -1040,10 +1048,15 @@ setInterval(() => {
   credential.
 - `projectId` scopes both load submission and replay status checks. When it is
   omitted, both use the BigQuery client's default project. Each replica must
-  be able to read the BigQuery jobs submitted by the other replicas. Set
-  `location` for any dataset outside the US and EU multi-regions: BigQuery
-  answers a job lookup without the right location with 404, and the sink then
-  cannot find the jobs it created.
+  be able to read the BigQuery jobs submitted by the other replicas. When
+  `location` is omitted, the first `runOnce()` reads it using the official
+  client's `dataset.getMetadata()` and caches it for that sink instance before
+  any warehouse work, even on an idle tick. This requires `bigquery.datasets.get`.
+  Discovery times out after 60 seconds, or `loadTimeoutMilliseconds` if shorter.
+  Both load submissions and job lookups use that location. Discovery failures
+  reject before any sink state or load is written and can be retried; they name
+  the permission and the `location` option. Set `location` explicitly to skip
+  metadata access, including when using a wrapper without `getMetadata()`.
 - `loadTimeoutMilliseconds` (default 10 minutes) is the base deadline for one
   run's work on one load: uploading the file, or waiting for a job that is still
   running. It bounds a run, not the job. BigQuery does not stop a load when the
@@ -1122,11 +1135,9 @@ setInterval(() => {
   cancels a load at its deadline, so one running beside a newer worker on the
   same sink can cancel a job the newer worker is waiting on. The job then ends
   `DONE` with an error and the attempt advances. Rows do not duplicate, but
-  convergence slows. Also set `location` to the dataset's location: without it
-  a replay lookup of a load job returns 404 for datasets outside the US and EU
-  multi-regions, and the sink uploads again, gets a 409, and fails with a
-  "check projectId and location" error. The sink warns once per process when
-  `location` is unset.
+  convergence slows. The sink now discovers an omitted `location` from dataset
+  metadata. Older workers require an explicit location for datasets outside the
+  US and EU multi-regions so replay lookups can find their load jobs.
 - Stop old sink workers before relying on these overlap guarantees. If an
   earlier overlapping run left a plan whose starting cursor differs from the
   committed cursor, the sink rejects it before loading. Reconcile the retained

package/docs/guides/REPORTING-SOURCE-EXECUTOR.md

@@ -120,6 +120,28 @@ Start with one atomic offering per publication class and semantic contract. Choo
 
 Conservative first defaults are a single source-day window, scheduled polling with polling fallback, no async jobs unless the source requires them, and `basic` manifest support. Declare only metrics, dimensions, formats, and attribution settings the adapter can satisfy exactly.
 
+### Products created per brief or buy
+
+For a fixed catalogue, keep `applicability: { productIds: ['product-id'], constituentKinds: ['media_buy'] }`. Products outside that list are rejected.
+
+If product IDs are created per brief or buy, declare host-attested eligibility:
+
+```ts
+applicability: {
+  constituentKinds: ['media_buy'],
+  productIds: [],
+  products: { kind: 'host_attested' },
+}
+```
+
+The trusted host's `resolveCoverage(account, configuration)` must authorize the denominator for that resolved account and check that each product's `reporting_capabilities.reporting_delivery_offering_ids` includes the selected offering. The SDK does not own or query the seller's product catalogue. Raw ledger/source integrations must perform the same authorization before installing configurations or submitting source requests. Source conformance checks the declared applicability mode; it cannot independently verify a host's catalogue assertion.
+
+Host attestation replaces only the offering's enumerated product check. Constituent kinds, exact coverage, account scope, product bindings, and frozen configuration generations still apply. Keep the real product ID in each media-buy or package constituent and its binding; several products in one media buy retain distinct constituent identities. Raw executors may also support `product` constituents, which have no media-buy/package binding by design: the trusted host must authorize those product identities directly. An injected executor may narrow a declared product list but cannot broaden it or replace it with host attestation.
+
+New products can enter a new configuration generation without rewriting the offering; increment `delivery_config_version` when the denominator changes. Reinstalling the same version with different coverage fails the existing immutability check. Existing generations retain their frozen denominator. Keep an offering's applicability compatible with its active generations: changing back to a list that omits their products makes source conformance reject those requests. Use a distinct offering ID for incompatible changes.
+
+This is an opt-in extension of the source v1 schema in SDK 16.5.0. Existing declarations, required `productIds: string[]` types, and capability hashes are unchanged. Host-attested declarations require an empty `productIds` array and the explicit `products` marker; a nonempty list with that marker is rejected. Hosts and readers of source offering declarations must upgrade before using host attestation; older strict v1 validators reject it. Published source capabilities retain the explicit `host_attested` declaration, which means per-product eligibility is attested by the host, rather than declaring universal applicability. `listedReportingSourceProductIdsV1(applicability)` returns the list for legacy declarations or `undefined` for host attestation.
+
 `null` and missing data are not zero delivery. A complete zero-row source result uses `explicitZero: true`; an unavailable full-coverage result returns `PARTIAL_RESULT` or `NOT_READY`.
 
 All reporting periods and `eventTimeRange` values use half-open `[start, end)` semantics. `eventTimeRange.end === period.end` means rows were observed up to the exclusive period boundary; it never admits an event at that instant.

package/docs/guides/SIGNING-GUIDE.md

@@ -216,6 +216,12 @@ const signingFetch = buildAgentSigningFetch({
 
 ### Diagnosing a seller's rejection of a signed request
 
+The client evaluates the seller's `request_signing.protocol_methods_required_for` and `protocol_methods_warn_for` separately from AdCP operation lists. With `sign_supported: true`, it also signs methods in `protocol_methods_supported_for`. Matching uses the decoded, case-sensitive JSON-RPC method: `tasks/cancel` and `CancelTask` are distinct. `tools/call` belongs to the AdCP-operation namespace through `params.name` and cannot appear in protocol-method overrides.
+
+Use `request_signing.always_sign_protocol_methods: ['tasks/cancel', 'CancelTask']` for a pilot before the seller advertises coverage. This works with inline keys and signing providers, including a cold capability cache. Keep `always_sign` for AdCP operation names. Cached transports and shared discovery/testing clients distinguish these signing policies. An ambiguous JSON body is refused before dispatch when protocol-method signing policy applies.
+
+The SDK's compatibility task polls (`tasks_get` over MCP and skill `tasks/get` over A2A) are signed when a signer is configured and the seller declares `request_signing.supported: true` with a compatible signing profile. They need no operation-list entry. Each poll uses a fresh nonce; native MCP `tasks/get`, `tasks/result`, `tasks/list`, and `tasks/cancel` on a signing-configured transport follow protocol-method coverage. A misconfigured signing identity can now cause these compatibility polls to fail signature verification even if a bearer previously let the unsigned poll through. Best-effort A2A cancellation retains its signing policy and uses the active AdCP wire-version pin. With Web Bot Auth, cancellation requires cached profile support; if that evidence is unavailable, the best-effort cancellation is abandoned.
+
 For SDK client calls over A2A or MCP, a signed HTTP 401 with a `Signature` challenge (or no challenge) produces an `AuthenticationRequiredError` with `requestSigned: true` and `status: 401`. Its `code` remains `AUTHENTICATION_REQUIRED` for compatibility; `signatureErrorCode` carries a recognized seller `request_signature_*` code, and the message includes the protocol's repair hint. Check the public discovery chain, `brand_json_url` → `agents[]` → `jwks_uri`, when the seller cannot resolve your key. Explicit Bearer or Basic gateway challenges retain their existing authentication recovery. For client-credentials agents, a bare 401 still permits one token refresh; a persistent signed rejection keeps its diagnostics. Other signed bare 401s bypass unsigned authentication probes and interactive OAuth recovery, so gateways requiring those flows should send an explicit Bearer challenge.
 
 `error.responseBody` contains a bounded, redacted seller diagnostic when capture succeeds. It is non-enumerable and excluded from JSON error reports. Custom header values are conservatively treated as credentials; short values can mask matching diagnostic text. Treat it as untrusted operator diagnostic text; do not feed it to automated prompts or use it as recovery instructions. Failed `TaskResult` values preserve this error under `result.errorInstance`, so the diagnostic is available as `result.errorInstance.responseBody` after narrowing to `AuthenticationRequiredError`. Conformance raw capture uses the same bounded, redacted diagnostic rather than the original response bytes for these failures. Low-level signing fetch presets continue to return the original HTTP `Response`.
@@ -420,6 +426,10 @@ app.use(createExpressVerifier({
 
 The schema uses one table with `(keyid, scope, nonce)` as the primary key, indexes on `expires_at` and `(keyid, scope, expires_at)`, and a table-specific guarded-insert function. Each insert attempt is one round trip to that function, which tries a transaction-scoped advisory lock and handles the replay/cap/insert decision atomically. Busy scopes use bounded client-side retry between queries, so pooled connections remain available to unrelated scopes. Rerun `getReplayStoreMigration()` before deploying an SDK upgrade so the function stays current; the migration is idempotent. The sweeper exists because Postgres has no native row-level TTL — it's a `DELETE FROM replay_cache WHERE expires_at <= now()` you call on a schedule. Other backends (Redis, KeyDB, anything supporting atomic insert-if-absent with TTL) can implement the `ReplayStore` interface the same way.
 
+The request and RFC 9421 webhook verifiers require an unpadded Base64URL nonce containing at least 16 bytes. SDK signers generate one by default. If you override `nonce`, use at least 16 random bytes encoded with `randomBytes(16).toString('base64url')`; short labels and padded values are rejected with `request_signature_params_incomplete` or `webhook_signature_params_incomplete` before key discovery.
+
+After signature and digest verification succeed, the verifier records the nonce before checking JSON body well-formedness. An authenticated malformed body returns `request_body_malformed` or `webhook_body_malformed` at checklist step 14; sending that frame again returns the replay error. Duplicate keys, invalid UTF-8 body bytes, and leading BOMs are refused. Errors contain a fixed message and reason code, without submitted body bytes or duplicate key names. Request operation-resolution prechecks can reject ambiguous bodies earlier, before signature verification.
+
 On successful verification, `req.verifiedSigner` contains `{ keyid, agent_url?, verified_at }`. On failure, the middleware returns `401` with `WWW-Authenticate: Signature error="<code>"`.
 
 ### Operation resolution: MCP and A2A

package/docs/guides/TYPED-CLIENT-TOOLS.md

@@ -0,0 +1,49 @@
+# Typed client tools
+
+`SingleAgentClient` and `AgentClient` expose a camelCase method for every tool
+in the bundled AdCP manifest. Each method uses the normal request validation,
+idempotency-key generation, and per-client version negotiation. `executeTask`
+also has typed request and response mappings for every tool.
+
+```ts
+const result = await client.getTaskStatus({ task_id: sellerTaskId, include_result: true });
+if (result.success) console.log(result.data.status, result.data.result);
+
+const tasks = await client.listTasks({}); // Queries the seller's list_tasks tool.
+```
+
+`getTaskStatus({ task_id })` returns the protocol response inside `TaskResult`.
+The observed task's `status` and `error` remain data: querying a failed or working
+task completes the query without resubmitting or following that task.
+
+For compatibility, `getTaskStatus(taskId)` still returns mapped `TaskInfo`, and
+`listTasks()` with no arguments still lists locally tracked tasks. Use
+`trackTask()` or a submitted result's `waitForCompletion()` to observe completion.
+The object overload calls `get_task_status` directly and requires a seller that
+supports that tool. Use the string overload or task tracking for negotiated
+compatibility with older sellers.
+The typed response preserves the seller's `task_id`; callers should compare it
+with the requested ID. The string overload and completion tracking enforce that
+identity check automatically. Discovery and authorization failures are surfaced
+rather than treated as evidence that only the legacy tool is supported.
+
+SDK polling chooses `get_task_status` when advertised by the seller, falling back
+to `tasks_get` for MCP or `tasks/get` for A2A otherwise.
+
+The supported tools `listCreativeFormats`, `buildCreative`, `listTransformers`,
+`getContentStandards`, `listContentStandards`, `calibrateContent`, and
+`validateContentDelivery` have ordinary typed methods. Their existing `*Legacy`
+aliases remain available. These tool methods return their protocol wire shapes;
+the SDK's canonical creative discovery and delivery helpers remain available too.
+On the SDK 16 line these are the AdCP 3.2 wire shapes, including any legacy
+`format_id` fields the protocol still supports. Generic `preview_creative`
+execution uses the canonical preview helper; use `previewCreativeLegacy` for
+raw named-format requests.
+
+Direct `SingleAgentClient.syncPlans` and `getPlanAuditLogs` calls use the
+configured governance agent when present. Without one, the client requires its
+own agent to advertise the governance tool before sending the request.
+
+`complyTestController` is typed for conformance testing against a seller that
+advertises it. Its availability does not imply that a production seller enables
+test controls.

package/docs/llms.txt

@@ -1,7 +1,7 @@
 # Ad Context Protocol (AdCP)
 
-> Generated at: 2026-10-23
-> Library: @adcp/sdk v16.4.0
+> Generated at: 2026-10-27
+> Library: @adcp/sdk v16.6.0
 > 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.
@@ -13,7 +13,7 @@ AdCP is an open protocol for AI agents to buy, manage, and optimize advertising
 
 ## Start here: AdCP 3.2
 
-The SDK requires Node.js `^20.19.0 || >=22.12.0`. Install this reference's release train with `npm install @adcp/sdk@16.4`; use the documentation from the exact published SDK version you install. For reproducible CLI runs, pin that exact SDK version. After installation, `node -p "require('@adcp/sdk').ADCP_VERSION"` reports its protocol pin; `ls node_modules/@adcp/sdk/compliance/cache` lists its packaged compliance versions. The legacy `adcp-3.2` npm tag selects SDK 14 and does not receive the refreshed compliance caches.
+The SDK requires Node.js `^20.19.0 || >=22.12.0`. Install this reference's release train with `npm install @adcp/sdk@16.6`; use the documentation from the exact published SDK version you install. For reproducible CLI runs, pin that exact SDK version. After installation, `node -p "require('@adcp/sdk').ADCP_VERSION"` reports its protocol pin; `ls node_modules/@adcp/sdk/compliance/cache` lists its packaged compliance versions. The legacy `adcp-3.2` npm tag selects SDK 14 and does not receive the refreshed compliance caches.
 
 The SDK is compact-lifecycle first: `list_products → buy_products → control_media_buy`, with `request_proposals → refine_proposals → accept_proposal` when terms need negotiation.
 
@@ -1529,7 +1529,7 @@ Flow: `get_products`
 **Product coverage is preserved across discovery surfaces** — Checks legacy and compact coverage predicates against independent negative controls without configuring delivery targeting.
 Flow: `get_products → list_products`
 
-**Seller applies deterministic product filters in every buying mode** — Verifies schema-valid get_products filters affect brief curation, wholesale feeds, and refinement instead of silently no-oping.
+**Seller applies deterministic product filters in supported buying modes** — Verifies schema-valid get_products filters affect brief curation, wholesale feeds, and refinement instead of silently no-oping.
 Flow: `get_products`
 
 **Seller exposes wholesale signal options and honors package-level signal_targeting_groups** — Verifies that a seller with wholesale products and wholesale get_signals can expose signal targeting eligibility, accept package-level signal_targeting_groups with pricing, reject unknown signals, and echo the applied grouped expression on readback.
@@ -1572,7 +1572,7 @@ Flow: `sync_accounts → get_products → create_media_buy → get_media_buys`
 Flow: `get_products → create_media_buy → update_media_buy → get_media_buys → update_media_buy → create_media_buy → get_products → create_media_buy → update_media_buy → get_media_buys → update_media_buy → get_media_buys`
 
 **Atomic media-buy total budget redistribution** — Verifies that a fixed media-buy total_budget update proportionally rescales active packages, returns auditable package state, and rejects competing package patches atomically.
-Flow: `sync_accounts → create_media_buy → update_media_buy → get_media_buys → update_media_buy`
+Flow: `sync_accounts → create_media_buy → get_media_buys → update_media_buy → get_media_buys → update_media_buy`
 
 **Seller handles typed proposal negotiation with constraints, product changes, and alternatives** — Verifies the AdCP 3.2 typed negotiation lifecycle: capability-gated constraint satisfaction, product changes, digest-verified alternatives, partial invariant, immutable lineage, finalize atomicity, and idempotent replay through refine_proposals.
 Flow: `get_adcp_capabilities → sync_accounts → request_proposals → refine_proposals → accept_proposal → refine_proposals`
@@ -1602,7 +1602,7 @@ Flow: `get_adcp_capabilities → get_products → create_media_buy → get_media
 Flow: `get_adcp_capabilities → sync_accounts → sync_catalogs → build_creative → expect_substitution_safe → get_products → create_media_buy → sync_event_sources → log_event → provide_performance_feedback → get_media_buy_delivery`
 
 **Digital out-of-home — non-guaranteed** — DOOH seller for non-guaranteed venue and screen inventory with canonical screen formats and substantive play reporting.
-Flow: `get_adcp_capabilities → list_products → create_media_buy → validate_input → sync_creatives → create_media_buy → comply_test_controller → get_media_buy_delivery`
+Flow: `get_adcp_capabilities → list_products → get_products → create_media_buy → validate_input → sync_creatives → create_media_buy → comply_test_controller → get_media_buy_delivery`
 
 **Programmatic exchange seller** — Programmatic exchange or SSP — multi-publisher auction inventory with floor prices, bid guidance, audience targeting, and auction-level delivery transparency.
 Flow: `get_adcp_capabilities → sync_accounts → sync_governance → get_products → create_media_buy → update_media_buy → get_media_buy_delivery`
@@ -1655,7 +1655,7 @@ Flow: `sync_accounts → get_products → create_media_buy → comply_test_contr
 Flow: `get_media_buys → comply_test_controller → get_media_buy_delivery`
 
 **End-to-end vendor-metric accountability: declaration → commitment → delivery audit** — Buyer commits vendor metrics on two packages, then verifies one clean package, one overdue gap, and one not-yet-measurable omission.
-Flow: `sync_accounts → get_products → create_media_buy → comply_test_controller → get_media_buy_delivery`
+Flow: `sync_accounts → get_products → create_media_buy → get_media_buys → comply_test_controller → get_media_buy_delivery`
 
 **Reliable Reporting: Managed Delivery** — Validates the Managed Delivery tier's explicit capability, atomic managed offering, resource retention, and authorization-revocation contract.
 Flow: `get_adcp_capabilities → comply_test_controller → get_reporting_status → comply_test_controller`
@@ -1838,6 +1838,8 @@ Flow: `get_adcp_capabilities → list_transformers → build_creative`
 
 **Runner output contract** — Required failure-detail shape that AdCP storyboard runners MUST emit so implementors can self-diagnose validation failures.
 
+**AdCP 4.0 compatibility checks**
+
 ### Error Handling
 
 **Billing contract and gate dispatch — sync_accounts capability vs per-buyer-agent gate** — Validates that account.supported_billing is declared and honored by sync_accounts, including out-of-set BILLING_NOT_SUPPORTED rejection, recovery-value consistency, and the distinct per-buyer-agent BILLING_NOT_PERMITTED_FOR_AGENT gate.
@@ -2045,6 +2047,8 @@ Run compliance tests with `adcp test <agent> <scenario>`. 24 built-in scenarios:
 
 ### Seeding fixtures for compliance (seller-side)
 
+Fresh fixture preparation can be gated with `prepareStoryboardFixtures(..., { prepared_fixtures_preparation_authorizer })`. It asks once before seller contact using a truthful proposed binding. The existing `prepared_fixtures_authorizer` remains reuse-only and is never called by preparation. The preparation-only option is rejected by run/step/comply; prepare explicitly before reusing state. See [collection fixture foundation](guides/COLLECTION-FIXTURE-FOUNDATION.md).
+
 Group A storyboards seed fixtures via `comply_test_controller.seed_product` (and the other `seed_*` scenarios) before calling the spec tool. Two SDK helpers bridge this:
 
 - **`mergeSeedProduct`** (plus the raw-wire `mergeSeedProductLegacy` migration counterpart, `mergeSeedPricingOption`, `mergeSeedCreative`, `mergeSeedPlan`, `mergeSeedMediaBuy`): permissive merge of a sparse storyboard fixture onto the seller's baseline defaults. `undefined`/`null` keep base; arrays replace by default; well-known id-keyed lists (`pricing_options`, `publisher_properties`, `packages`, `assets`, plan `findings`) overlay by id so seeding one entry doesn't drop the rest.