@adcp/sdk 16.0.0-beta.1 → 16.0.0-beta.3

package/dist/lib/v2/projection/creative-delivery.d.ts

@@ -78,16 +78,38 @@ export type CanonicalCreateMediaBuyRequest = Omit<CanonicalCreativeResponse<Crea
     packages?: CanonicalPackageRequest[];
 };
 type CanonicalReportingWebhook = NonNullable<CanonicalCreateMediaBuyRequest['reporting_webhook']>;
-type ReportingWebhookPreferences = Omit<CanonicalReportingWebhook, 'url' | 'authentication' | 'reporting_frequency'> & {
-    reporting_frequency?: CanonicalReportingWebhook['reporting_frequency'];
+/**
+ * Client-facing form of a wire reporting webhook `W`. Every field is optional:
+ * the SDK can supply the callback `url`, `reporting_frequency` and the
+ * `authentication` block from client configuration.
+ *
+ * `authentication` is optional even with a caller-supplied `url`. AdCP 3.3
+ * makes it optional on the wire when the seller signs webhooks under its
+ * profile (`webhook_signing.supported`), and the experimental 3.3 client sends
+ * the registration without it once it has negotiated that. Below 3.3 the wire
+ * still requires it: with `webhookUrlTemplate` configured the client throws
+ * rather than send a caller URL without credentials (it never pairs its own
+ * `webhookSecret` with a caller-controlled host), and request validation
+ * reports the missing field otherwise.
+ *
+ * Derived from `W` rather than restating its fields, so it accepts every
+ * reporting webhook the pinned schemas generate, whether they declare
+ * `authentication` required (3.2) or optional (3.3).
+ *
+ * Exported for the type tests only; not re-exported from the package root.
+ */
+export type ClientReportingWebhookInputFor<W extends {
+    url: string;
+    reporting_frequency: unknown;
+}> = Omit<W, 'url' | 'authentication' | 'reporting_frequency'> & {
+    url?: W['url'];
+    reporting_frequency?: W['reporting_frequency'];
+    /** Atomic: `schemes` and `credentials` always come from the same source. */
+    authentication?: W extends {
+        authentication?: infer A;
+    } ? (unknown extends A ? never : A) : never;
 };
-type ClientReportingWebhookInput = (ReportingWebhookPreferences & {
-    url?: never;
-    authentication?: CanonicalReportingWebhook['authentication'];
-}) | (ReportingWebhookPreferences & {
-    url: CanonicalReportingWebhook['url'];
-    authentication: CanonicalReportingWebhook['authentication'];
-});
+type ClientReportingWebhookInput = ClientReportingWebhookInputFor<CanonicalReportingWebhook>;
 /**
  * Client-facing create request. The SDK may supply the reporting callback URL
  * and its complete authentication block from client configuration; the wire

package/dist/lib/v2/projection/index.d.mts

@@ -43,7 +43,7 @@ export { projectV1ProductToV2, canonicalDeclarationFromBareId, resolveCanonicalF
 export type { V1ToV2Result, V1ToV2ProjectionOptions, BareFormatIdResolveOptions, LegacyFormatConversionContext, LegacyFormatConverter, LegacyFormatResolutionContext, LegacyFormatResolver, } from './v1-to-v2.mjs';
 export { projectV2ProductToV1 } from './v2-to-v1.mjs';
 export type { V2ToV1Result, V2ToV1ProjectionOptions, CanonicalFormatLegacyResolver, CanonicalFormatLegacyResolutionContext, CanonicalProductFormatLegacyResolutionContext, CanonicalCreativeFormatLegacyResolutionContext, CanonicalSelectorFormatLegacyResolutionContext, } from './v2-to-v1.mjs';
-export { canonicalFormatLegacyResolverFromRoutes, legacyRoutesForProduct, type CanonicalFormatLegacyRoute, type LegacyRoutesForProductOptions, } from './legacy-routes.mjs';
+export { canonicalFormatLegacyResolverFromRoutes, carryFormatOptionOrigins, legacyRoutesForProduct, type CanonicalFormatLegacyRoute, type LegacyRoutesForProductOptions, } from './legacy-routes.mjs';
 export { augmentProductWithFormatOptions, withFormatOptions, toCanonicalFormatOptionsWithRoutes, toAdditiveCanonicalProduct, withAdditiveCanonicalFormatOptions, toCanonicalOnlyProduct, toCanonicalOnlyResponse, type V2AugmentedProduct, type AdditiveCanonicalProduct, type CanonicalOnlyProduct, } from './augment-response.mjs';
 export { CanonicalFormat, audioDaastFormatDeclaration, audioHostedFormatDeclaration, audioVastFormatDeclaration, agentPlacementFormatDeclaration, canonicalFormatDeclaration, customFormatDeclaration, displayTagFormatDeclaration, legacyFormatRef, legacyFormatRefs, html5FormatDeclaration, imageCarouselFormatDeclaration, imageFormatDeclaration, nativeInFeedFormatDeclaration, productCard, productCardDetailed, responsiveCreativeFormatDeclaration, sellerRenderedStatefulDisplayFormatDeclaration, sponsoredPlacementFormatDeclaration, coordinatedPlacementsFormatDeclaration, videoHostedFormatDeclaration, videoVastFormatDeclaration, type CanonicalFormatDeclaration, type CanonicalFormatDeclarationFields, type CanonicalFormatKind, type CanonicalFormatParams, type FormatReferenceInput, type ProductCardDetailedFields, type ProductCardFields, } from './builders.mjs';
 export { packageRefsForFormatOptions, packageRefsForCapabilities, legacyFormatIdsFromOptions, tryLegacyFormatIdsFromOptions, legacyFormatIdsForFormatOption, legacyFormatIdsForCapability, lintPackageFormatSelectorDimensions, FormatOptionRefsLookupError, CapabilityIdsLookupError, type PackageFormatRefs, type PackageCapabilityRefs, type FormatOptionRef, type FormatOptionSelector, type FormatOptionRefsLookupErrorCode, type CapabilityIdsLookupErrorCode, type PackageFormatSelectorInput, type PackageFormatSelectorDimensionOptions, type FixedSizeDimensions, type PackageFormatSelectorDimensionDiagnosticCode, type PackageFormatSelectorDimensionDiagnostic, } from './write-side.mjs';

package/dist/lib/v2/projection/index.d.ts

@@ -43,7 +43,7 @@ export { projectV1ProductToV2, canonicalDeclarationFromBareId, resolveCanonicalF
 export type { V1ToV2Result, V1ToV2ProjectionOptions, BareFormatIdResolveOptions, LegacyFormatConversionContext, LegacyFormatConverter, LegacyFormatResolutionContext, LegacyFormatResolver, } from './v1-to-v2';
 export { projectV2ProductToV1 } from './v2-to-v1';
 export type { V2ToV1Result, V2ToV1ProjectionOptions, CanonicalFormatLegacyResolver, CanonicalFormatLegacyResolutionContext, CanonicalProductFormatLegacyResolutionContext, CanonicalCreativeFormatLegacyResolutionContext, CanonicalSelectorFormatLegacyResolutionContext, } from './v2-to-v1';
-export { canonicalFormatLegacyResolverFromRoutes, legacyRoutesForProduct, type CanonicalFormatLegacyRoute, type LegacyRoutesForProductOptions, } from './legacy-routes';
+export { canonicalFormatLegacyResolverFromRoutes, carryFormatOptionOrigins, legacyRoutesForProduct, type CanonicalFormatLegacyRoute, type LegacyRoutesForProductOptions, } from './legacy-routes';
 export { augmentProductWithFormatOptions, withFormatOptions, toCanonicalFormatOptionsWithRoutes, toAdditiveCanonicalProduct, withAdditiveCanonicalFormatOptions, toCanonicalOnlyProduct, toCanonicalOnlyResponse, type V2AugmentedProduct, type AdditiveCanonicalProduct, type CanonicalOnlyProduct, } from './augment-response';
 export { CanonicalFormat, audioDaastFormatDeclaration, audioHostedFormatDeclaration, audioVastFormatDeclaration, agentPlacementFormatDeclaration, canonicalFormatDeclaration, customFormatDeclaration, displayTagFormatDeclaration, legacyFormatRef, legacyFormatRefs, html5FormatDeclaration, imageCarouselFormatDeclaration, imageFormatDeclaration, nativeInFeedFormatDeclaration, productCard, productCardDetailed, responsiveCreativeFormatDeclaration, sellerRenderedStatefulDisplayFormatDeclaration, sponsoredPlacementFormatDeclaration, coordinatedPlacementsFormatDeclaration, videoHostedFormatDeclaration, videoVastFormatDeclaration, type CanonicalFormatDeclaration, type CanonicalFormatDeclarationFields, type CanonicalFormatKind, type CanonicalFormatParams, type FormatReferenceInput, type ProductCardDetailedFields, type ProductCardFields, } from './builders';
 export { packageRefsForFormatOptions, packageRefsForCapabilities, legacyFormatIdsFromOptions, tryLegacyFormatIdsFromOptions, legacyFormatIdsForFormatOption, legacyFormatIdsForCapability, lintPackageFormatSelectorDimensions, FormatOptionRefsLookupError, CapabilityIdsLookupError, type PackageFormatRefs, type PackageCapabilityRefs, type FormatOptionRef, type FormatOptionSelector, type FormatOptionRefsLookupErrorCode, type CapabilityIdsLookupErrorCode, type PackageFormatSelectorInput, type PackageFormatSelectorDimensionOptions, type FixedSizeDimensions, type PackageFormatSelectorDimensionDiagnosticCode, type PackageFormatSelectorDimensionDiagnostic, } from './write-side';

package/dist/lib/v2/projection/index.js

@@ -33,6 +33,7 @@ __export(projection_exports, {
   canonicalFormatDeclaration: () => import_builders.canonicalFormatDeclaration,
   canonicalFormatLegacyResolverFromCatalogSnapshots: () => import_catalog_snapshot.canonicalFormatLegacyResolverFromCatalogSnapshots,
   canonicalFormatLegacyResolverFromRoutes: () => import_legacy_routes.canonicalFormatLegacyResolverFromRoutes,
+  carryFormatOptionOrigins: () => import_legacy_routes.carryFormatOptionOrigins,
   coordinatedPlacementsFormatDeclaration: () => import_builders.coordinatedPlacementsFormatDeclaration,
   customFormatDeclaration: () => import_builders.customFormatDeclaration,
   displayTagFormatDeclaration: () => import_builders.displayTagFormatDeclaration,
@@ -111,6 +112,7 @@ var import_creative_delivery = require('./creative-delivery.js');
   canonicalFormatDeclaration,
   canonicalFormatLegacyResolverFromCatalogSnapshots,
   canonicalFormatLegacyResolverFromRoutes,
+  carryFormatOptionOrigins,
   coordinatedPlacementsFormatDeclaration,
   customFormatDeclaration,
   displayTagFormatDeclaration,

package/dist/lib/v2/projection/index.mjs

@@ -2,6 +2,7 @@ import { projectV1ProductToV2, canonicalDeclarationFromBareId, resolveCanonicalF
 import { projectV2ProductToV1 } from "./v2-to-v1.mjs";
 import {
   canonicalFormatLegacyResolverFromRoutes,
+  carryFormatOptionOrigins,
   legacyRoutesForProduct
 } from "./legacy-routes.mjs";
 import {
@@ -88,6 +89,7 @@ export {
   canonicalFormatDeclaration,
   canonicalFormatLegacyResolverFromCatalogSnapshots,
   canonicalFormatLegacyResolverFromRoutes,
+  carryFormatOptionOrigins,
   coordinatedPlacementsFormatDeclaration,
   customFormatDeclaration,
   displayTagFormatDeclaration,

package/dist/lib/v2/projection/legacy-routes.d.mts

@@ -81,4 +81,14 @@ export declare function legacyRoutesForProduct(productId: string, declarations:
  * must agree that the seller did not declare it.
  */
 export declare function formatOptionOriginFromRoutes(resolver: CanonicalFormatLegacyResolver | undefined, ref: FormatOptionReference, productId: string | undefined): FormatOptionOrigin | undefined;
+/**
+ * Make `resolver` report the format-option origins recorded by `sources`.
+ *
+ * A resolver built by {@link canonicalFormatLegacyResolverFromRoutes} carries
+ * each route's `seller_declared` origin, which `AgentClient` reads to rewrite
+ * options the seller never declared on the canonical wire. A resolver that
+ * wraps or composes it is a new function and would otherwise carry none.
+ * Returns `resolver` itself, so the call can wrap a composition inline.
+ */
+export declare function carryFormatOptionOrigins(resolver: CanonicalFormatLegacyResolver, ...sources: ReadonlyArray<CanonicalFormatLegacyResolver | undefined>): CanonicalFormatLegacyResolver;
 export declare function canonicalFormatLegacyResolverFromRoutes(routes: readonly CanonicalFormatLegacyRoute[]): CanonicalFormatLegacyResolver;

package/dist/lib/v2/projection/legacy-routes.d.ts

@@ -81,4 +81,14 @@ export declare function legacyRoutesForProduct(productId: string, declarations:
  * must agree that the seller did not declare it.
  */
 export declare function formatOptionOriginFromRoutes(resolver: CanonicalFormatLegacyResolver | undefined, ref: FormatOptionReference, productId: string | undefined): FormatOptionOrigin | undefined;
+/**
+ * Make `resolver` report the format-option origins recorded by `sources`.
+ *
+ * A resolver built by {@link canonicalFormatLegacyResolverFromRoutes} carries
+ * each route's `seller_declared` origin, which `AgentClient` reads to rewrite
+ * options the seller never declared on the canonical wire. A resolver that
+ * wraps or composes it is a new function and would otherwise carry none.
+ * Returns `resolver` itself, so the call can wrap a composition inline.
+ */
+export declare function carryFormatOptionOrigins(resolver: CanonicalFormatLegacyResolver, ...sources: ReadonlyArray<CanonicalFormatLegacyResolver | undefined>): CanonicalFormatLegacyResolver;
 export declare function canonicalFormatLegacyResolverFromRoutes(routes: readonly CanonicalFormatLegacyRoute[]): CanonicalFormatLegacyResolver;

package/dist/lib/v2/projection/legacy-routes.js

@@ -19,6 +19,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var legacy_routes_exports = {};
 __export(legacy_routes_exports, {
   canonicalFormatLegacyResolverFromRoutes: () => canonicalFormatLegacyResolverFromRoutes,
+  carryFormatOptionOrigins: () => carryFormatOptionOrigins,
   formatOptionOriginFromRoutes: () => formatOptionOriginFromRoutes,
   legacyRoutesForProduct: () => legacyRoutesForProduct,
   sameFormatOptionRef: () => sameFormatOptionRef,
@@ -204,6 +205,11 @@ function formatOptionOriginFromRoutes(resolver, ref, productId) {
   if (matching.some((entry) => entry.origin === void 0)) return void 0;
   return matching[0].origin;
 }
+function carryFormatOptionOrigins(resolver, ...sources) {
+  const carried = [resolver, ...sources].flatMap((source) => source ? originsByResolver.get(source) ?? [] : []);
+  if (carried.length > 0) originsByResolver.set(resolver, Object.freeze(carried));
+  return resolver;
+}
 function canonicalFormatLegacyResolverFromRoutes(routes) {
   const index = /* @__PURE__ */ new Map();
   const origins = [];
@@ -237,6 +243,7 @@ function canonicalFormatLegacyResolverFromRoutes(routes) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   canonicalFormatLegacyResolverFromRoutes,
+  carryFormatOptionOrigins,
   formatOptionOriginFromRoutes,
   legacyRoutesForProduct,
   sameFormatOptionRef,

package/dist/lib/v2/projection/legacy-routes.mjs

@@ -176,6 +176,11 @@ function formatOptionOriginFromRoutes(resolver, ref, productId) {
   if (matching.some((entry) => entry.origin === void 0)) return void 0;
   return matching[0].origin;
 }
+function carryFormatOptionOrigins(resolver, ...sources) {
+  const carried = [resolver, ...sources].flatMap((source) => source ? originsByResolver.get(source) ?? [] : []);
+  if (carried.length > 0) originsByResolver.set(resolver, Object.freeze(carried));
+  return resolver;
+}
 function canonicalFormatLegacyResolverFromRoutes(routes) {
   const index = /* @__PURE__ */ new Map();
   const origins = [];
@@ -208,6 +213,7 @@ function canonicalFormatLegacyResolverFromRoutes(routes) {
 }
 export {
   canonicalFormatLegacyResolverFromRoutes,
+  carryFormatOptionOrigins,
   formatOptionOriginFromRoutes,
   legacyRoutesForProduct,
   sameFormatOptionRef,

package/dist/lib/validation/schema-loader.js

@@ -48,6 +48,7 @@ __export(schema_loader_exports, {
   listValidatorKeys: () => listValidatorKeys,
   registerExternalSchemaRoot: () => registerExternalSchemaRoot,
   resolveBundleKey: () => resolveBundleKey,
+  resolveServedValidationVersion: () => resolveServedValidationVersion,
   schemaAllowsTopLevelField: () => schemaAllowsTopLevelField,
   toReleasePrecisionWire: () => toReleasePrecisionWire,
   unregisterExternalSchemaRoot: () => unregisterExternalSchemaRoot,
@@ -754,6 +755,29 @@ function hasSchemaBundle(version) {
     return false;
   }
 }
+const SERVED_RELEASE_MAJOR = /^(\d+)\.\d+(?:-[a-zA-Z0-9.-]+)?$/;
+const NUMERIC_PIN_MAJOR = /^(\d+)\.\d+/;
+function resolveServedValidationVersion(response, pinnedVersion) {
+  const pinMajor = NUMERIC_PIN_MAJOR.exec(pinnedVersion)?.[1];
+  if (pinMajor === void 0) return pinnedVersion;
+  try {
+    if (isExternalSchemaRootActive(pinnedVersion)) return pinnedVersion;
+  } catch {
+    return pinnedVersion;
+  }
+  const echoed = response !== null && typeof response === "object" ? response.adcp_version : void 0;
+  if (typeof echoed !== "string") return pinnedVersion;
+  const echoMajor = SERVED_RELEASE_MAJOR.exec(echoed)?.[1];
+  if (echoMajor === void 0 || echoMajor !== pinMajor) return pinnedVersion;
+  let pinnedRelease;
+  try {
+    pinnedRelease = toReleasePrecisionWire(pinnedVersion);
+  } catch {
+    return pinnedVersion;
+  }
+  if (echoed === pinnedRelease) return pinnedVersion;
+  return hasSchemaBundle(echoed) ? echoed : pinnedVersion;
+}
 const mcpToolSchemaCache = /* @__PURE__ */ new Map();
 const mcpToolSummaryCache = /* @__PURE__ */ new Map();
 function boundedMcpToolSummary(value) {
@@ -1019,6 +1043,7 @@ function cloneJsonValue(value) {
   listValidatorKeys,
   registerExternalSchemaRoot,
   resolveBundleKey,
+  resolveServedValidationVersion,
   schemaAllowsTopLevelField,
   toReleasePrecisionWire,
   unregisterExternalSchemaRoot,

package/dist/lib/validation/schema-loader.mjs

@@ -701,6 +701,29 @@ function hasSchemaBundle(version) {
     return false;
   }
 }
+const SERVED_RELEASE_MAJOR = /^(\d+)\.\d+(?:-[a-zA-Z0-9.-]+)?$/;
+const NUMERIC_PIN_MAJOR = /^(\d+)\.\d+/;
+function resolveServedValidationVersion(response, pinnedVersion) {
+  const pinMajor = NUMERIC_PIN_MAJOR.exec(pinnedVersion)?.[1];
+  if (pinMajor === void 0) return pinnedVersion;
+  try {
+    if (isExternalSchemaRootActive(pinnedVersion)) return pinnedVersion;
+  } catch {
+    return pinnedVersion;
+  }
+  const echoed = response !== null && typeof response === "object" ? response.adcp_version : void 0;
+  if (typeof echoed !== "string") return pinnedVersion;
+  const echoMajor = SERVED_RELEASE_MAJOR.exec(echoed)?.[1];
+  if (echoMajor === void 0 || echoMajor !== pinMajor) return pinnedVersion;
+  let pinnedRelease;
+  try {
+    pinnedRelease = toReleasePrecisionWire(pinnedVersion);
+  } catch {
+    return pinnedVersion;
+  }
+  if (echoed === pinnedRelease) return pinnedVersion;
+  return hasSchemaBundle(echoed) ? echoed : pinnedVersion;
+}
 const mcpToolSchemaCache = /* @__PURE__ */ new Map();
 const mcpToolSummaryCache = /* @__PURE__ */ new Map();
 function boundedMcpToolSummary(value) {
@@ -965,6 +988,7 @@ export {
   listValidatorKeys,
   registerExternalSchemaRoot,
   resolveBundleKey,
+  resolveServedValidationVersion,
   schemaAllowsTopLevelField,
   toReleasePrecisionWire,
   unregisterExternalSchemaRoot,

package/dist/lib/version.d.mts

@@ -1,7 +1,7 @@
 /**
  * AdCP SDK library version
  */
-export declare const LIBRARY_VERSION = "16.0.0-beta.1";
+export declare const LIBRARY_VERSION = "16.0.0-beta.3";
 /**
  * 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.0.0-beta.1";
+    readonly library: "16.0.0-beta.3";
     readonly adcp: "3.2.4";
     readonly compatibleVersions: readonly ["v2.5", "v2.6", "v3", "3.0.0", "3.0", "3.0.1", "3.0.2", "3.0.3", "3.0.4", "3.0.5", "3.0.6", "3.0.7", "3.0.8", "3.0.9", "3.0.10", "3.0.11", "3.0.12", "3.0.13", "3.0.14", "3.0.15", "3.0.16", "3.0.17", "3.0.18", "3.0.19", "3.0.20", "3.0.21", "3.0.22", "3.0.23", "3.0.24", "3.0.25", "3.1.0", "3.1", "3.1.1", "3.1.2", "3.1.3", "3.1.4", "3.1.5", "3.1.6", "3.1.7", "3.1.8", "3.1.9", "3.1.10", "3.1.11", "3.1.12", "3.1.13", "3.1.14", "3.1.15", "3.1.16", "3.1.17", "3.1.18", "3.1.19", "3.1.20", "3.1.21", "3.1.22", "3.1.23", "3.1.24", "3.2.1", "3.2", "3.2.2", "3.2.3", "3.2.4"];
-    readonly generatedAt: "2026-10-14T03:59:15.421Z";
+    readonly generatedAt: "2026-10-15T18:57:32.995Z";
 };
 /**
  * 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 = "16.0.0-beta.1";
+export declare const LIBRARY_VERSION = "16.0.0-beta.3";
 /**
  * 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.0.0-beta.1";
+    readonly library: "16.0.0-beta.3";
     readonly adcp: "3.2.4";
     readonly compatibleVersions: readonly ["v2.5", "v2.6", "v3", "3.0.0", "3.0", "3.0.1", "3.0.2", "3.0.3", "3.0.4", "3.0.5", "3.0.6", "3.0.7", "3.0.8", "3.0.9", "3.0.10", "3.0.11", "3.0.12", "3.0.13", "3.0.14", "3.0.15", "3.0.16", "3.0.17", "3.0.18", "3.0.19", "3.0.20", "3.0.21", "3.0.22", "3.0.23", "3.0.24", "3.0.25", "3.1.0", "3.1", "3.1.1", "3.1.2", "3.1.3", "3.1.4", "3.1.5", "3.1.6", "3.1.7", "3.1.8", "3.1.9", "3.1.10", "3.1.11", "3.1.12", "3.1.13", "3.1.14", "3.1.15", "3.1.16", "3.1.17", "3.1.18", "3.1.19", "3.1.20", "3.1.21", "3.1.22", "3.1.23", "3.1.24", "3.2.1", "3.2", "3.2.2", "3.2.3", "3.2.4"];
-    readonly generatedAt: "2026-10-14T03:59:15.421Z";
+    readonly generatedAt: "2026-10-15T18:57:32.995Z";
 };
 /**
  * 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.0.0-beta.1";
+const LIBRARY_VERSION = "16.0.0-beta.3";
 const ADCP_VERSION = "3.2.4";
 const ADCP_MAJOR_VERSION = 3;
 const COMPATIBLE_ADCP_VERSIONS = [
@@ -98,10 +98,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
   "3.2.4"
 ];
 const VERSION_INFO = {
-  library: "16.0.0-beta.1",
+  library: "16.0.0-beta.3",
   adcp: "3.2.4",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-10-14T03:59:15.421Z"
+  generatedAt: "2026-10-15T18:57:32.995Z"
 };
 function getAdcpVersion() {
   return ADCP_VERSION;

package/dist/lib/version.mjs

@@ -1,4 +1,4 @@
-const LIBRARY_VERSION = "16.0.0-beta.1";
+const LIBRARY_VERSION = "16.0.0-beta.3";
 const ADCP_VERSION = "3.2.4";
 const ADCP_MAJOR_VERSION = 3;
 const COMPATIBLE_ADCP_VERSIONS = [
@@ -65,10 +65,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
   "3.2.4"
 ];
 const VERSION_INFO = {
-  library: "16.0.0-beta.1",
+  library: "16.0.0-beta.3",
   adcp: "3.2.4",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-10-14T03:59:15.421Z"
+  generatedAt: "2026-10-15T18:57:32.995Z"
 };
 function getAdcpVersion() {
   return ADCP_VERSION;

package/docs/TYPE-SUMMARY.md

@@ -1,7 +1,7 @@
 # AdCP Type Summary
 
-> Generated at: 2026-10-14
-> @adcp/sdk v16.0.0-beta.1
+> Generated at: 2026-10-15
+> @adcp/sdk v16.0.0-beta.3
 
 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`.
 
@@ -49,6 +49,11 @@ interface A2ALegacyCompatOptions {
 }
 
 interface TransportOptions {
+  // Defaults to 4 MiB (DEFAULT_MAX_RESPONSE_BYTES); only 0 opts out
+  // (Infinity / negatives fall back to the default).
+  // SSE is bounded per event plus `maxResponseBytes * 2` cumulative per call.
+  // Over-cap responses throw ResponseTooLargeError; nothing is truncated.
+  // A per-call `transport` replaces this object; it does not merge.
   maxResponseBytes?: number;
   trustedFetchFn?: typeof fetch;
   allowPrivateIp?: boolean;

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

@@ -55,7 +55,7 @@ The key is a SHA-256 over:
 | configured `adcpVersion` / `wireAdcpVersion`         | negotiated version                                                                                                     |
 | every non-correlation, non-credential header         | unknown `x-*` tenant / routing / policy headers can select a different upstream view, so they fail closed into the key. This includes `baggage`, **ambient OpenTelemetry baggage included** |
 | request-signing identity and policy                  | `kind`, `kid`, `alg`, agent URL and signing policy; never the private key                                              |
-| effective `allowPrivateIp`, `maxResponseBytes`       | the transport policy the evidence was gathered under (per-call `transport` overrides included)                         |
+| configured `allowPrivateIp`, `maxResponseBytes`      | the transport policy the evidence was gathered under (per-call `transport` overrides included). These are the values the caller *configured*, not the effective ones: an unset `maxResponseBytes` keys as "unset" rather than as the 4 MiB default, so entries written before the default landed stay reusable. The MCP connection cache keys the *resolved* cap instead — see [Reusable MCP connections](#reusable-mcp-connections) |
 
 Not part of the key: correlation headers (`x-request-id`, `x-correlation-id`, `traceparent`, ...), and credential header values (`Authorization`, `x-adcp-auth`) — OAuth and `auth_token` credentials are also owned by `authIdentity`; a token rotation for the same authorization scope keeps the entry. **Choose `authIdentity` at least as narrow as the credential's authorization scope.** Change the identity or invalidate the cache when permissions change or access is revoked; use a distinct identity for anonymous access. Two principals must never share an identity. Keys are hashes and never contain the identity, token or header values.
 
@@ -101,7 +101,7 @@ Unlike [`primeCapabilities`](../TYPE-SUMMARY.md) — which stays client-bound an
 
 This behavior applies by default, including calls that pass a signal or timeout outside a connection scope. The process-wide legacy/OAuth session cache retains at most 20 connections per cache with LRU eviction and has no idle expiry. For request workflows with many distinct credentials, use a scope to bound session lifetime. At process shutdown, `closeConnections()` from `@adcp/sdk/advanced` closes the process-wide connections.
 
-A reusable session is keyed only by what changes the _connection_: endpoint, credential, tenant / routing headers, signing identity, `allowPrivateIp`, a caller-injected fetch, and the workflow scope. These no longer choose or split a session:
+A reusable session is keyed only by what changes the _connection_: endpoint, credential, tenant / routing headers, signing identity, `allowPrivateIp`, `maxResponseBytes`, a caller-injected fetch, and the workflow scope. These no longer choose or split a session:
 
 - **Correlation headers**: `traceparent`, `tracestate`, `x-request-id`, `x-correlation-id`, `x-trace-id`, `x-span-id`, `x-debug-id`, `x-client-request-id`, `x-b3-*`, `x-amzn-trace-id`, `x-cloud-trace-context`, `x-datadog-*`, `sentry-trace`, and vendor-prefixed `x-<vendor>-request-id` / `-correlation-id` / `-trace-id` / `-span-id` / `-debug-id`. Names suggesting credentials or tenant/routing identity (including `auth`, `token`, `tenant`, `account`, `workspace`, `seat`, `advertiser`, `publisher`, `buyer` and `seller`) are never treated as correlation. **`baggage` stays in the key**: it can carry tenant or routing members. Any header outside the list above also stays in the key (fail closed).
 - **`AbortSignal`** and **`requestTimeoutMs`**: they bound a call.
@@ -114,6 +114,7 @@ Isolation properties:
 - A caller that joins another caller's in-flight connect waits under its own signal and timeout. If the creator cancels the connect, the joiner retries for itself, with at most two retries after foreign aborts.
 - A caller-injected `fetchFn` (a per-call network trust boundary) keeps its own one-shot session outside a connection scope; inside a scope its identity is part of the key.
 - Connections are never shared across credentials, tenant headers, signing identities or `allowPrivateIp` settings.
+- Connections are never shared across different `maxResponseBytes` values either. The response cap is decided once per request, and a session's standalone `GET` event-stream listener issues exactly one request — at connect time — so it carries whatever policy opened the connection for the life of that connection. Sharing across policies would let one `maxResponseBytes: 0` call hand an uncapped listener to every later caller. The key uses the *resolved* cap, so an explicit `4 * 1024 * 1024` and an unset value are the same policy and share a session; `0` and any other number each get their own. Varying the cap per call therefore costs a session per distinct value against the same agent, against a 20-entry LRU — prefer a single client-level value where you can, or pin the session with `withMCPConnectionScope` where continuity matters.
 
 ### Public connection scope
 

package/docs/guides/REPORTING-LEDGER.md

@@ -1017,9 +1017,9 @@ setInterval(() => {
   BigQuery's server-side `jobTimeoutMs` is not used: for a local-file load the
   official client builds `configuration.load` from the load options and cannot
   set job-level fields, and BigQuery silently drops `labels` and `jobTimeoutMs`
-  found inside `configuration.load`. (Staging the file in GCS and submitting the load with
-  `bigquery.createJob` can set both; the sink does not stage files.) For the
-  same reason the `labels` option has no effect (it warns once per process and
+  found inside `configuration.load`. (Staging the file in GCS and submitting
+  the load with `bigquery.createJob` can set both; the sink does not stage
+  files.) For the same reason the `labels` option has no effect (it warns once per process and
   is deprecated). To attribute load cost, query
   `` `region-<location>`.INFORMATION_SCHEMA.JOBS_BY_PROJECT `` (needs
   `bigquery.jobs.listAll`; about 180 days of history), filtering on
@@ -1067,6 +1067,16 @@ setInterval(() => {
   rejects after clearing the sink (it could not unregister the consumer), call
   it again before restarting workers. Re-run `REPORTING_WAREHOUSE_SINK_MIGRATION`
   after upgrading: it adds the `reset_generation` column.
+- Upgrading from 15.9.0: stop every 15.9.0 sink worker before starting newer
+  ones, then re-apply `REPORTING_WAREHOUSE_SINK_MIGRATION`. A 15.9.0 worker
+  cancels a load at its deadline, so one running beside a newer worker on the
+  same sink can cancel a job the newer worker is waiting on. The job then ends
+  `DONE` with an error and the attempt advances. Rows do not duplicate, but
+  convergence slows. Also set `location` to the dataset's location: without it
+  a replay lookup of a load job returns 404 for datasets outside the US and EU
+  multi-regions, and the sink uploads again, gets a 409, and fails with a
+  "check projectId and location" error. The sink warns once per process when
+  `location` is unset.
 - Stop old sink workers before relying on these overlap guarantees. If an
   earlier overlapping run left a plan whose starting cursor differs from the
   committed cursor, the sink rejects it before loading. Reconcile the retained
@@ -1230,7 +1240,7 @@ Managed-only changes are lifecycle candidates in their own right. A settlement,
 
 `MAX_MATERIALIZATIONS_PER_ACCOUNT` and `MAX_RECEIPTS_PER_CONSUMER` are lifetime counts by default. Because managed evidence is immutable, a long-lived account eventually reaches them and then stops planning materializations and refuses every receipt with no way back. Construct the store with `new PostgresReportingManagedDeliveryStore(pool, { evidenceRetentionDays })` to make the caps active-scope: only evidence recorded inside that window counts against them, and `pruneExpiredEvidence({ account_id, limit })` deletes what has fallen outside it — never anything still inside the window, never a `pending` or leased materialization, and never a receipt batch inside its own replay retention. Retention has a floor: at least the 30-day receipt replay retention, and at least the strongest durable status or resource-retention horizon registered for the database. Adoption and binding installation exclusively lock the migration-created policy sentinel before account/binding locks; settlement, revocation claim, and pruning hold shared locks on it through their writes. A stronger promise therefore cannot land between a weaker check and its write, while unrelated hot-path readers remain concurrent. Pruning genuinely does its selection before taking the account lock, and asks which receipts a live replay row still names by expanding those rows once rather than posing a containment question per candidate — a shape no index could serve, which held the lock long enough to fail concurrent Core writes with 55P03. Because that selection is unlocked it is a proposal rather than a verdict: every victim is revalidated under the account lock against current live replay rows, surviving receipts and unexpired resources before it is deleted, so a replay that commits in the gap keeps the receipt it promised to reproduce. The revalidation is narrowed to the candidates' own consumers and keys, so the lock still holds no per-candidate scan. The registry lock is held to commit inside the transaction that acts on it, and a precondition such as the installed-window check runs inside that same transaction so a refusal rolls the write back rather than leaving a durable promise nobody validated, so an install cannot read an empty registry while a narrower promise is being registered, and a prune cannot approve a horizon another replica is about to widen. Pruning deletes and tombstones in one statement against one frozen cutoff, so a moving boundary can never leave a deleted row without its permanent identity. Successive prunes demote the tombstones they supersede, so a subject has exactly one tombstone still claiming to be its leaf and a chain pruned twice resolves the same way every time. Re-presenting a pruned receipt byte-identically answers `unchanged` with the instant the tombstone kept, resolves that receipt's own tombstone before any rule about its subject — so an exact re-presentation is not refused as new content for a settled subject — replays the same answer under the same idempotency key by rehydrating from the tombstone when the body is gone, counts as already-resolved for the batch's duplicate-subject rule, and never recreates the row: recreating it restarted the retention clock, undid the storage the prune reclaimed, and moved the published `received_at` to a moment the consumer never filed anything at. A pruned receipt ID can never bind different content, a subject whose accepted leaf expired can never reopen — the read projection consults tombstones, not just live rows — and materialization attempt history survives as a compact terminal record, so a revision that exhausted its attempts or already succeeded does not restart at attempt 1 once its rows age out. Both conclusions — the acceptance and the fact a delivery succeeded — are folded into the live, filtered and lifecycle projections alike. Counters describe exactly the records the response emits, never more and never less, so a buyer recomputing the association cannot see `ASSOCIATED_HISTORY_INCOMPLETE`; retention therefore refuses to prune an acceptance while the resource it accepts is still readable, which is what keeps a `complete` period from having nothing to show for itself. An acceptance carries the consumer that gave it, so one consumer's pruned acceptance never settles the obligation on another's behalf — including the anonymous fail-safe consumer, which owns no acceptances at all. Pruning also removes the expired replay row before the receipts it names, keeps any receipt a surviving replay row still references — a later batch can name an earlier receipt — and keeps any materialization whose resource is still readable or that a retained receipt names as its evidence. An adjustment receipt names no materialization — it names the revision it corrects — so the readable-resource hold matches on that revision as well, or a period whose revision resource was still readable lost the adjustment acceptance behind its own `complete`. Run it from the same scheduler that runs the worker. Lifecycle receipt reads are driven from the obligation's own subjects into a `(subject_id, receipt_kind, recorded_at)` index rather than asking the global receipt table which of its rows belong to an obligation — a question that supplies neither account nor consumer, so every due obligation re-scanned the whole receipt history. The managed state digest, the obligated-consumer roster read and the permanent delivery tombstones do the same — consumer statuses carry an `obligation_id` index and materialization tombstones an `(obligation_id, reached_success, reached_success_at)` one — because that digest is read inside the apply transaction while it holds the account lock: a scan there is a scan with the lock held, which pushed concurrent Core writes past their lock timeout and failed them with 55P03.
 
-The managed tables are additive and do not alter the Core tables. This is the schema boundary coordinated with #2943: that work owns transactional reporting notification/activity intent and the existing webhook delivery/credential plane. Managed Delivery does not create a second webhook sender, outbox, credential store, or subscriber model. Apply both feature migrations after the Core migration in either order; each owns separate tables and both reuse the Core authority.
+The managed tables are additive and do not alter the Core tables. This is the schema boundary coordinated with the reporting notification work: that work owns transactional reporting notification/activity intent and the existing webhook delivery/credential plane. Managed Delivery does not create a second webhook sender, outbox, credential store, or subscriber model. Apply both feature migrations after the Core migration in either order; each owns separate tables and both reuse the Core authority.
 
 ## Transactional reporting notifications and account activity
 
@@ -1749,7 +1759,7 @@ reconciliation and fails closed if both are supplied, preventing double fire;
 the port's pending rows, rather than `listPendingTransitions()`, own retry.
 
 The activity table is deliberately separate from Core revision and obligation
-rows. Managed Delivery/Reconciled Billing work in #2944 can add immutable
+rows. Managed Delivery/Reconciled Billing work can add immutable
 materialization and receipt tables without changing this transition identity,
 queue schema, or migration ordering.
 

package/docs/guides/REPORTING-OPERATIONS.md

@@ -121,7 +121,14 @@ service runs for you. See
    cannot hold the table indefinitely.
 5. **Warehouse sink.** Apply `REPORTING_WAREHOUSE_SINK_MIGRATION`, create the
    tables, and the `current_rows` view, then schedule `runOnce`. Point analysts
-   at `current_rows`.
+   at `current_rows`. Set the sink's `location` to the dataset's location: replay
+   lookups of load jobs need it outside the US and EU multi-regions, and the sink
+   warns once per process when it is unset. When upgrading from 15.9.0, stop
+   every 15.9.0 sink worker before starting newer ones, then re-apply
+   `REPORTING_WAREHOUSE_SINK_MIGRATION`. A 15.9.0 worker cancels a load at its
+   deadline, so one running beside a newer worker on the same sink can cancel a
+   job the newer worker is waiting on; the job ends `DONE` with an error and the
+   attempt advances. Rows do not duplicate, but convergence slows.
 6. **Retention.** Enable `retention` last, after confirming the advertised
    `status_retention_days` is the window you intend to keep. Retirement deletes
    rows and ledger records for whole periods and cannot be undone. Keep backups
@@ -344,7 +351,7 @@ What it checks:
   and job ID unchanged and that table's persisted deadline grown, the job must
   end `DONE` without an error (the sink never cancels it), and later runs under
   the same sink name must converge with no duplicate rows, the same job ID and
-  no second upload. A #3234 scenario runs a sink whose upload of a 50,000-row
+  no second upload. A slow-upload scenario runs a sink whose upload of a 50,000-row
   batch outlasts its 1-second deadline and asserts that it converges within 8
   runs, loads every row exactly once, never changes the job ID, and never
   starts an upload after the job exists (a link fast enough to beat the
@@ -356,11 +363,10 @@ What it checks:
   it; in practice it accepts the cancel and lets the load finish, which is why
   the sink never cancels a load and finds it by job ID instead.
 - **Overlapping runs** (`INFO`, never a failure). Two concurrent `runOnce()`
-  calls over one pending batch, and a deterministic reproduction of #3196: one
+  calls over one pending batch, and a deterministic reproduction of the stale-plan race: one
   run reads its sink state, another completes the batch and a new revision
   commits, then the first resumes. Without the fence the first run reloads
-  revisions the second already loaded (duplicate rows); with the fence from
-  PR #3197 it rejects as stale and nothing duplicates. Read the verdict in the
+  revisions the second already loaded (duplicate rows); with the plan fence it rejects as stale and nothing duplicates. Read the verdict in the
   report; the exit status does not depend on it.
 - **Cross-project.** Set `GCP_CLIENT_PROJECT` to a project other than
   `GCP_BQ_PROJECT`. Load jobs are then created in the destination project, and
@@ -446,15 +452,15 @@ export GCS_BUCKET=my-test-bucket GCS_PREFIX=adcp-reporting-validation
 npm run validate:reporting-gcp -- --yes
 ```
 
-Against a pull request branch (for example #3197), keep running the script from
+Against a pull request branch (replace `<n>` with its number), keep running the script from
 `main` and point it at a second built checkout, so a branch cut before this
 script existed still works:
 
 ```bash
-git fetch origin pull/3197/head:pr-3197
-git worktree add ../adcp-client-pr-3197 pr-3197
-(cd ../adcp-client-pr-3197 && npm ci && npm run build)
-ADCP_SDK_ROOT=../adcp-client-pr-3197 npm run validate:reporting-gcp -- --yes
+git fetch origin pull/<n>/head:pr-<n>
+git worktree add ../adcp-client-pr-<n> pr-<n>
+(cd ../adcp-client-pr-<n> && npm ci && npm run build)
+ADCP_SDK_ROOT=../adcp-client-pr-<n> npm run validate:reporting-gcp -- --yes
 ```
 
 The same environment applies. The run ends with a `PASS`, `FAIL` and `INFO`
@@ -462,7 +468,7 @@ report and a markdown block (project and bucket names masked) to paste into
 the PR. The exit status is 0 with no `FAIL`, 1 with any `FAIL`, and 2 for a
 configuration problem or a missing `--yes`. Results of the overlap probes are
 `INFO` on purpose: on `main` expect the stale-run probe to report duplicates,
-and on PR #3197 expect it to report none.
+and on a branch with the plan fence expect it to report none.
 
 `test/lib/reporting-gcp-validation-pg.test.js` drives the script's core against
 in-memory BigQuery and Storage doubles and a real PostgreSQL, so the logic,

package/docs/guides/UNIVERSAL-MACRO-COMPILATION.md

@@ -96,3 +96,41 @@ Do not create a global mapping based only on a token's spelling. A token such as
 cookie for another, and an account identifier for a third. Scope every mapping
 to its source dialect and keep the supporting vendor documentation with the
 registry entry.
+
+Vendor-scoped TCF mappings retain the complete receiving vendor ID: map
+`${GDPR_CONSENT_755}` to `{GDPR_CONSENT_755}`, never to unscoped
+`{GDPR_CONSENT}` or another vendor's token. The suffix must be a positive
+decimal integer without leading zeros. `{ADDTL_CONSENT}` is also supported,
+with the same source-dialect and documentation requirements. Its CMP-provided
+value is opaque; the helper does not generate consent or modify provider lists.
+
+For the return translation, supply exact native mappings:
+
+```typescript
+import { translateUniversalMacros } from '@adcp/sdk/substitution';
+
+const translated = translateUniversalMacros(
+  'https://pixel.vendor.example/i?gdpr={GDPR}&c={GDPR_CONSENT_755}&a={ADDTL_CONSENT}',
+  {
+    '{GDPR}': { native: '${GDPR}' },
+    '{GDPR_CONSENT_755}': { native: '${GDPR_CONSENT_755}' },
+    '{ADDTL_CONSENT}': { native: '${ADDTL_CONSENT}' },
+  }
+);
+```
+
+Existing native tokens pass through unchanged. The emitted URL may contain at
+most one scoped TCF token, including pre-existing tokens and native aliases
+identified by the supplied mappings. After dropping unsupported parameters,
+multiple occurrences throw `MultipleVendorConsentMacrosError` with code
+`multiple_vendor_consent_macros` and the second token in canonical AdCP form.
+Additional Consent does not count toward that limit. Concrete `value` mappings
+are encoded and reported in `frozen_consent_macros`; missing consent mappings
+appear in `dropped_consent_macros`. When an unscoped target requires an unknown
+vendor ID, use `'{GDPR_CONSENT}': { value: '' }` and translate `{GDPR}`
+independently rather than guessing an ID.
+
+These helpers implement the AdCP 3.3 translation contract. Generated protocol
+types and declaration/capability validation still follow the SDK's pinned schema
+release. Helper support alone does not establish a resolver's declared support
+for a scoped token or Additional Consent.

package/docs/guides/VALIDATE-YOUR-AGENT.md

@@ -668,6 +668,18 @@ try {
 
 These policies follow the language-neutral fixture ratified in [AdCP #6674](https://github.com/adcontextprotocol/adcp/issues/6674).
 
+The AdCP 3.3 fixture also covers vendor-scoped `{GDPR_CONSENT_<gvl_id>}` and
+`{ADDTL_CONSENT}`. Preserve the receiving vendor ID and treat Additional Consent
+as opaque CMP data. Both participate in dropped/frozen consent diagnostics.
+After unsupported parameters are dropped, a URL with multiple scoped TCF
+occurrences throws `MultipleVendorConsentMacrosError` (exported from both
+`@adcp/sdk` and `@adcp/sdk/substitution`), with code
+`multiple_vendor_consent_macros` and the canonical second token in `macro`.
+Existing native tokens and verified native aliases count; encoded concrete
+values and Additional Consent do not. See the
+[compilation guide](UNIVERSAL-MACRO-COMPILATION.md) for mapping and schema-version
+boundaries.
+
 ---
 
 ## The fork-matrix: canonical adapter → compliance

package/docs/llms.txt

@@ -1,7 +1,7 @@
 # Ad Context Protocol (AdCP)
 
-> Generated at: 2026-10-14
-> Library: @adcp/sdk v16.0.0-beta.1
+> Generated at: 2026-10-15
+> Library: @adcp/sdk v16.0.0-beta.3
 > 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.