@adcp/sdk 16.2.0 → 16.4.0

package/docs/guides/PROPOSAL-TERMS-VERIFICATION.md

@@ -152,3 +152,69 @@ ordered-array behavior, precise escaped pointers, failure on unreviewed schema
 semantics, and the same absence/opaque-reference/version behavior. The fixtures
 under `test/fixtures/proposal-commercial-terms` are portable JSON. Part A's unified
 action assessment and seller resolver remain separate work.
+
+
+### Proposal refinement on AdCP 3.3
+
+`AgentClient.refineProposals()` supports AdCP 3.2 and 3.3, including their
+release-precision prerelease pins. The request's `adcp_version` is a ceiling:
+a 3.3 buyer can accept a seller's lower supported 3.2 response. Upward, malformed,
+other-major and pre-3.2 echoes are rejected.
+
+The client's `adcpVersion` selects its schema bundle. `wireAdcpVersion` remains
+an envelope-only override: an unchanged echo of a consciously selected
+same-minor wire override keeps the configured schema pin. A genuine downgrade
+uses the bundle for the actual served contract, including an older prerelease.
+Missing selected schemas fail closed with the version and a registration hint.
+No older schema is relabelled as a new contract.
+
+Verification cross-checks any task echo against non-synthetic
+discovery/capability evidence already held by that client or coordinator.
+Only an explicit served-version observation constrains a compatible request
+ceiling; advertised `supported_versions` alone is not served-version evidence.
+An explicitly lower task ceiling does not inherit a higher discovery release;
+a raised task ceiling also does not inherit a selection made under a lower
+discovery ceiling.
+Applicable independent evidence takes precedence over task metadata, which can
+repeat the response echo. Task metadata supplies the served version when independent
+evidence is unavailable; both can supply it when the echo is omitted. If no actual served version is available, it keeps the configured
+schema pin; it does not infer a downgrade. Standalone callers that provide only
+`refinements` retain the SDK's default 3.2 validation behavior. To provide scoped
+actual-version evidence, pass `servedAdcpVersion` alongside the configured
+`adcpVersion` to `verifyRefineProposalsResponse()`. Generic strict response
+validation selects the same served schema before financial verification,
+including when an omitted task echo uses retained explicit discovery evidence
+after a durable continuation.
+
+For a genuine 3.3 preview, obtain the matching source schema bundle first and
+keep its external root registered throughout client creation and the workflow:
+
+```ts
+import { ADCPMultiAgentClient } from '@adcp/sdk';
+import { withExternalSchemaRoot } from '@adcp/sdk/testing';
+
+const candidateVersion = '3.3.0-beta.0';
+const candidateSchemaRoot = '/absolute/path/to/extracted/candidate/schemas';
+
+await withExternalSchemaRoot(candidateVersion, candidateSchemaRoot, async () => {
+  const client = ADCPMultiAgentClient.simple('https://seller.example/mcp', {
+    adcpVersion: candidateVersion,
+  });
+  return client.agent('default-agent').refineProposals({
+    refinements: [{ proposal_id: 'seller-issued-proposal', action: 'revise', ask: 'Reduce the total budget' }],
+  });
+});
+```
+
+The root must carry the matching version metadata and schema identities;
+`withExternalSchemaRoot` checks them. Do not copy and relabel a 3.2 release as
+3.3. This registration does not change the wire version or enable experimental
+features. The buyer still needs the seller's experimental feature opt-in before
+using such features. A server created inside the same scope also derives its
+typed error payloads from that root, including `errors[]` details and required
+error-arm discriminators. Nested or concurrent scopes keep their schema-derived
+error inventories separate.
+
+For shape-only verification, pass `{ adcpVersion: actualServedSchemaVersion }`
+to `validateRefineProposalsResponseShape()` to pin the already-selected served
+contract explicitly.

package/docs/llms.txt

@@ -1,7 +1,7 @@
 # Ad Context Protocol (AdCP)
 
-> Generated at: 2026-10-22
-> Library: @adcp/sdk v16.2.0
+> Generated at: 2026-10-23
+> Library: @adcp/sdk v16.4.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.2`; 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.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 is compact-lifecycle first: `list_products → buy_products → control_media_buy`, with `request_proposals → refine_proposals → accept_proposal` when terms need negotiation.
 
@@ -2146,6 +2146,7 @@ These docs are available locally in the repo and hosted at https://adcontextprot
 | Reliable Reporting production operations | docs/guides/REPORTING-OPERATIONS.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/REPORTING-OPERATIONS.md) |
 | Reliable Reporting stability policy (experimental storage package) | docs/guides/REPORTING-STABILITY.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/REPORTING-STABILITY.md) |
 | Validate your agent (5-command checklist) | docs/guides/VALIDATE-YOUR-AGENT.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/VALIDATE-YOUR-AGENT.md) |
+| Collection fixture foundation (storyboard fixtures) | docs/guides/COLLECTION-FIXTURE-FOUNDATION.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/COLLECTION-FIXTURE-FOUNDATION.md) |
 | Async patterns (polling, webhooks, deferred) | docs/guides/ASYNC-DEVELOPER-GUIDE.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/ASYNC-DEVELOPER-GUIDE.md) |
 | Async API reference | docs/guides/ASYNC-API-REFERENCE.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/ASYNC-API-REFERENCE.md) |
 | Durable task settlement intents | docs/guides/DURABLE-TASK-SETTLEMENT.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/DURABLE-TASK-SETTLEMENT.md) |

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

@@ -16,8 +16,8 @@ pin using `ADCP_VERSION` inside that tarball.
 
 | Fact | Value |
 | --- | --- |
-| Checkout `package.json` version | `@adcp/sdk@16.2.0` |
-| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@16.2.0 dist.integrity` |
+| Checkout `package.json` version | `@adcp/sdk@16.4.0` |
+| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@16.4.0 dist.integrity` |
 | Node.js runtime | `^20.19.0 || >=22.12.0` |
 | Default AdCP wire release | `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` |
@@ -26,8 +26,8 @@ pin using `ADCP_VERSION` inside that tarball.
 For a checkout at the published release commit, install the exact package version:
 
 ```bash
-npm install --save-exact '@adcp/sdk@16.2.0'
-npm view '@adcp/sdk@16.2.0' dist.integrity
+npm install --save-exact '@adcp/sdk@16.4.0'
+npm view '@adcp/sdk@16.4.0' dist.integrity
 ```
 
 ### Required and optional peers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adcp/sdk",
-  "version": "16.2.0",
+  "version": "16.4.0",
   "description": "AdCP SDK — client, server, and compliance harnesses for the AdContext Protocol (MCP + A2A)",
   "workspaces": [
     ".",