@adcp/sdk 14.0.0-beta.14 → 14.0.0-beta.15

package/dist/lib/testing/storyboard/oauth-metadata-graph/grader.mjs

@@ -1,5 +1,13 @@
 import { isAlwaysBlocked, isPrivateIp } from "../../../net/address-guards.mjs";
 import { ssrfSafeFetch, SsrfRefusedError } from "../../../net/ssrf-fetch.mjs";
+import {
+  buildProtectedResourceMetadataUrl,
+  normalizeOAuthResourceForComparison
+} from "../../../auth/oauth/resource-url.mjs";
+import {
+  buildProtectedResourceMetadataUrl as buildProtectedResourceMetadataUrl2,
+  normalizeOAuthResourceForComparison as normalizeOAuthResourceForComparison2
+} from "../../../auth/oauth/resource-url.mjs";
 const LIMITS = Object.freeze({
   authorizationServers: 16,
   uniqueUrls: 64,
@@ -24,40 +32,6 @@ const DIAGNOSTIC_ORDER = Object.freeze([
   "oauth_endpoint_unreachable",
   "oauth_jwks_unavailable"
 ]);
-function normalizeOAuthResourceForComparison(value) {
-  const match = /^([A-Za-z][A-Za-z\d+.-]*):\/\/([^/?#]*)([\s\S]*)$/.exec(value);
-  if (!match) return value;
-  const scheme = match[1].toLowerCase();
-  const authority = match[2];
-  const remainder = match[3];
-  const at = authority.lastIndexOf("@");
-  const userinfo = at >= 0 ? authority.slice(0, at + 1) : "";
-  const hostAndPort = at >= 0 ? authority.slice(at + 1) : authority;
-  let host;
-  let port = "";
-  if (hostAndPort.startsWith("[")) {
-    const bracket = hostAndPort.indexOf("]");
-    if (bracket < 0) return value;
-    host = hostAndPort.slice(0, bracket + 1).toLowerCase();
-    const suffix = hostAndPort.slice(bracket + 1);
-    if (suffix && !/^:\d+$/.test(suffix)) return value;
-    port = suffix.slice(1);
-  } else {
-    const colon = hostAndPort.lastIndexOf(":");
-    if (colon >= 0) {
-      const suffix = hostAndPort.slice(colon + 1);
-      if (!/^\d+$/.test(suffix)) return value;
-      host = hostAndPort.slice(0, colon).toLowerCase();
-      port = suffix;
-    } else {
-      host = hostAndPort.toLowerCase();
-    }
-  }
-  if (!host) return value;
-  const defaultPort = scheme === "https" ? "443" : scheme === "http" ? "80" : void 0;
-  const renderedPort = port && port !== defaultPort ? `:${port}` : "";
-  return `${scheme}://${userinfo}${host}${renderedPort}${remainder}`;
-}
 function redactOAuthUrlForOutput(value) {
   try {
     const u = new URL(value);
@@ -75,10 +49,6 @@ function redactOAuthUrlForOutput(value) {
 function redactOAuthUrlsInText(value) {
   return value.replace(/https?:\/\/[^\s"'<>]+/gi, (url) => redactOAuthUrlForOutput(url));
 }
-function buildProtectedResourceMetadataUrl(agentUrl) {
-  const u = new URL(agentUrl);
-  return `${u.origin}/.well-known/oauth-protected-resource${u.pathname}`;
-}
 function buildAuthorizationServerMetadataUrl(issuer) {
   const u = new URL(issuer);
   const issuerPath = u.pathname === "/" ? "" : u.pathname;
@@ -103,7 +73,7 @@ async function gradeOAuthMetadataGraphWithTransport(agentUrl, options = {}) {
   const findings = [];
   let protectedResourceUrl;
   try {
-    protectedResourceUrl = buildProtectedResourceMetadataUrl(agentUrl);
+    protectedResourceUrl = buildProtectedResourceMetadataUrl2(agentUrl);
   } catch {
     protectedResourceUrl = redactOAuthUrlForOutput(agentUrl);
     findings.push(finding("oauth_protected_resource_metadata_invalid", "Agent URL is not an absolute URL."));
@@ -148,7 +118,7 @@ async function gradeOAuthMetadataGraphWithTransport(agentUrl, options = {}) {
         "resource"
       )
     );
-  } else if (normalizeOAuthResourceForComparison(resource) !== normalizeOAuthResourceForComparison(agentUrl)) {
+  } else if (normalizeOAuthResourceForComparison2(resource) !== normalizeOAuthResourceForComparison2(agentUrl)) {
     findings.push(
       finding(
         "oauth_resource_mismatch",

package/dist/lib/testing/storyboard/validations.d.mts

@@ -197,7 +197,7 @@ export interface UpstreamTrafficQueryResult {
  */
 export declare function runValidations(validations: StoryboardValidation[], context: ValidationContext): ValidationResult[];
 /** Capability semver emitted in run summaries and used for advisory expiry. */
-export declare const RUNNER_CAPABILITY_VERSION = "14.0.0-beta.14";
+export declare const RUNNER_CAPABILITY_VERSION = "14.0.0-beta.15";
 /** True when a failed validation contributes to the owning step's grade. */
 export declare function validationFailsStep(result: ValidationResult): boolean;
 /**

package/dist/lib/testing/storyboard/validations.d.ts

@@ -197,7 +197,7 @@ export interface UpstreamTrafficQueryResult {
  */
 export declare function runValidations(validations: StoryboardValidation[], context: ValidationContext): ValidationResult[];
 /** Capability semver emitted in run summaries and used for advisory expiry. */
-export declare const RUNNER_CAPABILITY_VERSION = "14.0.0-beta.14";
+export declare const RUNNER_CAPABILITY_VERSION = "14.0.0-beta.15";
 /** True when a failed validation contributes to the owning step's grade. */
 export declare function validationFailsStep(result: ValidationResult): boolean;
 /**

package/dist/lib/utils/adcp-version-config.d.mts

@@ -1,5 +1,7 @@
 /** Compare full-semver and release-precision AdCP identifiers safely. */
 export declare function isAdcpVersionAtLeast(version: string | undefined, minimum: string): boolean;
+/** Whether an AdCP identifier is a parseable full or release-precision semver. */
+export declare function isValidAdcpVersion(version: string | undefined): version is string;
 /**
  * Resolve and validate a configured `adcpVersion`. Returns the value to store
  * on the instance — either the caller's pin or the SDK default.

package/dist/lib/utils/adcp-version-config.d.ts

@@ -1,5 +1,7 @@
 /** Compare full-semver and release-precision AdCP identifiers safely. */
 export declare function isAdcpVersionAtLeast(version: string | undefined, minimum: string): boolean;
+/** Whether an AdCP identifier is a parseable full or release-precision semver. */
+export declare function isValidAdcpVersion(version: string | undefined): version is string;
 /**
  * Resolve and validate a configured `adcpVersion`. Returns the value to store
  * on the instance — either the caller's pin or the SDK default.

package/dist/lib/utils/adcp-version-config.js

@@ -24,6 +24,7 @@ __export(adcp_version_config_exports, {
   isMovingAdcpPrereleaseFamilyAlias: () => isMovingAdcpPrereleaseFamilyAlias,
   isPre31AdcpVersion: () => isPre31AdcpVersion,
   isPre32AdcpVersion: () => isPre32AdcpVersion,
+  isValidAdcpVersion: () => isValidAdcpVersion,
   listBundledAdcpVersions: () => listBundledAdcpVersions,
   omit31BrandFields: () => omit31BrandFields,
   resolveAdcpVersion: () => resolveAdcpVersion,
@@ -47,6 +48,9 @@ function isAdcpVersionAtLeast(version, minimum) {
   const comparableMinimum = comparableAdcpSemver(minimum);
   return comparable !== void 0 && comparableMinimum !== void 0 && (0, import_semver.gte)(comparable, comparableMinimum);
 }
+function isValidAdcpVersion(version) {
+  return version !== void 0 && comparableAdcpSemver(version) !== void 0;
+}
 function resolveAdcpVersion(adcpVersion) {
   if (adcpVersion === void 0) return import_version.ADCP_VERSION;
   const currentReleasePrecision = (0, import_schema_loader.toReleasePrecisionWire)(import_version.ADCP_VERSION);
@@ -174,6 +178,7 @@ function listBundledAdcpVersions() {
   isMovingAdcpPrereleaseFamilyAlias,
   isPre31AdcpVersion,
   isPre32AdcpVersion,
+  isValidAdcpVersion,
   listBundledAdcpVersions,
   omit31BrandFields,
   resolveAdcpVersion,

package/dist/lib/utils/adcp-version-config.mjs

@@ -14,6 +14,9 @@ function isAdcpVersionAtLeast(version, minimum) {
   const comparableMinimum = comparableAdcpSemver(minimum);
   return comparable !== void 0 && comparableMinimum !== void 0 && semverGte(comparable, comparableMinimum);
 }
+function isValidAdcpVersion(version) {
+  return version !== void 0 && comparableAdcpSemver(version) !== void 0;
+}
 function resolveAdcpVersion(adcpVersion) {
   if (adcpVersion === void 0) return ADCP_VERSION;
   const currentReleasePrecision = toReleasePrecisionWire(ADCP_VERSION);
@@ -140,6 +143,7 @@ export {
   isMovingAdcpPrereleaseFamilyAlias,
   isPre31AdcpVersion,
   isPre32AdcpVersion,
+  isValidAdcpVersion,
   listBundledAdcpVersions,
   omit31BrandFields,
   resolveAdcpVersion,

package/dist/lib/version.d.mts

@@ -1,7 +1,7 @@
 /**
  * AdCP SDK library version
  */
-export declare const LIBRARY_VERSION = "14.0.0-beta.14";
+export declare const LIBRARY_VERSION = "14.0.0-beta.15";
 /**
  * AdCP specification version this library is built for
  */
@@ -33,10 +33,10 @@ export type AdcpVersion = (typeof COMPATIBLE_ADCP_VERSIONS)[number];
  * Full version information
  */
 export declare const VERSION_INFO: {
-    readonly library: "14.0.0-beta.14";
+    readonly library: "14.0.0-beta.15";
     readonly adcp: "3.2.0-beta.8";
     readonly compatibleVersions: readonly ["v2.5", "v2.6", "v3", "3.0.0-beta.1", "3.0-beta.1", "3.0-beta", "3.0.0-beta.3", "3.0-beta.3", "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.2.0-beta.8", "3.2-beta.8"];
-    readonly generatedAt: "2026-08-28T11:11:52.288Z";
+    readonly generatedAt: "2026-08-28T20:29:38.378Z";
 };
 /**
  * Get the AdCP specification version this library is built for

package/dist/lib/version.d.ts

@@ -1,7 +1,7 @@
 /**
  * AdCP SDK library version
  */
-export declare const LIBRARY_VERSION = "14.0.0-beta.14";
+export declare const LIBRARY_VERSION = "14.0.0-beta.15";
 /**
  * AdCP specification version this library is built for
  */
@@ -33,10 +33,10 @@ export type AdcpVersion = (typeof COMPATIBLE_ADCP_VERSIONS)[number];
  * Full version information
  */
 export declare const VERSION_INFO: {
-    readonly library: "14.0.0-beta.14";
+    readonly library: "14.0.0-beta.15";
     readonly adcp: "3.2.0-beta.8";
     readonly compatibleVersions: readonly ["v2.5", "v2.6", "v3", "3.0.0-beta.1", "3.0-beta.1", "3.0-beta", "3.0.0-beta.3", "3.0-beta.3", "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.2.0-beta.8", "3.2-beta.8"];
-    readonly generatedAt: "2026-08-28T11:11:52.288Z";
+    readonly generatedAt: "2026-08-28T20:29:38.378Z";
 };
 /**
  * Get the AdCP specification version this library is built for

package/dist/lib/version.js

@@ -31,7 +31,7 @@ __export(version_exports, {
   toReleasePrecisionVersion: () => toReleasePrecisionVersion
 });
 module.exports = __toCommonJS(version_exports);
-const LIBRARY_VERSION = "14.0.0-beta.14";
+const LIBRARY_VERSION = "14.0.0-beta.15";
 const ADCP_VERSION = "3.2.0-beta.8";
 const ADCP_MAJOR_VERSION = 3;
 const COMPATIBLE_ADCP_VERSIONS = [
@@ -94,10 +94,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
   "3.2-beta.8"
 ];
 const VERSION_INFO = {
-  library: "14.0.0-beta.14",
+  library: "14.0.0-beta.15",
   adcp: "3.2.0-beta.8",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-08-28T11:11:52.288Z"
+  generatedAt: "2026-08-28T20:29:38.378Z"
 };
 function getAdcpVersion() {
   return ADCP_VERSION;

package/dist/lib/version.mjs

@@ -1,4 +1,4 @@
-const LIBRARY_VERSION = "14.0.0-beta.14";
+const LIBRARY_VERSION = "14.0.0-beta.15";
 const ADCP_VERSION = "3.2.0-beta.8";
 const ADCP_MAJOR_VERSION = 3;
 const COMPATIBLE_ADCP_VERSIONS = [
@@ -61,10 +61,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
   "3.2-beta.8"
 ];
 const VERSION_INFO = {
-  library: "14.0.0-beta.14",
+  library: "14.0.0-beta.15",
   adcp: "3.2.0-beta.8",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-08-28T11:11:52.288Z"
+  generatedAt: "2026-08-28T20:29:38.378Z"
 };
 function getAdcpVersion() {
   return ADCP_VERSION;

package/docs/llms.txt

@@ -1,7 +1,7 @@
 # Ad Context Protocol (AdCP)
 
 > Generated at: 2026-08-28
-> Library: @adcp/sdk v14.0.0-beta.14
+> Library: @adcp/sdk v14.0.0-beta.15
 > 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.
@@ -1848,8 +1848,10 @@ See docs/TYPE-SUMMARY.md for field-level detail. Key types at a glance:
 | `GovernanceConfig` | Buyer-side governance middleware config |
 | `EstablishedProposalStore` | Durable 3.0/3.1 proposal snapshots, atomic mutation fences, seven-day completion proofs, pruning, and submitted-task reconciliation |
 | `WebhooksConfig.tenantScope` | Explicit trusted webhook namespace for a genuinely single-tenant server; multi-tenant servers derive scope per request |
+| `PostgresTaskSettlementCoordinator` | Atomically commits a push task terminal state and PostgreSQL recovery-outbox checkpoint for different-process workers |
 
 Production webhook publishers may construct an unbound emitter and call `forTenantScope(trustedTenant)` before every delivery. Direct unbound `emit()` fails before checkpointing or network access. `createAdcpServer` derives scope from trusted request context; configure `webhooks.tenantScope` only for a genuinely single-tenant factory.
+Push-enabled decisioning tasks settled by another process must return `ctx.handoffToTask(producer, { settlement: 'external' })`; the framework withholds `submitted` until the producer durably queues the complete scoped handle and encrypted route. Workers use `createPostgresTaskSettlementCoordinator()` with `completeScopedPushTask()` / `failScopedPushTask()`; the task mutation and encrypted recovery outbox checkpoint commit together. Acknowledge work only for `applied` or compatible `already_terminal`; retry or dead-letter scope misses and conflicts.
 
 ## Task Statuses
 

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

@@ -90,10 +90,11 @@ OAuth flow handlers must preserve `state`, verify callback binding, and pass an
 
 Cross-origin signing-key discovery now requires a schema-shaped, active
 `authorized_operators[]` grant. Broad grants use `brands: ['*']`, omitted
-scopes (or `['all']`), and omitted countries. For narrower grants, configure
-the matching trusted `requiredOperatorBrand`, `requiredOperatorScope`, and/or
-`requiredOperatorCountry` under `webhookVerification.resolverOptions` (or the
-corresponding low-level resolver options); constrained dimensions fail closed
+scopes (or `['all']`), and omitted countries. For narrower grants, pass
+`TaskOptions.delegatedOperatorAuthorization` per dispatch, or configure the
+matching trusted client-wide `requiredOperatorBrand`, `requiredOperatorScope`,
+and/or `requiredOperatorCountry` fallback under
+`webhookVerification.resolverOptions`. Constrained dimensions fail closed
 without context. Cached delegated keys expire no later than `valid_until`. See
 [the 13→14 migration detail](migration-13-to-14.md#cross-origin-signing-key-delegation).
 
@@ -103,7 +104,7 @@ without context. Cached delegated keys expire no later than `valid_until`. See
 - Add `zip`, `published_post`, `card`, `pixel_tracker`, `vast_tracker`, and `daast_tracker` to exhaustive `AssetInstance` handling.
 - Read canonical compliance scenarios from `ComplianceResult.tracks`; `tested_tracks` contains compact reference entries.
 - `createAdcpServerFromPlatform()` never emits a task webhook for an inline terminal result. The deprecated `autoEmitCompletionWebhooks` option is ignored under AdCP 3.2.
-- Rename raw platform hooks to explicit forms such as `buildCreativeLegacy`, `previewCreativeLegacy`, `listCreativeFormatsLegacy`, and the corresponding content-standard and brand-rights names. Canonical AdCP 3.2 previews now use `previewCreative` with `target_capability_id`, `creative_id`, or `creative_manifest`; retain `previewCreativeLegacy` only for `format_id` callers. Custom `WebhookRegistrationStore` implementations must round-trip the optional `previewMode` field so callback routing survives restarts.
+- Rename raw platform hooks to explicit forms such as `buildCreativeLegacy`, `previewCreativeLegacy`, `listCreativeFormatsLegacy`, and the corresponding content-standard and brand-rights names. Canonical AdCP 3.2 previews now use `previewCreative` with `target_capability_id`, `creative_id`, or `creative_manifest`; retain `previewCreativeLegacy` only for `format_id` callers. Custom `WebhookRegistrationStore` implementations must round-trip `previewMode`, `authorizationContextVersion`, and `delegatedOperatorAuthorization` so callback routing and delegated authority survive restarts; dispatch now fails closed if an immediate read-back loses the versioned authorization fields, and automatic key discovery rejects pre-upgrade RFC 9421 rows that lack the version marker.
 - Put incrementally migrated raw handler groups under `legacyHandlers`.
 - Replace removed registry hierarchy calls with `lookupBrand()`/`lookupBrands()` and inspect relationship evidence; use `{ fresh: true }` when a live origin check is required.
 - Use `PayloadDigestOptions` for `computePayloadDigestSha256()` rather than the removed bare `RegExp` or `false` overloads.

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

@@ -2,6 +2,12 @@
 
 SDK 14 adopts AdCP `3.2.0-beta.8` while preserving the canonical creative boundary introduced in SDK 13. Most SDK 13 applications can install the beta and continue using the established 3.x tools unchanged; adopt the compact 3.2 lifecycle only after the remote agent advertises it.
 
+Legacy signal-discovery adapters may keep supplying `opts.signals.getSignals`
+(or `legacyHandlers.signals.getSignals`) while declaring the truthful
+`signal-marketplace` or `signal-owned` specialism. That compatibility handler
+now satisfies platform validation without requiring adopters to invent an
+`activate_signal` implementation during an incremental migration.
+
 AdCP 3.2 prereleases are exact protocol pins: beta.6 replaces beta.5 in the
 SDK's compatible-version list rather than extending a rolling 3.2-beta range.
 Beta.1 restored `adcp_major_version` on `buy_products`,
@@ -57,11 +63,35 @@ const client = new SingleAgentClient(agent, {
 });
 ```
 
-These resolver options are trusted client-wide key-discovery policy, not
-per-operation authorization inferred from tool arguments. Use a separate
-client/resolver for each constrained brand, scope, and country tuple; do not
-reuse the example client for operations outside `brand_a` / `media_buying` /
-`GB`.
+These resolver options remain a trusted client-wide fallback for a client that
+uses one tuple. Shared clients can now select and durably persist the trusted
+tuple per dispatch:
+
+```ts
+await client.createMediaBuy(request, undefined, {
+  delegatedOperatorAuthorization: {
+    brand: 'brand_b',
+    scope: 'media_buying',
+    country: 'US',
+  },
+});
+```
+
+The per-call object takes whole-object precedence and is local receiver policy;
+the SDK neither infers it from request fields nor sends it on the wire. Custom
+`WebhookRegistrationStore` implementations must round-trip the versioned
+authorization fields so restart-time verification can revalidate the tuple
+against live `brand.json`, with immediate read-your-writes consistency after
+`putIfAbsent()`. The SDK reads the row back before seller dispatch and fails
+closed if a legacy projection drops either field. Do not persist a prior allow
+decision as authority.
+
+Pre-upgrade RFC 9421 rows without `authorizationContextVersion` cannot be
+safely backfilled from the receiver's current configuration. Automatic key
+discovery rejects them after upgrade; drain them first or re-dispatch the
+operation to create a versioned registration. A caller-supplied
+`webhookVerification.jwks` may support legacy rows only when it independently
+preserves their original trust boundary.
 
 The same options are accepted by `resolveAgent()`, `getAgentJwks()`,
 `createAgentJwksSet()`, and `ResolvedAgentJwksResolver`. A constrained list with
@@ -69,6 +99,8 @@ no corresponding trusted option fails closed. Built-in JWKS caches now expire
 at the earlier of their configured TTL and the accepted delegation's
 `valid_until` boundary. Low-level `getAgentJwks()` callers receive that boundary
 as `operatorAuthorizationValidUntil` and must apply it to any custom cache.
+Webhook verification also rechecks that boundary immediately before accepting a
+delivery and committing its replay nonce.
 
 ### Modern MCP validation errors
 
@@ -152,8 +184,9 @@ loading; keep using `requires_capability` for a singular predicate.
 12. Replace webhook emitter `operation_id` arguments with SDK-local `delivery_id` values and upgrade custom stores to `WebhookDeliveryStore`. One delivery ID binds one canonical payload and key; use a fresh delivery ID for each changed status observation while retaining the AdCP `operation_id` inside the payload.
 13. Ensure custom 3.2 buyers include `push_notification_config.operation_id`, and update A2A integrations to keep the AdCP registration in skill parameters even when native A2A push configuration is also present.
 14. Treat failed/rejected task results as canonical terminal artifacts when `include_result` is requested; do not discard them while preserving only the summary error.
-15. Persist the complete `ScopedTaskRef` for out-of-process task settlement and acknowledge durable queue items only after `applied` or `already_terminal`. Upgrade populated PostgreSQL task registries with the phased [`getDecisioningTaskRegistryScopeV1Upgrade()` runbook](./migration-task-registry-scoping.md#populated-postgresql-upgrade), not application-boot bootstrap DDL.
-16. Upgrade to Node `^20.19.0 || >=22.12.0`, whose two boundaries enable the `require(esm)` support needed by the SDK's CommonJS dependency graph. Node 21 and Node 22.0–22.11 are not supported. Keep Undici 6 for the fully supported configuration, or use the tested best-effort Undici 7 override on Node 20.19+. See the [Node/Undici compatibility policy](./guides/NODE-UNDICI-COMPATIBILITY.md).
+15. Persist the complete `ScopedTaskRef` for out-of-process task settlement and acknowledge durable queue items only after `applied` or a compatible `already_terminal` outcome with the intended status. Retry or dead-letter scoped misses and conflicting terminal outcomes. Upgrade populated PostgreSQL task registries with the phased [`getDecisioningTaskRegistryScopeV1Upgrade()` runbook](./migration-task-registry-scoping.md#populated-postgresql-upgrade), not application-boot bootstrap DDL.
+16. For out-of-process settlement, return `ctx.handoffToTask(producer, { settlement: 'external' })`; the producer must durably queue the complete handle before returning, and the framework withholds `submitted` until that commit succeeds. For a push-enabled task, configure `createPostgresTaskSettlementCoordinator()` on the same PostgreSQL pool as the task registry and use `completeScopedPushTask()` / `failScopedPushTask()`. Run the webhook recovery outbox migration and recovery worker; the polling-only scoped helpers still reject push tasks. See [task registry scope migration](./migration-task-registry-scoping.md#out-of-process-settlement).
+17. Upgrade to Node `^20.19.0 || >=22.12.0`, whose two boundaries enable the `require(esm)` support needed by the SDK's CommonJS dependency graph. Node 21 and Node 22.0–22.11 are not supported. Keep Undici 6 for the fully supported configuration, or use the tested best-effort Undici 7 override on Node 20.19+. See the [Node/Undici compatibility policy](./guides/NODE-UNDICI-COMPATIBILITY.md).
 
 ### Webhook delivery identity and retry horizons
 
@@ -227,6 +260,14 @@ plus a stable non-secret equality fingerprint. The adapter must authenticate
 the supplied tenant/destination/snapshot context. Settled records redact payload
 and protected secret references. The application still owns KMS
 keys, secret management, tenant authorization/RBAC, and management APIs or UI.
+For crash-safe task settlement, `createPostgresTaskSettlementCoordinator()`
+explicitly removes the top-level validation `token` from the persisted payload
+and protects it with the same adapter under the distinct `payload_token`
+purpose before writing the outbox. Generic recovery checkpoints preserve
+payload fields named `token`; use `recovery.prepare(...,
+{ protectPayloadToken: true })` only for a protocol field known to be secret.
+The legacy transport-authentication adapter context keeps `purpose` undefined
+for upgrade-compatible KMS AAD.
 
 `deliveryRetryHorizonSeconds` defaults to 86,400 seconds and accepts 86,400
 through 604,800. `createAdcpServer()` advertises the configured value under

package/docs/migration-task-registry-scoping.md

@@ -48,10 +48,9 @@ import {
 
 return ctx.handoffToTask(async taskCtx => {
   // The queue transaction must durably store the complete taskRef before the
-  // producer acknowledges this write. Persisting only taskCtx.id is unsafe.
+  // submitted response is sent. Persisting only taskCtx.id is unsafe.
   await approvals.enqueue({ taskRef: taskCtx.taskRef, request: approvalInput });
-  return await approvals.waitForResult(taskCtx.taskRef.taskId);
-});
+}, { settlement: 'external' });
 
 // A different process after restart:
 const item = await approvals.claim();
@@ -78,14 +77,168 @@ if (outcome.outcome === 'not_found_in_scope') {
 }
 ```
 
-This direct helper path is polling-only. It rejects tasks created with buyer
-push notifications because a registry write alone cannot durably deliver the
-terminal webhook after the request process restarts. For a request carrying
-`push_notification_config`, keep the handoff live and return the eventual
-result through its function so the framework owns both settlement and webhook
-delivery. Do not race a terminal scoped worker helper against that live
-handoff. `updateScopedTaskProgress()` remains available for push-enabled tasks
-because progress does not create a terminal delivery obligation.
+The direct `completeScopedTask()` / `failScopedTask()` path is polling-only and
+continues to reject push-enabled tasks. A registry write by itself cannot
+durably promise the terminal webhook.
+
+For PostgreSQL deployments, use the transactional push coordinator. It writes
+the terminal task row and the webhook recovery outbox entry in one transaction,
+then lets the ordinary webhook recovery worker publish it. Both tables must use
+the same `pg.Pool` and database/schema:
+
+```ts
+import {
+  completeScopedPushTask,
+  createPostgresTaskRegistry,
+  createPostgresTaskSettlementCoordinator,
+  createWebhookEmitter,
+  getWebhookDeliveryMigration,
+  getWebhookDeliveryRecoveryMigration,
+  pgWebhookDeliveryStore,
+  pollWebhookDeliveryRecovery,
+  TaskPushSettlementConfigurationError,
+} from '@adcp/sdk/server';
+
+// Integration sketch: pool, approvals, taskCtx, request, approvalInput,
+// seal/openPushRoute, the KMS adapter, and signerKey are application-owned.
+// The queue must persist encrypted push state before the request process exits.
+
+await pool.query(getWebhookDeliveryRecoveryMigration({
+  tableName: 'my_agent_task_webhook_outbox',
+}));
+await pool.query(getWebhookDeliveryMigration({
+  tableName: 'my_agent_webhook_bindings',
+}));
+
+const registry = createPostgresTaskRegistry({
+  pool,
+  namespace: 'tenant:my-agent',
+  storageId: 'prod-eu1:primary-db',
+});
+const settlements = createPostgresTaskSettlementCoordinator({
+  registry,
+  publisherScope: 'my-agent',
+  outbox: { tableName: 'my_agent_task_webhook_outbox' },
+  authenticationAdapter: kmsWebhookAuthenticationAdapter,
+});
+
+// In the specialism handler, the submitted response waits until the queue
+// transaction durably stores the complete taskRef plus encrypted push route.
+// The callback's return leaves the task submitted; only the worker below may
+// make it terminal. A callback rejection fails the initial invocation.
+return ctx.handoffToTask(async taskCtx => {
+  await approvals.enqueue({
+    taskRef: taskCtx.taskRef,
+    push: await sealPushRoute({
+      url: request.push_notification_config.url,
+      operationId: request.push_notification_config.operation_id,
+      // Always persist the negotiated version. A valid pre-3.2 version is
+      // required when operationId is absent and the stable fallback is used.
+      servedAdcpVersion,
+      token: request.push_notification_config.token,
+      authentication: request.push_notification_config.authentication,
+    }),
+    request: approvalInput,
+  });
+}, { settlement: 'external' });
+
+// A different process, including after the request process restarted:
+const item = await approvals.claim();
+const openedPush = await openPushRoute(item.push);
+const legacyScheme = openedPush.authentication?.schemes[0];
+let outcome;
+try {
+  outcome = await completeScopedPushTask(
+    settlements,
+    item.taskRef,
+    {
+      url: openedPush.url,
+      operationId: openedPush.operationId,
+      servedAdcpVersion: openedPush.servedAdcpVersion,
+      token: openedPush.token,
+      authentication:
+        legacyScheme === 'Bearer'
+          ? { type: 'bearer', token: openedPush.authentication.credentials }
+          : legacyScheme === 'HMAC-SHA256'
+            ? { type: 'hmac_sha256', secret: openedPush.authentication.credentials }
+            : null,
+    },
+    item.result,
+  );
+} catch (error) {
+  if (error instanceof TaskPushSettlementConfigurationError || error instanceof TypeError) {
+    await approvals.deadLetterAndAlert(item, error); // immutable bad route/config
+  } else {
+    await approvals.retry(item, error); // transaction/infrastructure failure
+  }
+  return;
+}
+
+if (
+  outcome.outcome === 'applied' ||
+  (outcome.outcome === 'already_terminal' && outcome.compatibility === 'compatible')
+) {
+  await approvals.ack(item);
+} else {
+  // A scope miss or conflicting terminal result must not be acknowledged as
+  // success. Apply the queue's bounded retry/dead-letter policy and alert.
+  await approvals.retryOrDeadLetter(item, outcome);
+}
+
+// Publish/recover outside the database transaction. The outbox lease is
+// fenced; a crash before publish or before acknowledgement is retryable.
+await pollWebhookDeliveryRecovery({
+  recovery: settlements.recovery,
+  deliver: async lease => {
+    const emitter = createWebhookEmitter({
+      signerKey,
+      publisherScope: lease.key.publisherScope,
+      tenantScope: lease.key.tenantScope,
+      deliveryStore: pgWebhookDeliveryStore(pool, {
+        tableName: 'my_agent_webhook_bindings',
+      }),
+      deliveryRecovery: settlements.recovery,
+    });
+    const result = await emitter.emitRecovered(lease);
+    return result.delivered
+      ? { disposition: 'delivered' }
+      : result.terminal
+        ? { disposition: 'terminal' }
+        : { disposition: 'retry', retryAfterMs: 1_000 };
+  },
+});
+```
+
+`TaskPushSettlementOutcome` reports the two independent state machines. Task
+mutation is `applied`, compatible/conflicting `already_terminal`, or the
+non-enumerating `not_found_in_scope`. Delivery is `durably_bound`,
+`recoverable`, `delivered`, or `terminal`; scope misses and conflicting
+settlements report `not_applicable` and never create an outbox entry. Retries
+reuse one deterministic delivery identity and the first committed payload.
+
+The settlement coordinator explicitly removes the top-level task-webhook
+`token` from the JSON payload before persistence and protects it through
+`authenticationAdapter`; generic recovery snapshots do not reinterpret a
+field merely because it is named `token`. The adapter context has
+`purpose: 'payload_token'` for that validation token. The context for legacy
+transport authentication intentionally leaves `purpose` undefined so pending
+snapshots encrypted by older SDK versions keep the same KMS AAD.
+Include a key version in `protectedValue`; retain old decrypt-only key versions
+until every pending delivery using them has settled and the configured retry
+horizon has elapsed. Rotate by writing with the new version while continuing
+to resolve old versions. Never store cleartext push tokens in the approval
+queue, task result, logs, metrics, or dead-letter metadata.
+
+`updateScopedTaskProgress()` remains available for push-enabled tasks because
+progress does not create a terminal delivery obligation. Use
+`{ settlement: 'external' }` for every handoff owned by these helpers. Its
+registry must declare `durability: 'durable'` and issue a stable `registryId`;
+the built-in in-memory registry is process-local and is rejected before the
+producer runs or the buyer receives `submitted`. Its
+producer callback may enqueue work but cannot return a terminal artifact; even
+if that callback throws, the framework rejects the initial invocation, leaves
+the task internally submitted, and writes no webhook. The buyer never receives
+an acknowledgment before recoverable work exists.
 
 The framework owns normal in-process handoff settlement. The direct registry
 surface is specifically for trusted webhook/queue workers and explicit

package/package.json

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

package/skills/build-decisioning-platform/advanced/REFERENCE.md

@@ -563,7 +563,7 @@ const server = createAdcpServerFromPlatform(platform, {
 });
 ```
 
-Cross-instance reads work — process A allocates the task, process B reads the lifecycle for `tasks_get`. Terminal-state idempotency is enforced atomically so concurrent settlements cannot overwrite each other. Background-completion tracking (`_registerBackground`) is process-local — promises do not serialize. Persist the complete `taskCtx.taskRef` before acknowledging an out-of-process queue write, then use `completeScopedTask()` / `failScopedTask()` and acknowledge only `applied` or an `already_terminal` result with the intended status. A scoped miss must retry or dead-letter. Direct worker settlement is polling-only and rejects tasks with buyer push notifications; those must return through the live framework handoff so terminal webhook delivery remains framework-owned.
+Cross-instance reads work — process A allocates the task, process B reads the lifecycle for `tasks_get`. Terminal-state idempotency is enforced atomically so concurrent settlements cannot overwrite each other. Background-completion tracking (`_registerBackground`) is process-local — promises do not serialize. Return `ctx.handoffToTask(producer, { settlement: 'external' })` and persist the complete `taskCtx.taskRef` before the producer returns; the framework withholds `submitted` until that durable write succeeds. Then use `completeScopedTask()` / `failScopedTask()` for polling-only tasks and acknowledge only `applied` or an `already_terminal` result with the intended status. A scoped miss must retry or dead-letter. For tasks with buyer push notifications, use `createPostgresTaskSettlementCoordinator()` with `completeScopedPushTask()` / `failScopedPushTask()` so the task transition and recovery outbox checkpoint commit atomically; registry-only helpers still reject these tasks.
 
 Custom backend? Implement the scoped `TaskRegistry` interface for Redis / DynamoDB / Spanner / etc. The framework awaits every storage method; apply both `accountId` and `ownerScope` on every read and write, then set `scopeVersion: 1`. Keep the explicitly named unsafe methods limited to trusted administrative and test paths.