@adcp/sdk 14.0.0 → 14.2.0

package/dist/lib/wholesale-feed-sync/types.d.mts

@@ -22,7 +22,7 @@ export type WholesaleFeedSyncMode = 'manual' | 'auto-poll';
 /**
  * Lifecycle state of the sync engine.
  */
-export type WholesaleFeedSyncState = 'idle' | 'bootstrapping' | 'syncing' | 'error';
+export type WholesaleFeedSyncState = 'idle' | 'bootstrapping' | 'syncing' | 'degraded' | 'error';
 /**
  * Subset of `SingleAgentClient` that {@link WholesaleFeedSync} actually uses.
  * Lets tests inject a minimal stub without constructing a full client.
@@ -178,8 +178,8 @@ export interface ResolvedCapabilities {
  *   picks a mode. Useful for UI mode badges.
  * - `resyncing` — emitted before a `wholesale_feed.bulk_change` recovery
  *   re-bootstrap, webhook-version mismatch repair, or manual refresh.
- * - `error` — background poll/probe error. Non-fatal; sync stays in
- *   `'syncing'` and retries on the next tick.
+ * - `error` — initial bootstrap, re-sync, or background probe failure.
+ *   Failed refreshes preserve the last good mirror and retry on the next tick.
  * - `stateChange` — fires on every {@link WholesaleFeedSyncState} transition.
  */
 export interface WholesaleFeedSyncEvents {
@@ -200,6 +200,7 @@ export interface WholesaleFeedSyncEvents {
     }];
     error: [{
         error: Error;
+        adcpError?: import('../core/ConversationTypes.mjs').AdcpErrorInfo;
     }];
     stateChange: [{
         from: WholesaleFeedSyncState;

package/dist/lib/wholesale-feed-sync/types.d.ts

@@ -22,7 +22,7 @@ export type WholesaleFeedSyncMode = 'manual' | 'auto-poll';
 /**
  * Lifecycle state of the sync engine.
  */
-export type WholesaleFeedSyncState = 'idle' | 'bootstrapping' | 'syncing' | 'error';
+export type WholesaleFeedSyncState = 'idle' | 'bootstrapping' | 'syncing' | 'degraded' | 'error';
 /**
  * Subset of `SingleAgentClient` that {@link WholesaleFeedSync} actually uses.
  * Lets tests inject a minimal stub without constructing a full client.
@@ -178,8 +178,8 @@ export interface ResolvedCapabilities {
  *   picks a mode. Useful for UI mode badges.
  * - `resyncing` — emitted before a `wholesale_feed.bulk_change` recovery
  *   re-bootstrap, webhook-version mismatch repair, or manual refresh.
- * - `error` — background poll/probe error. Non-fatal; sync stays in
- *   `'syncing'` and retries on the next tick.
+ * - `error` — initial bootstrap, re-sync, or background probe failure.
+ *   Failed refreshes preserve the last good mirror and retry on the next tick.
  * - `stateChange` — fires on every {@link WholesaleFeedSyncState} transition.
  */
 export interface WholesaleFeedSyncEvents {
@@ -200,6 +200,7 @@ export interface WholesaleFeedSyncEvents {
     }];
     error: [{
         error: Error;
+        adcpError?: import('../core/ConversationTypes').AdcpErrorInfo;
     }];
     stateChange: [{
         from: WholesaleFeedSyncState;

package/docs/README.md

@@ -25,6 +25,12 @@ Use the [buyer quick start](./guides/BUYER-QUICKSTART-3.2.md). For the complete
 tool and type inventory, use [llms.txt](./llms.txt) and the
 [type summary](./TYPE-SUMMARY.md).
 
+## Upgrade from SDK 14.0
+
+Use the [14.0-to-14.1 upgrade checklist](./migration-14.0-to-14.1.md) for
+required changes, opt-in features, and stricter signature verification. SDK
+14.1.0 continues to use AdCP 3.2.1 on the wire.
+
 ## Upgrade from SDK 13
 
 Start with the [release-bound upgrade worksheet](./migration-14.x-rc-worksheet.md),

package/docs/TYPE-SUMMARY.md

@@ -1,7 +1,7 @@
 # AdCP Type Summary
 
-> Generated at: 2026-10-01
-> @adcp/sdk v14.0.0
+> Generated at: 2026-10-05
+> @adcp/sdk v14.2.0
 
 Curated reference of the types that matter for using the AdCP client. For full generated types see `src/lib/types/tools.generated.ts` and `src/lib/types/core.generated.ts`.
 

package/docs/guides/BUILD-AN-AGENT.md

@@ -671,7 +671,7 @@ import {
   requireAuthenticatedOrSigned,
   mcpToolNameResolver,
 } from '@adcp/sdk/server';
-import { BrandJsonJwksResolver } from '@adcp/sdk/signing/server';
+import { ResolvedAgentJwksResolver } from '@adcp/sdk/signing/server';
 
 serve(
   () =>
@@ -692,7 +692,7 @@ serve(
     authenticate: requireAuthenticatedOrSigned({
       signature: verifySignatureAsAuthenticator({
         capability: { supported: true, required_for: ['create_media_buy', 'update_media_buy'], covers_content_digest: 'either' },
-        jwks: new BrandJsonJwksResolver(),
+        jwks: new ResolvedAgentJwksResolver('https://buyer.example/mcp', 'mcp'),
         resolveOperation: mcpToolNameResolver,
       }),
       fallback: verifyApiKey({ keys: { sk_live_abc: { principal: 'acct_42' } } }),

package/docs/guides/BUYER-QUICKSTART-3.2.md

@@ -1,5 +1,7 @@
 # Call a seller with AdCP 3.2
 
+For a new seller, start with [account setup and public discovery](./FIRST-CALL-TO-A-SELLER.md).
+
 For product possibility, accepted change rights, and current execution routes, use the [MediaBuy action assessment helpers](./MEDIA-BUY-ACTION-ASSESSMENT.md).
 
 Requires Node.js `^20.19.0 || >=22.12.0`. Install SDK 14

package/docs/guides/BUYER-STORAGE.md

@@ -0,0 +1,3 @@
+# Buyer-owned storage and scheduling
+
+See the [adapter contracts and recovery guide](https://github.com/adcontextprotocol/adcp-client/blob/main/docs/development/BUYER-STORAGE.md) for timer-free catalog mirrors, CAS provisioning, dispatch hooks, and caller-owned replay keys.

package/docs/guides/FIRST-CALL-TO-A-SELLER.md

@@ -0,0 +1,106 @@
+# First call to a seller
+
+An account reference selects a provisioned account at that seller. Discovery
+does not provision it. Until setup is complete, send a top-level `brand` on
+tools that support public discovery, and omit `account`.
+
+```ts
+import { AgentClient, createProductCache } from '@adcp/sdk';
+
+const client = new AgentClient(sellerConfig, {
+  accountPolicy: 'auto',
+  productCache: createProductCache({ publicTtl: 60_000, accountTtl: 30_000 }),
+});
+const capabilities = await client.getCapabilities();
+const brand = { domain: 'advertiser.example' };
+const account = { brand, operator: 'agency.example' };
+
+// Only use public discovery when the seller permits it.
+if (!capabilities.account?.requiredForProducts) {
+  const publicCatalog = await client.getProducts({ brand, brief: 'Display inventory' });
+  if (!publicCatalog.success) console.error(publicCatalog.adcpError);
+}
+
+// Choose billing terms before accepting them. This returns seller status and handle.
+const setup = await client.accounts.ensure(account, {
+  billing: 'operator',
+  paymentTerms: 'net_30',
+});
+if (setup.status === 'active') {
+  const pricedCatalog = await client.getProducts({ account, brand, brief: 'Display inventory' });
+  if (!pricedCatalog.success) console.error(pricedCatalog.adcpError);
+}
+```
+
+For agent-billed provisioning, pass `billingEntity` with the seller's required
+business identity. `paymentTerms` and `billingEntity` are also accepted by
+`resolveAccount()`. That helper keeps its existing pending-approval exception;
+`accounts.ensure()` returns the status so callers can present the setup flow.
+Non-active entries refresh through `list_accounts` when a seller handle is known.
+An existing registry entry prevents repeated provisioning and silent acceptance
+of new terms. To change terms, explicitly call `syncAccounts()`.
+An explicit `ensure` with conflicting known setup terms refuses the change.
+If the seller no longer lists an account, explicitly reestablish it with
+`syncAccounts` after choosing terms; status repair never silently re-provisions it.
+Caller cancellation stops waiting for setup; the single seller operation continues
+so another caller cannot accidentally accept different terms concurrently.
+Terminal setup failures permit an explicit retry. For interrupted async setup,
+read `accounts.get(key).pendingTaskId`, reconcile that seller task, and pass its
+completed rows to `accounts.observeSync([key], rows)` (or let the original
+`syncAccounts` completion handle update the registry). Do not resubmit unresolved tasks.
+
+For a seller that requires operator authentication, use `resolveAccount()` to
+select an active account returned by `list_accounts`. An account ID echoed by
+`sync_accounts` is a seller handle; implicit sellers still require the natural
+key on subsequent calls. Do not replace it with `{ account_id }` automatically.
+
+`accountPolicy` defaults to `'off'` to preserve existing requests. Opt-in
+`'auto'` omits unknown accounts on public discovery tools that support `brand`;
+it refuses required-account discovery, async discovery, and mutations until
+the registry knows the key. `'strict'` refuses every unknown account-carrying
+request. Both policies require an active account before spend commitments.
+Explicit account filters on `list_accounts` remain filters.
+Call `listAccounts` first when adopting these policies with existing opaque
+account IDs so the registry knows those seller handles.
+
+Provisioning is remembered per seller and caller. `syncAccounts()` and
+`listAccounts()` update the registry on completed results; failed rows and dry
+runs do not establish accounts. After verifying an `account.status_changed`
+notification, call `client.accounts.applyStatusChange({ account_id })` to repair
+from authoritative `list_accounts`. The notification's status is not trusted as
+a snapshot, which avoids reordered deliveries overwriting current state.
+
+The registry is in memory by default. Set `accountStorage` to an adapter with
+`get(key)` and `set(key, entry)` for persistence. For multiple processes, add
+revision-checked `compareAndSet` writes and dispatch ledger hooks; see
+[buyer storage and scheduling](BUYER-STORAGE.md). Keys partition by seller URI,
+protocol, and caller scope. Client-credentials OAuth uses the stable client ID, token endpoint, scopes, and resource. Authorization-code OAuth pins this client's initial grant fingerprint, keeping distinct user grants apart while automatic refreshes preserve its partition. Create a new client when switching users. Other credential modes fingerprint credentials;
+for continuity across token rotations, supply `accountRegistryScope` from a
+trusted stable principal identifier. Never share that scope between tenants.
+Request-signing key identity is also part of the default fingerprint, so distinct
+signers stay isolated. Key rotation requires reprovisioning or a trusted stable
+`accountRegistryScope` for the same principal.
+Registry memory and aliases per handle are bounded by `accountRegistryMaxEntries` (default 10,000); durable adapters allow entry eviction and reload. Without storage, reaching capacity throws a setup error; raise the limit or configure storage for large rosters. `resolveAccount()` uses the memoized registry only when you opt in with `accountPolicy: 'auto' | 'strict'`, `accountStorage`, `accountRegistryScope`, or `accountRegistryMaxEntries`; that internal use does not enable observations of unrelated rosters. Otherwise it keeps the 14.0 behavior: every call sends `sync_accounts` and reflects the seller's current status. Memoized entries require explicit `syncAccounts()` or authoritative status repair when seller linkage expires or is replaced externally. Stored entries contain account references, seller handles, status, optional pending task IDs, and hashes of explicitly chosen setup terms;
+billing entities and tokens are not persisted. Manual feed mode recovers through
+an explicit `refresh()`; auto-poll mode also retries initial failures.
+
+Typed `AccountNotFoundError`, `AccountSetupRequiredError`, and
+`AccountPaymentRequiredError` carry `fault: 'buyer_setup'`. Health trackers
+should exclude them from seller-health failure counts. Failed task results still
+expose the protocol code in `result.adcpError` and the typed exception in
+`result.errorInstance`.
+
+The optional product cache uses TTLs in milliseconds and keeps at most `maxEntries` entries (default 1,000). It keeps public and
+account-scoped responses apart and stores the feed version and pricing version
+with each snapshot. Missing `cache_scope` prevents caching. Stale entries are
+conditionally revalidated using their own tokens; failures remain visible to
+the caller and never erase the last valid entry. Caller-authored feed or pricing validators
+retain their unchanged-response semantics. Caches are scoped to the client
+instance so different local verification policies cannot share filtered results.
+
+`WholesaleFeedSync` similarly keeps its last good product and signal mirrors on
+a failed refresh. Its error event includes `adcpError`; a mirror becomes
+`degraded` until a successful refresh restores `syncing`. Initial failure sets
+`error`. Exhaustive state switches must handle the new `degraded` member.
+
+Manual `WholesaleFeedSync.refresh()` and webhook repairs reject failed catalog reads, including failed task results. A failed webhook repair remains eligible for redelivery; acknowledge it only after repair succeeds. Bootstrap `start()` still reports failed task results through its state and error callback/event, and schedules recovery in auto-poll mode.

package/docs/guides/SIGNING-GUIDE.md

@@ -53,7 +53,7 @@ Your domain (e.g., agent.example.com)
         -> /.well-known/jwks.json      # JSON Web Key Set with public keys
 ```
 
-`@adcp/sdk` provides `BrandJsonJwksResolver` which handles this entire chain automatically, with caching and refresh.
+`@adcp/sdk` provides `ResolvedAgentJwksResolver` which handles this entire chain automatically, with caching and refresh.
 
 ## Step 1: Generate a Signing Key
 
@@ -214,6 +214,12 @@ const signingFetch = buildAgentSigningFetch({
 });
 ```
 
+### Diagnosing a seller's rejection of a signed request
+
+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`.
+
 ## Step 3.5: Production Key Storage — KMS / HSM / Vault
 
 Holding a private JWK in process memory is fine for development and testing but it's not where you want production signing keys to live. A process compromise leaks the signing key, and the only remedy is rotation across every counterparty that's cached your public key (within their TTL). The AdCP spec recommends storing keys in a managed key store (HSM or KMS); the SDK supports this directly via the `SigningProvider` interface.
@@ -429,13 +435,13 @@ import {
   requireAuthenticatedOrSigned,
   mcpToolNameResolver,
 } from '@adcp/sdk/server';
-import { BrandJsonJwksResolver } from '@adcp/sdk/signing/server';
+import { ResolvedAgentJwksResolver } from '@adcp/sdk/signing/server';
 
 serve(createAgent, {
   authenticate: requireAuthenticatedOrSigned({
     signature: verifySignatureAsAuthenticator({
       capability: { supported: true, required_for: ['create_media_buy'], covers_content_digest: 'either' },
-      jwks: new BrandJsonJwksResolver(),
+      jwks: new ResolvedAgentJwksResolver(expectedBuyerAgentUrl, 'mcp'),
       resolveOperation: mcpToolNameResolver,
     }),
     fallback: verifyApiKey({ keys: { 'sk_live_abc': { principal: 'acct_42' } } }),
@@ -453,7 +459,8 @@ Set `requiredFor` to the AdCP operations you want to gate behind signatures —
 |---|---|
 | `StaticJwksResolver` | Fixed set of known buyer keys. Good for dev/testing. |
 | `HttpsJwksResolver` | Fetches JWKS from a URL with caching and refresh. |
-| `BrandJsonJwksResolver` | Full discovery chain: brand.json -> jwks_uri -> JWKS. Production recommended. |
+| `ResolvedAgentJwksResolver` | Capability-bound discovery from an expected agent URL. Production recommended. |
+| `BrandJsonJwksResolver` | Confirms an operator mapping against capabilities; accepts an explicit `agentUrl` or infers a unique onboarding URL from existing configuration. |
 
 ## Step 5: Verify Inbound Webhooks (Buyer / Orchestrator)
 
@@ -462,16 +469,18 @@ When sellers send webhooks, verify the signature to confirm authenticity:
 ```typescript
 import {
   verifyWebhookSignature,
-  BrandJsonJwksResolver,
+  ResolvedAgentJwksResolver,
   InMemoryReplayStore,
+  InMemoryRevocationStore,
 } from '@adcp/sdk/signing/server';
 
-const jwks = new BrandJsonJwksResolver();
+const jwks = new ResolvedAgentJwksResolver(expectedSellerAgentUrl, 'mcp', { legacyWebhookFallback: true });
 const replayStore = new InMemoryReplayStore();
+const revocationStore = new InMemoryRevocationStore();
 
 app.post('/webhook', async (req, res) => {
   try {
-    await verifyWebhookSignature(req, { jwks, replayStore });
+    await verifyWebhookSignature(req, { jwks, replayStore, revocationStore });
   } catch (err) {
     return res.status(401).json({ error: 'invalid webhook signature' });
   }

package/docs/guides/account-resolution.md

@@ -24,6 +24,94 @@ accounts: {
 }
 ```
 
+For buyer setup and opt-in lifecycle management, see
+[First call to a seller](./FIRST-CALL-TO-A-SELLER.md).
+For upgrading an existing integration, use the
+[14.0-to-14.1 checklist](../migration-14.0-to-14.1.md).
+
+Account resolvers receive `ctx.provisioning`. It is false on discovery and
+negotiation (`get_products`, `list_products`, `get_signals`, and proposal
+request/refine/decline); these tasks MUST use lookup only. It is true on spend
+commitments, `activate_signal`, and `sync_*` tasks. Lazy provisioning must be
+explicitly gated:
+
+```ts
+resolve: async (ref, ctx) => {
+  const existing = await db.findAuthorizedAccount(ref, ctx?.authInfo);
+  if (existing || !ctx?.provisioning) return existing;
+  return await db.createAuthorizedAccount(ref, ctx?.authInfo);
+},
+```
+
+When `resolveAccount` is configured, a supplied unknown reference returns
+`ACCOUNT_NOT_FOUND`, even on optional account tools.
+
+### Strict account references (`strictAccountReferences`)
+
+SDK 14 keeps four compatibility behaviors that strict mode removes:
+
+- A buyer-supplied `account` still reaches a raw handler-bag seller that has
+  no reference-aware `resolveAccount`: the handler sees `params.account` and
+  `ctx.account` is undefined. An auth-only `resolveAccountFromAuth` does not
+  authorize an arbitrary reference.
+- A seller that declares `capabilities.account.requiredForProducts` still
+  serves `get_products` when the request carries no account and
+  authentication resolves none.
+- `list_accounts.account` is resolved through `resolveAccount` as the
+  request's account (an unknown or unauthorized filter returns
+  `ACCOUNT_NOT_FOUND`). Strict mode treats it as a filter instead.
+- On `createAdcpServerFromPlatform` with `resolution: 'implicit'`, an account
+  whose returned identity metadata disagrees with the supplied natural key is
+  still used.
+
+Each logs a deprecation warning once per process per warning code (through
+`logger.warn`, plus `process.emitWarning` outside `NODE_ENV=production`);
+later occurrences log at debug level. Codes:
+`ADCP_UNRESOLVED_ACCOUNT_REFERENCE`, `ADCP_REQUIRED_FOR_PRODUCTS_NOT_ENFORCED`,
+`ADCP_LIST_ACCOUNTS_FILTER_RESOLVED`, and
+`ADCP_IMPLICIT_ACCOUNT_IDENTITY_MISMATCH`.
+
+**Strict mode becomes the default in the next major release.** Opt in now:
+
+```ts
+createAdcpServer({
+  name: 'Seller',
+  version: '1.0.0',
+  strictAccountReferences: true,
+  resolveAccount: (ref, ctx) => authorizedAccounts.find(ref, ctx.authInfo),
+  mediaBuy: {
+    getProducts: (params, ctx) => catalog.forAccount(ctx.account, params),
+  },
+});
+```
+
+With `strictAccountReferences: true`:
+
+- A supplied reference on a server without `resolveAccount` fails with
+  `ACCOUNT_NOT_FOUND` before the handler runs.
+- A `requiredForProducts` seller refuses account-less `get_products` with
+  `ACCOUNT_REQUIRED`.
+- `list_accounts.account` is a filter: `resolveAccount` is not called for it
+  and `ctx.account` comes from `resolveAccountFromAuth`.
+- An implicit-mode account whose returned identity metadata (`brand`,
+  `operator`, `operator_unit`, `currency`, `timezone`, `sandbox`) disagrees
+  with the supplied natural key is refused with `ACCOUNT_NOT_FOUND`. Fields
+  your store does not return are not compared.
+
+Migration for handler-bag sellers: move account authorization out of
+individual handlers and into `resolveAccount`, then set the flag.
+`authorizedAccounts.find` must return null on an unknown reference or a
+reference owned by another principal. Public discovery may omit `account`;
+resource creation and spend commitments need an authorized account. Implicit
+stores should resolve by the complete natural key and return identity
+metadata that echoes it, or omit the metadata.
+
+`InMemoryImplicitAccountStore` matches supplied refs on the complete natural
+key, including operator unit, currency, timezone, and sandbox. It retains its
+24-hour TTL and replacement sync semantics. Set `mergeOnUpsert: true` for
+additive batches and revoke individual refs with `remove(ref, ctx)`; passing
+`delete_missing: true` in `sync_accounts` retains replacement semantics.
+
 **Each mode has exactly one spelling.** `'derived'` keeps its name even
 though [adcp#5062](https://github.com/adcontextprotocol/adcp/pull/5062)
 calls the shape an *upstream-managed account-id namespace*: `resolution` is
@@ -47,29 +135,53 @@ construction, not a silent fallback.
 
 ### 1 · How it works
 
-1. Buyer calls `sync_accounts` with `AccountReference[]`.
+1. Buyer calls `sync_accounts` with natural-key provisioning entries.
 2. Framework calls your `accounts.upsert()` — you create/find accounts and
    store the `authPrincipal → accounts` mapping.
-3. Buyer calls any tool (e.g. `create_media_buy`) without `ext.account_ref`.
-4. Framework calls `accounts.resolve(undefined, ctx)` — you look up the
-   account by `ctx.authInfo`.
+3. On subsequent account-scoped calls, the buyer supplies top-level
+   `account: { brand, operator, ... }`. The framework calls
+   `accounts.resolve(ref, ctx)` with that natural key. Look it up within the
+   authenticated caller's synced roster; do not substitute another account.
+4. When a request omits `account`, the framework instead calls
+   `accounts.resolve(undefined, ctx)`. This is a separate auth-derived lookup
+   path. A null result is allowed for account-optional tools and yields
+   `ACCOUNT_REQUIRED` for account-required operations.
+
+Implicit sellers refuse the `{ account_id }` reference arm. A seller handle
+returned by `sync_accounts` does not replace the natural key on later calls.
 
 ### 2 · Key derivation
 
 Extract the principal key from `ctx.authInfo.credential`:
 
 ```ts
-resolve: async (_ref, ctx) => {
+resolve: async (ref, ctx) => {
   const cred = ctx?.authInfo?.credential;
   const key = cred?.kind === 'oauth'    ? `oauth:${cred.client_id}`
             : cred?.kind === 'api_key'  ? `api_key:${cred.key_id}`
             : cred?.kind === 'http_sig' ? `http_sig:${cred.agent_url}`
             : undefined;
   if (!key) return null;
+  if (ref !== undefined) {
+    // Match the full natural key within THIS principal's synced roster.
+    // An unknown or unauthorized ref returns null, without a fallback.
+    return await db.findSyncedAccountByNaturalKey(key, ref);
+  }
+  // Account omitted: use your existing auth-derived selection policy.
   return await db.findAccountByPrincipalKey(key);
 },
 ```
 
+The `db` methods above are operations you implement in your own store.
+`findSyncedAccountByNaturalKey` must compare the complete brand identity
+(domain, optional brand ID and countries), operator, operator-unit ID,
+currency, timezone, and sandbox within the principal's roster. Use consistent
+normalization at sync and lookup, including country ordering and omitted/false
+sandbox. It must not create an account or match on brand/operator alone.
+`findAccountByPrincipalKey` handles only the omitted-reference path according
+to your documented selection policy. The built-in `InMemoryImplicitAccountStore`
+keeps its historical first-account selection for that path.
+
 **Why `credential.client_id`, not `authInfo.sub`?**
 
 `credential.client_id` is the OAuth *client* identity — stable across token
@@ -101,14 +213,24 @@ receiving auth errors will refresh credentials or escalate, not call
 
 ```ts
 // ✓ Correct
-resolve: async (_ref, ctx) => {
-  const account = await db.findByPrincipal(extractKey(ctx?.authInfo));
-  return account ?? null;  // omitted account → ACCOUNT_REQUIRED
+resolve: async (ref, ctx) => {
+  const key = extractKey(ctx?.authInfo);
+  if (!key) return null;
+  const account = ref === undefined
+    ? await db.findAccountByPrincipalKey(key)
+    : await db.findSyncedAccountByNaturalKey(key, ref);
+  // Missing: supplied account → ACCOUNT_NOT_FOUND;
+  // omitted account on an account-required operation → ACCOUNT_REQUIRED.
+  return account ?? null;
 },
 
 // ✗ Wrong — misleads buyers about how to recover
-resolve: async (_ref, ctx) => {
-  const account = await db.findByPrincipal(extractKey(ctx?.authInfo));
+resolve: async (ref, ctx) => {
+  const key = extractKey(ctx?.authInfo);
+  if (!key) return null;
+  const account = ref === undefined
+    ? await db.findAccountByPrincipalKey(key)
+    : await db.findSyncedAccountByNaturalKey(key, ref);
   if (!account) throw new AdcpError('AUTH_MISSING', { message: 'call sync_accounts first' });
   return account;
 },

package/docs/llms.txt

@@ -1,7 +1,7 @@
 # Ad Context Protocol (AdCP)
 
-> Generated at: 2026-10-01
-> Library: @adcp/sdk v14.0.0
+> Generated at: 2026-10-05
+> Library: @adcp/sdk v14.2.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.
@@ -19,6 +19,7 @@ SDK 14 is compact-lifecycle first: `list_products → buy_products → control_m
 
 - **MediaBuy change rights:** use `assessMediaBuyAction` from `@adcp/sdk/media-buy/actions` for possible / promised / available-now assessment, and `mediaBuyActionResolver` from `@adcp/sdk/server` for explicit seller acceptance and current projection. See `docs/guides/MEDIA-BUY-ACTION-ASSESSMENT.md`.
 - **Buyer** (calling a seller): read `docs/guides/BUYER-QUICKSTART-3.2.md` first.
+- **Account setup and first discovery:** read `docs/guides/FIRST-CALL-TO-A-SELLER.md` for the provisioning registry, account policies, billing terms, and product cache.
 - **Buyer Reliable Reporting**: import reconciliation, PostgreSQL persistence, and the worker from `@adcp/sdk/reporting/consumer`; see `docs/guides/REPORTING-RECONCILIATION.md`.
 - **Before proposal acceptance:** use `verifyProposalCommercialTerms` from `@adcp/sdk/negotiation/verification` with a complete, independently reviewed snapshot and the seller-served schema version. Never use an unreviewed candidate as its own expected terms. See `docs/guides/PROPOSAL-TERMS-VERIFICATION.md`.
 - **Seller** (implementing an agent that others call): read `docs/guides/SELLER-QUICKSTART-3.2.md` first, then `docs/guides/BUILD-AN-AGENT.md` for the complete framework surface.

package/docs/migration-14.0-to-14.1.md

@@ -0,0 +1,85 @@
+# Migrating from SDK 14.0 to 14.1
+
+SDK **14.1.0** still uses AdCP **3.2.1** on the wire. Its signature verification
+adopts the AdCP 3.3 agent-resolution algorithm; this does not upgrade your wire
+protocol or require enabling a new media-buy lifecycle.
+
+```sh
+npm install @adcp/sdk@14.1.0
+```
+
+Account policies and strict account references keep their 14.0 defaults. Check
+the applicable rows below before rolling out: some TypeScript types change,
+and signature verification rejects identities or keys it cannot confirm.
+
+## Required changes when applicable
+
+| If your integration… | Change for 14.1 |
+|---|---|
+| Exhaustively switches over `WholesaleFeedSyncState` | Add a `degraded` case. A failed refresh preserves an existing mirror and marks it degraded; an initial failure still sets `error`. |
+| Reads registry refresh fence fields as required values | Handle `undefined` on the deprecated fields in `AgentComplianceDetail.refresh_availability` and the `refreshAgent` 503 response. For example, use `refresh_availability.code ?? 'unknown'` for a local display label. The live registry no longer returns these fields; removal from SDK types is planned for the next major release. |
+| Uses a standalone `BrandJsonJwksResolver` with A2A | Set `protocol: 'a2a'`. Capability discovery defaults to MCP; the onboarding record does not select the transport. |
+| Supplies a natural-key account reference to an implicit seller | Resolve the complete key within the authenticated caller's synced roster. Include brand identity, operator, operator unit, currency, timezone, and sandbox. An unknown supplied reference must return `null`, never fall back to another account. See [account resolution](./guides/account-resolution.md#implicit-deep-dive). |
+| Stores non-canonical issuer URLs in governance principal, replay, or revocation indexes | Migrate those keys to the canonical issuer identity before switching verification. Preserve replay and revocation history; use the [signature migration guide](./migration-agent-resolution-3.3.md) to check normalization rules. |
+| Configures JWKS or operator discovery cache limits | Review the bounds in the [signature migration guide](./migration-agent-resolution-3.3.md). Brand discovery requires positive `maxAgeSeconds`; non-finite or negative cache options fail configuration validation. Expired mappings and keys are refused rather than reused. |
+| Repairs wholesale mirrors from webhook deliveries | Acknowledge only after `refresh()` or repair succeeds. Failed catalog reads now reject, preserving the mirror and leaving the delivery eligible for retry. |
+
+For the complete list of newly optional registry fields, see the
+[14.1.0 changelog](https://github.com/adcontextprotocol/adcp-client/blob/main/CHANGELOG.md#1410).
+
+## Security behavior to verify
+
+Existing resolver constructor signatures remain supported, but accepting a key
+now requires a confirmed canonical agent identity and the capabilities-selected
+operator record. Ambiguous onboarding and unconfirmed cross-domain mappings
+fail closed. Prefer supplying the expected `agentUrl` already recorded by your
+integration.
+
+Publisher-pinned webhook keys must also appear in the agent JWKS as the same
+public key. Resolve pins from your persisted registration and media-buy record
+for every affected publisher, rather than selecting publishers from the webhook
+payload. Refresh callbacks must throw on fetch failure; `null` confirms removal
+of a pin. Follow the [publisher-pin migration guidance](./migration-agent-resolution-3.3.md#publisher-pin-context).
+
+`SingleAgentClient` and `BrandJsonJwksResolver` retain legacy 3.x webhook
+fallback by default. A standalone `ResolvedAgentJwksResolver` requires explicit
+opt-in. That fallback does not authorize request signatures.
+
+Signed MCP and A2A HTTP 401 errors now retain signature diagnostics and repair
+guidance. Explicit Signature-challenge rejections skip unsigned authentication
+probes and credential refresh retries. Bare signed 401s retain the existing
+single client-credentials refresh attempt.
+
+## Optional adoption
+
+| Feature | Default and adoption path |
+|---|---|
+| Buyer account registry | `accountPolicy` remains `'off'`. Set `'auto'` or `'strict'` to enforce setup, or configure registry storage/scope/capacity to opt into memoized `resolveAccount()`. Without opt-in, that helper still sends `sync_accounts` on each call. See [first call to a seller](./guides/FIRST-CALL-TO-A-SELLER.md). |
+| Product cache | Opt in with `createProductCache`. Public and account-scoped responses stay separate; missing `cache_scope` prevents caching. See [buyer setup and caching](./guides/FIRST-CALL-TO-A-SELLER.md). |
+| Strict seller account references | `strictAccountReferences` remains false; compatibility paths warn. Move reference authorization into `resolveAccount`, then set it to true. It becomes the default in the next major release. See [strict account references](./guides/account-resolution.md#strict-account-references-strictaccountreferences). |
+| Additive implicit account sync | `InMemoryImplicitAccountStore` keeps replacement sync semantics and its 24-hour TTL. Set `mergeOnUpsert: true` for additive batches; `delete_missing: true` still requests replacement. Use `remove(ref, ctx)` for individual revocation. |
+
+Account resolvers now receive `ctx.provisioning`. Discovery and negotiation
+must remain lookup-only; gate any lazy account creation on this flag. The
+[seller account guide](./guides/account-resolution.md) includes an example.
+
+## Check your rollout
+
+- Compile your application to catch the new state and optional registry fields.
+- Exercise signed requests and webhooks against your actual agent/operator
+  records, including key rotation and any publisher pins.
+- Check that supplied unknown or unauthorized account references are refused,
+  and that discovery does not create accounts.
+- If you handle `sync_accounts` results, handle per-account notification
+  event-type failures. In strict request validation, valid siblings can proceed;
+  with `delete_missing: true`, the invalid batch is refused before writes.
+  Warn-mode validation remains advisory, as in 14.0.
+- Exercise failed feed refreshes and webhook redelivery without losing the last
+  good mirror.
+
+The published 14.1.0 artifact passed reporting core **4/4** and full lifecycle
+**4/4** qualification, with integrity and provenance verified. This covers
+Python producers and TypeScript consumers. It does not establish reverse-direction
+parity or Python version-skew coverage; broader work remains in
+[#3027](https://github.com/adcontextprotocol/adcp-client/issues/3027).
+See the [published release and qualification evidence](https://github.com/adcontextprotocol/adcp-client/releases/tag/%40adcp/sdk%4014.1.0).

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

@@ -11,8 +11,8 @@ below as the publication/deployment gate.
 
 | Fact | Value |
 | --- | --- |
-| Exact npm package | `@adcp/sdk@14.0.0` |
-| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@14.0.0 dist.integrity` |
+| Exact npm package | `@adcp/sdk@14.2.0` |
+| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@14.2.0 dist.integrity` |
 | Node.js runtime | `^20.19.0 || >=22.12.0` |
 | Default AdCP wire release | `3.2.1` |
 | 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.2.1`, `3.2` |
@@ -21,8 +21,8 @@ below as the publication/deployment gate.
 Install exact production inputs rather than a moving range or dist-tag:
 
 ```bash
-npm install --save-exact '@adcp/sdk@14.0.0'
-npm view '@adcp/sdk@14.0.0' dist.integrity
+npm install --save-exact '@adcp/sdk@14.2.0'
+npm view '@adcp/sdk@14.2.0' dist.integrity
 ```
 
 ### Required and optional peers

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

@@ -450,6 +450,7 @@ import {
 } from '@adcp/sdk/signing/server';
 
 const jwks = new BrandJsonJwksResolver('https://publisher.example/.well-known/brand.json', {
+  agentUrl: 'https://publisher.example/mcp',
   agentType: 'sales',
 });