@adcp/sdk 14.0.0-rc.38 → 14.0.0-rc.39

package/dist/lib/wholesale-feed-sync/webhook-notification.mjs

@@ -32,6 +32,7 @@ function parseWholesaleFeedWebhookNotification(input) {
   const wholesaleFeedVersion = readRequiredString(webhook, "wholesale_feed_version");
   const previousWholesaleFeedVersion = readOptionalString(webhook, "previous_wholesale_feed_version");
   const cacheScope = readCacheScope(readRequiredString(webhook, "cache_scope"), "cache_scope");
+  assertLegacyWholesaleFeedRepresentation(webhook);
   const eventId = readRequiredString(event, "event.event_id");
   if (notificationId !== eventId) {
     throw new WholesaleFeedWebhookNotificationError(
@@ -200,11 +201,13 @@ function validatePayloadForEvent(notificationType, entityId, payload) {
     case "product.created":
     case "product.updated": {
       assertEntityIdMatchesPayload(entityId, readRequiredString(payload, "event.payload.product_id"), "product_id");
+      rejectCanonicalPayloadField(payload, "canonical_product");
       readRequiredRecord(payload, "event.payload.product");
       return void 0;
     }
     case "product.priced": {
       assertEntityIdMatchesPayload(entityId, readRequiredString(payload, "event.payload.product_id"), "product_id");
+      rejectCanonicalPayloadField(payload, "canonical_pricing_options");
       readRequiredNonEmptyArray(payload, "event.payload.pricing_options");
       return void 0;
     }
@@ -245,6 +248,46 @@ function validatePayloadForEvent(notificationType, entityId, payload) {
       return readBulkChangeAffectedEntityType(payload);
   }
 }
+function assertLegacyProductPayloadView(notificationType, productPayloadView) {
+  const isProductEvent = notificationType.startsWith("product.");
+  if (isProductEvent && (productPayloadView === void 0 || productPayloadView === "legacy")) return;
+  if (!isProductEvent && productPayloadView === void 0) return;
+  throw new WholesaleFeedWebhookNotificationError(
+    "wholesale_feed_webhook_field_invalid",
+    isProductEvent ? 'WholesaleFeedSync supports only product_payload_view "legacy".' : "Non-product wholesale-feed webhooks must omit product_payload_view.",
+    {
+      field: "product_payload_view",
+      expected: isProductEvent ? ["legacy"] : ["absent"],
+      actual: productPayloadView
+    }
+  );
+}
+function assertLegacyWholesaleFeedRepresentation(webhook) {
+  const notificationType = webhook.notification_type;
+  if (typeof notificationType !== "string" || !WHOLESALE_FEED_NOTIFICATION_TYPES.has(notificationType))
+    return;
+  const productPayloadView = readOptionalString(webhook, "product_payload_view");
+  assertLegacyProductPayloadView(notificationType, productPayloadView);
+  if (!notificationType.startsWith("product.")) return;
+  const event = webhook.event;
+  if (!event || typeof event !== "object" || Array.isArray(event)) return;
+  const payload = event.payload;
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return;
+  const payloadRecord = payload;
+  if (notificationType === "product.created" || notificationType === "product.updated") {
+    rejectCanonicalPayloadField(payloadRecord, "canonical_product");
+  } else if (notificationType === "product.priced") {
+    rejectCanonicalPayloadField(payloadRecord, "canonical_pricing_options");
+  }
+}
+function rejectCanonicalPayloadField(payload, field) {
+  if (!Object.prototype.hasOwnProperty.call(payload, field)) return;
+  throw new WholesaleFeedWebhookNotificationError(
+    "wholesale_feed_webhook_field_invalid",
+    `WholesaleFeedSync legacy product view does not accept event.payload.${field}.`,
+    { field: `event.payload.${field}`, expected: "absent", actual: payload[field] }
+  );
+}
 function assertEntityIdMatchesPayload(entityId, payloadEntityId, payloadField) {
   if (entityId === payloadEntityId) return;
   throw new WholesaleFeedWebhookNotificationError(
@@ -276,6 +319,7 @@ function describeValue(value) {
 }
 export {
   WholesaleFeedWebhookNotificationError,
+  assertLegacyWholesaleFeedRepresentation,
   normalizeWholesaleFeedWebhookNotification,
   parseWholesaleFeedWebhookNotification
 };

package/docs/CLI.md

@@ -320,7 +320,7 @@ Useful flags:
 
 - `--storyboards ID,...`: Run specific storyboard or bundle IDs instead of capability-driven selection
 - `--tracks core,products,...`: Restrict the run to specific tracks
-- `--compliance-version VERSION`: Select the compliance cache/spec line, for example `3.0.12` or `3.1.0-beta.7`; use the same flag with `storyboard list`, `show`, and `step` when reproducing a pinned run
+- `--compliance-version VERSION`: Select a packaged compliance cache/spec line, for example `3.1.18` or `3.2.0-rc.3`; use the same flag with `storyboard list`, `show`, and `step` when reproducing a pinned run
 - `--compliance-dir PATH`: Use a specific compliance cache directory, mainly for local protocol/cache development
 - `--brief TEXT`: Override the default sample discovery brief
 - `--dry-run`: Preview steps without executing

package/docs/TYPE-SUMMARY.md

@@ -1,10 +1,24 @@
 # AdCP Type Summary
 
-> Generated at: 2026-09-15
-> @adcp/sdk v14.0.0-rc.38
+> Generated at: 2026-09-18
+> @adcp/sdk v14.0.0-rc.39
 
 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`.
 
+## MediaBuy Action Assessment Types
+
+Use `@adcp/sdk/media-buy/actions` for pure buyer assessment and `@adcp/sdk/server` for `mediaBuyActionResolver`. See [action assessment guide](guides/MEDIA-BUY-ACTION-ASSESSMENT.md).
+
+| Type | Use |
+| --- | --- |
+| `MediaBuyTask` | Narrow routing union: `update_media_buy`, `control_media_buy`, `refine_proposals`, `sync_creatives`. |
+| `ActionAvailability` | `available_now` with optional `nonDefaultRoute`, mode and authority; or `currently_unavailable` with reason, certainty and optional compatibility/constraint detail. |
+| `ActionBuy`, `ActionProduct`, `ActionProposal` | Structural inputs for joining current accepted terms with live actions and advisory products. |
+| `LiveMediaBuyAction` | Readable canonical or legacy entry for assessment, projection and existing preflight helpers, including rc.3 package scope. |
+| `MediaBuyAvailableAction`, `MediaBuyValidAction` | Generated legacy wire entry / deprecated flat vocabulary; distinct from canonical helper entries. |
+| `MediaBuyAction`, `MediaBuyActionId` | Action identifiers accepted by assessment / mutation helpers; runtime validation preserves unknown future data. |
+| `ProposalChangeTerm`, `ChangeTermConstraints` | Negotiated term view and portable discriminated budget / flight / package-count / effective-timing constraints. |
+
 ## Client Types
 
 ```typescript
@@ -41,12 +55,24 @@ interface TransportOptions {
 interface TaskOptions {
   timeout?: number;             // Absolute whole-task deadline
   signal?: AbortSignal;         // Caller cancellation
+  // Direct A2A mutation route, bound to authenticated principal + account scope.
+  durableContinuationRecovery?: { ownerScope: string };
   // Trusted local receiver policy; snapshotted and persisted with generated
   // webhook registrations, never inferred from or sent in task arguments.
   delegatedOperatorAuthorization?: DelegatedOperatorAuthorizationContext;
   // ...deadline, cancellation, transport, and conversation options...
 }
 
+interface DeferredContinuation<T> {
+  token: string;
+  question?: string;
+  resume(input: unknown): Promise<TaskResult<T>>;
+  recovery?: { operationId: string; recoveryKey: string }; // Host-only, persist once
+}
+
+// AgentClient public direct-mutation route recovery
+agent.recoverDirectPauseContinuation<T>({ operationId, recoveryKey, ownerScope });
+
 interface ValidateAdAgentsOptions {
   timeoutMs?: number;           // Per-request ceiling
   signal?: AbortSignal;         // One signal/deadline across the complete discovery flow
@@ -2799,6 +2825,14 @@ interface ReportingSourceStagedObjectReaderV1 {
 type ReportingSourceExecutorResultV1 =
   | { ok: true; response: ReportingSourceExecutionResponseV1; manifestBytes: Uint8Array }
   | { ok: false; error: ReportingSourceErrorV1 };
+type InlineReportingMetricEvidenceV1 =
+  | { constituent_id: string; metric: string; status: 'present' | 'explicit_zero'; data_through: string }
+  | { constituent_id: string; metric: string; status: 'unsupported' | 'delayed' | 'partial' | 'stale' | 'missing'; reason: string; data_through?: string };
+interface InlineReportingAvailabilityEvidenceV1 {
+  version: '1.0';
+  cells: readonly InlineReportingMetricEvidenceV1[];
+}
+// Inline callback requests include constituents: { constituent_id, media_buy_id }[]; evidence-bearing responses add availability_evidence.
 // validateReportingSourceExecutionV1({ level, capabilities, request, result, objectReader })
 // runReportingSourceReplayConformanceV1({ level, executor, request, objectReader })
 // validateReportingRevisionSequenceV1(manifests, { crossFinalityBridge })
@@ -2809,11 +2843,41 @@ type ReportingSourceExecutorResultV1 =
 
 ## Seller Reporting Ledger
 
-Import from `@adcp/sdk/reporting/ledger`.
+Ledger symbols import from `@adcp/sdk/reporting/ledger`; `createPostgresPersistentNotificationRuntime` is a server symbol and imports from `@adcp/sdk/server`.
 
 ```typescript
-const store = new PostgresReportingLedgerStore(pool, { acknowledgeIsolatedDatabase: true });
+// Build the notification path first: the store must be constructed with the
+// activity port, or lifecycle transitions record no activity and notify nobody.
+const attemptCheckpoint = createPostgresReportingNotificationAttemptCheckpoint({
+  db: pool,
+  namespace: 'seller-production',
+});
+const notifications = createPostgresPersistentNotificationRuntime({
+  db: pool,
+  publisherScope: 'seller-production',
+  checkpointDeliveryAttempt: attemptCheckpoint,
+  subscriptions: { acknowledgeIsolatedDatabase: true },
+  ...notificationOptions,
+});
+const reportingActivity = createPostgresReportingNotificationActivityRuntime({
+  db: pool,
+  notifications,
+  namespace: 'seller-production',
+  attemptCheckpoint,
+  tenantScopeForAccount: accountId => trustedTenantDirectory.tenantFor(accountId),
+});
+
+// One store, wired to the activity port, used by every participant below.
+const store = new PostgresReportingLedgerStore(pool, {
+  acknowledgeIsolatedDatabase: true,
+  notificationActivityPort: reportingActivity.port,
+});
+
+// Every migration this wiring needs, before probing.
 await pool.query(REPORTING_LEDGER_MIGRATION);
+for (const sql of notifications.migrations.all) await pool.query(sql);
+for (const sql of reportingActivity.migrations.all) await pool.query(sql);
+
 const producer = createReportingProducer({ store, source, offerings, contact });
 await producer.planObligations();
 await producer.runWorker();
@@ -2824,10 +2888,60 @@ const getMediaBuyDelivery = createReportingDeliveryHandler(store); // exact repo
 const syncReportingStatus = createSyncReportingStatusHandler(store, {
   resolveConsumerId: context => context.agent.agent_url,
 });
+
+await reportingActivity.probe();
+// Run repeatedly from a durable scheduler; this call is bounded.
+await reportingActivity.recoverOnce({ ownerToken: stableWorkerId });
+const activityPage = await reportingActivity.listActivity({
+  tenantId: trustedTenant,
+  accountId: resolvedAccountId,
+  limit: 100,
+});
 ```
 
 The store freezes configuration lineage and period-end denominators, retains immutable RFC 8785 JCS/SHA-256-bound revisions, atomically fences lifecycle projections against their revision evidence, and provides leased production plus snapshot-stable status pagination. `projectReportingObligationHealthV1` implements waiting, healthy, delayed, action_required, and complete without I/O.
 
+`ReportingLedgerNotificationActivityPortV1<TTransaction>` is the custom-store seam. Invoke it inside the authoritative transition transaction and fence both predecessor health and finality. The bundled PostgreSQL runtime persists exactly-once intent plus paginatable account activity, then projects health changes through `PersistentNotificationRuntime`; finality-only changes remain internal activity. It never owns subscriber credentials or sends webhooks itself. `listActivity()` is adopter-facing only because no public AdCP account-activity read task exists.
+
+## Reliable Reporting Service
+
+Import from `@adcp/sdk/reporting/service`. This is the adapter-first lifecycle owner over the source and ledger primitives; it does not introduce another store or transport.
+
+```typescript
+interface ReliableReportingAdapterV1 {
+  readonly sourceOffering: ReportingSourceOfferingV1;
+  readonly deliveryOffering: ReportingDeliveryOffering;
+  // Exactly one of fetchSlice or executor.
+  readonly fetchSlice?: InlineReportingDeliveryFetchV1;
+  readonly executor?: ReportingSourceWithReaderV1;
+  // Opt-in bounded replay window for the inline executor; never applied
+  // silently. A feed that outlives its replay ceiling needs this or a
+  // durable executor.
+  readonly inlineReplayRetention?: InlineReportingReplayRetentionV1;
+}
+
+const reporting = createReliableReportingService({
+  store,
+  adapters,
+  contact,
+  automatedRecoveryWindowSeconds,
+  statusRetentionDays, // enforce this commitment in the ledger database
+  resolveSource: account => ({ adapterId, sourceScope, sourceTimezone }),
+  resolveCurrency: account => currency,
+  resolveCoverage: account => ({ constituents }), // authorized media-buy/package denominator
+  resolveConsumerId, // optional; controls consumer-status handler/capability
+});
+
+await pool.query(reporting.setup.migrations[0]);
+const installedPlatform = reporting.install(platform);
+await reporting.installConfiguration(configuration, { account: ctx.account });
+await reporting.runCycle({ accountId }); // tenant-partitioned
+reporting.start({ intervalMilliseconds, deploymentWide: true }); // explicit full-ledger scan
+await reporting.stop();
+```
+
+Account identity comes only from the framework-resolved context. Trusted host callbacks derive adapter routing, credential-free `sourceScope`, source timezone, currency, and the authorized constituent denominator. A declaration cannot supply `account`, `sourceScope`, `sourceTimezone`, `contract`, `currency`, `constituents`, or `mediaBuyIds`; `mediaBuyIds` is derived from `resolveCoverage`, so a buyer cannot name another buyer's media buys on a shared upstream network. Currency is frozen into configuration and obligation lineage. Capabilities are Core-only and derived from installed adapters and handlers; managed delivery, reconciled billing, receipts, webhook activity, and notifications are not advertised. Installation requires `platform.accounts.upsert`, which owns the advertised `sync_accounts` configuration path.
+
 ## Key Enums
 
 | Enum | Values |

package/docs/guides/ASYNC-API-REFERENCE.md

@@ -251,6 +251,11 @@ interface TaskOptions {
   contextId?: string;
   /** Enable debug logging for this task */
   debug?: boolean;
+  /** Operation-routed crash recovery for direct A2A mutations */
+  durableContinuationRecovery?: {
+    /** Stable host authorization scope for the authenticated principal + account */
+    ownerScope: string;
+  };
   /** Additional metadata to include */
   metadata?: Record<string, any>;
 }
@@ -571,6 +576,11 @@ interface DeferredContinuation<T> {
   question?: string;
   /** Resume the task with user input */
   resume: (input: any) => Promise<TaskResult<T>>;
+  /** Host-only route capability; present for opted-in direct mutations */
+  recovery?: {
+    operationId: string;
+    recoveryKey: string;
+  };
 }
 ```
 
@@ -878,6 +888,9 @@ interface DeferredTaskState {
   clientContext?: unknown; // Opaque SDK context; round-trip unchanged
   settlementOperationId?: string; // Trusted committed-mutation recovery route
   settlementOperationRouteRequired?: true; // New-format routed record; preserve on every successor
+  directContinuationRecovery?: true; // Routed direct pause, not committed settlement
+  directContinuationRecoveryKeyDigest?: string; // SHA-256; raw capability is never stored
+  directContinuationOwnerBindingDigest?: string; // Authenticated owner/account + trusted seller binding
   settlementResumeAuthorizationRequired?: boolean; // Owning coordinator must authorize seller-input dispatch
   settlementServerTaskId?: string; // Durably bound seller work handle
   settlementPendingTaskId?: string; // Nonterminal seller work retained for restart polling
@@ -919,6 +932,12 @@ interface DeferredTaskStorage extends Storage<DeferredTaskState> {
 ```
 
 `putIfAbsent()` must atomically reject an existing unexpired key.
+Custom adapters MUST round-trip every `DeferredTaskState` field opaquely,
+including fields introduced by newer SDK versions. When A→B moves an
+operation route but retains A as a dispatch fence, later deletion or expiry of
+A MUST clear the route only if it still points at A; it must never delete the
+route that now points at B. Deploy readers that preserve new fields before
+enabling new routed writers in a shared store.
 For ordinary and marker-absent legacy records, `replaceIfVersion()` is the
 exclusive seller-dispatch claim: it must replace only the exact generation and
 keep the key present under the SDK-supplied internal safety TTL. New
@@ -939,7 +958,7 @@ dispatch, the SDK generation-conditionally restores the original state with
 its remaining human-input TTL.
 
 The three settlement-operation methods form a second atomic index over
-committed continuations. Initial pause creation writes the opaque token and
+committed continuations and opted-in direct mutation pauses. Initial pause creation writes the opaque token and
 operation route together. A nested pause writes B and moves the route from the
 exact dispatch-committed generation A in one transaction while retaining A as
 a dispatch fence. `getBySettlementOperationId()` returns that exact current
@@ -959,6 +978,48 @@ trusted settlement operation identity. A terminal restart resume is returned
 only after a reconstructed durable coordinator settles it; without a matching
 recoverer, the resume fails closed.
 
+Direct A2A mutations opt in per call with an authenticated owner/account scope:
+
+```typescript
+const paused = await agent.buyProducts(request, undefined, {
+  durableContinuationRecovery: {
+    ownerScope: `principal:${principalId}/account:${accountId}`,
+  },
+});
+
+// Persist this pair once in host-only storage. The recovery key is distinct
+// from the human-facing resume token and must never be sent to the seller.
+const route = paused.deferred?.recovery;
+if (!route) throw new Error('Seller did not return a recoverable A2A pause');
+
+const recovered = await restartedAgent.recoverDirectPauseContinuation({
+  operationId: route.operationId,
+  recoveryKey: route.recoveryKey,
+  ownerScope: `principal:${principalId}/account:${accountId}`,
+});
+```
+
+The SDK stores only the recovery-key digest, binds it to the supplied stable
+principal/account owner scope and trusted seller ID/origin, and validates the route
+store before seller dispatch. Unknown routes, wrong capabilities, owner drift,
+and seller drift fail without revealing a token. The host must authenticate
+the caller before constructing `ownerScope`; request fields are not an
+authentication source. Keep the scope byte-stable for the operation lifetime;
+do not use a mutable display name, seller-supplied value, seller task ID, or
+request idempotency key. Custom stores must round-trip all three
+`directContinuation*` fields and implement the operation-route methods as one
+linearizable index. Direct routes do not enter committed-settlement recovery,
+so the existing callback and terminal settlement fences remain unchanged.
+The operation route covers resumable pause generations. If resume instead
+reaches `submitted` or a terminal result, persist the returned seller task ID
+and result through the normal host operation record; terminal uncertainty is
+reconciled by polling that seller task ID, never by redispatching the mutation.
+Persist the first returned recovery pair before considering the initial pause
+restart-safe. After any possible continuation dispatch, an absent pause route
+does not authorize redispatch.
+
+### Committed coordinator checkpoints
+
 If seller continuation reaches a terminal result, the SDK replaces the human
 input record with an opaque terminal checkpoint using the same independent
 safety horizon. Recovery and application completion handlers retry from that

package/docs/guides/ASYNC-DEVELOPER-GUIDE.md

@@ -412,6 +412,31 @@ async function manageTaskLifecycle() {
 }
 ```
 
+For a direct A2A mutation that may pause more than once, opt into an atomic
+operation route and persist the returned host-only capability once:
+
+```typescript
+const paused = await agent.buyProducts(request, undefined, {
+  durableContinuationRecovery: {
+    ownerScope: `principal:${principalId}/account:${accountId}`,
+  },
+});
+
+const savedRecovery = paused.deferred?.recovery;
+if (!savedRecovery) throw new Error('Seller did not return a recoverable A2A pause');
+await saveHostOnly(savedRecovery);
+
+const current = await restartedAgent.recoverDirectPauseContinuation({
+  ...savedRecovery,
+  ownerScope: `principal:${principalId}/account:${accountId}`,
+});
+```
+
+`ownerScope` must come from authenticated host context. The recovery key is
+separate from the resume token and must not be placed in approval links or
+sent to the seller. Recovery returns the current nested pause without a seller
+call; its `deferred.resume()` remains generation-fenced.
+
 Durable snapshots redact entire secret-shaped containers and truncate
 over-depth subtrees. `SingleAgentClient.getProducts()` rejects an authenticated
 request `property_list` before seller dispatch when durable storage also needs

package/docs/guides/ASYNC-DOCUMENTATION-INDEX.md

@@ -4,6 +4,9 @@
 
 Complete documentation for the ADCP TypeScript client library's new async execution model introduced in PR #78. This documentation covers migration from old patterns, comprehensive developer guidance, and production-ready implementation strategies.
 
+Deploying request-scoped callers across multiple processes? Start with
+[Durable buyer writes across processes](./DURABLE-BUYER-WRITES.md).
+
 ## 📚 Documentation Structure
 
 ### 1. [Migration Guide](./ASYNC-MIGRATION-GUIDE.md)

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

@@ -1,8 +1,13 @@
 # Call a seller with AdCP 3.2
 
+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 the SDK 14 prerelease
 and create one client:
 
+For request-scoped callers whose callback or poll may run on another process,
+use the [durable buyer writes recipe](./DURABLE-BUYER-WRITES.md).
+
 ```bash
 npm install '@adcp/sdk@^14.0.0-0'
 ```