@adcp/sdk 17.0.0-beta.0 → 17.0.0-beta.1

package/dist/lib/utils/envelope-status-compat.mjs

@@ -25,7 +25,7 @@ function injectLegacyEnvelopeStatus(response, options) {
     return response;
   }
   if (options?.toolName && STATUS_FREE_SYNC_RESPONSE_TOOLS.has(options.toolName)) return response;
-  if (options?.toolName && MEDIA_BUY_STATUS_RESPONSE_TOOLS.has(options.toolName) && allowsDeprecatedMediaBuyStatus(response) && isMediaBuySuccessStatusForCompat(response)) {
+  if (options?.toolName && MEDIA_BUY_STATUS_RESPONSE_TOOLS.has(options.toolName) && allowsDeprecatedMediaBuyStatus(response) && isMediaBuySuccessStatusForCompat(response, options)) {
     const mediaBuyStatus = response.status;
     return {
       ...response,
@@ -50,16 +50,16 @@ function normalizeLegacyMediaBuyStatusForReturn(response, options) {
   if (!response || typeof response !== "object" || Array.isArray(response)) {
     return response;
   }
-  if (!options?.toolName || !MEDIA_BUY_STATUS_RESPONSE_TOOLS.has(options.toolName) || !allowsDeprecatedMediaBuyStatus(response) || !isMediaBuySuccessStatusForCompat(response)) {
+  if (!options?.toolName || !MEDIA_BUY_STATUS_RESPONSE_TOOLS.has(options.toolName) || !allowsDeprecatedMediaBuyStatus(response) || !isMediaBuySuccessStatusForCompat(response, options)) {
     return response;
   }
-  const status = getAuthoritativeMediaBuyStatus(response);
+  const status = getAuthoritativeMediaBuyStatus(withRequestedVersion(response, options));
   if (!status || response.media_buy_status === status) return response;
   return { ...response, media_buy_status: status };
 }
-function isMediaBuySuccessStatusForCompat(response) {
+function isMediaBuySuccessStatusForCompat(response, options) {
   const status = response.status;
-  if (getAuthoritativeMediaBuyStatus(response) !== status) return false;
+  if (getAuthoritativeMediaBuyStatus(withRequestedVersion(response, options)) !== status) return false;
   if (typeof response.media_buy_status === "string" && response.media_buy_status !== status) {
     return false;
   }
@@ -74,6 +74,12 @@ function allowsDeprecatedMediaBuyStatus(payload) {
   if (typeof major === "number") return major === 3;
   return true;
 }
+function withRequestedVersion(payload, options) {
+  const requested = options?.adcpVersion;
+  if (typeof requested !== "string" || requested.length === 0) return payload;
+  if (typeof payload.adcp_version === "string" || typeof payload.adcp_major_version === "number") return payload;
+  return { ...payload, adcp_version: requested };
+}
 export {
   STATUS_FREE_SYNC_RESPONSE_TOOLS,
   injectLegacyEnvelopeStatus,

package/dist/lib/utils/response-unwrapper.js

@@ -218,9 +218,10 @@ function unwrapProtocolResponse(protocolResponse, toolName, protocol, options) {
     const schema = TOOL_RESPONSE_SCHEMAS[toolName];
     if (schema) {
       const { _message: _msg, ...stripped } = unwrapped;
+      const compatOptions = { toolName, adcpVersion: options?.responseAdcpVersion };
       const dataToValidate = prepareResponseForSchemaValidation(
         toolName,
-        (0, import_envelope_status_compat.injectLegacyEnvelopeStatus)(stripped, { toolName }),
+        (0, import_envelope_status_compat.injectLegacyEnvelopeStatus)(stripped, compatOptions),
         options?.responseAdcpVersion
       );
       const result = schema.safeParse(dataToValidate);
@@ -233,7 +234,7 @@ function unwrapProtocolResponse(protocolResponse, toolName, protocol, options) {
               const { status: _s, ...rest } = validated2;
               validated2 = rest;
             } else {
-              validated2 = restoreLegacyMediaBuyStatusForReturn(validated2, stripped, dataToValidate, toolName);
+              validated2 = restoreLegacyMediaBuyStatusForReturn(validated2, stripped, dataToValidate, compatOptions);
             }
             validated2 = restoreCompatibilityVersionForReturn(validated2, stripped, dataToValidate);
             if (!("adcp_version" in stripped)) {
@@ -260,7 +261,7 @@ function unwrapProtocolResponse(protocolResponse, toolName, protocol, options) {
         const { status: _s, ...rest } = validated;
         validated = rest;
       } else {
-        validated = restoreLegacyMediaBuyStatusForReturn(validated, stripped, dataToValidate, toolName);
+        validated = restoreLegacyMediaBuyStatusForReturn(validated, stripped, dataToValidate, compatOptions);
       }
       validated = restoreCompatibilityVersionForReturn(validated, stripped, dataToValidate);
       if (!("adcp_version" in stripped)) {
@@ -279,16 +280,18 @@ function restoreCompatibilityVersionForReturn(validated, original, compat) {
   }
   return validated;
 }
-function restoreLegacyMediaBuyStatusForReturn(validated, original, compat, toolName) {
+function restoreLegacyMediaBuyStatusForReturn(validated, original, compat, compatOptions) {
+  const { toolName } = compatOptions;
   if ((toolName === "create_media_buy" || toolName === "update_media_buy") && typeof original.media_buy_id === "string" && typeof original.status === "string" && compat.status === "completed" && typeof compat.media_buy_status === "string") {
     return (0, import_envelope_status_compat.normalizeLegacyMediaBuyStatusForReturn)(
       { ...validated, status: original.status },
-      { toolName }
+      compatOptions
     );
   }
-  return (0, import_envelope_status_compat.normalizeLegacyMediaBuyStatusForReturn)(validated, {
-    toolName
-  });
+  return (0, import_envelope_status_compat.normalizeLegacyMediaBuyStatusForReturn)(
+    validated,
+    compatOptions
+  );
 }
 function filterInvalidProducts(schema, data) {
   const { z } = require("zod");
@@ -499,7 +502,7 @@ function isAdcpSuccess(response, taskName, responseAdcpVersion) {
     const { _message: _, ...stripped } = response ?? {};
     const dataToValidate = prepareResponseForSchemaValidation(
       taskName,
-      (0, import_envelope_status_compat.injectLegacyEnvelopeStatus)(stripped, { toolName: taskName }),
+      (0, import_envelope_status_compat.injectLegacyEnvelopeStatus)(stripped, { toolName: taskName, adcpVersion: responseAdcpVersion }),
       responseAdcpVersion
     );
     const result = schema.safeParse(dataToValidate);

package/dist/lib/utils/response-unwrapper.mjs

@@ -192,9 +192,10 @@ function unwrapProtocolResponse(protocolResponse, toolName, protocol, options) {
     const schema = TOOL_RESPONSE_SCHEMAS[toolName];
     if (schema) {
       const { _message: _msg, ...stripped } = unwrapped;
+      const compatOptions = { toolName, adcpVersion: options?.responseAdcpVersion };
       const dataToValidate = prepareResponseForSchemaValidation(
         toolName,
-        injectLegacyEnvelopeStatus(stripped, { toolName }),
+        injectLegacyEnvelopeStatus(stripped, compatOptions),
         options?.responseAdcpVersion
       );
       const result = schema.safeParse(dataToValidate);
@@ -207,7 +208,7 @@ function unwrapProtocolResponse(protocolResponse, toolName, protocol, options) {
               const { status: _s, ...rest } = validated2;
               validated2 = rest;
             } else {
-              validated2 = restoreLegacyMediaBuyStatusForReturn(validated2, stripped, dataToValidate, toolName);
+              validated2 = restoreLegacyMediaBuyStatusForReturn(validated2, stripped, dataToValidate, compatOptions);
             }
             validated2 = restoreCompatibilityVersionForReturn(validated2, stripped, dataToValidate);
             if (!("adcp_version" in stripped)) {
@@ -234,7 +235,7 @@ function unwrapProtocolResponse(protocolResponse, toolName, protocol, options) {
         const { status: _s, ...rest } = validated;
         validated = rest;
       } else {
-        validated = restoreLegacyMediaBuyStatusForReturn(validated, stripped, dataToValidate, toolName);
+        validated = restoreLegacyMediaBuyStatusForReturn(validated, stripped, dataToValidate, compatOptions);
       }
       validated = restoreCompatibilityVersionForReturn(validated, stripped, dataToValidate);
       if (!("adcp_version" in stripped)) {
@@ -253,16 +254,18 @@ function restoreCompatibilityVersionForReturn(validated, original, compat) {
   }
   return validated;
 }
-function restoreLegacyMediaBuyStatusForReturn(validated, original, compat, toolName) {
+function restoreLegacyMediaBuyStatusForReturn(validated, original, compat, compatOptions) {
+  const { toolName } = compatOptions;
   if ((toolName === "create_media_buy" || toolName === "update_media_buy") && typeof original.media_buy_id === "string" && typeof original.status === "string" && compat.status === "completed" && typeof compat.media_buy_status === "string") {
     return normalizeLegacyMediaBuyStatusForReturn(
       { ...validated, status: original.status },
-      { toolName }
+      compatOptions
     );
   }
-  return normalizeLegacyMediaBuyStatusForReturn(validated, {
-    toolName
-  });
+  return normalizeLegacyMediaBuyStatusForReturn(
+    validated,
+    compatOptions
+  );
 }
 function filterInvalidProducts(schema, data) {
   const { z } = require2("zod");
@@ -473,7 +476,7 @@ function isAdcpSuccess(response, taskName, responseAdcpVersion) {
     const { _message: _, ...stripped } = response ?? {};
     const dataToValidate = prepareResponseForSchemaValidation(
       taskName,
-      injectLegacyEnvelopeStatus(stripped, { toolName: taskName }),
+      injectLegacyEnvelopeStatus(stripped, { toolName: taskName, adcpVersion: responseAdcpVersion }),
       responseAdcpVersion
     );
     const result = schema.safeParse(dataToValidate);

package/dist/lib/v2/projection/creative-delivery.js

@@ -725,7 +725,6 @@ function projectInlineMarkupToLegacyHtml(assetsValue, definition, operation, cre
         {
           asset_type: "html",
           content: asset.markup,
-          ...renderedSizeFields(asset),
           ...asset.provenance !== void 0 && { provenance: asset.provenance }
         }
       ];
@@ -787,15 +786,31 @@ function projectCreative(creative, formatId, legacyFormatDefinitions, operation
     }
   }
   if (Object.hasOwn(creative, "assets")) {
-    next.assets = projectLegacyAssetKeys(
-      projectInlineMarkupToLegacyHtml(
-        creative.assets,
-        markupDefinition,
-        operation,
-        typeof creative.creative_id === "string" ? creative.creative_id : "(unknown)"
-      ),
-      definition
+    const legacyAssets = projectInlineMarkupToLegacyHtml(
+      creative.assets,
+      markupDefinition,
+      operation,
+      typeof creative.creative_id === "string" ? creative.creative_id : "(unknown)"
     );
+    const refSize = legacyRefParameterConstraints(formatId);
+    const acceptsDimensions = Array.isArray(markupDefinition?.accepts_parameters) && markupDefinition.accepts_parameters.includes("dimensions");
+    const hasFixedRender = Array.isArray(markupDefinition?.renders) && markupDefinition.renders.some(
+      (render) => typeof render.dimensions?.width === "number" || typeof render.dimensions?.height === "number"
+    );
+    if (legacyAssets !== creative.assets && acceptsDimensions && !hasFixedRender && refSize.width === void 0 && refSize.height === void 0) {
+      const inlineAssets = Object.fromEntries(
+        Object.entries(record(creative.assets) ?? {}).filter(([, value]) => {
+          const asset = record(value);
+          return asset?.asset_type === "display_tag" && asset.delivery_type === "inline_markup";
+        })
+      );
+      const size = assetRenderedSize({ assets: inlineAssets });
+      const requested = creativeFormatParameterConstraints(creative);
+      if (typeof size?.width === "number" && typeof size.height === "number" && Number.isSafeInteger(size.width) && Number.isSafeInteger(size.height) && size.width > 0 && size.height > 0 && (requested?.width === void 0 || requested.width === size.width) && (requested?.height === void 0 || requested.height === size.height)) {
+        next.format_id = { ...formatId, width: size.width, height: size.height };
+      }
+    }
+    next.assets = projectLegacyAssetKeys(legacyAssets, definition);
   }
   return next;
 }
@@ -1130,14 +1145,44 @@ function projectCreativeForDelivery(creative, selectorContainer, wireMode = "can
       throw new CreativeFormatProjectionError(
         operation,
         creativeId,
-        `the seller advertised ${candidates.length} legacy refs for canonical kind ${creativeRecord.format_kind}`
+        `the seller advertised ${candidates.length} legacy refs for canonical kind ${creativeRecord.format_kind}` + (candidates.some((candidate) => legacyIdPinsDimensions(candidate.ref) === true) ? "; set format_parameters.width/height or give the asset one rendered width/height to select one" : "")
       );
     }
-    const reason = pinned ? "the creative is pinned to a format option that names none of the selected seller product legacy format references" : "the selected seller product did not provide one unambiguous legacy format reference";
+    const reason = pinned ? "the creative is pinned to a format option that names none of the selected seller product legacy format references" : describeUnmatchedLegacyCandidates(creativeRecord, allCandidates);
     throw new CreativeFormatProjectionError(operation, creativeId, reason);
   }
   return creative;
 }
+function describeUnmatchedLegacyCandidates(creative, allCandidates) {
+  const generic = "the selected seller product did not provide one unambiguous legacy format reference";
+  const kind = String(creative.format_kind);
+  if (allCandidates.length === 0) return generic;
+  const sameKind = allCandidates.filter((candidate) => candidate.formatKind === kind);
+  if (sameKind.length === 0) {
+    const offered = [
+      ...new Set(allCandidates.flatMap((candidate) => candidate.formatKind ? [candidate.formatKind] : []))
+    ];
+    if (offered.length === 0) return generic;
+    const htmlMarkupHint = kind === "html5" && offered.includes("display_tag") ? ". HTML-markup formats (display_html, display_WxH_html) take display_tag inline markup since SDK 17; send HTML snippets as a display_tag asset with delivery_type inline_markup (docs/migration-16-to-17.md)" : "";
+    return `the selected seller product offers legacy refs for canonical kind ${offered.join(", ")}, not ${kind}${htmlMarkupHint}`;
+  }
+  const deliveryTypes = creativeDisplayTagDeliveryTypes(creative);
+  if (deliveryTypes) {
+    const accepting = sameKind.filter((candidate) => {
+      const accepted = candidateDeliveryTypes(candidate);
+      return [...deliveryTypes].every((type) => accepted.includes(type));
+    });
+    if (accepting.length === 0) {
+      const accepted = [...new Set(sameKind.flatMap((candidate) => candidateDeliveryTypes(candidate).map(String)))];
+      return `none of the seller's ${sameKind.length} ${kind} legacy refs accepts delivery_type ${[...deliveryTypes].join(", ")} (they accept ${accepted.join(", ")})`;
+    }
+  }
+  const size = creativeFormatParameterConstraints(creative);
+  if (size?.width !== void 0 && size.height !== void 0) {
+    return `none of the seller's ${sameKind.length} ${kind} legacy refs matches the creative's ${size.width}x${size.height} size`;
+  }
+  return generic;
+}
 function projectMediaBuyCreativesForDelivery(request, wireMode = "canonical", operation = "create_media_buy", legacyFormatConverter, canonicalFormatLegacyResolver, legacyFormatDefinitions) {
   const requestRecord = record(request);
   if (!requestRecord) return request;

package/dist/lib/v2/projection/creative-delivery.mjs

@@ -704,7 +704,6 @@ function projectInlineMarkupToLegacyHtml(assetsValue, definition, operation, cre
         {
           asset_type: "html",
           content: asset.markup,
-          ...renderedSizeFields(asset),
           ...asset.provenance !== void 0 && { provenance: asset.provenance }
         }
       ];
@@ -766,15 +765,31 @@ function projectCreative(creative, formatId, legacyFormatDefinitions, operation
     }
   }
   if (Object.hasOwn(creative, "assets")) {
-    next.assets = projectLegacyAssetKeys(
-      projectInlineMarkupToLegacyHtml(
-        creative.assets,
-        markupDefinition,
-        operation,
-        typeof creative.creative_id === "string" ? creative.creative_id : "(unknown)"
-      ),
-      definition
+    const legacyAssets = projectInlineMarkupToLegacyHtml(
+      creative.assets,
+      markupDefinition,
+      operation,
+      typeof creative.creative_id === "string" ? creative.creative_id : "(unknown)"
     );
+    const refSize = legacyRefParameterConstraints(formatId);
+    const acceptsDimensions = Array.isArray(markupDefinition?.accepts_parameters) && markupDefinition.accepts_parameters.includes("dimensions");
+    const hasFixedRender = Array.isArray(markupDefinition?.renders) && markupDefinition.renders.some(
+      (render) => typeof render.dimensions?.width === "number" || typeof render.dimensions?.height === "number"
+    );
+    if (legacyAssets !== creative.assets && acceptsDimensions && !hasFixedRender && refSize.width === void 0 && refSize.height === void 0) {
+      const inlineAssets = Object.fromEntries(
+        Object.entries(record(creative.assets) ?? {}).filter(([, value]) => {
+          const asset = record(value);
+          return asset?.asset_type === "display_tag" && asset.delivery_type === "inline_markup";
+        })
+      );
+      const size = assetRenderedSize({ assets: inlineAssets });
+      const requested = creativeFormatParameterConstraints(creative);
+      if (typeof size?.width === "number" && typeof size.height === "number" && Number.isSafeInteger(size.width) && Number.isSafeInteger(size.height) && size.width > 0 && size.height > 0 && (requested?.width === void 0 || requested.width === size.width) && (requested?.height === void 0 || requested.height === size.height)) {
+        next.format_id = { ...formatId, width: size.width, height: size.height };
+      }
+    }
+    next.assets = projectLegacyAssetKeys(legacyAssets, definition);
   }
   return next;
 }
@@ -1109,14 +1124,44 @@ function projectCreativeForDelivery(creative, selectorContainer, wireMode = "can
       throw new CreativeFormatProjectionError(
         operation,
         creativeId,
-        `the seller advertised ${candidates.length} legacy refs for canonical kind ${creativeRecord.format_kind}`
+        `the seller advertised ${candidates.length} legacy refs for canonical kind ${creativeRecord.format_kind}` + (candidates.some((candidate) => legacyIdPinsDimensions(candidate.ref) === true) ? "; set format_parameters.width/height or give the asset one rendered width/height to select one" : "")
       );
     }
-    const reason = pinned ? "the creative is pinned to a format option that names none of the selected seller product legacy format references" : "the selected seller product did not provide one unambiguous legacy format reference";
+    const reason = pinned ? "the creative is pinned to a format option that names none of the selected seller product legacy format references" : describeUnmatchedLegacyCandidates(creativeRecord, allCandidates);
     throw new CreativeFormatProjectionError(operation, creativeId, reason);
   }
   return creative;
 }
+function describeUnmatchedLegacyCandidates(creative, allCandidates) {
+  const generic = "the selected seller product did not provide one unambiguous legacy format reference";
+  const kind = String(creative.format_kind);
+  if (allCandidates.length === 0) return generic;
+  const sameKind = allCandidates.filter((candidate) => candidate.formatKind === kind);
+  if (sameKind.length === 0) {
+    const offered = [
+      ...new Set(allCandidates.flatMap((candidate) => candidate.formatKind ? [candidate.formatKind] : []))
+    ];
+    if (offered.length === 0) return generic;
+    const htmlMarkupHint = kind === "html5" && offered.includes("display_tag") ? ". HTML-markup formats (display_html, display_WxH_html) take display_tag inline markup since SDK 17; send HTML snippets as a display_tag asset with delivery_type inline_markup (docs/migration-16-to-17.md)" : "";
+    return `the selected seller product offers legacy refs for canonical kind ${offered.join(", ")}, not ${kind}${htmlMarkupHint}`;
+  }
+  const deliveryTypes = creativeDisplayTagDeliveryTypes(creative);
+  if (deliveryTypes) {
+    const accepting = sameKind.filter((candidate) => {
+      const accepted = candidateDeliveryTypes(candidate);
+      return [...deliveryTypes].every((type) => accepted.includes(type));
+    });
+    if (accepting.length === 0) {
+      const accepted = [...new Set(sameKind.flatMap((candidate) => candidateDeliveryTypes(candidate).map(String)))];
+      return `none of the seller's ${sameKind.length} ${kind} legacy refs accepts delivery_type ${[...deliveryTypes].join(", ")} (they accept ${accepted.join(", ")})`;
+    }
+  }
+  const size = creativeFormatParameterConstraints(creative);
+  if (size?.width !== void 0 && size.height !== void 0) {
+    return `none of the seller's ${sameKind.length} ${kind} legacy refs matches the creative's ${size.width}x${size.height} size`;
+  }
+  return generic;
+}
 function projectMediaBuyCreativesForDelivery(request, wireMode = "canonical", operation = "create_media_buy", legacyFormatConverter, canonicalFormatLegacyResolver, legacyFormatDefinitions) {
   const requestRecord = record(request);
   if (!requestRecord) return request;

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

@@ -319,7 +319,7 @@ function selectResponseVariant(payload) {
   return "sync";
 }
 function validateResponse(toolName, payload, version) {
-  const compatPayload = payload && typeof payload === "object" && !Array.isArray(payload) ? (0, import_envelope_status_compat.injectLegacyEnvelopeStatus)(payload, { toolName }) : payload;
+  const compatPayload = payload && typeof payload === "object" && !Array.isArray(payload) ? (0, import_envelope_status_compat.injectLegacyEnvelopeStatus)(payload, { toolName, adcpVersion: version }) : payload;
   const variant = selectResponseVariant(compatPayload);
   const validator = (0, import_schema_loader.getValidator)(toolName, variant, version);
   const effective = validator ?? (variant !== "sync" ? (0, import_schema_loader.getValidator)(toolName, "sync", version) : void 0);

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

@@ -292,7 +292,7 @@ function selectResponseVariant(payload) {
   return "sync";
 }
 function validateResponse(toolName, payload, version) {
-  const compatPayload = payload && typeof payload === "object" && !Array.isArray(payload) ? injectLegacyEnvelopeStatus(payload, { toolName }) : payload;
+  const compatPayload = payload && typeof payload === "object" && !Array.isArray(payload) ? injectLegacyEnvelopeStatus(payload, { toolName, adcpVersion: version }) : payload;
   const variant = selectResponseVariant(compatPayload);
   const validator = getValidator(toolName, variant, version);
   const effective = validator ?? (variant !== "sync" ? getValidator(toolName, "sync", version) : void 0);

package/dist/lib/version.d.mts

@@ -1,7 +1,7 @@
 /**
  * AdCP SDK library version
  */
-export declare const LIBRARY_VERSION = "17.0.0-beta.0";
+export declare const LIBRARY_VERSION = "17.0.0-beta.1";
 /**
  * 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: "17.0.0-beta.0";
+    readonly library: "17.0.0-beta.1";
     readonly adcp: "3.3.0-beta.0";
     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", "3.3.0-beta.0", "3.3-beta.0"];
-    readonly generatedAt: "2026-10-25T18:17:08.998Z";
+    readonly generatedAt: "2026-10-26T05:11:17.402Z";
 };
 /**
  * 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 = "17.0.0-beta.0";
+export declare const LIBRARY_VERSION = "17.0.0-beta.1";
 /**
  * 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: "17.0.0-beta.0";
+    readonly library: "17.0.0-beta.1";
     readonly adcp: "3.3.0-beta.0";
     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", "3.3.0-beta.0", "3.3-beta.0"];
-    readonly generatedAt: "2026-10-25T18:17:08.998Z";
+    readonly generatedAt: "2026-10-26T05:11:17.402Z";
 };
 /**
  * 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 = "17.0.0-beta.0";
+const LIBRARY_VERSION = "17.0.0-beta.1";
 const ADCP_VERSION = "3.3.0-beta.0";
 const ADCP_MAJOR_VERSION = 3;
 const COMPATIBLE_ADCP_VERSIONS = [
@@ -106,10 +106,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
   "3.3-beta.0"
 ];
 const VERSION_INFO = {
-  library: "17.0.0-beta.0",
+  library: "17.0.0-beta.1",
   adcp: "3.3.0-beta.0",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-10-25T18:17:08.998Z"
+  generatedAt: "2026-10-26T05:11:17.402Z"
 };
 function getAdcpVersion() {
   return ADCP_VERSION;

package/dist/lib/version.mjs

@@ -1,4 +1,4 @@
-const LIBRARY_VERSION = "17.0.0-beta.0";
+const LIBRARY_VERSION = "17.0.0-beta.1";
 const ADCP_VERSION = "3.3.0-beta.0";
 const ADCP_MAJOR_VERSION = 3;
 const COMPATIBLE_ADCP_VERSIONS = [
@@ -73,10 +73,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
   "3.3-beta.0"
 ];
 const VERSION_INFO = {
-  library: "17.0.0-beta.0",
+  library: "17.0.0-beta.1",
   adcp: "3.3.0-beta.0",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-10-25T18:17:08.998Z"
+  generatedAt: "2026-10-26T05:11:17.402Z"
 };
 function getAdcpVersion() {
   return ADCP_VERSION;

package/docs/TYPE-SUMMARY.md

@@ -1,7 +1,7 @@
 # AdCP Type Summary
 
-> Generated at: 2026-10-25
-> @adcp/sdk v17.0.0-beta.0
+> Generated at: 2026-10-26
+> @adcp/sdk v17.0.0-beta.1
 
 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/COLLECTION-FIXTURE-FOUNDATION.md

@@ -562,6 +562,17 @@ guarantees:
   retain their host-owned identity. A drift refusal after contact cannot undo
   earlier calls; their evidence goes only to the private audit sink.
 
+  After authorization and capability discovery, preparation evaluates the same
+  root `requires_capability`, `requires_all_capabilities`, `required_any_of_tools`,
+  and `required_tools` applicability gates as execution. `required_tools` accepts
+  any listed tool; every `required_any_of_tools` family must have a match.
+  Routed preparation unions advertised tools across routes. Root capability
+  predicates belong to `default_agent` when set; otherwise each selected step
+  route is evaluated separately, and preparation skips only when all decline.
+  Unmet gates return `status: 'unsupported', reason: 'not_applicable'` with a
+  discovery phase before any catalog read or controller seeding. Hosts can pass
+  the preparation authorizer directly without doing their own discovery first.
+
   The existing `PreparedFixturesLookup.binding` stays required and its gate
   union stays `run | pass | step`. Existing reuse authorizers need no migration.
   A host can explicitly share one implementation between the two options:

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

@@ -115,7 +115,18 @@ const client = new AgentClient(seller, {
 
 The partition is local configuration. It is hashed into MCP connection, discovery, and signing-policy cache keys and never sent in headers or tool arguments. Keep it stable for the same authorization scope, and use distinct values for different principals even when they share a seller token. Partitions also separate sessions within a single `withMCPConnectionScope` workflow.
 
-Outside a connection scope, calls now open and close their own MCP sessions by default. To retain process-wide reuse, provide a nonempty `connectionPartition`, or set `transport: { connectionReuse: 'process' }` when every caller with the same credentials and routing headers represents one principal. A supplied `trustedFetchFn` continues to use one-shot sessions outside an explicit scope, including with a partition or process opt-in.
+Outside a connection scope, calls now open and close their own MCP sessions by default. To retain process-wide reuse, provide a nonempty `connectionPartition`, or set `transport: { connectionReuse: 'process' }` when every caller with the same credentials and routing headers represents one principal. Low-level calls with a supplied `trustedFetchFn` continue to use one-shot sessions outside a scope, including with a partition or process opt-in.
+
+High-level `SingleAgentClient` task and discovery methods create a scope for
+one operation when the caller has not configured reuse. Endpoint discovery,
+`tools/list`, capability preflight, and dispatch share that operation's sessions,
+which close when it finishes. Caller-owned scopes and explicit process reuse
+keep their existing lifetimes. A supplied `trustedFetchFn` shares sessions
+within this operation scope, including when a principal partition is set;
+it never enables process-wide session reuse. A cold legacy endpoint still needs one v2 era
+classification handshake and one v1 Tasks-capable session; the credential- and
+policy-scoped classification is cached for five minutes, so later operations
+can go straight to their v1 session. Different credentials remain isolated.
 
 Successful calls and ordinary errors terminate one-shot sessions. When a call throws because it was cancelled or timed out, the SDK closes its client without sending DELETE, so it does not terminate work still running on the seller; remaining server session state follows the seller's TTL.
 

package/docs/llms.txt

@@ -1,7 +1,7 @@
 # Ad Context Protocol (AdCP)
 
-> Generated at: 2026-10-25
-> Library: @adcp/sdk v17.0.0-beta.0
+> Generated at: 2026-10-26
+> Library: @adcp/sdk v17.0.0-beta.1
 > 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.

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

@@ -16,8 +16,8 @@ pin using `ADCP_VERSION` inside that tarball.
 
 | Fact | Value |
 | --- | --- |
-| Checkout `package.json` version | `@adcp/sdk@17.0.0-beta.0` |
-| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@17.0.0-beta.0 dist.integrity` |
+| Checkout `package.json` version | `@adcp/sdk@17.0.0-beta.1` |
+| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@17.0.0-beta.1 dist.integrity` |
 | Node.js runtime | `^20.19.0 || >=22.12.0` |
 | Default AdCP wire release | `3.3.0-beta.0` |
 | Maintained wire releases | `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`, `3.3.0-beta.0`, `3.3-beta.0` |
@@ -26,8 +26,8 @@ pin using `ADCP_VERSION` inside that tarball.
 For a checkout at the published release commit, install the exact package version:
 
 ```bash
-npm install --save-exact '@adcp/sdk@17.0.0-beta.0'
-npm view '@adcp/sdk@17.0.0-beta.0' dist.integrity
+npm install --save-exact '@adcp/sdk@17.0.0-beta.1'
+npm view '@adcp/sdk@17.0.0-beta.1' dist.integrity
 ```
 
 ### Required and optional peers

package/docs/migration-16-to-17.md

@@ -3,6 +3,26 @@
 SDK 17 beta pins the signed AdCP `3.3.0-beta.0` release. Use the beta in
 development and staging; production remains on SDK 16 and AdCP 3.2.
 
+## Companion packages
+
+`@adcp/reporting-storage` declares `@adcp/sdk` as a peer, so it ships a release
+for each SDK line. Its stable releases accept only SDK 16: `0.1.x` takes
+`^16.0.0` and `0.2.0` takes `^16.5.0`. Installing SDK 17 beta beside either one
+makes npm report an invalid tree (`npm ls` prints
+`invalid: "^16.0.0" from node_modules/@adcp/reporting-storage` for `0.1.x`) or
+refuse with `ERESOLVE`. Install the
+storage release from the same `beta` train:
+
+```bash
+npm install --save-exact @adcp/sdk@17.0.0-beta.0 @adcp/reporting-storage@0.2.1-beta.0
+```
+
+`0.2.1-beta.0` has the same storage code and SQL migrations as `0.2.0`; only its
+`@adcp/sdk` peer range changes (`^17.0.0-beta.0`). A `~0.2.0` range does not match
+the prerelease, so pin the exact version. If you are upgrading from SDK 16.4 or
+earlier, read the [`0.2.0` notes](https://github.com/adcontextprotocol/adcp-client/blob/main/packages/reporting-storage/CHANGELOG.md#020)
+for BigQuery sinks that omit `location`. No other storage change is required.
+
 ## Protocol and discovery
 
 The SDK packages the exact 3.3 beta schema and compliance bundle alongside
@@ -77,7 +97,10 @@ including when the local `assetType: 'html5'` hint selects an `_html` ID.
 Actual zip creatives remain `html5` and cannot match HTML-markup-only products.
 
 Legacy delivery preserves the seller's format URL and size and emits the markup
-bytes in `html_creative.content`. Tag URLs and inline markup select only legacy
+bytes in `html_creative.content`. The rendered `width`, `height` and `sizes` are
+AdCP 3.3 asset fields, so they are not copied onto the legacy `html` asset: the
+selected `display_WxH_html` ref carries the size. Sellers on 3.3 get the
+canonical `display_tag` with those fields. Tag URLs and inline markup select only legacy
 refs that accept their delivery type. A paired redirect or inline-markup creative
 cannot use a ref that accepts only tag URLs. Multi-size tag-URL declarations keep
 their seller-asserted refs rather than expanding into inline-markup HTML formats.

package/docs/migration-reporting-storage-package.md

@@ -14,7 +14,7 @@ Why: storage keeps its own release cadence, as Auth.js, LangGraph and OpenTeleme
    npm install @adcp/sdk@^16.0.0 @adcp/reporting-storage@~0.1.0
    ```
 
-   Pin the storage package with `~` (`"@adcp/reporting-storage": "~0.1.0"`; this stable range does not match the earlier `0.1.0-beta.0` prerelease): it is pre-1.0 and every export is experimental. The cloud SDKs are optional peers of the new package, not of `@adcp/sdk` any more, so keep `@aws-sdk/client-s3`, `@azure/storage-blob` and `@google-cloud/storage` in your own dependencies for the providers you use.
+   Pin the storage package with `~` (`"@adcp/reporting-storage": "~0.1.0"`; this stable range does not match the earlier `0.1.0-beta.0` prerelease): it is pre-1.0 and every export is experimental. Choose the storage release whose `@adcp/sdk` peer range covers your SDK: `~0.1.0` for SDK 16.0 to 16.4, `~0.2.0` for SDK 16.5 and later 16.x, and the exact `0.2.1-beta.0` for SDK 17 beta (see the [16 to 17 migration guide](migration-16-to-17.md#companion-packages)). The cloud SDKs are optional peers of the new package, not of `@adcp/sdk` any more, so keep `@aws-sdk/client-s3`, `@azure/storage-blob` and `@google-cloud/storage` in your own dependencies for the providers you use.
 
 2. Change the imports using the table below, then run `tsc --noEmit`. A moved name on `@adcp/sdk/reporting/ledger` or `/service` is `TS2305: Module '"@adcp/sdk/reporting/ledger"' has no exported member 'PostgresReportingLedgerStore'`; a deleted subpath is `TS2307: Cannot find module '@adcp/sdk/reporting/gcs'`. At runtime the deleted subpaths fail with `ERR_PACKAGE_PATH_NOT_EXPORTED`, and a stale CommonJS `require` of a moved name on a kept subpath destructures to `undefined` and fails later as `X is not a constructor`, so grep JavaScript too (see [Self-grade](#self-grade)).
 

package/package.json

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