@adcp/sdk 16.1.0 → 16.3.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-20
-> Library: @adcp/sdk v16.1.0
+> Generated at: 2026-10-22
+> Library: @adcp/sdk v16.3.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.1`; 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.3`; 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.1.0` |
-| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@16.1.0 dist.integrity` |
+| Checkout `package.json` version | `@adcp/sdk@16.3.0` |
+| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@16.3.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.1.0'
-npm view '@adcp/sdk@16.1.0' dist.integrity
+npm install --save-exact '@adcp/sdk@16.3.0'
+npm view '@adcp/sdk@16.3.0' dist.integrity
 ```
 
 ### Required and optional peers

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

@@ -375,12 +375,57 @@ included) never falls back to brand.json `authorized_operators[]`, and it is
 not a grant removal: spend gets a retryable `SERVICE_UNAVAILABLE`.
 
 Origin key revocations use `/.well-known/governance-revocations.json`, signed
-with `typ: adcp-gov-revocation+jws`, as ratified R3 specifies. This origin key
-list does not migrate governance-context, designated-task response or rights
-JWS discovery: those retain the RFC chain in 3.3. Polling fails closed, revoked
+with `typ: adcp-gov-revocation+jws`, as ratified R3 specifies. The same list
+revokes the keys a WBA identity signs its JWS artifacts with (see
+[JWS artifacts](#jws-artifacts)). Polling fails closed, revoked
 keys remain revoked forever, `keyCompromise` cannot be weakened, and the earliest
 `invalidity_date` is retained. Revocation never pauses or cancels committed buys.
 
+### JWS artifacts
+
+Governance contexts, designated-task responses and rights attestations from a
+WBA identity are signed with keys from that identity's key directory (R4 as
+amended by adcontextprotocol/adcp#8299). `O` is the canonical origin of the
+signing agent's URL: `iss` for a governance context, `agent_url` for a
+designated-task response, `rights_agent.url` for a rights attestation. Pass it
+from your own context, never from the unverified token.
+
+- `selectJwsArtifactProfile(agentUrl, trust)` derives the trust record from
+  `O`. When it lists `O`, the artifact is verified on the WBA path; when the
+  operator has not published a record, or the record does not list `O`, it
+  stays on the 3.2 profile. A trust-record fetch failure throws
+  `JwsArtifactError` (`jws_key_unavailable`): it is never absence and never
+  selects 3.2. A 404/410 from an operator that once served a record is an
+  outage too, but the evaluator remembers that 200 only in process unless you
+  give it durable `authorityHistory` (`createIdentity33StateStores`). Public,
+  multi-replica and serverless verifiers must, as for grants.
+- `verifyWebBotAuthJwsArtifact(token, origin, { typ, directory, revocation })`
+  requires the `typ` the surface accepts, `alg` `EdDSA` and a `kid` equal to the
+  key's JWK thumbprint, applies no `use`/`key_ops`/`adcp_use` check, and checks
+  `O`'s revocation list. Purpose separation is by origin, so one key at `O` may
+  sign every artifact `O` issues and `typ` tells them apart. `revocation` is
+  required; pass `false` only if you check the returned `kid` yourself. It
+  verifies key and signature only; the surface keeps its own claim checks.
+- `verifyGovernanceAuthorization({ ..., webBotAuth: { trust, directory,
+  revocation } })` applies the rule to governance contexts. Every other check is
+  unchanged, including the `buyerIdentity` cross-check that `iss` is the buyer's
+  governance agent; only the key source moves. `revocation` is required, and an
+  origin that serves no list fails closed, since a governance context
+  authorizes spend. Outages (trust record, directory, revocation list) set
+  `retryable: true` on the failure. Without `webBotAuth` the verifier is 3.2
+  only, as before.
+- `verifyHistoricalGovernanceContext({ token, expectedIssuer, webBotAuth: {
+  ..., archive } })` verifies a retained governance context for audit. A key
+  rotated out of the directory is read from the governance key archive at `O`
+  (`/.well-known/jwks-archive.json`, `GovernanceKeyArchiveResolver`), on the
+  same `EdDSA` and thumbprint rules. A revoked key still verifies here: the
+  result reports `revocation: 'revoked'` and the stored R9 detail (`reason`,
+  `invalidity_date`) for the audit to weigh. Expiry, audience, replay and the
+  request binding are not checked.
+
+The SDK has no designated-task response or rights-attestation verifier of its
+own; a verifier for either uses the two primitives above.
+
 Permanent revocation storage reserves separate bounded capacity for audited bound
 origins and anonymous/self-service origins, so first-contact traffic cannot exhaust the bound
 pool. Storage failures deny reads and mutations without outage grace; inspect the
@@ -492,9 +537,9 @@ so verification can run in a CDN or middleware in front of the AdCP server.
   Cloudflare's `web-bot-auth`; they already used signed directories and are
   unchanged.
 #7894 drops the governance-token checks and the `governance/` vectors from the
-WBA profile. Governance moves to the AdCP layer under a separate R4 erratum,
-which moves JWS artifacts, governance included, to the identity's WBA key
-directory in 3.3. This change leaves the SDK's governance code as it is.
+WBA profile. Governance moves to the AdCP layer under a separate R4 erratum
+(adcontextprotocol/adcp#8299), which moves JWS artifacts, governance included,
+to the identity's WBA key directory in 3.3; see [JWS artifacts](#jws-artifacts).
 The buyer default onboarding field is `profiles.adcp.onboarding`, matching the
 schema; the design's `record_profiles` wording names the schema definition.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adcp/sdk",
-  "version": "16.1.0",
+  "version": "16.3.0",
   "description": "AdCP SDK — client, server, and compliance harnesses for the AdContext Protocol (MCP + A2A)",
   "workspaces": [
     ".",
@@ -729,10 +729,10 @@
     "email": "bugs@adcontextprotocol.org"
   },
   "dependencies": {
-    "@modelcontextprotocol/client": "2.2.0",
+    "@modelcontextprotocol/client": "2.3.1",
     "@modelcontextprotocol/ext-apps": "2.0.0",
     "@modelcontextprotocol/node": "2.0.0",
-    "@modelcontextprotocol/server": "2.2.0",
+    "@modelcontextprotocol/server": "2.3.1",
     "@types/ws": "^8.18.1",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
@@ -814,7 +814,9 @@
     "@changesets/parse": {
       "js-yaml": "^3.15.2"
     },
-    "minimatch": "^10.2.1"
+    "minimatch": "^10.2.1",
+    "launch-editor": "^2.14.2",
+    "markdown-it": "^14.3.3"
   },
   "adcp_version": "3.2.5",
   "sideEffects": [