@adcp/sdk 16.5.0 → 16.6.0

package/dist/lib/version.d.ts

@@ -1,7 +1,7 @@
 /**
  * AdCP SDK library version
  */
-export declare const LIBRARY_VERSION = "16.5.0";
+export declare const LIBRARY_VERSION = "16.6.0";
 /**
  * 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: "16.5.0";
+    readonly library: "16.6.0";
     readonly adcp: "3.2.7";
     readonly compatibleVersions: readonly ["v3", "3.0.0", "3.0", "3.0.1", "3.0.2", "3.0.3", "3.0.4", "3.0.5", "3.0.6", "3.0.7", "3.0.8", "3.0.9", "3.0.10", "3.0.11", "3.0.12", "3.0.13", "3.0.14", "3.0.15", "3.0.16", "3.0.17", "3.0.18", "3.0.19", "3.0.20", "3.0.21", "3.0.22", "3.0.23", "3.0.24", "3.0.25", "3.1.0", "3.1", "3.1.1", "3.1.2", "3.1.3", "3.1.4", "3.1.5", "3.1.6", "3.1.7", "3.1.8", "3.1.9", "3.1.10", "3.1.11", "3.1.12", "3.1.13", "3.1.14", "3.1.15", "3.1.16", "3.1.17", "3.1.18", "3.1.19", "3.1.20", "3.1.21", "3.1.22", "3.1.23", "3.1.24", "3.1.25", "3.1.26", "3.1.27", "3.1.28", "3.1.29", "3.2.1", "3.2", "3.2.2", "3.2.3", "3.2.4", "3.2.5", "3.2.6", "3.2.7"];
-    readonly generatedAt: "2026-10-25T14:43:55.588Z";
+    readonly generatedAt: "2026-10-27T06:39:57.335Z";
 };
 /**
  * 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 = "16.5.0";
+const LIBRARY_VERSION = "16.6.0";
 const ADCP_VERSION = "3.2.7";
 const ADCP_MAJOR_VERSION = 3;
 const COMPATIBLE_ADCP_VERSIONS = [
@@ -104,10 +104,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
   "3.2.7"
 ];
 const VERSION_INFO = {
-  library: "16.5.0",
+  library: "16.6.0",
   adcp: "3.2.7",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-10-25T14:43:55.588Z"
+  generatedAt: "2026-10-27T06:39:57.335Z"
 };
 function getAdcpVersion() {
   return ADCP_VERSION;

package/dist/lib/version.mjs

@@ -1,4 +1,4 @@
-const LIBRARY_VERSION = "16.5.0";
+const LIBRARY_VERSION = "16.6.0";
 const ADCP_VERSION = "3.2.7";
 const ADCP_MAJOR_VERSION = 3;
 const COMPATIBLE_ADCP_VERSIONS = [
@@ -71,10 +71,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
   "3.2.7"
 ];
 const VERSION_INFO = {
-  library: "16.5.0",
+  library: "16.6.0",
   adcp: "3.2.7",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-10-25T14:43:55.588Z"
+  generatedAt: "2026-10-27T06:39:57.335Z"
 };
 function getAdcpVersion() {
   return ADCP_VERSION;

package/dist/lib/webhooks/index.d.mts

@@ -74,3 +74,6 @@ export type PreflightWebhookRequestResult = {
 };
 /** Validate headers and freshness before looking up a secret. Success does not authenticate the request. */
 export declare function preflightWebhookRequest(request: PreflightWebhookRequest, options?: PreflightWebhookRequestOptions): PreflightWebhookRequestResult;
+export { parseMediaBuyDeliveryWebhook } from './media-buy-delivery.mjs';
+export type { ParseMediaBuyDeliveryWebhookOptions, MediaBuyDeliveryWebhookEnvelope, MediaBuyDeliveryWebhookParseErrorCode, MediaBuyDeliveryWebhookParseResult, } from './media-buy-delivery.mjs';
+export type { MediaBuyDeliveryReport } from '../types/media-buy-delivery-report.mjs';

package/dist/lib/webhooks/index.d.ts

@@ -74,3 +74,6 @@ export type PreflightWebhookRequestResult = {
 };
 /** Validate headers and freshness before looking up a secret. Success does not authenticate the request. */
 export declare function preflightWebhookRequest(request: PreflightWebhookRequest, options?: PreflightWebhookRequestOptions): PreflightWebhookRequestResult;
