@adcp/sdk 16.0.0-beta.9 → 16.1.0

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

@@ -4,6 +4,7 @@ import type { CanonicalFormatLegacyResolver } from './v2-to-v1';
 import type { CanonicalFormatKind, ProjectionDiagnostic, V1FormatId } from './types';
 import type { CanonicalFormatDeclaration } from './legacy-metadata';
 import type { UndeclaredFormatOptionSelector } from './legacy-routes';
+import { type V1FormatDefinition } from './catalog';
 type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, Extract<keyof T, K>> : never;
 /**
  * Primary SDK creative shape. Spell out the named fields rather than using
@@ -276,15 +277,20 @@ export declare class CreativeFormatCapabilityError extends Error {
     readonly code = "ADCP_CREATIVE_FORMAT_CAPABILITY_CONTRADICTION";
     constructor(message: string);
 }
-export declare function projectCreativeForDelivery<T extends CreativeAsset>(creative: T, selectorContainer: CreativeFormatSelectorContainer, wireMode?: 'canonical', operation?: string, legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver): CanonicalProjectedCreative<T>;
-export declare function projectCreativeForDelivery<T extends CreativeAsset>(creative: T, selectorContainer: CreativeFormatSelectorContainer, wireMode: 'legacy' | 'unknown', operation?: string, legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver): LegacyProjectedCreative<T>;
-export declare function projectCreativeForDelivery<T extends CreativeAsset>(creative: T, selectorContainer: CreativeFormatSelectorContainer, wireMode: CreativeFormatWireMode, operation?: string, legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver): CanonicalProjectedCreative<T> | LegacyProjectedCreative<T>;
-export declare function projectMediaBuyCreativesForDelivery<T>(request: T, wireMode: 'canonical', operation?: 'create_media_buy' | 'update_media_buy', legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver): ProjectedMediaBuyCreativeRequest<T, 'canonical'>;
-export declare function projectMediaBuyCreativesForDelivery<T>(request: T, wireMode: 'legacy' | 'unknown', operation?: 'create_media_buy' | 'update_media_buy', legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver): ProjectedMediaBuyCreativeRequest<T, 'legacy'>;
-export declare function projectMediaBuyCreativesForDelivery<T>(request: T, wireMode: CreativeFormatWireMode, operation?: 'create_media_buy' | 'update_media_buy', legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver): ProjectedMediaBuyCreativeRequest<T, 'canonical'> | ProjectedMediaBuyCreativeRequest<T, 'legacy'>;
-export declare function projectSyncCreativesForDelivery<T>(request: T, selectorContainers: ReadonlyArray<CreativeFormatSelectorContainer>, wireMode: 'canonical', legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver): ProjectedSyncCreativeRequest<T, 'canonical'>;
-export declare function projectSyncCreativesForDelivery<T>(request: T, selectorContainers: ReadonlyArray<CreativeFormatSelectorContainer>, wireMode: 'legacy' | 'unknown', legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver): ProjectedSyncCreativeRequest<T, 'legacy'>;
-export declare function projectSyncCreativesForDelivery<T>(request: T, selectorContainers: ReadonlyArray<CreativeFormatSelectorContainer>, wireMode: CreativeFormatWireMode, legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver): ProjectedSyncCreativeRequest<T, 'canonical'> | ProjectedSyncCreativeRequest<T, 'legacy'>;
+/**
+ * Project identity and asset keys for the selected wire mode. Optional
+ * `legacyFormatDefinitions` override bundled definitions by exact format owner
+ * and ID; ambiguous definitions leave asset keys unchanged.
+ */
+export declare function projectCreativeForDelivery<T extends CreativeAsset>(creative: T, selectorContainer: CreativeFormatSelectorContainer, wireMode?: 'canonical', operation?: string, legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[]): CanonicalProjectedCreative<T>;
+export declare function projectCreativeForDelivery<T extends CreativeAsset>(creative: T, selectorContainer: CreativeFormatSelectorContainer, wireMode: 'legacy' | 'unknown', operation?: string, legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[]): LegacyProjectedCreative<T>;
+export declare function projectCreativeForDelivery<T extends CreativeAsset>(creative: T, selectorContainer: CreativeFormatSelectorContainer, wireMode: CreativeFormatWireMode, operation?: string, legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[]): CanonicalProjectedCreative<T> | LegacyProjectedCreative<T>;
+export declare function projectMediaBuyCreativesForDelivery<T>(request: T, wireMode: 'canonical', operation?: 'create_media_buy' | 'update_media_buy', legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[]): ProjectedMediaBuyCreativeRequest<T, 'canonical'>;
+export declare function projectMediaBuyCreativesForDelivery<T>(request: T, wireMode: 'legacy' | 'unknown', operation?: 'create_media_buy' | 'update_media_buy', legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[]): ProjectedMediaBuyCreativeRequest<T, 'legacy'>;
+export declare function projectMediaBuyCreativesForDelivery<T>(request: T, wireMode: CreativeFormatWireMode, operation?: 'create_media_buy' | 'update_media_buy', legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[]): ProjectedMediaBuyCreativeRequest<T, 'canonical'> | ProjectedMediaBuyCreativeRequest<T, 'legacy'>;
+export declare function projectSyncCreativesForDelivery<T>(request: T, selectorContainers: ReadonlyArray<CreativeFormatSelectorContainer>, wireMode: 'canonical', legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[]): ProjectedSyncCreativeRequest<T, 'canonical'>;
+export declare function projectSyncCreativesForDelivery<T>(request: T, selectorContainers: ReadonlyArray<CreativeFormatSelectorContainer>, wireMode: 'legacy' | 'unknown', legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[]): ProjectedSyncCreativeRequest<T, 'legacy'>;
+export declare function projectSyncCreativesForDelivery<T>(request: T, selectorContainers: ReadonlyArray<CreativeFormatSelectorContainer>, wireMode: CreativeFormatWireMode, legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[]): ProjectedSyncCreativeRequest<T, 'canonical'> | ProjectedSyncCreativeRequest<T, 'legacy'>;
 export type { UndeclaredFormatOptionSelector } from './legacy-routes';
 /**
  * Looks up a format option the SDK derived from a seller's legacy `format_ids`.

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

@@ -33,6 +33,7 @@ var import_v1_to_v2 = require('./v1-to-v2.js');
 var import_v2_to_v1 = require('./v2-to-v1.js');
 var import_legacy_metadata = require('./legacy-metadata.js');
 var import_jcs = require('../../utils/jcs.js');
+var import_catalog = require('./catalog.js');
 function stripLegacyCreativeIdentity(value) {
   const legacyTokens = /* @__PURE__ */ new Set();
   const legacyUrlTokens = /* @__PURE__ */ new Set();
