@adcp/sdk 12.1.1 → 13.0.0-rc.0

package/dist/lib/v2/projection/augment-response.mjs

@@ -1,7 +1,134 @@
 import { projectV1ProductToV2 } from "./v1-to-v2.mjs";
 import { LIBRARY_VERSION } from "../../version.mjs";
+import { canonicalize as canonicalizeJson } from "../../utils/jcs.mjs";
+import { concealLegacyFormatRefs } from "./legacy-metadata.mjs";
 const SDK_ID = `@adcp/sdk@${LIBRARY_VERSION}`;
-function augmentProductWithFormatOptions(product) {
+function canonicalDiagnostic(diagnostic) {
+  return {
+    ...diagnostic,
+    // A source `format_ids[i]` index is not an index into the projected
+    // `format_options[]`: earlier source refs may have failed while later refs
+    // projected successfully. Point at the canonical collection instead of
+    // claiming that a successful projected option is the failing value.
+    field: diagnostic.field.replace(/\.format_ids\[\d+\]/g, ".format_options")
+  };
+}
+function projectionErrorMessage(code) {
+  switch (code) {
+    case "CANONICAL_PRODUCT_FORMATS_UNAVAILABLE":
+      return "Product has no format declaration representable on the canonical-only surface";
+    case "FORMAT_PROJECTION_FAILED":
+      return "Legacy creative format could not be projected to a canonical declaration";
+    case "FORMAT_DECLARATION_V1_AMBIGUOUS":
+      return "Canonical creative format has no unambiguous legacy declaration";
+    case "FORMAT_DECLARATION_V1_NOT_APPLICABLE":
+      return "Canonical-only creative format cannot be represented on a legacy format path";
+    case "CANONICAL_NOT_V1_TRANSLATABLE":
+      return "Canonical creative format has no legacy representation";
+    case "FORMAT_DECLARATION_V1_LOSSY_MULTI_SIZE":
+      return "Canonical multi-size format has incomplete legacy coverage";
+    case "LEGACY_FORMAT_ID_DROPPED_UNMAPPED":
+      return "Redundant legacy creative identity has no canonical counterpart";
+  }
+}
+function projectionDiagnosticToError(diagnostic) {
+  return {
+    code: diagnostic.code,
+    message: projectionErrorMessage(diagnostic.code),
+    field: diagnostic.field,
+    recovery: "correctable",
+    source: diagnostic.source,
+    sdk_id: diagnostic.sdk_id,
+    details: diagnostic.error.details
+  };
+}
+function canonicalFormatsUnavailableForProduct(product, reason) {
+  return {
+    source: "sdk",
+    sdk_id: SDK_ID,
+    field: `products[${product.product_id}].format_options`,
+    code: "CANONICAL_PRODUCT_FORMATS_UNAVAILABLE",
+    error: {
+      details: {
+        product_id: product.product_id,
+        reason
+      }
+    }
+  };
+}
+function errorIdentity(value) {
+  if (typeof value.code !== "string" || typeof value.field !== "string") return void 0;
+  try {
+    return `${value.code}\0${value.field}\0${canonicalizeJson(value.details ?? null)}`;
+  } catch {
+    return void 0;
+  }
+}
+function mergeProjectionErrors(existing, diagnostics) {
+  const merged = Array.isArray(existing) ? [...existing] : [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const value of merged) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+    const record = value;
+    const key = errorIdentity(record);
+    if (key) seen.add(key);
+  }
+  for (const diagnostic of diagnostics) {
+    const error = projectionDiagnosticToError(diagnostic);
+    const key = errorIdentity(error);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    merged.push(error);
+  }
+  return merged;
+}
+function remapExistingProductErrors(existing, originalToOutputIndex, products) {
+  if (!Array.isArray(existing)) return existing;
+  return existing.map((value) => {
+    if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+    const record = value;
+    let issuesChanged = false;
+    const issues = Array.isArray(record.issues) ? record.issues.map((issue) => {
+      if (!issue || typeof issue !== "object" || Array.isArray(issue)) return issue;
+      const issueRecord = issue;
+      if (typeof issueRecord.pointer !== "string") return issue;
+      const pointerMatch = /^\/products\/(\d+)(\/.*)?$/.exec(issueRecord.pointer);
+      if (!pointerMatch) return issue;
+      const originalIssueIndex = Number(pointerMatch[1]);
+      if (!originalToOutputIndex.has(originalIssueIndex)) return issue;
+      const outputIssueIndex = originalToOutputIndex.get(originalIssueIndex);
+      issuesChanged = true;
+      return {
+        ...issueRecord,
+        pointer: outputIssueIndex === void 0 ? "/products" : `/products/${outputIssueIndex}${pointerMatch[2] ?? ""}`
+      };
+    }) : record.issues;
+    const withIssues = issuesChanged ? { ...record, issues } : record;
+    if (typeof record.field !== "string") return issuesChanged ? withIssues : value;
+    const match = /^products\[(\d+)\](.*)$/.exec(record.field);
+    if (!match) return issuesChanged ? withIssues : value;
+    const originalIndex = Number(match[1]);
+    if (!originalToOutputIndex.has(originalIndex)) return issuesChanged ? withIssues : value;
+    const outputIndex = originalToOutputIndex.get(originalIndex);
+    if (outputIndex !== void 0) {
+      return { ...withIssues, field: `products[${outputIndex}]${match[2] ?? ""}` };
+    }
+    const productId = products[originalIndex]?.product_id;
+    const details = record.details && typeof record.details === "object" && !Array.isArray(record.details) ? { ...record.details } : {};
+    if (typeof productId === "string" && details.product_id === void 0) details.product_id = productId;
+    return { ...withIssues, field: "products", ...Object.keys(details).length > 0 ? { details } : {} };
+  });
+}
+function hasEmptyPlacementFormatOptions(product) {
+  const placements = product.placements;
+  if (!Array.isArray(placements)) return false;
+  return placements.some((value) => {
+    if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+    const options = value.format_options;
+    return Array.isArray(options) && options.length === 0;
+  });
+}
+function augmentProductWithFormatOptions(product, options) {
   const existing = product.format_options;
   if (Array.isArray(existing)) {
     return {
@@ -15,7 +142,7 @@ function augmentProductWithFormatOptions(product) {
       diagnostics: []
     };
   }
-  const { v2, diagnostics } = projectV1ProductToV2(product);
+  const { v2, diagnostics } = projectV1ProductToV2(product, options);
   return {
     product: {
       ...product,
@@ -24,7 +151,7 @@ function augmentProductWithFormatOptions(product) {
     diagnostics
   };
 }
-function withFormatOptions(response) {
+function withFormatOptions(response, options) {
   if (!Array.isArray(response?.products)) {
     return {
       response: { ...response, products: [] },
@@ -34,7 +161,7 @@ function withFormatOptions(response) {
   const out = [];
   const diagnostics = [];
   for (const p of response.products) {
-    const { product, diagnostics: d } = augmentProductWithFormatOptions(p);
+    const { product, diagnostics: d } = augmentProductWithFormatOptions(p, options);
     out.push(product);
     diagnostics.push(...d);
   }
@@ -43,15 +170,50 @@ function withFormatOptions(response) {
     diagnostics
   };
 }
+function canonicalDeclarations(values) {
+  return values.map((value) => concealLegacyFormatRefs(value));
+}
+function canonicalPlacements(product, options, diagnostics) {
+  if (!Array.isArray(product.placements)) return product.placements;
+  return product.placements.map((value, placementIndex) => {
+    if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+    const placement = value;
+    const { format_ids: _drop, ...rest } = placement;
+    void _drop;
+    const hasLegacyFormats = Array.isArray(placement.format_ids);
+    const hasCanonicalFormats = Array.isArray(placement.format_options);
+    if (!hasLegacyFormats && !hasCanonicalFormats) return rest;
+    const productId = typeof product.product_id === "string" ? product.product_id : "(unknown)";
+    const placementId = typeof placement.placement_id === "string" ? placement.placement_id : String(placementIndex);
+    const pseudoProduct = {
+      product_id: `${productId}:placement:${placementId}`,
+      name: typeof placement.name === "string" ? placement.name : placementId,
+      description: `Nested placement ${placementId}`,
+      ...hasLegacyFormats ? { format_ids: placement.format_ids } : {},
+      ...hasCanonicalFormats ? { format_options: placement.format_options } : {}
+    };
+    const projected = toCanonicalOnlyProduct(pseudoProduct, options);
+    for (const diagnostic of projected.diagnostics) {
+      diagnostics.push({
+        ...diagnostic,
+        field: diagnostic.field.replace(/^products\[[^\]]+\]/, `products[${productId}].placements[${placementIndex}]`)
+      });
+    }
+    return {
+      ...rest,
+      format_options: projected.product.format_options
+    };
+  });
+}
 function formatRefCoverageKey(ref) {
   const url = ref.agent_url && !ref.agent_url.endsWith("/") ? ref.agent_url + "/" : ref.agent_url;
   return `${url}::${ref.id}::${ref.width ?? ""}x${ref.height ?? ""}::${ref.duration_ms ?? ""}`;
 }
-function toCanonicalOnlyProduct(product) {
+function toCanonicalOnlyProduct(product, options) {
   const existing = product.format_options;
   if (Array.isArray(existing)) {
     const formatOptions = existing;
-    const diagnostics = [];
+    const diagnostics2 = [];
     const inputIds = Array.isArray(product.format_ids) ? product.format_ids : [];
     if (inputIds.length > 0) {
       const covered = /* @__PURE__ */ new Set();
@@ -62,22 +224,15 @@ function toCanonicalOnlyProduct(product) {
       for (let k = 0; k < inputIds.length; k++) {
         const fid = inputIds[k];
         if (!covered.has(formatRefCoverageKey(fid))) {
-          const dropped_format_id = { agent_url: fid.agent_url, id: fid.id };
-          if (typeof fid.width === "number") dropped_format_id.width = fid.width;
-          if (typeof fid.height === "number") dropped_format_id.height = fid.height;
-          if (typeof fid.duration_ms === "number") dropped_format_id.duration_ms = fid.duration_ms;
-          diagnostics.push({
+          diagnostics2.push({
             source: "sdk",
             sdk_id: SDK_ID,
-            // Indexed to match the v1→v2 projection path's
-            // `products[id].format_ids[K]` so consumers correlate diagnostics
-            // by `field` shape across both paths.
-            field: `products[${product.product_id}].format_ids[${k}]`,
+            field: `products[${product.product_id}].format_options`,
             code: "LEGACY_FORMAT_ID_DROPPED_UNMAPPED",
             error: {
               details: {
                 product_id: product.product_id,
-                dropped_format_id
+                resolution_failure: "unmapped_legacy_format"
               }
             }
           });
@@ -86,25 +241,41 @@ function toCanonicalOnlyProduct(product) {
     }
     const { format_ids: _dropV2, ...rest2 } = product;
     void _dropV2;
-    return { product: rest2, diagnostics };
+    return {
+      product: {
+        ...rest2,
+        format_options: canonicalDeclarations(formatOptions),
+        ...Array.isArray(product.placements) ? { placements: canonicalPlacements(product, options, diagnostics2) } : {}
+      },
+      diagnostics: diagnostics2.map(canonicalDiagnostic)
+    };
   }
   if (Array.isArray(product.format_ids)) {
-    const { v2, diagnostics } = projectV1ProductToV2(product);
+    const { v2, diagnostics: diagnostics2 } = projectV1ProductToV2(product, options);
     const { format_ids: _dropV1, ...rest2 } = product;
     void _dropV1;
     return {
-      product: { ...rest2, format_options: v2.format_options },
-      diagnostics
+      product: {
+        ...rest2,
+        format_options: canonicalDeclarations(v2.format_options),
+        ...Array.isArray(product.placements) ? { placements: canonicalPlacements(product, options, diagnostics2) } : {}
+      },
+      diagnostics: diagnostics2.map(canonicalDiagnostic)
     };
   }
   const { format_ids: _dropNone, ...rest } = product;
   void _dropNone;
+  const diagnostics = [];
   return {
-    product: { ...rest, format_options: [] },
-    diagnostics: []
+    product: {
+      ...rest,
+      format_options: [],
+      ...Array.isArray(product.placements) ? { placements: canonicalPlacements(product, options, diagnostics) } : {}
+    },
+    diagnostics: diagnostics.map(canonicalDiagnostic)
   };
 }
-function toCanonicalOnlyResponse(response) {
+function toCanonicalOnlyResponse(response, options) {
   if (!Array.isArray(response?.products)) {
     return {
       response: { ...response, products: [] },
@@ -113,18 +284,52 @@ function toCanonicalOnlyResponse(response) {
   }
   const out = [];
   const diagnostics = [];
-  for (const p of response.products) {
-    const { product, diagnostics: d } = toCanonicalOnlyProduct(p);
-    out.push(product);
+  const originalToOutputIndex = /* @__PURE__ */ new Map();
+  for (let productIndex = 0; productIndex < response.products.length; productIndex++) {
+    const p = response.products[productIndex];
+    const { product, diagnostics: rawDiagnostics } = toCanonicalOnlyProduct(p, options);
+    const hasEmptyPlacement = hasEmptyPlacementFormatOptions(product);
+    const keep = product.format_options.length > 0 && !hasEmptyPlacement;
+    const outputIndex = keep ? out.length : void 0;
+    originalToOutputIndex.set(productIndex, outputIndex);
+    const d = rawDiagnostics.map((diagnostic) => ({
+      ...diagnostic,
+      field: keep ? diagnostic.field.replace(/^products\[[^\]]+\]/, `products[${outputIndex}]`) : "products",
+      error: keep ? diagnostic.error : {
+        details: {
+          ...diagnostic.error.details,
+          product_id: p.product_id
+        }
+      }
+    }));
+    if (!keep && d.length === 0) {
+      const reason = hasEmptyPlacement ? "nested_placement_format_list_empty" : Array.isArray(p.format_options) ? "canonical_format_list_empty" : Array.isArray(p.format_ids) ? "legacy_format_list_empty" : "missing_format_declaration";
+      d.push({
+        ...canonicalFormatsUnavailableForProduct(p, reason),
+        field: "products"
+      });
+    }
     diagnostics.push(...d);
+    if (keep) out.push(product);
   }
+  const remappedExistingErrors = remapExistingProductErrors(
+    response.errors,
+    originalToOutputIndex,
+    response.products
+  );
+  const errors = mergeProjectionErrors(remappedExistingErrors, diagnostics);
   return {
-    response: { ...response, products: out },
+    response: {
+      ...response,
+      products: out,
+      ...errors.length > 0 ? { errors } : {}
+    },
     diagnostics
   };
 }
 export {
   augmentProductWithFormatOptions,
+  projectionDiagnosticToError,
   toCanonicalOnlyProduct,
   toCanonicalOnlyResponse,
   withFormatOptions

package/dist/lib/v2/projection/augment-response.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../src/lib/v2/projection/augment-response.ts"],"sourcesContent":["/**\n * Buyer-side helpers that augment a v1-shaped agent response with v2\n * `format_options[]` derived from the existing `format_ids[]` on each\n * Product.\n *\n * Buyers who want the canonical creative-format model call\n * `withFormatOptions(response)` and read `format_options` instead of\n * relying only on legacy `format_ids`.\n *\n * The SDK also auto-projects compatible `AgentClient.getProducts()`\n * responses; this helper remains useful for cached responses, fixtures,\n * upstream seller/storefront composition, and explicit migration code.\n *\n * Pure functions — no IO, no caching. Each Product is projected\n * independently; diagnostics aggregate so a multi-product response\n * surfaces every projection issue at once. The helpers preserve the\n * input shape verbatim and add `format_options[]` (additive). They do\n * NOT drop `format_ids[]` — that's the 8.0 narrowing. To DROP\n * `format_ids[]` once a consumer has fully migrated, use\n * `toCanonicalOnlyProduct` / `toCanonicalOnlyResponse`.\n */\n\nimport type { V1Product, V1FormatId, V2ProductFormatDeclaration, ProjectionDiagnostic } from './types';\nimport { projectV1ProductToV2 } from './v1-to-v2';\nimport { LIBRARY_VERSION } from '../../version';\n\nconst SDK_ID = `@adcp/sdk@${LIBRARY_VERSION}`;\n\n/**\n * A Product that has been augmented with `format_options[]` while\n * preserving the original `format_ids[]`. Carries the projection\n * diagnostics that were generated mapping each `format_id` so the\n * buyer can see what (if anything) didn't project cleanly.\n *\n * **Write-side bridge.** After picking a `format_options[i]` entry,\n * use {@link formatIdsFromOptions} (from `@adcp/sdk/v2/projection`)\n * to extract the `format_ids[]` value for a `create_media_buy`\n * package. Inlining `decl.v1_format_ref` works but bypasses the\n * fail-closed semantics (canonical_formats_only / inherently-v2\n * canonical → throw). The spec gap that forces this bridge is tracked\n * at adcontextprotocol/adcp#4842.\n *\n * @see formatIdsFromOptions\n * @see formatIdsForCapability\n */\nexport type V2AugmentedProduct<P> = P & {\n  format_options: V2ProductFormatDeclaration[];\n};\n\n/**\n * Augment a single Product. Idempotent — when `format_options[]` is\n * already present (the seller is v2-native), passes the Product\n * through unchanged. Otherwise projects from `format_ids[]`.\n *\n * Returns `{ product, diagnostics }`. `diagnostics` is empty for a\n * clean projection; populated when individual format_ids don't have\n * a v2 mapping (catalog gap, structural unreachability, etc.).\n *\n * @see toCanonicalOnlyProduct — the canonical-only counterpart that DROPS\n * `format_ids[]` for a fully-migrated consumer.\n */\nexport function augmentProductWithFormatOptions<P extends V1Product>(\n  product: P\n): { product: V2AugmentedProduct<P>; diagnostics: ProjectionDiagnostic[] } {\n  // Already v2-shaped (seller sent format_options directly) — pass through.\n  const existing = (product as unknown as { format_options?: unknown }).format_options;\n  if (Array.isArray(existing)) {\n    return {\n      product: product as V2AugmentedProduct<P>,\n      diagnostics: [],\n    };\n  }\n  // v1 shape — project to add format_options[].\n  if (!Array.isArray(product.format_ids)) {\n    // Neither shape — nothing to project. Return as-is with an empty\n    // format_options so the buyer doesn't have to special-case.\n    return {\n      product: { ...product, format_options: [] },\n      diagnostics: [],\n    };\n  }\n  const { v2, diagnostics } = projectV1ProductToV2(product);\n  // Preserve the original product shape (especially format_ids); just\n  // add format_options.\n  return {\n    product: {\n      ...product,\n      format_options: v2.format_options,\n    },\n    diagnostics,\n  };\n}\n\n/**\n * Augment every Product in a `get_products` response with\n * `format_options[]`. Returns `{ response, diagnostics }` so callers\n * can surface projection diagnostics alongside the response's existing\n * `errors[]` array (or filter by `source: 'sdk'` to distinguish SDK\n * diagnostics from seller-emitted errors).\n *\n * Idempotent: if the seller is v2-native and every Product already\n * carries `format_options[]`, returns the response verbatim with no\n * diagnostics.\n *\n * @see toCanonicalOnlyResponse — the canonical-only counterpart that DROPS\n * `format_ids[]` for a fully-migrated consumer.\n */\nexport function withFormatOptions<R extends { products?: V1Product[] }>(\n  response: R\n): { response: R & { products: V2AugmentedProduct<V1Product>[] }; diagnostics: ProjectionDiagnostic[] } {\n  if (!Array.isArray(response?.products)) {\n    return {\n      response: { ...response, products: [] } as R & { products: V2AugmentedProduct<V1Product>[] },\n      diagnostics: [],\n    };\n  }\n  const out: V2AugmentedProduct<V1Product>[] = [];\n  const diagnostics: ProjectionDiagnostic[] = [];\n  for (const p of response.products) {\n    const { product, diagnostics: d } = augmentProductWithFormatOptions(p);\n    out.push(product);\n    diagnostics.push(...d);\n  }\n  return {\n    response: { ...response, products: out } as R & { products: V2AugmentedProduct<V1Product>[] },\n    diagnostics,\n  };\n}\n\n/**\n * A Product reduced to the canonical creative-format surface:\n * `format_options[]` only, with the legacy `format_ids[]` removed. The\n * read-side counterpart to a fully-migrated consumer — naive downstream\n * code can no longer fall back to the stale `{ agent_url, id }` shape and\n * silently bypass the canonical model.\n */\nexport type CanonicalOnlyProduct<P> = Omit<P, 'format_ids'> & {\n  format_options: V2ProductFormatDeclaration[];\n};\n\n/**\n * Identity key for a `format_id` ref used by the coverage check.\n * Trailing-slash-insensitive on `agent_url` (folds the AAO host's slash /\n * no-slash forms, per `catalog.ts`'s `normalizeAgentUrl`), and includes the\n * dimensional discriminators so multi-size declarations sharing one\n * `{ agent_url, id }` but differing by size/duration are NOT collapsed —\n * the same key shape `write-side.ts` uses for v1 ref de-dup. Without the\n * size half, a `format_ids[]` entry for a size no `v1_format_ref` covers\n * would read as covered and be dropped silently.\n */\nfunction formatRefCoverageKey(ref: V1FormatId): string {\n  const url = ref.agent_url && !ref.agent_url.endsWith('/') ? ref.agent_url + '/' : ref.agent_url;\n  return `${url}::${ref.id}::${ref.width ?? ''}x${ref.height ?? ''}::${ref.duration_ms ?? ''}`;\n}\n\n/**\n * Project a single Product to the canonical-only shape: `format_options[]`\n * present, `format_ids[]` dropped.\n *\n * **Dropping legacy never silently loses a format.** Every input\n * `format_id` is either represented in the returned `format_options[]` or\n * surfaced in `diagnostics` — never discarded without a trace:\n *\n *   - **v1-shaped input** (`format_ids[]`, no `format_options[]`): runs the\n *     v1 → v2 projection. Mapped refs become `format_options[]`; any ref\n *     the projection can't map is surfaced as `FORMAT_PROJECTION_FAILED`.\n *   - **v2-native input** (`format_options[]` already present): keeps the\n *     seller's canonical surface and drops the redundant v1 fallback. If a\n *     `format_ids[]` entry exists that no `format_options[].v1_format_ref`\n *     covers, it surfaces as `LEGACY_FORMAT_ID_DROPPED_UNMAPPED` — the gap\n *     the projection path can't see.\n *   - **neither shape**: returns `format_options: []`; there is nothing to\n *     project and nothing to lose.\n *\n * Pure and subtractive: unlike {@link augmentProductWithFormatOptions}\n * (which preserves `format_ids[]`), this drops it — the opt-in narrowing for\n * a consumer that has fully migrated. Complements the write-side\n * non-invertibility tracked at adcontextprotocol/adcp#4842 — this is the\n * read-side transparency half.\n */\nexport function toCanonicalOnlyProduct<P extends V1Product>(\n  product: P\n): { product: CanonicalOnlyProduct<P>; diagnostics: ProjectionDiagnostic[] } {\n  const existing = (product as unknown as { format_options?: unknown }).format_options;\n\n  // v2-native: the seller already sent format_options[]. Drop the\n  // redundant v1 fallback, but flag any legacy ref no v1_format_ref covers.\n  if (Array.isArray(existing)) {\n    const formatOptions = existing as V2ProductFormatDeclaration[];\n    const diagnostics: ProjectionDiagnostic[] = [];\n    const inputIds = Array.isArray(product.format_ids) ? product.format_ids : [];\n    if (inputIds.length > 0) {\n      const covered = new Set<string>();\n      for (const opt of formatOptions) {\n        const refs = Array.isArray(opt?.v1_format_ref) ? opt.v1_format_ref : [];\n        for (const ref of refs) covered.add(formatRefCoverageKey(ref));\n      }\n      for (let k = 0; k < inputIds.length; k++) {\n        const fid = inputIds[k]!;\n        if (!covered.has(formatRefCoverageKey(fid))) {\n          // Echo the full ref the SDK saw — including dimensions — so a\n          // buyer can tell WHICH variant was dropped (matches the\n          // FORMAT_DECLARATION_V1_LOSSY_MULTI_SIZE size-in-details contract).\n          const dropped_format_id: {\n            agent_url: string;\n            id: string;\n            width?: number;\n            height?: number;\n            duration_ms?: number;\n          } = { agent_url: fid.agent_url, id: fid.id };\n          if (typeof fid.width === 'number') dropped_format_id.width = fid.width;\n          if (typeof fid.height === 'number') dropped_format_id.height = fid.height;\n          if (typeof fid.duration_ms === 'number') dropped_format_id.duration_ms = fid.duration_ms;\n          diagnostics.push({\n            source: 'sdk',\n            sdk_id: SDK_ID,\n            // Indexed to match the v1→v2 projection path's\n            // `products[id].format_ids[K]` so consumers correlate diagnostics\n            // by `field` shape across both paths.\n            field: `products[${product.product_id}].format_ids[${k}]`,\n            code: 'LEGACY_FORMAT_ID_DROPPED_UNMAPPED',\n            error: {\n              details: {\n                product_id: product.product_id,\n                dropped_format_id,\n              },\n            },\n          });\n        }\n      }\n    }\n    const { format_ids: _dropV2, ...rest } = product as P & { format_ids?: unknown };\n    void _dropV2;\n    return { product: rest as CanonicalOnlyProduct<P>, diagnostics };\n  }\n\n  // v1 shape: project. projectV1ProductToV2 already omits format_ids and\n  // emits a diagnostic for every ref it couldn't map.\n  if (Array.isArray(product.format_ids)) {\n    const { v2, diagnostics } = projectV1ProductToV2(product);\n    const { format_ids: _dropV1, ...rest } = product as P & { format_ids?: unknown };\n    void _dropV1;\n    return {\n      product: { ...(rest as Omit<P, 'format_ids'>), format_options: v2.format_options } as CanonicalOnlyProduct<P>,\n      diagnostics,\n    };\n  }\n\n  // Neither shape — nothing to project, nothing to lose.\n  const { format_ids: _dropNone, ...rest } = product as P & { format_ids?: unknown };\n  void _dropNone;\n  return {\n    product: { ...(rest as Omit<P, 'format_ids'>), format_options: [] } as CanonicalOnlyProduct<P>,\n    diagnostics: [],\n  };\n}\n\n/**\n * Reduce every Product in a `get_products` response to the canonical-only\n * shape — `format_options[]` present, `format_ids[]` dropped. Returns\n * `{ response, diagnostics }` so callers surface projection diagnostics\n * alongside the response's existing `errors[]`.\n *\n * Response-level counterpart to {@link toCanonicalOnlyProduct}; same\n * never-silently-lose-a-format guarantee, aggregated across products. The\n * canonical-only sibling of {@link withFormatOptions} (which is additive\n * and preserves `format_ids[]`).\n */\nexport function toCanonicalOnlyResponse<R extends { products?: V1Product[] }>(\n  response: R\n): {\n  response: Omit<R, 'products'> & { products: CanonicalOnlyProduct<V1Product>[] };\n  diagnostics: ProjectionDiagnostic[];\n} {\n  if (!Array.isArray(response?.products)) {\n    return {\n      response: { ...response, products: [] } as Omit<R, 'products'> & { products: CanonicalOnlyProduct<V1Product>[] },\n      diagnostics: [],\n    };\n  }\n  const out: CanonicalOnlyProduct<V1Product>[] = [];\n  const diagnostics: ProjectionDiagnostic[] = [];\n  for (const p of response.products) {\n    const { product, diagnostics: d } = toCanonicalOnlyProduct(p);\n    out.push(product);\n    diagnostics.push(...d);\n  }\n  return {\n    response: { ...response, products: out } as Omit<R, 'products'> & { products: CanonicalOnlyProduct<V1Product>[] },\n    diagnostics,\n  };\n}\n"],"mappings":"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","names":["rest"]}
+{"version":3,"sources":["../../../../src/lib/v2/projection/augment-response.ts"],"sourcesContent":["/**\n * Buyer-side helpers that augment a v1-shaped agent response with v2\n * `format_options[]` derived from the existing `format_ids[]` on each\n * Product.\n *\n * Buyers who want the canonical creative-format model call\n * `withFormatOptions(response)` and read `format_options` instead of\n * relying only on legacy `format_ids`.\n *\n * The SDK also auto-projects compatible `AgentClient.getProducts()`\n * responses; this helper remains useful for cached responses, fixtures,\n * upstream seller/storefront composition, and explicit migration code.\n *\n * Pure functions — no IO, no caching. Each Product is projected\n * independently; diagnostics aggregate so a multi-product response\n * surfaces every projection issue at once. The helpers preserve the\n * input shape verbatim and add `format_options[]` (additive). They do\n * NOT drop `format_ids[]` — that's the 8.0 narrowing. To DROP\n * `format_ids[]` once a consumer has fully migrated, use\n * `toCanonicalOnlyProduct` / `toCanonicalOnlyResponse`.\n */\n\nimport type { V1Product, V1FormatId, V2ProductFormatDeclaration, ProjectionDiagnostic } from './types';\nimport { projectV1ProductToV2 } from './v1-to-v2';\nimport type { V1ToV2ProjectionOptions } from './v1-to-v2';\nimport { LIBRARY_VERSION } from '../../version';\nimport { canonicalize as canonicalizeJson } from '../../utils/jcs';\nimport { concealLegacyFormatRefs } from './legacy-metadata';\nimport type { CanonicalFormatDeclaration } from './legacy-metadata';\n\nconst SDK_ID = `@adcp/sdk@${LIBRARY_VERSION}`;\n\nfunction canonicalDiagnostic(diagnostic: ProjectionDiagnostic): ProjectionDiagnostic {\n  return {\n    ...diagnostic,\n    // A source `format_ids[i]` index is not an index into the projected\n    // `format_options[]`: earlier source refs may have failed while later refs\n    // projected successfully. Point at the canonical collection instead of\n    // claiming that a successful projected option is the failing value.\n    field: diagnostic.field.replace(/\\.format_ids\\[\\d+\\]/g, '.format_options'),\n  };\n}\n\n/** Protocol Error shape used for portable response-level projection advisories. */\nexport interface CanonicalProjectionError {\n  code: ProjectionDiagnostic['code'];\n  message: string;\n  field: string;\n  recovery: 'correctable';\n  source: 'sdk';\n  sdk_id: string;\n  details: ProjectionDiagnostic['error']['details'];\n}\n\nfunction projectionErrorMessage(code: ProjectionDiagnostic['code']): string {\n  switch (code) {\n    case 'CANONICAL_PRODUCT_FORMATS_UNAVAILABLE':\n      return 'Product has no format declaration representable on the canonical-only surface';\n    case 'FORMAT_PROJECTION_FAILED':\n      return 'Legacy creative format could not be projected to a canonical declaration';\n    case 'FORMAT_DECLARATION_V1_AMBIGUOUS':\n      return 'Canonical creative format has no unambiguous legacy declaration';\n    case 'FORMAT_DECLARATION_V1_NOT_APPLICABLE':\n      return 'Canonical-only creative format cannot be represented on a legacy format path';\n    case 'CANONICAL_NOT_V1_TRANSLATABLE':\n      return 'Canonical creative format has no legacy representation';\n    case 'FORMAT_DECLARATION_V1_LOSSY_MULTI_SIZE':\n      return 'Canonical multi-size format has incomplete legacy coverage';\n    case 'LEGACY_FORMAT_ID_DROPPED_UNMAPPED':\n      return 'Redundant legacy creative identity has no canonical counterpart';\n  }\n}\n\n/** Flatten the projector's internal diagnostic into the protocol `Error` shape. */\nexport function projectionDiagnosticToError(diagnostic: ProjectionDiagnostic): CanonicalProjectionError {\n  return {\n    code: diagnostic.code,\n    message: projectionErrorMessage(diagnostic.code),\n    field: diagnostic.field,\n    recovery: 'correctable',\n    source: diagnostic.source,\n    sdk_id: diagnostic.sdk_id,\n    details: diagnostic.error.details,\n  } as CanonicalProjectionError;\n}\n\nfunction canonicalFormatsUnavailableForProduct(\n  product: V1Product,\n  reason: Extract<ProjectionDiagnostic, { code: 'CANONICAL_PRODUCT_FORMATS_UNAVAILABLE' }>['error']['details']['reason']\n): ProjectionDiagnostic {\n  return {\n    source: 'sdk',\n    sdk_id: SDK_ID,\n    field: `products[${product.product_id}].format_options`,\n    code: 'CANONICAL_PRODUCT_FORMATS_UNAVAILABLE',\n    error: {\n      details: {\n        product_id: product.product_id,\n        reason,\n      },\n    },\n  };\n}\n\nfunction errorIdentity(value: Record<string, unknown>): string | undefined {\n  if (typeof value.code !== 'string' || typeof value.field !== 'string') return undefined;\n  try {\n    return `${value.code}\\u0000${value.field}\\u0000${canonicalizeJson(value.details ?? null)}`;\n  } catch {\n    // Preserve unreadable third-party errors instead of falsely deduplicating.\n    return undefined;\n  }\n}\n\nfunction mergeProjectionErrors(existing: unknown, diagnostics: readonly ProjectionDiagnostic[]): unknown[] {\n  const merged = Array.isArray(existing) ? [...existing] : [];\n  const seen = new Set<string>();\n  for (const value of merged) {\n    if (!value || typeof value !== 'object' || Array.isArray(value)) continue;\n    const record = value as Record<string, unknown>;\n    const key = errorIdentity(record);\n    if (key) seen.add(key);\n  }\n  for (const diagnostic of diagnostics) {\n    const error = projectionDiagnosticToError(diagnostic) as unknown as Record<string, unknown>;\n    const key = errorIdentity(error)!;\n    if (seen.has(key)) continue;\n    seen.add(key);\n    merged.push(error);\n  }\n  return merged;\n}\n\nfunction remapExistingProductErrors(\n  existing: unknown,\n  originalToOutputIndex: ReadonlyMap<number, number | undefined>,\n  products: readonly V1Product[]\n): unknown {\n  if (!Array.isArray(existing)) return existing;\n  return existing.map(value => {\n    if (!value || typeof value !== 'object' || Array.isArray(value)) return value;\n    const record = value as Record<string, unknown>;\n    let issuesChanged = false;\n    const issues = Array.isArray(record.issues)\n      ? record.issues.map(issue => {\n          if (!issue || typeof issue !== 'object' || Array.isArray(issue)) return issue;\n          const issueRecord = issue as Record<string, unknown>;\n          if (typeof issueRecord.pointer !== 'string') return issue;\n          const pointerMatch = /^\\/products\\/(\\d+)(\\/.*)?$/.exec(issueRecord.pointer);\n          if (!pointerMatch) return issue;\n          const originalIssueIndex = Number(pointerMatch[1]);\n          if (!originalToOutputIndex.has(originalIssueIndex)) return issue;\n          const outputIssueIndex = originalToOutputIndex.get(originalIssueIndex);\n          issuesChanged = true;\n          return {\n            ...issueRecord,\n            pointer:\n              outputIssueIndex === undefined ? '/products' : `/products/${outputIssueIndex}${pointerMatch[2] ?? ''}`,\n          };\n        })\n      : record.issues;\n    const withIssues = issuesChanged ? { ...record, issues } : record;\n    if (typeof record.field !== 'string') return issuesChanged ? withIssues : value;\n    const match = /^products\\[(\\d+)\\](.*)$/.exec(record.field);\n    if (!match) return issuesChanged ? withIssues : value;\n    const originalIndex = Number(match[1]);\n    if (!originalToOutputIndex.has(originalIndex)) return issuesChanged ? withIssues : value;\n    const outputIndex = originalToOutputIndex.get(originalIndex);\n    if (outputIndex !== undefined) {\n      return { ...withIssues, field: `products[${outputIndex}]${match[2] ?? ''}` };\n    }\n    const productId = products[originalIndex]?.product_id;\n    const details =\n      record.details && typeof record.details === 'object' && !Array.isArray(record.details)\n        ? { ...(record.details as Record<string, unknown>) }\n        : {};\n    if (typeof productId === 'string' && details.product_id === undefined) details.product_id = productId;\n    return { ...withIssues, field: 'products', ...(Object.keys(details).length > 0 ? { details } : {}) };\n  });\n}\n\nfunction hasEmptyPlacementFormatOptions(product: CanonicalOnlyProduct<V1Product>): boolean {\n  const placements = (product as Record<string, unknown>).placements;\n  if (!Array.isArray(placements)) return false;\n  return placements.some(value => {\n    if (!value || typeof value !== 'object' || Array.isArray(value)) return false;\n    const options = (value as Record<string, unknown>).format_options;\n    return Array.isArray(options) && options.length === 0;\n  });\n}\n\n/**\n * A Product that has been augmented with `format_options[]` while\n * preserving the original `format_ids[]`. Carries the projection\n * diagnostics that were generated mapping each `format_id` so the\n * buyer can see what (if anything) didn't project cleanly.\n *\n * **Write-side bridge.** After picking a `format_options[i]` entry,\n * use {@link formatIdsFromOptions} (from `@adcp/sdk/v2/projection`)\n * to extract the `format_ids[]` value for a `create_media_buy`\n * package. Inlining `decl.v1_format_ref` works but bypasses the\n * fail-closed semantics (canonical_formats_only / inherently-v2\n * canonical → throw). The spec gap that forces this bridge is tracked\n * at adcontextprotocol/adcp#4842.\n *\n * @see formatIdsFromOptions\n * @see formatIdsForCapability\n */\nexport type V2AugmentedProduct<P> = P & {\n  format_options: V2ProductFormatDeclaration[];\n};\n\n/**\n * Augment a single Product. Idempotent — when `format_options[]` is\n * already present (the seller is v2-native), passes the Product\n * through unchanged. Otherwise projects from `format_ids[]`.\n *\n * Returns `{ product, diagnostics }`. `diagnostics` is empty for a\n * clean projection; populated when individual format_ids don't have\n * a v2 mapping (catalog gap, structural unreachability, etc.).\n *\n * @see toCanonicalOnlyProduct — the canonical-only counterpart that DROPS\n * `format_ids[]` for a fully-migrated consumer.\n */\nexport function augmentProductWithFormatOptions<P extends V1Product>(\n  product: P,\n  options?: V1ToV2ProjectionOptions\n): { product: V2AugmentedProduct<P>; diagnostics: ProjectionDiagnostic[] } {\n  // Already v2-shaped (seller sent format_options directly) — pass through.\n  const existing = (product as unknown as { format_options?: unknown }).format_options;\n  if (Array.isArray(existing)) {\n    return {\n      product: product as V2AugmentedProduct<P>,\n      diagnostics: [],\n    };\n  }\n  // v1 shape — project to add format_options[].\n  if (!Array.isArray(product.format_ids)) {\n    // Neither shape — nothing to project. Return as-is with an empty\n    // format_options so the buyer doesn't have to special-case.\n    return {\n      product: { ...product, format_options: [] },\n      diagnostics: [],\n    };\n  }\n  const { v2, diagnostics } = projectV1ProductToV2(product, options);\n  // Preserve the original product shape (especially format_ids); just\n  // add format_options.\n  return {\n    product: {\n      ...product,\n      format_options: v2.format_options,\n    },\n    diagnostics,\n  };\n}\n\n/**\n * Augment every Product in a `get_products` response with\n * `format_options[]`. Returns `{ response, diagnostics }` so callers\n * can surface projection diagnostics alongside the response's existing\n * `errors[]` array (or filter by `source: 'sdk'` to distinguish SDK\n * diagnostics from seller-emitted errors).\n *\n * Idempotent: if the seller is v2-native and every Product already\n * carries `format_options[]`, returns the response verbatim with no\n * diagnostics.\n *\n * @see toCanonicalOnlyResponse — the canonical-only counterpart that DROPS\n * `format_ids[]` for a fully-migrated consumer.\n */\nexport function withFormatOptions<R extends { products?: V1Product[] }>(\n  response: R,\n  options?: V1ToV2ProjectionOptions\n): { response: R & { products: V2AugmentedProduct<V1Product>[] }; diagnostics: ProjectionDiagnostic[] } {\n  if (!Array.isArray(response?.products)) {\n    return {\n      response: { ...response, products: [] } as R & { products: V2AugmentedProduct<V1Product>[] },\n      diagnostics: [],\n    };\n  }\n  const out: V2AugmentedProduct<V1Product>[] = [];\n  const diagnostics: ProjectionDiagnostic[] = [];\n  for (const p of response.products) {\n    const { product, diagnostics: d } = augmentProductWithFormatOptions(p, options);\n    out.push(product);\n    diagnostics.push(...d);\n  }\n  return {\n    response: { ...response, products: out } as R & { products: V2AugmentedProduct<V1Product>[] },\n    diagnostics,\n  };\n}\n\n/**\n * A Product reduced to the canonical creative-format surface:\n * `format_options[]` only, with the legacy `format_ids[]` removed. The\n * read-side counterpart to a fully-migrated consumer — naive downstream\n * code can no longer fall back to the stale `{ agent_url, id }` shape and\n * silently bypass the canonical model.\n */\nexport type CanonicalOnlyProduct<P> = Omit<P, 'format_ids'> & {\n  format_ids?: never;\n  format_options: CanonicalFormatDeclaration[];\n};\n\nfunction canonicalDeclarations(values: readonly V2ProductFormatDeclaration[]): CanonicalFormatDeclaration[] {\n  return values.map(value => concealLegacyFormatRefs(value));\n}\n\nfunction canonicalPlacements(\n  product: Record<string, unknown>,\n  options: V1ToV2ProjectionOptions | undefined,\n  diagnostics: ProjectionDiagnostic[]\n): unknown {\n  if (!Array.isArray(product.placements)) return product.placements;\n  return product.placements.map((value, placementIndex) => {\n    if (!value || typeof value !== 'object' || Array.isArray(value)) return value;\n    const placement = value as Record<string, unknown>;\n    const { format_ids: _drop, ...rest } = placement;\n    void _drop;\n    const hasLegacyFormats = Array.isArray(placement.format_ids);\n    const hasCanonicalFormats = Array.isArray(placement.format_options);\n    if (!hasLegacyFormats && !hasCanonicalFormats) return rest;\n\n    const productId = typeof product.product_id === 'string' ? product.product_id : '(unknown)';\n    const placementId = typeof placement.placement_id === 'string' ? placement.placement_id : String(placementIndex);\n    const pseudoProduct = {\n      product_id: `${productId}:placement:${placementId}`,\n      name: typeof placement.name === 'string' ? placement.name : placementId,\n      description: `Nested placement ${placementId}`,\n      ...(hasLegacyFormats ? { format_ids: placement.format_ids } : {}),\n      ...(hasCanonicalFormats ? { format_options: placement.format_options } : {}),\n    } as unknown as V1Product;\n    const projected = toCanonicalOnlyProduct(pseudoProduct, options);\n    for (const diagnostic of projected.diagnostics) {\n      diagnostics.push({\n        ...diagnostic,\n        field: diagnostic.field.replace(/^products\\[[^\\]]+\\]/, `products[${productId}].placements[${placementIndex}]`),\n      });\n    }\n    return {\n      ...rest,\n      format_options: projected.product.format_options,\n    };\n  });\n}\n\n/**\n * Identity key for a `format_id` ref used by the coverage check.\n * Trailing-slash-insensitive on `agent_url` (folds the AAO host's slash /\n * no-slash forms, per `catalog.ts`'s `normalizeAgentUrl`), and includes the\n * dimensional discriminators so multi-size declarations sharing one\n * `{ agent_url, id }` but differing by size/duration are NOT collapsed —\n * the same key shape `write-side.ts` uses for v1 ref de-dup. Without the\n * size half, a `format_ids[]` entry for a size no `v1_format_ref` covers\n * would read as covered and be dropped silently.\n */\nfunction formatRefCoverageKey(ref: V1FormatId): string {\n  const url = ref.agent_url && !ref.agent_url.endsWith('/') ? ref.agent_url + '/' : ref.agent_url;\n  return `${url}::${ref.id}::${ref.width ?? ''}x${ref.height ?? ''}::${ref.duration_ms ?? ''}`;\n}\n\n/**\n * Project a single Product to the canonical-only shape: `format_options[]`\n * present, `format_ids[]` dropped.\n *\n * **Dropping legacy never silently loses a format.** Every input\n * `format_id` is either represented in the returned `format_options[]` or\n * surfaced in `diagnostics` — never discarded without a trace:\n *\n *   - **v1-shaped input** (`format_ids[]`, no `format_options[]`): runs the\n *     v1 → v2 projection. Mapped refs become `format_options[]`; any ref\n *     the projection can't map is surfaced as `FORMAT_PROJECTION_FAILED`.\n *   - **v2-native input** (`format_options[]` already present): keeps the\n *     seller's canonical surface and drops the redundant v1 fallback. If a\n *     legacy routing entry exists that no canonical option covers, it\n *     surfaces a canonical-safe `LEGACY_FORMAT_ID_DROPPED_UNMAPPED`\n *     diagnostic without echoing the routing identifier.\n *   - **neither shape**: returns `format_options: []`; there is nothing to\n *     project and nothing to lose.\n *\n * Pure and subtractive: unlike {@link augmentProductWithFormatOptions}\n * (which preserves `format_ids[]`), this drops it — the opt-in narrowing for\n * a consumer that has fully migrated. Complements the write-side\n * non-invertibility tracked at adcontextprotocol/adcp#4842 — this is the\n * read-side transparency half.\n */\nexport function toCanonicalOnlyProduct<P extends V1Product>(\n  product: P,\n  options?: V1ToV2ProjectionOptions\n): { product: CanonicalOnlyProduct<P>; diagnostics: ProjectionDiagnostic[] } {\n  const existing = (product as unknown as { format_options?: unknown }).format_options;\n\n  // v2-native: the seller already sent format_options[]. Drop the\n  // redundant v1 fallback, but flag any legacy ref no v1_format_ref covers.\n  if (Array.isArray(existing)) {\n    const formatOptions = existing as V2ProductFormatDeclaration[];\n    const diagnostics: ProjectionDiagnostic[] = [];\n    const inputIds = Array.isArray(product.format_ids) ? product.format_ids : [];\n    if (inputIds.length > 0) {\n      const covered = new Set<string>();\n      for (const opt of formatOptions) {\n        const refs = Array.isArray(opt?.v1_format_ref) ? opt.v1_format_ref : [];\n        for (const ref of refs) covered.add(formatRefCoverageKey(ref));\n      }\n      for (let k = 0; k < inputIds.length; k++) {\n        const fid = inputIds[k]!;\n        if (!covered.has(formatRefCoverageKey(fid))) {\n          diagnostics.push({\n            source: 'sdk',\n            sdk_id: SDK_ID,\n            field: `products[${product.product_id}].format_options`,\n            code: 'LEGACY_FORMAT_ID_DROPPED_UNMAPPED',\n            error: {\n              details: {\n                product_id: product.product_id,\n                resolution_failure: 'unmapped_legacy_format',\n              },\n            },\n          });\n        }\n      }\n    }\n    const { format_ids: _dropV2, ...rest } = product as P & { format_ids?: unknown };\n    void _dropV2;\n    return {\n      product: {\n        ...rest,\n        format_options: canonicalDeclarations(formatOptions),\n        ...(Array.isArray((product as Record<string, unknown>).placements)\n          ? { placements: canonicalPlacements(product as Record<string, unknown>, options, diagnostics) }\n          : {}),\n      } as CanonicalOnlyProduct<P>,\n      diagnostics: diagnostics.map(canonicalDiagnostic),\n    };\n  }\n\n  // v1 shape: project. projectV1ProductToV2 already omits format_ids and\n  // emits a diagnostic for every ref it couldn't map.\n  if (Array.isArray(product.format_ids)) {\n    const { v2, diagnostics } = projectV1ProductToV2(product, options);\n    const { format_ids: _dropV1, ...rest } = product as P & { format_ids?: unknown };\n    void _dropV1;\n    return {\n      product: {\n        ...(rest as Omit<P, 'format_ids'>),\n        format_options: canonicalDeclarations(v2.format_options),\n        ...(Array.isArray((product as Record<string, unknown>).placements)\n          ? { placements: canonicalPlacements(product as Record<string, unknown>, options, diagnostics) }\n          : {}),\n      } as CanonicalOnlyProduct<P>,\n      diagnostics: diagnostics.map(canonicalDiagnostic),\n    };\n  }\n\n  // Neither shape — nothing to project, nothing to lose.\n  const { format_ids: _dropNone, ...rest } = product as P & { format_ids?: unknown };\n  void _dropNone;\n  const diagnostics: ProjectionDiagnostic[] = [];\n  return {\n    product: {\n      ...(rest as Omit<P, 'format_ids'>),\n      format_options: [],\n      ...(Array.isArray((product as Record<string, unknown>).placements)\n        ? { placements: canonicalPlacements(product as Record<string, unknown>, options, diagnostics) }\n        : {}),\n    } as CanonicalOnlyProduct<P>,\n    diagnostics: diagnostics.map(canonicalDiagnostic),\n  };\n}\n\n/**\n * Reduce every Product in a `get_products` response to the canonical-only\n * shape — `format_options[]` present, `format_ids[]` dropped. Returns\n * `{ response, diagnostics }` so callers surface projection diagnostics\n * alongside the response's existing `errors[]`.\n *\n * Response-level counterpart to {@link toCanonicalOnlyProduct}; same\n * fail-closed guarantee, aggregated across products. A wholly unmappable\n * legacy product cannot be represented as a canonical Product because the\n * protocol requires `format_options` to contain at least one declaration. It\n * is therefore omitted from the canonical list and surfaced through the\n * response's portable `errors[]` plus the SDK convenience diagnostics. A\n * partially mappable product remains with its mapped options and advisories\n * for the refs that could not be projected.\n */\nexport function toCanonicalOnlyResponse<R extends { products?: V1Product[] }>(\n  response: R,\n  options?: V1ToV2ProjectionOptions\n): {\n  response: Omit<R, 'products'> & { products: CanonicalOnlyProduct<V1Product>[]; errors?: unknown[] };\n  diagnostics: ProjectionDiagnostic[];\n} {\n  if (!Array.isArray(response?.products)) {\n    return {\n      response: { ...response, products: [] } as Omit<R, 'products'> & {\n        products: CanonicalOnlyProduct<V1Product>[];\n        errors?: unknown[];\n      },\n      diagnostics: [],\n    };\n  }\n  const out: CanonicalOnlyProduct<V1Product>[] = [];\n  const diagnostics: ProjectionDiagnostic[] = [];\n  const originalToOutputIndex = new Map<number, number | undefined>();\n  for (let productIndex = 0; productIndex < response.products.length; productIndex++) {\n    const p = response.products[productIndex]!;\n    const { product, diagnostics: rawDiagnostics } = toCanonicalOnlyProduct(p, options);\n    const hasEmptyPlacement = hasEmptyPlacementFormatOptions(product);\n    const keep = product.format_options.length > 0 && !hasEmptyPlacement;\n    const outputIndex = keep ? out.length : undefined;\n    originalToOutputIndex.set(productIndex, outputIndex);\n    const d = rawDiagnostics.map(diagnostic => ({\n      ...diagnostic,\n      field: keep ? diagnostic.field.replace(/^products\\[[^\\]]+\\]/, `products[${outputIndex}]`) : 'products',\n      error: keep\n        ? diagnostic.error\n        : {\n            details: {\n              ...diagnostic.error.details,\n              product_id: p.product_id,\n            },\n          },\n    })) as ProjectionDiagnostic[];\n    if (!keep && d.length === 0) {\n      const reason = hasEmptyPlacement\n        ? 'nested_placement_format_list_empty'\n        : Array.isArray((p as Record<string, unknown>).format_options)\n          ? 'canonical_format_list_empty'\n          : Array.isArray(p.format_ids)\n            ? 'legacy_format_list_empty'\n            : 'missing_format_declaration';\n      d.push({\n        ...canonicalFormatsUnavailableForProduct(p, reason),\n        field: 'products',\n      });\n    }\n    diagnostics.push(...d);\n    if (keep) out.push(product);\n  }\n  const remappedExistingErrors = remapExistingProductErrors(\n    (response as { errors?: unknown }).errors,\n    originalToOutputIndex,\n    response.products\n  );\n  const errors = mergeProjectionErrors(remappedExistingErrors, diagnostics);\n  return {\n    response: {\n      ...response,\n      products: out,\n      ...(errors.length > 0 ? { errors } : {}),\n    } as Omit<R, 'products'> & { products: CanonicalOnlyProduct<V1Product>[]; errors?: unknown[] },\n    diagnostics,\n  };\n}\n"],"mappings":"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","names":["diagnostics","rest"]}

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

@@ -1,6 +1,9 @@
 import type { FormatReferenceStructuredObject } from '../../types/core.generated.mjs';
-import type { AgentPlacementFormatDeclaration, CustomFormatDeclaration, DAASTAudioFormatDeclaration, DisplayTagFormatDeclaration, HTML5FormatDeclaration, HostedAudioFormatDeclaration, HostedVideoFormatDeclaration, ImageAsset, ImageCarouselFormatDeclaration, ImageFormatDeclaration, NativeInFeedFormatDeclaration, ProductFormatDeclaration, ResponsiveCreativeFormatDeclaration, SponsoredPlacementFormatDeclaration, VASTVideoFormatDeclaration } from '../../types/tools.generated.mjs';
-type WithCommonDeclaration<T> = ProductFormatDeclaration & T;
+import type { AgentPlacementFormatDeclaration, CustomFormatDeclaration, DAASTAudioFormatDeclaration, DisplayTagFormatDeclaration, HTML5FormatDeclaration, HostedAudioFormatDeclaration, HostedVideoFormatDeclaration, ImageAsset, ImageCarouselFormatDeclaration, ImageFormatDeclaration, NativeInFeedFormatDeclaration, ResponsiveCreativeFormatDeclaration, SponsoredPlacementFormatDeclaration, VASTVideoFormatDeclaration } from '../../types/tools.generated.mjs';
+import type { CanonicalFormatDeclaration as CanonicalBaseFormatDeclaration } from './legacy-metadata.mjs';
+type WithCommonDeclaration<T> = CanonicalBaseFormatDeclaration & Omit<T, 'v1_format_ref'> & {
+    v1_format_ref?: never;
+};
 interface CanonicalFormatDeclarationMap {
     image: WithCommonDeclaration<ImageFormatDeclaration>;
     html5: WithCommonDeclaration<HTML5FormatDeclaration>;
@@ -45,8 +48,8 @@ export interface ProductCardDetailedFields {
  * bare string when populating Product.format_ids, ProductFormatDeclaration
  * v1_format_ref, or list_creative_formats filters.
  */
-export declare function formatRef(agent_url: string, id: string, fields?: Omit<Partial<FormatReferenceStructuredObject>, 'agent_url' | 'id'> & Record<string, unknown>): FormatReferenceStructuredObject;
-export declare function formatRefs(...refs: FormatReferenceInput[]): FormatReferenceStructuredObject[];
+export declare function legacyFormatRef(agent_url: string, id: string, fields?: Omit<Partial<FormatReferenceStructuredObject>, 'agent_url' | 'id'> & Record<string, unknown>): FormatReferenceStructuredObject;
+export declare function legacyFormatRefs(...refs: FormatReferenceInput[]): FormatReferenceStructuredObject[];
 /**
  * Generic canonical-format declaration builder. It sets the format_kind
  * discriminator and keeps common declaration metadata in the third argument.
@@ -72,8 +75,6 @@ export declare function customFormatDeclaration(format_shape: string, format_sch
 export declare function productCard(fields: ProductCardFields): ProductCardFields;
 export declare function productCardDetailed(fields: ProductCardDetailedFields): ProductCardDetailedFields;
 export declare const CanonicalFormat: {
-    readonly ref: typeof formatRef;
-    readonly refs: typeof formatRefs;
     readonly declaration: typeof canonicalFormatDeclaration;
     readonly image: typeof imageFormatDeclaration;
     readonly html5: typeof html5FormatDeclaration;

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

@@ -1,6 +1,9 @@
 import type { FormatReferenceStructuredObject } from '../../types/core.generated';
-import type { AgentPlacementFormatDeclaration, CustomFormatDeclaration, DAASTAudioFormatDeclaration, DisplayTagFormatDeclaration, HTML5FormatDeclaration, HostedAudioFormatDeclaration, HostedVideoFormatDeclaration, ImageAsset, ImageCarouselFormatDeclaration, ImageFormatDeclaration, NativeInFeedFormatDeclaration, ProductFormatDeclaration, ResponsiveCreativeFormatDeclaration, SponsoredPlacementFormatDeclaration, VASTVideoFormatDeclaration } from '../../types/tools.generated';
-type WithCommonDeclaration<T> = ProductFormatDeclaration & T;
+import type { AgentPlacementFormatDeclaration, CustomFormatDeclaration, DAASTAudioFormatDeclaration, DisplayTagFormatDeclaration, HTML5FormatDeclaration, HostedAudioFormatDeclaration, HostedVideoFormatDeclaration, ImageAsset, ImageCarouselFormatDeclaration, ImageFormatDeclaration, NativeInFeedFormatDeclaration, ResponsiveCreativeFormatDeclaration, SponsoredPlacementFormatDeclaration, VASTVideoFormatDeclaration } from '../../types/tools.generated';
+import type { CanonicalFormatDeclaration as CanonicalBaseFormatDeclaration } from './legacy-metadata';
+type WithCommonDeclaration<T> = CanonicalBaseFormatDeclaration & Omit<T, 'v1_format_ref'> & {
+    v1_format_ref?: never;
+};
 interface CanonicalFormatDeclarationMap {
     image: WithCommonDeclaration<ImageFormatDeclaration>;
     html5: WithCommonDeclaration<HTML5FormatDeclaration>;
@@ -45,8 +48,8 @@ export interface ProductCardDetailedFields {
  * bare string when populating Product.format_ids, ProductFormatDeclaration
  * v1_format_ref, or list_creative_formats filters.
  */
-export declare function formatRef(agent_url: string, id: string, fields?: Omit<Partial<FormatReferenceStructuredObject>, 'agent_url' | 'id'> & Record<string, unknown>): FormatReferenceStructuredObject;
-export declare function formatRefs(...refs: FormatReferenceInput[]): FormatReferenceStructuredObject[];
+export declare function legacyFormatRef(agent_url: string, id: string, fields?: Omit<Partial<FormatReferenceStructuredObject>, 'agent_url' | 'id'> & Record<string, unknown>): FormatReferenceStructuredObject;
+export declare function legacyFormatRefs(...refs: FormatReferenceInput[]): FormatReferenceStructuredObject[];
 /**
  * Generic canonical-format declaration builder. It sets the format_kind
  * discriminator and keeps common declaration metadata in the third argument.
@@ -72,8 +75,6 @@ export declare function customFormatDeclaration(format_shape: string, format_sch
 export declare function productCard(fields: ProductCardFields): ProductCardFields;
 export declare function productCardDetailed(fields: ProductCardDetailedFields): ProductCardDetailedFields;
 export declare const CanonicalFormat: {
-    readonly ref: typeof formatRef;
-    readonly refs: typeof formatRefs;
     readonly declaration: typeof canonicalFormatDeclaration;
     readonly image: typeof imageFormatDeclaration;
     readonly html5: typeof html5FormatDeclaration;

package/dist/lib/v2/projection/builders.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../../../src/lib/v2/projection/builders.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../../../src/lib/v2/projection/builders.ts"],"names":[],"mappings":"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"}

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

@@ -25,11 +25,11 @@ __export(builders_exports, {
   canonicalFormatDeclaration: () => canonicalFormatDeclaration,
   customFormatDeclaration: () => customFormatDeclaration,
   displayTagFormatDeclaration: () => displayTagFormatDeclaration,
-  formatRef: () => formatRef,
-  formatRefs: () => formatRefs,
   html5FormatDeclaration: () => html5FormatDeclaration,
   imageCarouselFormatDeclaration: () => imageCarouselFormatDeclaration,
   imageFormatDeclaration: () => imageFormatDeclaration,
+  legacyFormatRef: () => legacyFormatRef,
+  legacyFormatRefs: () => legacyFormatRefs,
   nativeInFeedFormatDeclaration: () => nativeInFeedFormatDeclaration,
   productCard: () => productCard,
   productCardDetailed: () => productCardDetailed,
@@ -39,13 +39,18 @@ __export(builders_exports, {
   videoVastFormatDeclaration: () => videoVastFormatDeclaration
 });
 module.exports = __toCommonJS(builders_exports);
-function formatRef(agent_url, id, fields = {}) {
+function legacyFormatRef(agent_url, id, fields = {}) {
   return { ...fields, agent_url, id };
 }
-function formatRefs(...refs) {
+function legacyFormatRefs(...refs) {
   return refs.map((ref) => ({ ...ref }));
 }
 function canonicalFormatDeclaration(format_kind, params, fields = {}) {
+  if (Reflect.has(fields, "v1_format_ref")) {
+    throw new Error(
+      "canonicalFormatDeclaration does not accept legacy routing references; use explicitly named legacy migration helpers outside the canonical surface"
+    );
+  }
   return { ...fields, format_kind, params };
 }
 function imageFormatDeclaration(params, fields = {}) {
@@ -98,8 +103,6 @@ function productCardDetailed(fields) {
   };
 }
 const CanonicalFormat = {
-  ref: formatRef,
-  refs: formatRefs,
   declaration: canonicalFormatDeclaration,
   image: imageFormatDeclaration,
   html5: html5FormatDeclaration,
@@ -126,11 +129,11 @@ const CanonicalFormat = {
   canonicalFormatDeclaration,
   customFormatDeclaration,
   displayTagFormatDeclaration,
-  formatRef,
-  formatRefs,
   html5FormatDeclaration,
   imageCarouselFormatDeclaration,
   imageFormatDeclaration,
+  legacyFormatRef,
+  legacyFormatRefs,
   nativeInFeedFormatDeclaration,
   productCard,
   productCardDetailed,