+export { parseMediaBuyDeliveryWebhook } from './media-buy-delivery';
+export type { ParseMediaBuyDeliveryWebhookOptions, MediaBuyDeliveryWebhookEnvelope, MediaBuyDeliveryWebhookParseErrorCode, MediaBuyDeliveryWebhookParseResult, } from './media-buy-delivery';
+export type { MediaBuyDeliveryReport } from '../types/media-buy-delivery-report';

package/dist/lib/webhooks/index.js

@@ -21,6 +21,7 @@ var webhooks_exports = {};
 __export(webhooks_exports, {
   WholesaleFeedWebhookNotificationError: () => import_webhook_notification.WholesaleFeedWebhookNotificationError,
   normalizeWholesaleFeedWebhookNotification: () => import_webhook_notification.normalizeWholesaleFeedWebhookNotification,
+  parseMediaBuyDeliveryWebhook: () => import_media_buy_delivery.parseMediaBuyDeliveryWebhook,
   parseWholesaleFeedWebhookNotification: () => import_webhook_notification.parseWholesaleFeedWebhookNotification,
   preflightWebhookRequest: () => preflightWebhookRequest,
   verifyWebhookRequest: () => verifyWebhookRequest
@@ -29,6 +30,7 @@ module.exports = __toCommonJS(webhooks_exports);
 var import_crypto = require("crypto");
 __reExport(webhooks_exports, require('../notifications/account-change-recorded.js'), module.exports);
 var import_webhook_notification = require('../wholesale-feed-sync/webhook-notification.js');
+var import_media_buy_delivery = require('./media-buy-delivery.js');
 function verifyWebhookRequest(options) {
   const preflight = preflightWebhookRequest(options, {
     now: options.now,
@@ -172,6 +174,7 @@ function isHeaders(headers) {
 0 && (module.exports = {
   WholesaleFeedWebhookNotificationError,
   normalizeWholesaleFeedWebhookNotification,
+  parseMediaBuyDeliveryWebhook,
   parseWholesaleFeedWebhookNotification,
   preflightWebhookRequest,
   verifyWebhookRequest,

package/dist/lib/webhooks/index.mjs

@@ -144,9 +144,11 @@ function normalizeHeaderValue(value) {
 function isHeaders(headers) {
   return typeof headers.get === "function";
 }
+import { parseMediaBuyDeliveryWebhook } from "./media-buy-delivery.mjs";
 export {
   WholesaleFeedWebhookNotificationError,
   normalizeWholesaleFeedWebhookNotification,
+  parseMediaBuyDeliveryWebhook,
   parseWholesaleFeedWebhookNotification,
   preflightWebhookRequest,
   verifyWebhookRequest

package/dist/lib/webhooks/media-buy-delivery.d.mts

@@ -0,0 +1,43 @@
+import type { MCPWebhookPayload } from '../types/core.generated.mjs';
+import type { MediaBuyDeliveryReport } from '../types/media-buy-delivery-report.mjs';
+export interface ParseMediaBuyDeliveryWebhookOptions {
+    /** Trusted release negotiated with the seller. Defaults to the SDK pin; never read from the body. */
+    adcpVersion?: string;
+    /** Accept an unenveloped report and mark its wire format. Defaults to false. */
+    acceptBareDeliveryReport?: boolean;
+}
+/** AdCP 3.0 permits operation_id to be absent. No missing envelope fields are synthesized. */
+export type MediaBuyDeliveryWebhookEnvelope = Omit<MCPWebhookPayload, 'result' | 'task_type' | 'operation_id'> & {
+    task_type: 'media_buy_delivery';
+    operation_id?: string;
+    result: MediaBuyDeliveryReport;
+};
+export type MediaBuyDeliveryWebhookParseErrorCode = 'webhook_envelope_invalid' | 'webhook_result_invalid' | 'webhook_unsupported_payload';
+export type MediaBuyDeliveryWebhookParseResult = {
+    ok: true;
+    wireFormat: 'mcp_envelope';
+    adcpVersion: string;
+    envelope: MediaBuyDeliveryWebhookEnvelope;
+    result: MediaBuyDeliveryReport;
+} | {
+    ok: true;
+    wireFormat: 'bare_delivery_report';
+    adcpVersion: string;
+    envelope?: undefined;
+    result: MediaBuyDeliveryReport;
+} | {
+    ok: false;
+    code: MediaBuyDeliveryWebhookParseErrorCode;
+    message: string;
+    errors: readonly string[];
+};
+/**
+ * Validate an ALREADY AUTHENTICATED delivery webhook. This performs no signature,
+ * sender, registration, or replay verification. Verify the original request bytes
+ * first and select adcpVersion from trusted seller/buy state. Malformed bodies
+ * return diagnostics; invalid version configuration throws ConfigurationError.
+ *
+ * Envelope status follows the selected release's task-status enum. A delayed
+ * notification may use working; notification_type is independent of task status.
+ */
+export declare function parseMediaBuyDeliveryWebhook(body: unknown, options?: ParseMediaBuyDeliveryWebhookOptions): MediaBuyDeliveryWebhookParseResult;

package/dist/lib/webhooks/media-buy-delivery.d.ts

@@ -0,0 +1,43 @@
+import type { MCPWebhookPayload } from '../types/core.generated';
+import type { MediaBuyDeliveryReport } from '../types/media-buy-delivery-report';
+export interface ParseMediaBuyDeliveryWebhookOptions {
+    /** Trusted release negotiated with the seller. Defaults to the SDK pin; never read from the body. */
+    adcpVersion?: string;
+    /** Accept an unenveloped report and mark its wire format. Defaults to false. */
+    acceptBareDeliveryReport?: boolean;
+}
+/** AdCP 3.0 permits operation_id to be absent. No missing envelope fields are synthesized. */
+export type MediaBuyDeliveryWebhookEnvelope = Omit<MCPWebhookPayload, 'result' | 'task_type' | 'operation_id'> & {
+    task_type: 'media_buy_delivery';
+    operation_id?: string;
+    result: MediaBuyDeliveryReport;
+};
+export type MediaBuyDeliveryWebhookParseErrorCode = 'webhook_envelope_invalid' | 'webhook_result_invalid' | 'webhook_unsupported_payload';
+export type MediaBuyDeliveryWebhookParseResult = {
+    ok: true;
+    wireFormat: 'mcp_envelope';
+    adcpVersion: string;
+    envelope: MediaBuyDeliveryWebhookEnvelope;
+    result: MediaBuyDeliveryReport;
+} | {
+    ok: true;
+    wireFormat: 'bare_delivery_report';
+    adcpVersion: string;
+    envelope?: undefined;
+    result: MediaBuyDeliveryReport;
+} | {
+    ok: false;
+    code: MediaBuyDeliveryWebhookParseErrorCode;
+    message: string;
+    errors: readonly string[];
+};
+/**
+ * Validate an ALREADY AUTHENTICATED delivery webhook. This performs no signature,
+ * sender, registration, or replay verification. Verify the original request bytes
+ * first and select adcpVersion from trusted seller/buy state. Malformed bodies
+ * return diagnostics; invalid version configuration throws ConfigurationError.
+ *
+ * Envelope status follows the selected release's task-status enum. A delayed
+ * notification may use working; notification_type is independent of task status.
+ */
+export declare function parseMediaBuyDeliveryWebhook(body: unknown, options?: ParseMediaBuyDeliveryWebhookOptions): MediaBuyDeliveryWebhookParseResult;

package/dist/lib/webhooks/media-buy-delivery.js

@@ -0,0 +1,119 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var media_buy_delivery_exports = {};
+__export(media_buy_delivery_exports, {
+  parseMediaBuyDeliveryWebhook: () => parseMediaBuyDeliveryWebhook,
+  prepareMediaBuyDeliveryWebhookValidation: () => prepareMediaBuyDeliveryWebhookValidation
+});
+module.exports = __toCommonJS(media_buy_delivery_exports);
+var import_node_util = require("node:util");
+var import_account_change_json = require('../client/account-change-json.js');
+var import_errors = require('../errors/index.js');
+var import_adcp_version_config = require('../utils/adcp-version-config.js');
+var import_schema_loader = require('../validation/schema-loader.js');
+const MAX_BODY_BYTES = 16 * 1024 * 1024;
+const ENVELOPE_FIELDS = ["result", "task_type", "task_id", "operation_id", "idempotency_key", "timestamp"];
+function prepareMediaBuyDeliveryWebhookValidation(version) {
+  const adcpVersion = (0, import_adcp_version_config.resolveAdcpVersion)(version);
+  const validateEnvelope = (0, import_schema_loader.getMediaBuyDeliveryEnvelopeValidator)(adcpVersion);
+  const validateResult = (0, import_schema_loader.getSchemaValidatorByRef)(
+    (0, import_adcp_version_config.isPre31AdcpVersion)(adcpVersion) ? "media-buy/get-media-buy-delivery-response.json" : "media-buy/media-buy-delivery-webhook-result.json",
+    adcpVersion
+  );
+  if (!validateEnvelope || !validateResult) {
+    throw new import_errors.ConfigurationError("Bundled delivery webhook schemas are unavailable.", "adcpVersion");
+  }
+  return { adcpVersion, validateEnvelope, validateResult };
+}
+function parseMediaBuyDeliveryWebhook(body, options = {}) {
+  const { adcpVersion, validateEnvelope, validateResult } = prepareMediaBuyDeliveryWebhookValidation(
+    options.adcpVersion
+  );
+  let parsed;
+  try {
+    if (typeof body === "string" || body instanceof Uint8Array) {
+      if ((typeof body === "string" ? Buffer.byteLength(body) : body.byteLength) > MAX_BODY_BYTES) {
+        throw new Error("Body is too large");
+      }
+      parsed = JSON.parse(
+        typeof body === "string" ? body : new import_node_util.TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(body)
+      );
+    } else {
+      parsed = body;
+    }
+    (0, import_account_change_json.assertAccountChangeJsonSize)(parsed, MAX_BODY_BYTES);
+    parsed = structuredClone(parsed);
+  } catch {
+    return failure("webhook_envelope_invalid", [
+      "Webhook body must be valid JSON within 16 MiB and 64 nesting levels."
+    ]);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return failure("webhook_envelope_invalid", ["Webhook body must be an object."]);
+  }
+  const envelope = parsed;
+  const bare = Object.hasOwn(envelope, "media_buy_deliveries") && !ENVELOPE_FIELDS.some((field) => Object.hasOwn(envelope, field));
+  if (bare && options.acceptBareDeliveryReport !== true) {
+    return failure("webhook_unsupported_payload", [
+      "Bare delivery reports require acceptBareDeliveryReport: true; the default expects an MCP envelope with result."
+    ]);
+  }
+  if (!bare) {
+    if (typeof envelope.task_type === "string" && envelope.task_type !== "media_buy_delivery") {
+      return failure("webhook_unsupported_payload", ["task_type must be media_buy_delivery."]);
+    }
+    if (!validateEnvelope(envelope)) return failure("webhook_envelope_invalid", diagnostics(validateEnvelope.errors));
+  }
+  const result = bare ? envelope : envelope.result;
+  if (!validateResult(result))
+    return failure("webhook_result_invalid", diagnostics(validateResult.errors, bare ? "" : "result"));
+  if (bare)
+    return { ok: true, wireFormat: "bare_delivery_report", adcpVersion, result };
+  return {
+    ok: true,
+    wireFormat: "mcp_envelope",
+    adcpVersion,
+    envelope,
+    result
+  };
+}
+function failure(code, errors) {
+  return { ok: false, code, message: errors.join("; "), errors };
+}
+function diagnostics(errors, prefix = "") {
+  if (!errors?.length) return [`${prefix || "body"} is invalid`];
+  return errors.slice(0, 20).map((error) => {
+    const fields = error.instancePath.split("/").slice(1).map((field) => field.replace(/~1/g, "/").replace(/~0/g, "~"));
+    if (error.keyword === "required" && typeof error.params.missingProperty === "string")
+      fields.push(error.params.missingProperty);
+    if (error.keyword === "additionalProperties" && typeof error.params.additionalProperty === "string")
+      fields.push(error.params.additionalProperty);
+    let path = prefix;
+    for (const field of fields) {
+      const bounded = field.length > 80 ? field.slice(0, 80) + "\u2026" : field;
+      path += /^(0|[1-9][0-9]*)$/.test(bounded) ? `[${bounded}]` : /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(bounded) ? `${path ? "." : ""}${bounded}` : `[${JSON.stringify(bounded)}]`;
+    }
+    return `${path || "body"} ${error.keyword === "required" ? "is required" : error.message ?? "is invalid"}`;
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  parseMediaBuyDeliveryWebhook,
+  prepareMediaBuyDeliveryWebhookValidation
+});

package/dist/lib/webhooks/media-buy-delivery.mjs

@@ -0,0 +1,94 @@
+import { TextDecoder } from "node:util";
+import { assertAccountChangeJsonSize } from "../client/account-change-json.mjs";
+import { ConfigurationError } from "../errors/index.mjs";
+import { isPre31AdcpVersion, resolveAdcpVersion } from "../utils/adcp-version-config.mjs";
+import { getMediaBuyDeliveryEnvelopeValidator, getSchemaValidatorByRef } from "../validation/schema-loader.mjs";
+const MAX_BODY_BYTES = 16 * 1024 * 1024;
+const ENVELOPE_FIELDS = ["result", "task_type", "task_id", "operation_id", "idempotency_key", "timestamp"];
+function prepareMediaBuyDeliveryWebhookValidation(version) {
+  const adcpVersion = resolveAdcpVersion(version);
+  const validateEnvelope = getMediaBuyDeliveryEnvelopeValidator(adcpVersion);
+  const validateResult = getSchemaValidatorByRef(
+    isPre31AdcpVersion(adcpVersion) ? "media-buy/get-media-buy-delivery-response.json" : "media-buy/media-buy-delivery-webhook-result.json",
+    adcpVersion
+  );
+  if (!validateEnvelope || !validateResult) {
+    throw new ConfigurationError("Bundled delivery webhook schemas are unavailable.", "adcpVersion");
+  }
+  return { adcpVersion, validateEnvelope, validateResult };
+}
+function parseMediaBuyDeliveryWebhook(body, options = {}) {
+  const { adcpVersion, validateEnvelope, validateResult } = prepareMediaBuyDeliveryWebhookValidation(
+    options.adcpVersion
+  );
+  let parsed;
+  try {
+    if (typeof body === "string" || body instanceof Uint8Array) {
+      if ((typeof body === "string" ? Buffer.byteLength(body) : body.byteLength) > MAX_BODY_BYTES) {
+        throw new Error("Body is too large");
+      }
+      parsed = JSON.parse(
+        typeof body === "string" ? body : new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(body)
+      );
+    } else {
+      parsed = body;
+    }
+    assertAccountChangeJsonSize(parsed, MAX_BODY_BYTES);
+    parsed = structuredClone(parsed);
+  } catch {
+    return failure("webhook_envelope_invalid", [
+      "Webhook body must be valid JSON within 16 MiB and 64 nesting levels."
+    ]);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return failure("webhook_envelope_invalid", ["Webhook body must be an object."]);
+  }
+  const envelope = parsed;
+  const bare = Object.hasOwn(envelope, "media_buy_deliveries") && !ENVELOPE_FIELDS.some((field) => Object.hasOwn(envelope, field));
+  if (bare && options.acceptBareDeliveryReport !== true) {
+    return failure("webhook_unsupported_payload", [
+      "Bare delivery reports require acceptBareDeliveryReport: true; the default expects an MCP envelope with result."
+    ]);
+  }
+  if (!bare) {
+    if (typeof envelope.task_type === "string" && envelope.task_type !== "media_buy_delivery") {
+      return failure("webhook_unsupported_payload", ["task_type must be media_buy_delivery."]);
+    }
+    if (!validateEnvelope(envelope)) return failure("webhook_envelope_invalid", diagnostics(validateEnvelope.errors));
+  }
+  const result = bare ? envelope : envelope.result;
+  if (!validateResult(result))
+    return failure("webhook_result_invalid", diagnostics(validateResult.errors, bare ? "" : "result"));
+  if (bare)
+    return { ok: true, wireFormat: "bare_delivery_report", adcpVersion, result };
+  return {
+    ok: true,
+    wireFormat: "mcp_envelope",
+    adcpVersion,
+    envelope,
+    result
+  };
+}
+function failure(code, errors) {
+  return { ok: false, code, message: errors.join("; "), errors };
+}
+function diagnostics(errors, prefix = "") {
+  if (!errors?.length) return [`${prefix || "body"} is invalid`];
+  return errors.slice(0, 20).map((error) => {
+    const fields = error.instancePath.split("/").slice(1).map((field) => field.replace(/~1/g, "/").replace(/~0/g, "~"));
+    if (error.keyword === "required" && typeof error.params.missingProperty === "string")
+      fields.push(error.params.missingProperty);
+    if (error.keyword === "additionalProperties" && typeof error.params.additionalProperty === "string")
+      fields.push(error.params.additionalProperty);
+    let path = prefix;
+    for (const field of fields) {
+      const bounded = field.length > 80 ? field.slice(0, 80) + "\u2026" : field;
+      path += /^(0|[1-9][0-9]*)$/.test(bounded) ? `[${bounded}]` : /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(bounded) ? `${path ? "." : ""}${bounded}` : `[${JSON.stringify(bounded)}]`;
+    }
+    return `${path || "body"} ${error.keyword === "required" ? "is required" : error.message ?? "is invalid"}`;
+  });
+}
+export {
+  parseMediaBuyDeliveryWebhook,
+  prepareMediaBuyDeliveryWebhookValidation
+};

package/docs/TYPE-SUMMARY.md

@@ -1,7 +1,7 @@
 # AdCP Type Summary
 
-> Generated at: 2026-10-25
-> @adcp/sdk v16.5.0
+> Generated at: 2026-10-27
+> @adcp/sdk v16.6.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

@@ -252,11 +252,19 @@ Six helper families adopters reach for. Pick what your agent shape needs:
 | `InMemoryImplicitAccountStore` (Shape A) / `createOAuthPassthroughResolver` (Shape B) / `createRosterAccountStore` (Shape C) | Reference `AccountStore` shapes. Shape A: `'implicit'` buyer-driven onboarding. Shape B: vendor OAuth + `/me/adaccounts`. Shape C: publisher-curated roster. |
 | `createTenantRegistry` (host-routed) / `createTenantStore` (account-routed) | Multi-tenant. Host-routed = one server per tenant + tenant-id keyed lookup. Account-routed = one server with built-in fail-closed tenant-isolation gate on `upsert` / `syncGovernance`. |
 | `BuyerAgentRegistry.signingOnly` / `bearerOnly` / `mixed` (+ `cached`) | Durable buyer-agent identity. Resolved `BuyerAgent` flows through `ctx.agent` to every `AccountStore` method and `tasks_get` polling. `BuyerAgent.status === 'suspended' \| 'blocked'` triggers `AGENT_SUSPENDED` / `AGENT_BLOCKED`; `sync_accounts.billing` is enforced against `BuyerAgent.billing_capabilities`. See [`docs/migration-buyer-agent-registry.md`](../migration-buyer-agent-registry.md). |
-| `MEDIA_BUY_TRANSITIONS` / `assertMediaBuyTransition` (+ creative pair) | Canonical lifecycle graph the storyboard runner uses. `assertMediaBuyTransition(from, to)` throws `AdcpError` with the spec-correct code (`NOT_CANCELLABLE` / `INVALID_STATE`). Replaces local copies of the status graph. |
+| `MEDIA_BUY_TRANSITIONS` / `getMediaBuyTransitions` / `assertMediaBuyTransition` (+ creative pair) | Canonical lifecycle graphs shared with the storyboard runner. `getMediaBuyTransitions(adcpVersion)` selects the served release; `MEDIA_BUY_TRANSITIONS` uses the SDK default. `assertMediaBuyTransition(from, to, adcpVersion?)` throws `AdcpError` with the spec-correct code (`NOT_CANCELLABLE` / `INVALID_STATE`). Replaces local copies of the status graph. |
 | `createMediaBuyStore({ store })`                                       | Opt-in `targeting_overlay` echo on `get_media_buys`. Sellers claiming `property-lists` / `collection-lists` MUST echo the persisted list reference. |
 
 The full migration recipe walking adopters through each is at [`docs/migration-6.6-to-6.7.md`](../migration-6.6-to-6.7.md). The `examples/hello_*` family demonstrates each helper in a runnable adapter.
 
+When serving AdCP 3.3 or its beta/RC candidates, pass the negotiated release to
+`isLegalMediaBuyTransition` or `assertMediaBuyTransition` as the optional third
+argument. A blocking creative review rejection can move a not-yet-active buy
+from `pending_start` to `pending_creatives`; active and paused buys still cannot
+rewind to a pending state. Omitting the version keeps the SDK default release's
+contract. The storyboard runner selects the graph from the seller's response
+version, falling back to the run's `adcpVersion` and then the SDK default.
+
 ### Exposing your agent over A2A (preview)
 
 MCP is the default transport. To additionally expose the same `AdcpServer` over A2A JSON-RPC — so A2A-native buyers can discover and call your agent — mount `createA2AAdapter`:

package/docs/guides/DELIVERY-WEBHOOK-PARSING.md

@@ -0,0 +1,135 @@
+# Parsing media-buy delivery webhooks
+
+Use `parseMediaBuyDeliveryWebhook` from `@adcp/sdk/webhooks` after your receiver
+has authenticated the original HTTP body and enforced replay protection. It
+validates delivery content without requiring an `AgentClient`, an SDK callback
+registry, or a signature-verification strategy. It performs no authentication
+itself; `ok: true` means the payload is valid, not that its sender is trusted.
+
+```typescript
+import { parseMediaBuyDeliveryWebhook } from '@adcp/sdk/webhooks';
+
+// Call only after signature verification. Load the version from the registered
+// seller/buy record, rather than trusting a version claim in the request body.
+function parseAuthenticatedDelivery(verifiedRawBody: Uint8Array, negotiatedVersion: string) {
+  const parsed = parseMediaBuyDeliveryWebhook(verifiedRawBody, {
+    adcpVersion: negotiatedVersion,
+  });
+  if (!parsed.ok) {
+    // Suitable for a 400 response: paths are readable and omit report values (map key names can appear in paths).
+    // e.g. result.media_buy_deliveries[0].by_package is required
+    return { status: 400, error: parsed.message, errors: parsed.errors };
+  }
+  return { status: 200, report: parsed.result };
+}
+```
+
+Pass the exact bytes you authenticated to avoid parsing a different body from
+JSON middleware. The parser also accepts a parsed JSON object or a JSON string. It returns
+a detached copy of validated data and preserves the seller's fields. It does
+not add a task status, operation ID, currency, package breakdown, or other
+missing data. Bodies are limited to 16 MiB and 64 nesting levels before schema
+validation. Schema diagnostics use fail-fast validation and readable paths.
+Invalid bodies return one of:
+
+| Code | Meaning |
+| --- | --- |
+| `webhook_envelope_invalid` | Malformed JSON, invalid envelope metadata, or a missing result. |
+| `webhook_result_invalid` | The nested delivery report fails the selected release's schema. |
+| `webhook_unsupported_payload` | Another task type, or an unenveloped report without explicit opt-in. |
+
+An invalid or unbundled `adcpVersion` is a caller configuration error and throws
+`ConfigurationError`. Omission selects the SDK's protocol pin. The body does not
+select its own validation release.
+
+## Select the release used for the buy
+
+A reporting webhook does not provide a trustworthy negotiated-version field.
+Keep that release with the callback/buy registration and supply it for every
+report. Stable patch pins select their bundled minor contract; preview pins
+remain exact.
+
+| Release | Report validation | Envelope details |
+| --- | --- | --- |
+| 3.0 | `get-media-buy-delivery-response.json`; report-wide currency is required. | `operation_id` is optional and remains absent when omitted. The parser accepts the documented `media_buy_delivery` discriminator even though the old task enum omits it. |
+| 3.1 | `media-buy-delivery-webhook-result.json`; report-wide currency is required. | `operation_id` is required. |
+| 3.2 | Dedicated webhook-result schema; report-wide currency is optional. | `operation_id` is required. |
+
+All releases require `by_package` on each delivery row. The SDK's schema loader
+handles both relative and absolute schema IDs. No external `$ref` traversal or
+network fetch is needed.
+
+On SDK 16, the standalone parser is additive. Existing `verifyAndParseWebhook`
+contracts remain unchanged; receivers needing per-buy release selection can pass
+already-authenticated bytes to this parser.
+
+## Bare-report compatibility is explicit
+
+The default rejects a body with top-level `media_buy_deliveries` and no MCP
+envelope. For a temporary migration, opt in explicitly:
+
+```typescript
+const parsed = parseMediaBuyDeliveryWebhook(verifiedRawBody, {
+  adcpVersion: savedBuy.adcpVersion,
+  acceptBareDeliveryReport: true,
+});
+if (parsed.ok && parsed.wireFormat === 'bare_delivery_report') {
+  // Record the seller's protocol violation and repair its callback format.
+  // parsed.envelope is undefined; no transport identity has been invented.
+}
+```
+
+The report still undergoes release-specific validation. A poll-shaped report
+with only a task `status` and no envelope identity is also bare; any such field
+is preserved when the selected report schema permits it. An incomplete or invalid
+envelope never falls back to bare-report acceptance. A normal envelope returns
+`wireFormat: 'mcp_envelope'` and the validated `envelope`. Authentication and
+sender, account, media-buy authorization, and deduplication remain the receiver's
+responsibility in either format.
+
+## A shared delivery body for polling and pushing
+
+`MediaBuyDeliveryReport` imports from `@adcp/sdk/types` or `@adcp/sdk/webhooks`.
+`MediaBuyDeliveryReportSchema` imports from `@adcp/sdk/schemas` and
+`@adcp/sdk/schemas/browser`. This payload-only shape accepts a polled report or a
+webhook result without requiring a task-level `status`. The shared TypeScript type and these Zod schemas describe
+the SDK's current pin; use the parser above for older release-specific checks.
+
+`GetMediaBuyDeliveryResponseSchema` still requires task status through its
+referenced `core/protocol-envelope.json`. The absence of `status` from the
+response document's own `required` list does not remove that inherited
+requirement. Use the shared body schema for ingestion, and the full response
+schema for a poll's protocol envelope. `MediaBuyDeliveryWebhookResultSchema`
+now retains the canonical required row fields, including `by_package`.
+
+## Envelope status and notification type are independent
+
+The parser accepts the selected release's task-status enum; it does not require
+`completed` for all reporting messages. For example, `notification_type:
+'delayed'` may accompany `status: 'working'` when a valid report is present.
+`delayed` itself is not a task status. A progress-only message without a report
+is not a delivery-data webhook.
+
+`notification_type: 'final'` concerns report scheduling; envelope `completed`
+does not mean the media buy has finished. Per-buy state remains in
+`media_buy_deliveries[].status`. This follows the protocol's
+[envelope/result distinction](https://github.com/adcontextprotocol/adcp/blob/v3.3.0-beta.0/docs/building/by-layer/L3/webhooks.mdx#payload-anatomy-envelope-vs-result).
+
+The protocol also requires receivers to ignore `aggregated_totals` in pushed
+reports as an authority source. The parser preserves that field for auditing
+when supplied; reconcile authoritative totals through a poll or per-delivery
+rows instead.
+
+For offline tooling that needs all raw JSON Schema diagnostics,
+`@adcp/sdk/schemas` also exports `getSchemaValidatorByRef`. Its default is
+fail-fast; complete diagnostics are an explicit option:
+
+```typescript
+import { getSchemaValidatorByRef } from '@adcp/sdk/schemas';
+const validate = getSchemaValidatorByRef(
+  'media-buy/media-buy-delivery-webhook-result.json',
+  '3.1',
+  undefined,
+  { allErrors: true },
+);
+```

package/docs/guides/DISCOVERY-CACHE-AND-SESSION-REUSE.md

@@ -162,6 +162,21 @@ Await every operation before the scope callback returns; the callback owns the s
 
 Inside a scope the endpoint probe, capability discovery, `tools/list` and tool calls share one negotiated session per identity. `closeScopedConnections()` closes the current MCP scope's sessions early and does nothing when no MCP scope is active (A2A connections are not scoped). Nested `withMCPConnectionScope` calls join the outer scope unless you pass `{ isolate: true }`.
 
+An implicit high-level task scope closes local transports without sending session
+`DELETE` when its final result is accepted `submitted`, `working`, `input-required`,
+`auth-required`, or `deferred` work. (`deferred` is a task/HITL result, not an MCP
+wire status.) The owning task's final result decides; an earlier nested result
+cannot change a completed owner's cleanup. Completed tasks keep normal session
+termination.
+
+An explicit `withMCPConnectionScope` workflow remains caller-owned: its final
+cleanup terminates its sessions even if a call inside returned `submitted` or
+`working`. End that callback only when you intend to relinquish those sessions.
+Implicit preservation means avoiding termination, not retaining a connection for
+resumption: local clients are closed and evicted, later calls open fresh sessions,
+and the seller owns expiration of its retained sessions. A preserved implicit
+scope can include discovery sessions as well as the dispatch session.
+
 ### One exception: the first legacy handoff
 
 For a seller on the pre-2026 MCP protocol era, the SDK negotiates with the v2 client first and then hands the call to the v1 client so 2025 Tasks keep working. That handoff is a cold cost the SDK cannot avoid: the first scope against such a seller opens one classification handshake plus one shared v1 session. Within the scope everything after that (probe aside) shares the v1 session, including `tools/list`, and the classification is remembered across scopes for five minutes, so a later scope opens only its own session. Modern-era sellers need a single negotiation per scope.