@@ -591,11 +592,55 @@ function selectLegacyRef(creative, container, canonicalFormatLegacyResolver, ope
   matching = preferMostConstrainedLegacyCandidates(matching, creative);
   return matching.length === 1 ? matching[0].ref : void 0;
 }
-function projectCreative(creative, formatId) {
+function projectLegacyAssetKeys(assetsValue, definition) {
+  const assets = record(assetsValue);
+  if (!assets || !Array.isArray(definition?.assets)) return assetsValue;
+  const slots = definition.assets.filter((slot) => record(slot) !== void 0);
+  if (slots.some((slot) => slot.item_type !== void 0 && slot.item_type !== "individual")) return assetsValue;
+  const declaredIds = new Set(slots.map((slot) => slot.asset_id));
+  const availableSlots = slots.filter(
+    (slot) => (slot.item_type === void 0 || slot.item_type === "individual") && typeof slot.asset_id === "string" && slot.asset_id.length > 0 && !Object.hasOwn(assets, slot.asset_id)
+  );
+  const targetBySource = /* @__PURE__ */ new Map();
+  const sourcesByTarget = /* @__PURE__ */ new Map();
+  for (const [key, value] of Object.entries(assets)) {
+    if (declaredIds.has(key)) continue;
+    const asset = record(value);
+    if (!asset || typeof asset.asset_type !== "string") continue;
+    const matches = availableSlots.filter((slot) => {
+      if (slot.asset_type !== asset.asset_type) return false;
+      if (asset.asset_type === "url") {
+        return typeof asset.url_type === "string" && asset.url_type === slot.requirements?.url_type;
+      }
+      if (asset.asset_type === "pixel_tracker") {
+        return typeof asset.event === "string" && asset.event === slot.event && (asset.event !== "custom" || typeof asset.custom_event_name === "string" && asset.custom_event_name === slot.custom_event_name);
+      }
+      return true;
+    });
+    if (matches.length !== 1) continue;
+    const target = matches[0].asset_id;
+    targetBySource.set(key, target);
+    const sources = sourcesByTarget.get(target) ?? [];
+    sources.push(key);
+    sourcesByTarget.set(target, sources);
+  }
+  for (const sources of sourcesByTarget.values()) {
+    if (sources.length > 1) for (const source of sources) targetBySource.delete(source);
+  }
+  if (targetBySource.size === 0) return assetsValue;
+  return Object.fromEntries(Object.entries(assets).map(([key, value]) => [targetBySource.get(key) ?? key, value]));
+}
+function projectCreative(creative, formatId, legacyFormatDefinitions) {
   const next = { ...creative };
   delete next.format_kind;
   delete next.format_option_ref;
   next.format_id = { ...formatId };
+  const supplied = legacyFormatDefinitions?.filter((definition2) => {
+    const ref = legacyRef(record(definition2)?.format_id);
+    return ref !== void 0 && sameLegacyIdentity(ref, formatId);
+  });
+  const definition = supplied?.length ? supplied.length === 1 ? supplied[0] : void 0 : (0, import_catalog.lookupV1Format)(formatId);
+  if (Object.hasOwn(creative, "assets")) next.assets = projectLegacyAssetKeys(creative.assets, definition);
   return next;
 }
 function dedupeLegacyRefs(refs) {
@@ -829,7 +874,7 @@ function canonicalizeCreative(creative, selectorContainer, operation, legacyForm
   }
   return next;
 }
-function projectCreativeForDelivery(creative, selectorContainer, wireMode = "canonical", operation = "creative_delivery", legacyFormatConverter, canonicalFormatLegacyResolver) {
+function projectCreativeForDelivery(creative, selectorContainer, wireMode = "canonical", operation = "creative_delivery", legacyFormatConverter, canonicalFormatLegacyResolver, legacyFormatDefinitions) {
   const inputRecord = creative;
   const originalLegacyRef = legacyRef(inputRecord.format_id);
   const creativeRecord = canonicalizeCreative(inputRecord, selectorContainer, operation, legacyFormatConverter);
@@ -837,7 +882,11 @@ function projectCreativeForDelivery(creative, selectorContainer, wireMode = "can
   if (originalLegacyRef) {
     const selectedOriginal = selectLegacyRef(inputRecord, selectorContainer, canonicalFormatLegacyResolver, operation);
     if (selectedOriginal) {
-      return projectCreative(creativeRecord, selectedOriginal);
+      return projectCreative(
+        creativeRecord,
+        selectedOriginal,
+        legacyFormatDefinitions
+      );
     }
     throw new CreativeFormatProjectionError(
       operation,
@@ -846,7 +895,8 @@ function projectCreativeForDelivery(creative, selectorContainer, wireMode = "can
     );
   }
   const formatId = selectLegacyRef(creativeRecord, selectorContainer, canonicalFormatLegacyResolver, operation);
-  if (formatId) return projectCreative(creativeRecord, formatId);
+  if (formatId)
+    return projectCreative(creativeRecord, formatId, legacyFormatDefinitions);
   if (typeof creativeRecord.format_kind === "string") {
     const creativeId = typeof creativeRecord.creative_id === "string" ? creativeRecord.creative_id : "(unknown)";
     const allCandidates = candidatesFromContainer(selectorContainer, canonicalFormatLegacyResolver, operation);
@@ -881,10 +931,19 @@ function projectCreativeForDelivery(creative, selectorContainer, wireMode = "can
         "canonical format legacy resolver returned an invalid or ambiguous creative mapping"
       );
     }
-    if (resolved) return projectCreative(creativeRecord, resolved[0]);
+    if (resolved)
+      return projectCreative(
+        creativeRecord,
+        resolved[0],
+        legacyFormatDefinitions
+      );
     const pinned = optionReference(creativeRecord.format_option_ref) !== void 0;
     if (candidates.length === 1 && !pinned) {
-      return projectCreative(creativeRecord, candidates[0].ref);
+      return projectCreative(
+        creativeRecord,
+        candidates[0].ref,
+        legacyFormatDefinitions
+      );
     }
     if (candidates.length > 1) {
       throw new CreativeFormatProjectionError(
@@ -898,7 +957,7 @@ function projectCreativeForDelivery(creative, selectorContainer, wireMode = "can
   }
   return creative;
 }
-function projectMediaBuyCreativesForDelivery(request, wireMode = "canonical", operation = "create_media_buy", legacyFormatConverter, canonicalFormatLegacyResolver) {
+function projectMediaBuyCreativesForDelivery(request, wireMode = "canonical", operation = "create_media_buy", legacyFormatConverter, canonicalFormatLegacyResolver, legacyFormatDefinitions) {
   const requestRecord = record(request);
   if (!requestRecord) return request;
   let changed = false;
@@ -918,7 +977,8 @@ function projectMediaBuyCreativesForDelivery(request, wireMode = "canonical", op
           wireMode,
           operation,
           legacyFormatConverter,
-          canonicalFormatLegacyResolver
+          canonicalFormatLegacyResolver,
+          legacyFormatDefinitions
         );
         if (projected !== creativeValue) changed = true;
         return projected;
@@ -936,7 +996,7 @@ function projectMediaBuyCreativesForDelivery(request, wireMode = "canonical", op
   }
   return changed ? next : request;
 }
-function projectSyncCreativesForDelivery(request, selectorContainers, wireMode = "canonical", legacyFormatConverter, canonicalFormatLegacyResolver) {
+function projectSyncCreativesForDelivery(request, selectorContainers, wireMode = "canonical", legacyFormatConverter, canonicalFormatLegacyResolver, legacyFormatDefinitions) {
   const requestRecord = record(request);
   if (!requestRecord || !Array.isArray(requestRecord.creatives)) {
     return request;
@@ -965,7 +1025,8 @@ function projectSyncCreativesForDelivery(request, selectorContainers, wireMode =
       wireMode,
       "sync_creatives",
       legacyFormatConverter,
-      canonicalFormatLegacyResolver
+      canonicalFormatLegacyResolver,
+      legacyFormatDefinitions
     );
     if (projected !== creativeValue) changed = true;
     return projected;

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

@@ -12,6 +12,7 @@ import {
   transferLegacyCreativeMetadata
 } from "./legacy-metadata.mjs";
 import { canonicalize as canonicalizeJson } from "../../utils/jcs.mjs";
+import { lookupV1Format } from "./catalog.mjs";
 function stripLegacyCreativeIdentity(value) {
   const legacyTokens = /* @__PURE__ */ new Set();
   const legacyUrlTokens = /* @__PURE__ */ new Set();
@@ -570,11 +571,55 @@ function selectLegacyRef(creative, container, canonicalFormatLegacyResolver, ope
   matching = preferMostConstrainedLegacyCandidates(matching, creative);
   return matching.length === 1 ? matching[0].ref : void 0;
 }
-function projectCreative(creative, formatId) {
+function projectLegacyAssetKeys(assetsValue, definition) {
+  const assets = record(assetsValue);
+  if (!assets || !Array.isArray(definition?.assets)) return assetsValue;
+  const slots = definition.assets.filter((slot) => record(slot) !== void 0);
+  if (slots.some((slot) => slot.item_type !== void 0 && slot.item_type !== "individual")) return assetsValue;
+  const declaredIds = new Set(slots.map((slot) => slot.asset_id));
+  const availableSlots = slots.filter(
+    (slot) => (slot.item_type === void 0 || slot.item_type === "individual") && typeof slot.asset_id === "string" && slot.asset_id.length > 0 && !Object.hasOwn(assets, slot.asset_id)
+  );
+  const targetBySource = /* @__PURE__ */ new Map();
+  const sourcesByTarget = /* @__PURE__ */ new Map();
+  for (const [key, value] of Object.entries(assets)) {
+    if (declaredIds.has(key)) continue;
+    const asset = record(value);
+    if (!asset || typeof asset.asset_type !== "string") continue;
+    const matches = availableSlots.filter((slot) => {
+      if (slot.asset_type !== asset.asset_type) return false;
+      if (asset.asset_type === "url") {
+        return typeof asset.url_type === "string" && asset.url_type === slot.requirements?.url_type;
+      }
+      if (asset.asset_type === "pixel_tracker") {
+        return typeof asset.event === "string" && asset.event === slot.event && (asset.event !== "custom" || typeof asset.custom_event_name === "string" && asset.custom_event_name === slot.custom_event_name);
+      }
+      return true;
+    });
+    if (matches.length !== 1) continue;
+    const target = matches[0].asset_id;
+    targetBySource.set(key, target);
+    const sources = sourcesByTarget.get(target) ?? [];
+    sources.push(key);
+    sourcesByTarget.set(target, sources);
+  }
+  for (const sources of sourcesByTarget.values()) {
+    if (sources.length > 1) for (const source of sources) targetBySource.delete(source);
+  }
+  if (targetBySource.size === 0) return assetsValue;
+  return Object.fromEntries(Object.entries(assets).map(([key, value]) => [targetBySource.get(key) ?? key, value]));
+}
+function projectCreative(creative, formatId, legacyFormatDefinitions) {
   const next = { ...creative };
   delete next.format_kind;
   delete next.format_option_ref;
   next.format_id = { ...formatId };
+  const supplied = legacyFormatDefinitions?.filter((definition2) => {
+    const ref = legacyRef(record(definition2)?.format_id);
+    return ref !== void 0 && sameLegacyIdentity(ref, formatId);
+  });
+  const definition = supplied?.length ? supplied.length === 1 ? supplied[0] : void 0 : lookupV1Format(formatId);
+  if (Object.hasOwn(creative, "assets")) next.assets = projectLegacyAssetKeys(creative.assets, definition);
   return next;
 }
 function dedupeLegacyRefs(refs) {
@@ -808,7 +853,7 @@ function canonicalizeCreative(creative, selectorContainer, operation, legacyForm
   }
   return next;
 }
-function projectCreativeForDelivery(creative, selectorContainer, wireMode = "canonical", operation = "creative_delivery", legacyFormatConverter, canonicalFormatLegacyResolver) {
+function projectCreativeForDelivery(creative, selectorContainer, wireMode = "canonical", operation = "creative_delivery", legacyFormatConverter, canonicalFormatLegacyResolver, legacyFormatDefinitions) {
   const inputRecord = creative;
   const originalLegacyRef = legacyRef(inputRecord.format_id);
   const creativeRecord = canonicalizeCreative(inputRecord, selectorContainer, operation, legacyFormatConverter);
@@ -816,7 +861,11 @@ function projectCreativeForDelivery(creative, selectorContainer, wireMode = "can
   if (originalLegacyRef) {
     const selectedOriginal = selectLegacyRef(inputRecord, selectorContainer, canonicalFormatLegacyResolver, operation);
     if (selectedOriginal) {
-      return projectCreative(creativeRecord, selectedOriginal);
+      return projectCreative(
+        creativeRecord,
+        selectedOriginal,
+        legacyFormatDefinitions
+      );
     }
     throw new CreativeFormatProjectionError(
       operation,
@@ -825,7 +874,8 @@ function projectCreativeForDelivery(creative, selectorContainer, wireMode = "can
     );
   }
   const formatId = selectLegacyRef(creativeRecord, selectorContainer, canonicalFormatLegacyResolver, operation);
-  if (formatId) return projectCreative(creativeRecord, formatId);
+  if (formatId)
+    return projectCreative(creativeRecord, formatId, legacyFormatDefinitions);
   if (typeof creativeRecord.format_kind === "string") {
     const creativeId = typeof creativeRecord.creative_id === "string" ? creativeRecord.creative_id : "(unknown)";
     const allCandidates = candidatesFromContainer(selectorContainer, canonicalFormatLegacyResolver, operation);
@@ -860,10 +910,19 @@ function projectCreativeForDelivery(creative, selectorContainer, wireMode = "can
         "canonical format legacy resolver returned an invalid or ambiguous creative mapping"
       );
     }
-    if (resolved) return projectCreative(creativeRecord, resolved[0]);
+    if (resolved)
+      return projectCreative(
+        creativeRecord,
+        resolved[0],
+        legacyFormatDefinitions
+      );
     const pinned = optionReference(creativeRecord.format_option_ref) !== void 0;
     if (candidates.length === 1 && !pinned) {
-      return projectCreative(creativeRecord, candidates[0].ref);
+      return projectCreative(
+        creativeRecord,
+        candidates[0].ref,
+        legacyFormatDefinitions
+      );
     }
     if (candidates.length > 1) {
       throw new CreativeFormatProjectionError(
@@ -877,7 +936,7 @@ function projectCreativeForDelivery(creative, selectorContainer, wireMode = "can
   }
   return creative;
 }
-function projectMediaBuyCreativesForDelivery(request, wireMode = "canonical", operation = "create_media_buy", legacyFormatConverter, canonicalFormatLegacyResolver) {
+function projectMediaBuyCreativesForDelivery(request, wireMode = "canonical", operation = "create_media_buy", legacyFormatConverter, canonicalFormatLegacyResolver, legacyFormatDefinitions) {
   const requestRecord = record(request);
   if (!requestRecord) return request;
   let changed = false;
@@ -897,7 +956,8 @@ function projectMediaBuyCreativesForDelivery(request, wireMode = "canonical", op
           wireMode,
           operation,
           legacyFormatConverter,
-          canonicalFormatLegacyResolver
+          canonicalFormatLegacyResolver,
+          legacyFormatDefinitions
         );
         if (projected !== creativeValue) changed = true;
         return projected;
@@ -915,7 +975,7 @@ function projectMediaBuyCreativesForDelivery(request, wireMode = "canonical", op
   }
   return changed ? next : request;
 }
-function projectSyncCreativesForDelivery(request, selectorContainers, wireMode = "canonical", legacyFormatConverter, canonicalFormatLegacyResolver) {
+function projectSyncCreativesForDelivery(request, selectorContainers, wireMode = "canonical", legacyFormatConverter, canonicalFormatLegacyResolver, legacyFormatDefinitions) {
   const requestRecord = record(request);
   if (!requestRecord || !Array.isArray(requestRecord.creatives)) {
     return request;
@@ -944,7 +1004,8 @@ function projectSyncCreativesForDelivery(request, selectorContainers, wireMode =
       wireMode,
       "sync_creatives",
       legacyFormatConverter,
-      canonicalFormatLegacyResolver
+      canonicalFormatLegacyResolver,
+      legacyFormatDefinitions
     );
     if (projected !== creativeValue) changed = true;
     return projected;

package/dist/lib/v2/projection/v1-to-v2.js

@@ -219,7 +219,8 @@ function projectFormatId(fid, productId, field, options) {
   const exactCatalogEntry = (0, import_catalog.lookupV1Format)(fid, options?._catalogPath);
   const canonicalAgentUrl = (0, import_resolve_agent_properties.canonicalizeAgentUrl)(fid.agent_url);
   const mayUseUniqueAlias = canonicalAgentUrl !== null && new URL(canonicalAgentUrl).protocol === "https:" && !(0, import_address_guards.isLikelyPrivateUrl)(canonicalAgentUrl);
-  const uniqueAliasEntry = exactCatalogEntry === void 0 && mayUseUniqueAlias ? (0, import_catalog.lookupUniqueV1FormatById)(fid.id, options?._catalogPath) : void 0;
+  const aaoGuessesApply = options?._authoritativeOnly !== true || (0, import_catalog.isAaoAgentUrl)(fid.agent_url);
+  const uniqueAliasEntry = exactCatalogEntry === void 0 && mayUseUniqueAlias && aaoGuessesApply ? (0, import_catalog.lookupUniqueV1FormatById)(fid.id, options?._catalogPath) : void 0;
   if (uniqueAliasEntry) {
     const explicit = projectWithLegacyConverter(fid, productId, field, options?.legacyFormatConverter);
     if (explicit) return explicit;
@@ -277,7 +278,7 @@ function projectFormatId(fid, productId, field, options) {
       }
     };
   }
-  const globMatch = (0, import_registry.forwardLookupByGlob)(fid.id);
+  const globMatch = aaoGuessesApply ? (0, import_registry.forwardLookupByGlob)(fid.id) : void 0;
   if (globMatch) {
     return {
       decl: {

package/dist/lib/v2/projection/v1-to-v2.mjs

@@ -4,7 +4,7 @@ import { createRequire as __adcpCreateRequire } from "node:module";
 const __dirname = __adcpDirname(__adcpFileURLToPath(import.meta.url));
 const require2 = __adcpCreateRequire(import.meta.url);
 import { forwardLookupByGlob, forwardLookupByStructural } from "./registry.mjs";
-import { lookupUniqueV1FormatById, lookupV1Format } from "./catalog.mjs";
+import { isAaoAgentUrl, lookupUniqueV1FormatById, lookupV1Format } from "./catalog.mjs";
 import { AAO_CANONICAL_AGENT_URL } from "./constants.mjs";
 import { LIBRARY_VERSION } from "../../version.mjs";
 import { legacyFormatConverterFromCatalogSnapshots } from "./catalog-snapshot.mjs";
@@ -202,7 +202,8 @@ function projectFormatId(fid, productId, field, options) {
   const exactCatalogEntry = lookupV1Format(fid, options?._catalogPath);
   const canonicalAgentUrl = canonicalizeAgentUrl(fid.agent_url);
   const mayUseUniqueAlias = canonicalAgentUrl !== null && new URL(canonicalAgentUrl).protocol === "https:" && !isLikelyPrivateUrl(canonicalAgentUrl);
-  const uniqueAliasEntry = exactCatalogEntry === void 0 && mayUseUniqueAlias ? lookupUniqueV1FormatById(fid.id, options?._catalogPath) : void 0;
+  const aaoGuessesApply = options?._authoritativeOnly !== true || isAaoAgentUrl(fid.agent_url);
+  const uniqueAliasEntry = exactCatalogEntry === void 0 && mayUseUniqueAlias && aaoGuessesApply ? lookupUniqueV1FormatById(fid.id, options?._catalogPath) : void 0;
   if (uniqueAliasEntry) {
     const explicit = projectWithLegacyConverter(fid, productId, field, options?.legacyFormatConverter);
     if (explicit) return explicit;
@@ -260,7 +261,7 @@ function projectFormatId(fid, productId, field, options) {
       }
     };
   }
-  const globMatch = forwardLookupByGlob(fid.id);
+  const globMatch = aaoGuessesApply ? forwardLookupByGlob(fid.id) : void 0;
   if (globMatch) {
     return {
       decl: {

package/dist/lib/version.d.mts

@@ -1,7 +1,7 @@
 /**
  * AdCP SDK library version
  */
-export declare const LIBRARY_VERSION = "16.0.0-beta.9";
+export declare const LIBRARY_VERSION = "16.1.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.0.0-beta.9";
+    readonly library: "16.1.0";
     readonly adcp: "3.2.5";
     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"];
-    readonly generatedAt: "2026-10-19T19:41:05.601Z";
+    readonly generatedAt: "2026-10-20T17:31:57.242Z";
 };
 /**
  * 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.9";
+export declare const LIBRARY_VERSION = "16.1.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.0.0-beta.9";
+    readonly library: "16.1.0";
     readonly adcp: "3.2.5";
     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"];
-    readonly generatedAt: "2026-10-19T19:41:05.601Z";
+    readonly generatedAt: "2026-10-20T17:31:57.242Z";
 };
 /**
  * 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.9";
+const LIBRARY_VERSION = "16.1.0";
 const ADCP_VERSION = "3.2.5";
 const ADCP_MAJOR_VERSION = 3;
 const COMPATIBLE_ADCP_VERSIONS = [
@@ -102,10 +102,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
   "3.2.5"
 ];
 const VERSION_INFO = {
-  library: "16.0.0-beta.9",
+  library: "16.1.0",
   adcp: "3.2.5",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-10-19T19:41:05.601Z"
+  generatedAt: "2026-10-20T17:31:57.242Z"
 };
 function getAdcpVersion() {
   return ADCP_VERSION;

package/dist/lib/version.mjs

@@ -1,4 +1,4 @@
-const LIBRARY_VERSION = "16.0.0-beta.9";
+const LIBRARY_VERSION = "16.1.0";
 const ADCP_VERSION = "3.2.5";
 const ADCP_MAJOR_VERSION = 3;
 const COMPATIBLE_ADCP_VERSIONS = [
@@ -69,10 +69,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
   "3.2.5"
 ];
 const VERSION_INFO = {
-  library: "16.0.0-beta.9",
+  library: "16.1.0",
   adcp: "3.2.5",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-10-19T19:41:05.601Z"
+  generatedAt: "2026-10-20T17:31:57.242Z"
 };
 function getAdcpVersion() {
   return ADCP_VERSION;

package/docs/TYPE-SUMMARY.md

@@ -1,7 +1,7 @@
 # AdCP Type Summary
 
-> Generated at: 2026-10-19
-> @adcp/sdk v16.0.0-beta.9
+> Generated at: 2026-10-20
+> @adcp/sdk v16.1.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`.
 
@@ -95,6 +95,7 @@ interface AgentDiscoverySeed {
 // client.invalidateDiscoveryCache(): Promise<void>; refresh after a seller change.
 
 interface TaskOptions {
+  operationId?: string;        // Stable caller correlation id (otherwise a UUID); not an idempotency key
   skipStatusHandlers?: boolean; // Skip inline completion handlers, including continuations
   timeout?: number;             // Absolute whole-task deadline
   signal?: AbortSignal;         // Caller cancellation
@@ -106,6 +107,15 @@ interface TaskOptions {
   // ...deadline, cancellation, transport, and conversation options...
 }
 
+// Resume observation of persisted seller work (SingleAgentClient or AgentClient).
+// Save metadata.serverTaskId, metadata.taskName as taskType, and metadata.taskId as operationId.
+const tracked = await agent.trackTask({ taskId: saved.serverTaskId, taskType: saved.taskType, operationId: saved.operationId });
+await tracked.track(); // One status read; TaskInfo includes operationId and serverTaskId
+await tracked.waitForCompletion(1000, signal); // Same polling path as submitted continuations
+// No per-poll protocol activity. Terminal status_change carries operation_id and server_task_id.
+// Local observation errors do not terminalize seller work. Matching identities can reattach on the same client.
+// Results retain seller tool response shapes; tracking does not restore prior request context or handlers.
+
 interface DeferredContinuation<T> {
   token: string;
   question?: string;

package/docs/guides/CREATIVE-DELIVERY.md

@@ -124,7 +124,24 @@ await agent.syncCreatives(
 The same pure functions are available from the explicit
 `@adcp/sdk/v2/projection` migration subpath for composition outside a client call:
 `projectCreativeForDelivery()`, `projectMediaBuyCreativesForDelivery()`, and
-`projectSyncCreativesForDelivery()`. Capability resolution uses the client's
+`projectSyncCreativesForDelivery()`.
+
+When these helpers emit a legacy `format_id`, they also map assets to the
+definition's `asset_id` keys. Definitions come from the bundled reference
+catalog, or from an optional final `legacyFormatDefinitions` array supplied to
+any of the three helpers. Caller definitions take precedence and must match
+both the format agent URL and ID. No network lookup occurs during projection.
+
+Existing declared asset keys keep their values. Other assets move only to one
+unoccupied slot with the same `asset_type`; URL assets must also match
+`requirements.url_type`, and pixel trackers must match the slot's `event`.
+Custom tracker events also match `custom_event_name`. Definitions containing
+repeatable groups retain all asset keys; projection does not infer group membership.
+Unmatched assets, ambiguous matches, and assets competing for the same slot
+keep their original keys. Unknown definitions leave assets unchanged. Canonical
+delivery retains its asset keys, and projection never mutates the caller's data.
+
+Capability resolution uses the client's
 emitted wire release pin: AdCP 3.2+ is canonical by contract, 3.0 is legacy, and 3.1
 checks the explicit `media_buy.features.canonical_creatives` declaration. A
 3.1 peer without the feature is deliberately

package/docs/guides/REPORTING-STABILITY.md

@@ -44,7 +44,7 @@ If you are unsure about a symbol, read its TSDoc. An `@experimental` tag means i
 
 ## How the two packages line up
 
-`@adcp/reporting-storage` declares `@adcp/sdk` as a **peer dependency** (`^16.0.0-beta.0` while SDK 16 is in beta), not a dependency. The store, its errors and the handlers share types and symbol-keyed guards, so the host must hold one copy of `@adcp/sdk`. A change to a storage interface in the SDK ships with a matching storage release; the changeset for each says which pair to install. The cloud SDKs (`@aws-sdk/client-s3`, `@azure/storage-blob`, `@google-cloud/storage`) are optional peers of the storage package. `@adcp/sdk` does not import `@adcp/reporting-storage`, and a test and a lint rule keep it that way.
+`@adcp/reporting-storage` declares `@adcp/sdk` as a **peer dependency** (`^16.0.0` for SDK 16), not a dependency. The store, its errors and the handlers share types and symbol-keyed guards, so the host must hold one copy of `@adcp/sdk`. A change to a storage interface in the SDK ships with a matching storage release; the changeset for each says which pair to install. The cloud SDKs (`@aws-sdk/client-s3`, `@azure/storage-blob`, `@google-cloud/storage`) are optional peers of the storage package. `@adcp/sdk` does not import `@adcp/reporting-storage`, and a test and a lint rule keep it that way.
 
 ## How to pin
 
@@ -53,19 +53,19 @@ Pin the storage package with a tilde range. A caret range on a `0.x` version alr
 ```json
 {
   "dependencies": {
-    "@adcp/sdk": "^16.0.0-beta.0",
-    "@adcp/reporting-storage": "~0.1.0-beta.0"
+    "@adcp/sdk": "^16.0.0",
+    "@adcp/reporting-storage": "~0.1.0"
   }
 }
 ```
 
-Those are the beta pins. A prerelease range such as `~0.1.0` does not match `0.1.0-beta.0`, so use the `-beta.0` form until stable releases exist, then move to `^16.0.0` and `~0.1.0`.
+These pins select SDK 16 and storage 0.1 stable versions. A stable range such as `~0.1.0` does not match `0.1.0-beta.0`; migrate both packages from their beta pins together.
 
-- `~0.1.0` (after the first stable release) takes patches only (recommended).
-- An exact version (`"0.1.0-beta.0"`) is stricter still.
+- `~0.1.0` takes patches only (recommended).
+- An exact version (`"0.1.0"`) is stricter still.
 - Read the changelog before widening to a new minor, and apply any migration it names.
 
-`@adcp/sdk` itself can use a caret range as usual, because the SDK's own surface follows semver. While SDK 16 is in beta, install both packages with the `beta` dist-tag (`npm install @adcp/sdk@beta @adcp/reporting-storage@beta`) until stable releases exist.
+`@adcp/sdk` itself can use a caret range as usual, because the SDK's own surface follows semver. Install the stable pair with `npm install @adcp/sdk@^16.0.0 @adcp/reporting-storage@~0.1.0`. The storage API remains experimental under the policy above.
 
 ## Migrations
 

package/docs/llms.txt

@@ -1,7 +1,7 @@
 # Ad Context Protocol (AdCP)
 
-> Generated at: 2026-10-19
-> Library: @adcp/sdk v16.0.0-beta.9
+> Generated at: 2026-10-20
+> Library: @adcp/sdk v16.1.0
 > 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.
@@ -13,7 +13,7 @@ AdCP is an open protocol for AI agents to buy, manage, and optimize advertising
 
 ## Start here: AdCP 3.2
 
-The SDK requires Node.js `^20.19.0 || >=22.12.0`. Install this reference's release train with `npm install @adcp/sdk@beta`; use the documentation from the exact published SDK version you install. For reproducible CLI runs, pin that exact SDK version. After installation, `node -p "require('@adcp/sdk').ADCP_VERSION"` reports its protocol pin; `ls node_modules/@adcp/sdk/compliance/cache` lists its packaged compliance versions. The legacy `adcp-3.2` npm tag selects SDK 14 and does not receive the refreshed compliance caches.
+The SDK requires Node.js `^20.19.0 || >=22.12.0`. Install this reference's release train with `npm install @adcp/sdk@16.1`; use the documentation from the exact published SDK version you install. For reproducible CLI runs, pin that exact SDK version. After installation, `node -p "require('@adcp/sdk').ADCP_VERSION"` reports its protocol pin; `ls node_modules/@adcp/sdk/compliance/cache` lists its packaged compliance versions. The legacy `adcp-3.2` npm tag selects SDK 14 and does not receive the refreshed compliance caches.
 
 The SDK is compact-lifecycle first: `list_products → buy_products → control_media_buy`, with `request_proposals → refine_proposals → accept_proposal` when terms need negotiation.