@adcp/sdk 12.1.0 → 13.0.0-rc.0

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

@@ -0,0 +1,73 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var legacy_metadata_exports = {};
+__export(legacy_metadata_exports, {
+  concealLegacyFormatRefs: () => concealLegacyFormatRefs,
+  concealSelectedFormatOptions: () => concealSelectedFormatOptions,
+  legacyFormatRefsForDeclaration: () => legacyFormatRefsForDeclaration,
+  selectedFormatOptions: () => selectedFormatOptions,
+  transferLegacyCreativeMetadata: () => transferLegacyCreativeMetadata
+});
+module.exports = __toCommonJS(legacy_metadata_exports);
+const legacyRefsByDeclaration = /* @__PURE__ */ new WeakMap();
+const selectedOptionsByRefs = /* @__PURE__ */ new WeakMap();
+function concealLegacyFormatRefs(declaration) {
+  const { v1_format_ref: refs, ...canonical } = declaration;
+  const existingHidden = legacyRefsByDeclaration.get(declaration);
+  const refsToConceal = Array.isArray(existingHidden) && existingHidden.length > 0 ? existingHidden : refs;
+  if (Array.isArray(refsToConceal) && refsToConceal.length > 0) {
+    legacyRefsByDeclaration.set(
+      canonical,
+      refsToConceal.map((ref) => ({ ...ref }))
+    );
+  }
+  return canonical;
+}
+function legacyFormatRefsForDeclaration(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return [];
+  const declaration = value;
+  const hidden = legacyRefsByDeclaration.get(declaration);
+  if (Array.isArray(hidden)) return hidden;
+  return Array.isArray(declaration.v1_format_ref) ? declaration.v1_format_ref : [];
+}
+function selectedFormatOptions(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return [];
+  const refs = value.format_option_refs;
+  if (!Array.isArray(refs)) return [];
+  const selected = selectedOptionsByRefs.get(refs);
+  return Array.isArray(selected) ? selected : [];
+}
+function concealSelectedFormatOptions(refs, declarations) {
+  selectedOptionsByRefs.set(refs, declarations);
+}
+function transferLegacyCreativeMetadata(source, target) {
+  const refs = legacyRefsByDeclaration.get(source);
+  if (refs) legacyRefsByDeclaration.set(target, refs);
+  const selected = selectedOptionsByRefs.get(source);
+  if (selected) selectedOptionsByRefs.set(target, selected);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  concealLegacyFormatRefs,
+  concealSelectedFormatOptions,
+  legacyFormatRefsForDeclaration,
+  selectedFormatOptions,
+  transferLegacyCreativeMetadata
+});
+//# sourceMappingURL=legacy-metadata.js.map

package/dist/lib/v2/projection/legacy-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/lib/v2/projection/legacy-metadata.ts"],"sourcesContent":["import type { ProductFormatDeclaration } from '../../types/tools.generated';\nimport type { V1FormatId, V2ProductFormatDeclaration } from './types';\n\n/**\n * SDK-private downgrade metadata held out-of-band. WeakMaps keep legacy\n * routing identifiers absent from canonical objects even under reflective\n * inspection while still allowing object-spread package authoring.\n */\n\nexport type CanonicalFormatDeclaration = Omit<V2ProductFormatDeclaration, 'v1_format_ref'> & {\n  v1_format_ref?: never;\n};\n\ntype DeclarationWithMetadata = CanonicalFormatDeclaration;\n\nexport type PackageSelectionMetadata = {\n  format_option_refs?: readonly unknown[];\n};\n\nconst legacyRefsByDeclaration = new WeakMap<object, readonly V1FormatId[]>();\nconst selectedOptionsByRefs = new WeakMap<object, readonly DeclarationWithMetadata[]>();\n\nexport function concealLegacyFormatRefs(\n  declaration: ProductFormatDeclaration | V2ProductFormatDeclaration | CanonicalFormatDeclaration\n): DeclarationWithMetadata {\n  const { v1_format_ref: refs, ...canonical } = declaration as ProductFormatDeclaration;\n  const existingHidden = legacyRefsByDeclaration.get(declaration as object);\n  const refsToConceal = Array.isArray(existingHidden) && existingHidden.length > 0 ? existingHidden : refs;\n  if (Array.isArray(refsToConceal) && refsToConceal.length > 0) {\n    legacyRefsByDeclaration.set(\n      canonical,\n      refsToConceal.map(ref => ({ ...ref }))\n    );\n  }\n  return canonical as DeclarationWithMetadata;\n}\n\nexport function legacyFormatRefsForDeclaration(value: unknown): readonly V1FormatId[] {\n  if (!value || typeof value !== 'object' || Array.isArray(value)) return [];\n  const declaration = value as ProductFormatDeclaration & DeclarationWithMetadata;\n  const hidden = legacyRefsByDeclaration.get(declaration);\n  if (Array.isArray(hidden)) return hidden;\n  return Array.isArray(declaration.v1_format_ref) ? declaration.v1_format_ref : [];\n}\n\nexport function selectedFormatOptions(value: unknown): readonly DeclarationWithMetadata[] {\n  if (!value || typeof value !== 'object' || Array.isArray(value)) return [];\n  const refs = (value as PackageSelectionMetadata).format_option_refs;\n  if (!Array.isArray(refs)) return [];\n  const selected = selectedOptionsByRefs.get(refs);\n  return Array.isArray(selected) ? selected : [];\n}\n\nexport function concealSelectedFormatOptions(\n  refs: readonly unknown[],\n  declarations: readonly DeclarationWithMetadata[]\n): void {\n  selectedOptionsByRefs.set(refs, declarations);\n}\n\n/** Preserve out-of-band downgrade metadata when a canonical sanitizer clones a value. */\nexport function transferLegacyCreativeMetadata(source: object, target: object): void {\n  const refs = legacyRefsByDeclaration.get(source);\n  if (refs) legacyRefsByDeclaration.set(target, refs);\n  const selected = selectedOptionsByRefs.get(source);\n  if (selected) selectedOptionsByRefs.set(target, selected);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAmBA,MAAM,0BAA0B,oBAAI,QAAuC;AAC3E,MAAM,wBAAwB,oBAAI,QAAoD;AAE/E,SAAS,wBACd,aACyB;AACzB,QAAM,EAAE,eAAe,MAAM,GAAG,UAAU,IAAI;AAC9C,QAAM,iBAAiB,wBAAwB,IAAI,WAAqB;AACxE,QAAM,gBAAgB,MAAM,QAAQ,cAAc,KAAK,eAAe,SAAS,IAAI,iBAAiB;AACpG,MAAI,MAAM,QAAQ,aAAa,KAAK,cAAc,SAAS,GAAG;AAC5D,4BAAwB;AAAA,MACtB;AAAA,MACA,cAAc,IAAI,UAAQ,EAAE,GAAG,IAAI,EAAE;AAAA,IACvC;AAAA,EACF;AACA,SAAO;AACT;AAEO,SAAS,+BAA+B,OAAuC;AACpF,MAAI,CAAC,SAAS,OAAO,UAAU,YAAY,MAAM,QAAQ,KAAK,EAAG,QAAO,CAAC;AACzE,QAAM,cAAc;AACpB,QAAM,SAAS,wBAAwB,IAAI,WAAW;AACtD,MAAI,MAAM,QAAQ,MAAM,EAAG,QAAO;AAClC,SAAO,MAAM,QAAQ,YAAY,aAAa,IAAI,YAAY,gBAAgB,CAAC;AACjF;AAEO,SAAS,sBAAsB,OAAoD;AACxF,MAAI,CAAC,SAAS,OAAO,UAAU,YAAY,MAAM,QAAQ,KAAK,EAAG,QAAO,CAAC;AACzE,QAAM,OAAQ,MAAmC;AACjD,MAAI,CAAC,MAAM,QAAQ,IAAI,EAAG,QAAO,CAAC;AAClC,QAAM,WAAW,sBAAsB,IAAI,IAAI;AAC/C,SAAO,MAAM,QAAQ,QAAQ,IAAI,WAAW,CAAC;AAC/C;AAEO,SAAS,6BACd,MACA,cACM;AACN,wBAAsB,IAAI,MAAM,YAAY;AAC9C;AAGO,SAAS,+BAA+B,QAAgB,QAAsB;AACnF,QAAM,OAAO,wBAAwB,IAAI,MAAM;AAC/C,MAAI,KAAM,yBAAwB,IAAI,QAAQ,IAAI;AAClD,QAAM,WAAW,sBAAsB,IAAI,MAAM;AACjD,MAAI,SAAU,uBAAsB,IAAI,QAAQ,QAAQ;AAC1D;","names":[]}

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

@@ -0,0 +1,45 @@
+const legacyRefsByDeclaration = /* @__PURE__ */ new WeakMap();
+const selectedOptionsByRefs = /* @__PURE__ */ new WeakMap();
+function concealLegacyFormatRefs(declaration) {
+  const { v1_format_ref: refs, ...canonical } = declaration;
+  const existingHidden = legacyRefsByDeclaration.get(declaration);
+  const refsToConceal = Array.isArray(existingHidden) && existingHidden.length > 0 ? existingHidden : refs;
+  if (Array.isArray(refsToConceal) && refsToConceal.length > 0) {
+    legacyRefsByDeclaration.set(
+      canonical,
+      refsToConceal.map((ref) => ({ ...ref }))
+    );
+  }
+  return canonical;
+}
+function legacyFormatRefsForDeclaration(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return [];
+  const declaration = value;
+  const hidden = legacyRefsByDeclaration.get(declaration);
+  if (Array.isArray(hidden)) return hidden;
+  return Array.isArray(declaration.v1_format_ref) ? declaration.v1_format_ref : [];
+}
+function selectedFormatOptions(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return [];
+  const refs = value.format_option_refs;
+  if (!Array.isArray(refs)) return [];
+  const selected = selectedOptionsByRefs.get(refs);
+  return Array.isArray(selected) ? selected : [];
+}
+function concealSelectedFormatOptions(refs, declarations) {
+  selectedOptionsByRefs.set(refs, declarations);
+}
+function transferLegacyCreativeMetadata(source, target) {
+  const refs = legacyRefsByDeclaration.get(source);
+  if (refs) legacyRefsByDeclaration.set(target, refs);
+  const selected = selectedOptionsByRefs.get(source);
+  if (selected) selectedOptionsByRefs.set(target, selected);
+}
+export {
+  concealLegacyFormatRefs,
+  concealSelectedFormatOptions,
+  legacyFormatRefsForDeclaration,
+  selectedFormatOptions,
+  transferLegacyCreativeMetadata
+};
+//# sourceMappingURL=legacy-metadata.mjs.map

package/dist/lib/v2/projection/legacy-metadata.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/lib/v2/projection/legacy-metadata.ts"],"sourcesContent":["import type { ProductFormatDeclaration } from '../../types/tools.generated';\nimport type { V1FormatId, V2ProductFormatDeclaration } from './types';\n\n/**\n * SDK-private downgrade metadata held out-of-band. WeakMaps keep legacy\n * routing identifiers absent from canonical objects even under reflective\n * inspection while still allowing object-spread package authoring.\n */\n\nexport type CanonicalFormatDeclaration = Omit<V2ProductFormatDeclaration, 'v1_format_ref'> & {\n  v1_format_ref?: never;\n};\n\ntype DeclarationWithMetadata = CanonicalFormatDeclaration;\n\nexport type PackageSelectionMetadata = {\n  format_option_refs?: readonly unknown[];\n};\n\nconst legacyRefsByDeclaration = new WeakMap<object, readonly V1FormatId[]>();\nconst selectedOptionsByRefs = new WeakMap<object, readonly DeclarationWithMetadata[]>();\n\nexport function concealLegacyFormatRefs(\n  declaration: ProductFormatDeclaration | V2ProductFormatDeclaration | CanonicalFormatDeclaration\n): DeclarationWithMetadata {\n  const { v1_format_ref: refs, ...canonical } = declaration as ProductFormatDeclaration;\n  const existingHidden = legacyRefsByDeclaration.get(declaration as object);\n  const refsToConceal = Array.isArray(existingHidden) && existingHidden.length > 0 ? existingHidden : refs;\n  if (Array.isArray(refsToConceal) && refsToConceal.length > 0) {\n    legacyRefsByDeclaration.set(\n      canonical,\n      refsToConceal.map(ref => ({ ...ref }))\n    );\n  }\n  return canonical as DeclarationWithMetadata;\n}\n\nexport function legacyFormatRefsForDeclaration(value: unknown): readonly V1FormatId[] {\n  if (!value || typeof value !== 'object' || Array.isArray(value)) return [];\n  const declaration = value as ProductFormatDeclaration & DeclarationWithMetadata;\n  const hidden = legacyRefsByDeclaration.get(declaration);\n  if (Array.isArray(hidden)) return hidden;\n  return Array.isArray(declaration.v1_format_ref) ? declaration.v1_format_ref : [];\n}\n\nexport function selectedFormatOptions(value: unknown): readonly DeclarationWithMetadata[] {\n  if (!value || typeof value !== 'object' || Array.isArray(value)) return [];\n  const refs = (value as PackageSelectionMetadata).format_option_refs;\n  if (!Array.isArray(refs)) return [];\n  const selected = selectedOptionsByRefs.get(refs);\n  return Array.isArray(selected) ? selected : [];\n}\n\nexport function concealSelectedFormatOptions(\n  refs: readonly unknown[],\n  declarations: readonly DeclarationWithMetadata[]\n): void {\n  selectedOptionsByRefs.set(refs, declarations);\n}\n\n/** Preserve out-of-band downgrade metadata when a canonical sanitizer clones a value. */\nexport function transferLegacyCreativeMetadata(source: object, target: object): void {\n  const refs = legacyRefsByDeclaration.get(source);\n  if (refs) legacyRefsByDeclaration.set(target, refs);\n  const selected = selectedOptionsByRefs.get(source);\n  if (selected) selectedOptionsByRefs.set(target, selected);\n}\n"],"mappings":"AAmBA,MAAM,0BAA0B,oBAAI,QAAuC;AAC3E,MAAM,wBAAwB,oBAAI,QAAoD;AAE/E,SAAS,wBACd,aACyB;AACzB,QAAM,EAAE,eAAe,MAAM,GAAG,UAAU,IAAI;AAC9C,QAAM,iBAAiB,wBAAwB,IAAI,WAAqB;AACxE,QAAM,gBAAgB,MAAM,QAAQ,cAAc,KAAK,eAAe,SAAS,IAAI,iBAAiB;AACpG,MAAI,MAAM,QAAQ,aAAa,KAAK,cAAc,SAAS,GAAG;AAC5D,4BAAwB;AAAA,MACtB;AAAA,MACA,cAAc,IAAI,UAAQ,EAAE,GAAG,IAAI,EAAE;AAAA,IACvC;AAAA,EACF;AACA,SAAO;AACT;AAEO,SAAS,+BAA+B,OAAuC;AACpF,MAAI,CAAC,SAAS,OAAO,UAAU,YAAY,MAAM,QAAQ,KAAK,EAAG,QAAO,CAAC;AACzE,QAAM,cAAc;AACpB,QAAM,SAAS,wBAAwB,IAAI,WAAW;AACtD,MAAI,MAAM,QAAQ,MAAM,EAAG,QAAO;AAClC,SAAO,MAAM,QAAQ,YAAY,aAAa,IAAI,YAAY,gBAAgB,CAAC;AACjF;AAEO,SAAS,sBAAsB,OAAoD;AACxF,MAAI,CAAC,SAAS,OAAO,UAAU,YAAY,MAAM,QAAQ,KAAK,EAAG,QAAO,CAAC;AACzE,QAAM,OAAQ,MAAmC;AACjD,MAAI,CAAC,MAAM,QAAQ,IAAI,EAAG,QAAO,CAAC;AAClC,QAAM,WAAW,sBAAsB,IAAI,IAAI;AAC/C,SAAO,MAAM,QAAQ,QAAQ,IAAI,WAAW,CAAC;AAC/C;AAEO,SAAS,6BACd,MACA,cACM;AACN,wBAAsB,IAAI,MAAM,YAAY;AAC9C;AAGO,SAAS,+BAA+B,QAAgB,QAAsB;AACnF,QAAM,OAAO,wBAAwB,IAAI,MAAM;AAC/C,MAAI,KAAM,yBAAwB,IAAI,QAAQ,IAAI;AAClD,QAAM,WAAW,sBAAsB,IAAI,MAAM;AACjD,MAAI,SAAU,uBAAsB,IAAI,QAAQ,QAAQ;AAC1D;","names":[]}

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

@@ -79,8 +79,9 @@ export interface V1Product {
     [k: string]: unknown;
 }
 /**
- * Structured diagnostic shape matching the spec's `errors[]` augmentation
- * contract (`source: "sdk"`, `sdk_id`, `code`, `field`, `error.details`).
+ * Internal structured diagnostic produced by the pure projection algorithms.
+ * `toCanonicalOnlyResponse()` flattens this into the protocol `Error` shape
+ * (`message` plus top-level `details`) before augmenting `errors[]`.
  * Spec codes — `FORMAT_PROJECTION_FAILED` and `FORMAT_DECLARATION_V1_AMBIGUOUS`
  * — come straight from `enums/error-code.json`. The two SDK-local codes
  * (`*_NOT_APPLICABLE`, `CANONICAL_NOT_V1_TRANSLATABLE`) cover cases the
@@ -88,10 +89,9 @@ export interface V1Product {
  * skip silently") but where buyer-side transparency is more useful
  * than silent product drops.
  *
- * **Never logger-only**, per the resolution-order amendment — emitted
- * on the response envelope's `errors[]` array and surfaced on the
- * SDK's `TaskResult` for caller-side handling without re-walking
- * `errors[]`.
+ * **Never logger-only**, per the resolution-order amendment. The internal
+ * nesting keeps projection code strongly discriminated; it is not itself a
+ * wire/protocol Error and must be normalized before public response emission.
  */
 export interface ProjectionDiagnosticBase {
     /** Spec-mandated origin marker for SDK-augmented diagnostics. */
@@ -102,6 +102,19 @@ export interface ProjectionDiagnosticBase {
     field: string;
 }
 export type ProjectionDiagnostic = (ProjectionDiagnosticBase & {
+    /**
+     * SDK-local code: a valid seller product cannot be represented on the
+     * canonical-only public surface because it has no canonical option.
+     * Legacy `format_ids: []` is format-agnostic, not a failed lookup.
+     */
+    code: 'CANONICAL_PRODUCT_FORMATS_UNAVAILABLE';
+    error: {
+        details: {
+            product_id: string;
+            reason: 'legacy_format_list_empty' | 'canonical_format_list_empty' | 'missing_format_declaration' | 'nested_placement_format_list_empty';
+        };
+    };
+}) | (ProjectionDiagnosticBase & {
     /**
      * Spec code (`enums/error-code.json`): registry-coverage gap or
      * v1-catalog-coverage gap depending on `resolution_failure`:
@@ -119,6 +132,10 @@ export type ProjectionDiagnostic = (ProjectionDiagnosticBase & {
      *     possible"; this signals "no v2 form yet."
      *   - `no_match` — v1→v2 direction, format not in catalog or
      *     registry, no structural match.
+     *   - `invalid_format_id_parameters` — the legacy ref carries
+     *     malformed dimensional or duration discriminators.
+     *   - `catalog_requirement_conflict` — catalog-authored fixed
+     *     requirements are internally ambiguous or contradict the ref.
      */
     code: 'FORMAT_PROJECTION_FAILED';
     error: {
@@ -126,7 +143,8 @@ export type ProjectionDiagnostic = (ProjectionDiagnosticBase & {
             format_kind: CanonicalFormatKind;
             product_id: string;
             format_option_id?: string;
-            resolution_failure: 'no_registry_match' | 'catalog_lacks_canonical_annotation' | 'no_match';
+            resolution_failure: 'no_registry_match' | 'catalog_lacks_canonical_annotation' | 'no_match' | 'custom_converter_failed' | 'invalid_format_id_parameters' | 'catalog_requirement_conflict';
+            converter_error?: string;
         };
     };
 }) | (ProjectionDiagnosticBase & {
@@ -226,8 +244,8 @@ export type ProjectionDiagnostic = (ProjectionDiagnosticBase & {
 }) | (ProjectionDiagnosticBase & {
     /**
      * SDK-local code: canonical-only projection (`toCanonicalOnlyProduct`
-     * / `toCanonicalOnlyResponse`) dropped a legacy `format_id` that no
-     * `format_options[].v1_format_ref` covers. Emitted only on the
+     * / `toCanonicalOnlyResponse`) found legacy routing metadata that no
+     * canonical format option covers. Emitted only on the
      * v2-native pass-through path — a seller that sent `format_options[]`
      * directly but also carried a `format_ids[]` entry with no canonical
      * representation. Without it, canonical-only mode would silently
@@ -243,20 +261,8 @@ export type ProjectionDiagnostic = (ProjectionDiagnosticBase & {
     error: {
         details: {
             product_id: string;
-            /**
-             * The full ref that was dropped, including the dimensional
-             * discriminators (`width` / `height` / `duration_ms`) when the
-             * input carried them — so a buyer can tell which variant of a
-             * multi-size/multi-duration family was lost and re-acquire it on
-             * the v1 path. Omitted keys mean the input ref carried no value.
-             */
-            dropped_format_id: {
-                agent_url: string;
-                id: string;
-                width?: number;
-                height?: number;
-                duration_ms?: number;
-            };
+            /** Stable category only; canonical diagnostics never echo routing identifiers. */
+            resolution_failure: 'unmapped_legacy_format';
         };
     };
 });

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

@@ -79,8 +79,9 @@ export interface V1Product {
     [k: string]: unknown;
 }
 /**
- * Structured diagnostic shape matching the spec's `errors[]` augmentation
- * contract (`source: "sdk"`, `sdk_id`, `code`, `field`, `error.details`).
+ * Internal structured diagnostic produced by the pure projection algorithms.
+ * `toCanonicalOnlyResponse()` flattens this into the protocol `Error` shape
+ * (`message` plus top-level `details`) before augmenting `errors[]`.
  * Spec codes — `FORMAT_PROJECTION_FAILED` and `FORMAT_DECLARATION_V1_AMBIGUOUS`
  * — come straight from `enums/error-code.json`. The two SDK-local codes
  * (`*_NOT_APPLICABLE`, `CANONICAL_NOT_V1_TRANSLATABLE`) cover cases the
@@ -88,10 +89,9 @@ export interface V1Product {
  * skip silently") but where buyer-side transparency is more useful
  * than silent product drops.
  *
- * **Never logger-only**, per the resolution-order amendment — emitted
- * on the response envelope's `errors[]` array and surfaced on the
- * SDK's `TaskResult` for caller-side handling without re-walking
- * `errors[]`.
+ * **Never logger-only**, per the resolution-order amendment. The internal
+ * nesting keeps projection code strongly discriminated; it is not itself a
+ * wire/protocol Error and must be normalized before public response emission.
  */
 export interface ProjectionDiagnosticBase {
     /** Spec-mandated origin marker for SDK-augmented diagnostics. */
@@ -102,6 +102,19 @@ export interface ProjectionDiagnosticBase {
     field: string;
 }
 export type ProjectionDiagnostic = (ProjectionDiagnosticBase & {
+    /**
+     * SDK-local code: a valid seller product cannot be represented on the
+     * canonical-only public surface because it has no canonical option.
+     * Legacy `format_ids: []` is format-agnostic, not a failed lookup.
+     */
+    code: 'CANONICAL_PRODUCT_FORMATS_UNAVAILABLE';
+    error: {
+        details: {
+            product_id: string;
+            reason: 'legacy_format_list_empty' | 'canonical_format_list_empty' | 'missing_format_declaration' | 'nested_placement_format_list_empty';
+        };
+    };
+}) | (ProjectionDiagnosticBase & {
     /**
      * Spec code (`enums/error-code.json`): registry-coverage gap or
      * v1-catalog-coverage gap depending on `resolution_failure`:
@@ -119,6 +132,10 @@ export type ProjectionDiagnostic = (ProjectionDiagnosticBase & {
      *     possible"; this signals "no v2 form yet."
      *   - `no_match` — v1→v2 direction, format not in catalog or
      *     registry, no structural match.
+     *   - `invalid_format_id_parameters` — the legacy ref carries
+     *     malformed dimensional or duration discriminators.
+     *   - `catalog_requirement_conflict` — catalog-authored fixed
+     *     requirements are internally ambiguous or contradict the ref.
      */
     code: 'FORMAT_PROJECTION_FAILED';
     error: {
@@ -126,7 +143,8 @@ export type ProjectionDiagnostic = (ProjectionDiagnosticBase & {
             format_kind: CanonicalFormatKind;
             product_id: string;
             format_option_id?: string;
-            resolution_failure: 'no_registry_match' | 'catalog_lacks_canonical_annotation' | 'no_match';
+            resolution_failure: 'no_registry_match' | 'catalog_lacks_canonical_annotation' | 'no_match' | 'custom_converter_failed' | 'invalid_format_id_parameters' | 'catalog_requirement_conflict';
+            converter_error?: string;
         };
     };
 }) | (ProjectionDiagnosticBase & {
@@ -226,8 +244,8 @@ export type ProjectionDiagnostic = (ProjectionDiagnosticBase & {
 }) | (ProjectionDiagnosticBase & {
     /**
      * SDK-local code: canonical-only projection (`toCanonicalOnlyProduct`
-     * / `toCanonicalOnlyResponse`) dropped a legacy `format_id` that no
-     * `format_options[].v1_format_ref` covers. Emitted only on the
+     * / `toCanonicalOnlyResponse`) found legacy routing metadata that no
+     * canonical format option covers. Emitted only on the
      * v2-native pass-through path — a seller that sent `format_options[]`
      * directly but also carried a `format_ids[]` entry with no canonical
      * representation. Without it, canonical-only mode would silently
@@ -243,20 +261,8 @@ export type ProjectionDiagnostic = (ProjectionDiagnosticBase & {
     error: {
         details: {
             product_id: string;
-            /**
-             * The full ref that was dropped, including the dimensional
-             * discriminators (`width` / `height` / `duration_ms`) when the
-             * input carried them — so a buyer can tell which variant of a
-             * multi-size/multi-duration family was lost and re-acquire it on
-             * the v1 path. Omitted keys mean the input ref carried no value.
-             */
-            dropped_format_id: {
-                agent_url: string;
-                id: string;
-                width?: number;
-                height?: number;
-                duration_ms?: number;
-            };
+            /** Stable category only; canonical diagnostics never echo routing identifiers. */
+            resolution_failure: 'unmapped_legacy_format';
         };
     };
 });

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

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

package/dist/lib/v2/projection/types.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../src/lib/v2/projection/types.ts"],"sourcesContent":["/**\n * Hand-rolled type surface for the v2 → v1 projection layer.\n *\n * These shadow `schemas/cache/3.1.0-beta.0/core/{product,product-format-declaration,format-id}.json`\n * at the precision the projection layer cares about — slot-level fields\n * like `slots[]`, `platform_extensions[]`, and per-canonical params blocks\n * are kept loose (`Record<string, unknown>`) because the projection\n * algorithm doesn't read them. Root-level canonical format builders use the\n * generated `ProductFormatDeclaration` types; these projection-local shapes\n * remain for legacy projection APIs and diagnostics.\n */\n\n/** v1 format_id (`{ agent_url, id }`). Same shape in 3.0 and 3.1. */\nexport interface V1FormatId {\n  agent_url: string;\n  id: string;\n  width?: number;\n  height?: number;\n  duration_ms?: number;\n}\n\n/**\n * 12 canonical `format_kind` values from\n * `static/schemas/source/formats/canonical/` plus the `custom` escape\n * hatch. Kept as a literal union so a future canonical gets surfaced at\n * the projection's switch statement (exhaustive-check).\n */\nexport type CanonicalFormatKind =\n  | 'image'\n  | 'html5'\n  | 'display_tag'\n  | 'image_carousel'\n  | 'video_hosted'\n  | 'video_vast'\n  | 'audio_hosted'\n  | 'audio_daast'\n  | 'sponsored_placement'\n  | 'native_in_feed'\n  | 'responsive_creative'\n  | 'agent_placement'\n  | 'custom';\n\n/**\n * v2 `ProductFormatDeclaration`. The `params` object is canonical-specific\n * and stays loose at this layer — the projection algorithm reads only\n * `format_kind`, `v1_format_ref`, and `canonical_formats_only`. Width /\n * height (for image canonicals) are surfaced as optional top-level fields\n * the registry reverse-lookup can read without unwrapping params.\n */\nexport interface V2ProductFormatDeclaration {\n  format_kind: CanonicalFormatKind;\n  params: Record<string, unknown>;\n  capability_id?: string;\n  format_option_id?: string;\n  publisher_domain?: string;\n  display_name?: string;\n  seller_preference?: 'preferred' | 'accepted' | 'discouraged';\n  applies_to_channels?: string[];\n  canonical_formats_only?: boolean;\n  experimental?: boolean;\n  format_shape?: string;\n  /**\n   * Authoritative v2 → v1 link. Always an array (3.1-beta normative): single-ref\n   * is `[{...}]`, multi-size carries one entry per size. v1-only buyers see\n   * every entry via `format_ids[]` dual-emission. When `v1_format_ref.length <\n   * params.sizes.length`, SDKs emit `FORMAT_DECLARATION_V1_LOSSY_MULTI_SIZE`\n   * to signal incomplete coverage.\n   */\n  v1_format_ref?: V1FormatId[];\n  format_schema?: { uri: string; digest: string };\n}\n\n/**\n * Public-surface Product (V2-shaped per the 8.0 design at\n * `docs/development/v3.1-sdk-design.md`). All other fields are passthrough.\n */\nexport interface V2Product {\n  product_id: string;\n  name: string;\n  description: string;\n  format_options: V2ProductFormatDeclaration[];\n  [k: string]: unknown;\n}\n\n/**\n * Wire-level v1 Product. Carries `format_ids` (the v1 path). Other fields\n * are passthrough; we don't model them at the projection layer.\n */\nexport interface V1Product {\n  product_id: string;\n  name: string;\n  description: string;\n  format_ids: V1FormatId[];\n  [k: string]: unknown;\n}\n\n/**\n * Structured diagnostic shape matching the spec's `errors[]` augmentation\n * contract (`source: \"sdk\"`, `sdk_id`, `code`, `field`, `error.details`).\n * Spec codes — `FORMAT_PROJECTION_FAILED` and `FORMAT_DECLARATION_V1_AMBIGUOUS`\n * — come straight from `enums/error-code.json`. The two SDK-local codes\n * (`*_NOT_APPLICABLE`, `CANONICAL_NOT_V1_TRANSLATABLE`) cover cases the\n * spec leaves to SDK discretion (\"surface as a different diagnostic or\n * skip silently\") but where buyer-side transparency is more useful\n * than silent product drops.\n *\n * **Never logger-only**, per the resolution-order amendment — emitted\n * on the response envelope's `errors[]` array and surfaced on the\n * SDK's `TaskResult` for caller-side handling without re-walking\n * `errors[]`.\n */\nexport interface ProjectionDiagnosticBase {\n  /** Spec-mandated origin marker for SDK-augmented diagnostics. */\n  source: 'sdk';\n  /** Spec-mandated SDK identity for multi-hop deduplication. */\n  sdk_id: string;\n  /** Field path into the offending declaration. */\n  field: string;\n}\n\nexport type ProjectionDiagnostic =\n  | (ProjectionDiagnosticBase & {\n      /**\n       * Spec code (`enums/error-code.json`): registry-coverage gap or\n       * v1-catalog-coverage gap depending on `resolution_failure`:\n       *\n       *   - `no_registry_match` — v2→v1 direction. Registry has no\n       *     entries for this canonical (and v1_translatable is true).\n       *   - `catalog_lacks_canonical_annotation` — v1→v2 direction.\n       *     The AAO catalog has this v1 format but hasn't annotated\n       *     it with a `canonical:` field. Native, DOOH, broadcast,\n       *     and card-scaffolding categories sit in this bucket at\n       *     3.1 GA. Distinct from a generic registry gap — the\n       *     catalog DOES know the format, it just hasn't blessed a\n       *     v2 canonical mapping yet. Symmetric counterpart to\n       *     CANONICAL_NOT_V1_TRANSLATABLE: that signals \"no v1 form\n       *     possible\"; this signals \"no v2 form yet.\"\n       *   - `no_match` — v1→v2 direction, format not in catalog or\n       *     registry, no structural match.\n       */\n      code: 'FORMAT_PROJECTION_FAILED';\n      error: {\n        details: {\n          format_kind: CanonicalFormatKind;\n          product_id: string;\n          format_option_id?: string;\n          resolution_failure: 'no_registry_match' | 'catalog_lacks_canonical_annotation' | 'no_match';\n        };\n      };\n    })\n  | (ProjectionDiagnosticBase & {\n      /**\n       * Spec code (`enums/error-code.json`): registry has family-level\n       * structural entries for this canonical (e.g., the VAST entries\n       * for `video_vast`), but none are invertible to a specific v1\n       * named format. Family is known, specific format isn't pickable.\n       * Correctable by the seller adding `v1_format_ref` to the\n       * declaration.\n       */\n      code: 'FORMAT_DECLARATION_V1_AMBIGUOUS';\n      error: {\n        details: {\n          format_kind: CanonicalFormatKind;\n          product_id: string;\n          format_option_id?: string;\n          registry_matches: number;\n        };\n      };\n    })\n  | (ProjectionDiagnosticBase & {\n      /**\n       * SDK-local code: declaration has `canonical_formats_only: true`.\n       * Seller explicitly opted out of v1 emission. Not a registry-\n       * coverage gap; not ambiguous. Informational so buyers can see\n       * why a product disappeared from a v1-only catalog.\n       */\n      code: 'FORMAT_DECLARATION_V1_NOT_APPLICABLE';\n      error: {\n        details: {\n          format_kind: CanonicalFormatKind;\n          product_id: string;\n          format_option_id?: string;\n          reason: 'canonical_formats_only';\n        };\n      };\n    })\n  | (ProjectionDiagnosticBase & {\n      /**\n       * SDK-local code: canonical declares `v1_translatable: false`.\n       * Structural v1-unreachability — no v1 form is possible for this\n       * canonical regardless of registry coverage. The 4 inherently-v2\n       * canonicals at 3.1 GA: `image_carousel`, `sponsored_placement`,\n       * `responsive_creative`, `agent_placement`. Spec is explicit:\n       * **SDKs MUST NOT emit `FORMAT_PROJECTION_FAILED`** for these\n       * (they're not coverage gaps).\n       */\n      code: 'CANONICAL_NOT_V1_TRANSLATABLE';\n      error: {\n        details: {\n          format_kind: CanonicalFormatKind;\n          product_id: string;\n          format_option_id?: string;\n        };\n      };\n    })\n  | (ProjectionDiagnosticBase & {\n      /**\n       * SDK-local code: v2 declaration uses multi-size (`sizes: [...]`)\n       * or responsive (`min_width`/`max_width`/`min_height`/`max_height`)\n       * params, but `v1_format_ref` is a single catalog entry that can\n       * only carry ONE fixed (width, height). The v1 wire emit\n       * represents only the seller-chosen representative size; the\n       * remaining sizes are **silently dropped on the v1 wire**.\n       *\n       * This diagnostic is emitted **alongside** the v1 format_id —\n       * not instead of it — so the v1 buyer still sees the product\n       * but the buyer code is told what coverage was lost. Different\n       * from FORMAT_DECLARATION_V1_AMBIGUOUS (no v1 emit) and\n       * FORMAT_DECLARATION_V1_NOT_APPLICABLE (seller opt-out).\n       *\n       * Surface follow-up: an SDK MAY (non-normative) expand multi-\n       * size to N v1 format_ids by looking up the catalog for each\n       * size. Today's prototype emits only the seller-asserted\n       * representative; multi-emit is a follow-up.\n       */\n      code: 'FORMAT_DECLARATION_V1_LOSSY_MULTI_SIZE';\n      error: {\n        details: {\n          format_kind: CanonicalFormatKind;\n          product_id: string;\n          format_option_id?: string;\n          size_mode: 'sizes' | 'responsive_range';\n          declared_sizes_count?: number;\n          /**\n           * How many v1 format_ids the SDK actually emitted. <\n           * `declared_sizes_count` when the catalog doesn't cover every\n           * declared size; equal when the catalog has full coverage.\n           * The fan-out is non-normative — when this equals 1, only the\n           * seller-asserted rep was emitted; v1 buyers lose the rest.\n           */\n          emitted_sizes_count?: number;\n          v1_emit_represents_size?: { width?: number; height?: number };\n        };\n      };\n    })\n  | (ProjectionDiagnosticBase & {\n      /**\n       * SDK-local code: canonical-only projection (`toCanonicalOnlyProduct`\n       * / `toCanonicalOnlyResponse`) dropped a legacy `format_id` that no\n       * `format_options[].v1_format_ref` covers. Emitted only on the\n       * v2-native pass-through path — a seller that sent `format_options[]`\n       * directly but also carried a `format_ids[]` entry with no canonical\n       * representation. Without it, canonical-only mode would silently\n       * discard a format the buyer could still have acted on via the v1\n       * path.\n       *\n       * On the v1 → v2 projection path an unmappable ref is already\n       * surfaced as `FORMAT_PROJECTION_FAILED`; this code covers the gap\n       * the projection path can't see (no projection runs when the seller\n       * is already v2-native).\n       */\n      code: 'LEGACY_FORMAT_ID_DROPPED_UNMAPPED';\n      error: {\n        details: {\n          product_id: string;\n          /**\n           * The full ref that was dropped, including the dimensional\n           * discriminators (`width` / `height` / `duration_ms`) when the\n           * input carried them — so a buyer can tell which variant of a\n           * multi-size/multi-duration family was lost and re-acquire it on\n           * the v1 path. Omitted keys mean the input ref carried no value.\n           */\n          dropped_format_id: { agent_url: string; id: string; width?: number; height?: number; duration_ms?: number };\n        };\n      };\n    });\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../../../../src/lib/v2/projection/types.ts"],"sourcesContent":["/**\n * Hand-rolled type surface for the v2 → v1 projection layer.\n *\n * These shadow `schemas/cache/3.1.0-beta.0/core/{product,product-format-declaration,format-id}.json`\n * at the precision the projection layer cares about — slot-level fields\n * like `slots[]`, `platform_extensions[]`, and per-canonical params blocks\n * are kept loose (`Record<string, unknown>`) because the projection\n * algorithm doesn't read them. Root-level canonical format builders use the\n * generated `ProductFormatDeclaration` types; these projection-local shapes\n * remain for legacy projection APIs and diagnostics.\n */\n\n/** v1 format_id (`{ agent_url, id }`). Same shape in 3.0 and 3.1. */\nexport interface V1FormatId {\n  agent_url: string;\n  id: string;\n  width?: number;\n  height?: number;\n  duration_ms?: number;\n}\n\n/**\n * 12 canonical `format_kind` values from\n * `static/schemas/source/formats/canonical/` plus the `custom` escape\n * hatch. Kept as a literal union so a future canonical gets surfaced at\n * the projection's switch statement (exhaustive-check).\n */\nexport type CanonicalFormatKind =\n  | 'image'\n  | 'html5'\n  | 'display_tag'\n  | 'image_carousel'\n  | 'video_hosted'\n  | 'video_vast'\n  | 'audio_hosted'\n  | 'audio_daast'\n  | 'sponsored_placement'\n  | 'native_in_feed'\n  | 'responsive_creative'\n  | 'agent_placement'\n  | 'custom';\n\n/**\n * v2 `ProductFormatDeclaration`. The `params` object is canonical-specific\n * and stays loose at this layer — the projection algorithm reads only\n * `format_kind`, `v1_format_ref`, and `canonical_formats_only`. Width /\n * height (for image canonicals) are surfaced as optional top-level fields\n * the registry reverse-lookup can read without unwrapping params.\n */\nexport interface V2ProductFormatDeclaration {\n  format_kind: CanonicalFormatKind;\n  params: Record<string, unknown>;\n  capability_id?: string;\n  format_option_id?: string;\n  publisher_domain?: string;\n  display_name?: string;\n  seller_preference?: 'preferred' | 'accepted' | 'discouraged';\n  applies_to_channels?: string[];\n  canonical_formats_only?: boolean;\n  experimental?: boolean;\n  format_shape?: string;\n  /**\n   * Authoritative v2 → v1 link. Always an array (3.1-beta normative): single-ref\n   * is `[{...}]`, multi-size carries one entry per size. v1-only buyers see\n   * every entry via `format_ids[]` dual-emission. When `v1_format_ref.length <\n   * params.sizes.length`, SDKs emit `FORMAT_DECLARATION_V1_LOSSY_MULTI_SIZE`\n   * to signal incomplete coverage.\n   */\n  v1_format_ref?: V1FormatId[];\n  format_schema?: { uri: string; digest: string };\n}\n\n/**\n * Public-surface Product (V2-shaped per the 8.0 design at\n * `docs/development/v3.1-sdk-design.md`). All other fields are passthrough.\n */\nexport interface V2Product {\n  product_id: string;\n  name: string;\n  description: string;\n  format_options: V2ProductFormatDeclaration[];\n  [k: string]: unknown;\n}\n\n/**\n * Wire-level v1 Product. Carries `format_ids` (the v1 path). Other fields\n * are passthrough; we don't model them at the projection layer.\n */\nexport interface V1Product {\n  product_id: string;\n  name: string;\n  description: string;\n  format_ids: V1FormatId[];\n  [k: string]: unknown;\n}\n\n/**\n * Internal structured diagnostic produced by the pure projection algorithms.\n * `toCanonicalOnlyResponse()` flattens this into the protocol `Error` shape\n * (`message` plus top-level `details`) before augmenting `errors[]`.\n * Spec codes — `FORMAT_PROJECTION_FAILED` and `FORMAT_DECLARATION_V1_AMBIGUOUS`\n * — come straight from `enums/error-code.json`. The two SDK-local codes\n * (`*_NOT_APPLICABLE`, `CANONICAL_NOT_V1_TRANSLATABLE`) cover cases the\n * spec leaves to SDK discretion (\"surface as a different diagnostic or\n * skip silently\") but where buyer-side transparency is more useful\n * than silent product drops.\n *\n * **Never logger-only**, per the resolution-order amendment. The internal\n * nesting keeps projection code strongly discriminated; it is not itself a\n * wire/protocol Error and must be normalized before public response emission.\n */\nexport interface ProjectionDiagnosticBase {\n  /** Spec-mandated origin marker for SDK-augmented diagnostics. */\n  source: 'sdk';\n  /** Spec-mandated SDK identity for multi-hop deduplication. */\n  sdk_id: string;\n  /** Field path into the offending declaration. */\n  field: string;\n}\n\nexport type ProjectionDiagnostic =\n  | (ProjectionDiagnosticBase & {\n      /**\n       * SDK-local code: a valid seller product cannot be represented on the\n       * canonical-only public surface because it has no canonical option.\n       * Legacy `format_ids: []` is format-agnostic, not a failed lookup.\n       */\n      code: 'CANONICAL_PRODUCT_FORMATS_UNAVAILABLE';\n      error: {\n        details: {\n          product_id: string;\n          reason:\n            | 'legacy_format_list_empty'\n            | 'canonical_format_list_empty'\n            | 'missing_format_declaration'\n            | 'nested_placement_format_list_empty';\n        };\n      };\n    })\n  | (ProjectionDiagnosticBase & {\n      /**\n       * Spec code (`enums/error-code.json`): registry-coverage gap or\n       * v1-catalog-coverage gap depending on `resolution_failure`:\n       *\n       *   - `no_registry_match` — v2→v1 direction. Registry has no\n       *     entries for this canonical (and v1_translatable is true).\n       *   - `catalog_lacks_canonical_annotation` — v1→v2 direction.\n       *     The AAO catalog has this v1 format but hasn't annotated\n       *     it with a `canonical:` field. Native, DOOH, broadcast,\n       *     and card-scaffolding categories sit in this bucket at\n       *     3.1 GA. Distinct from a generic registry gap — the\n       *     catalog DOES know the format, it just hasn't blessed a\n       *     v2 canonical mapping yet. Symmetric counterpart to\n       *     CANONICAL_NOT_V1_TRANSLATABLE: that signals \"no v1 form\n       *     possible\"; this signals \"no v2 form yet.\"\n       *   - `no_match` — v1→v2 direction, format not in catalog or\n       *     registry, no structural match.\n       *   - `invalid_format_id_parameters` — the legacy ref carries\n       *     malformed dimensional or duration discriminators.\n       *   - `catalog_requirement_conflict` — catalog-authored fixed\n       *     requirements are internally ambiguous or contradict the ref.\n       */\n      code: 'FORMAT_PROJECTION_FAILED';\n      error: {\n        details: {\n          format_kind: CanonicalFormatKind;\n          product_id: string;\n          format_option_id?: string;\n          resolution_failure:\n            | 'no_registry_match'\n            | 'catalog_lacks_canonical_annotation'\n            | 'no_match'\n            | 'custom_converter_failed'\n            | 'invalid_format_id_parameters'\n            | 'catalog_requirement_conflict';\n          converter_error?: string;\n        };\n      };\n    })\n  | (ProjectionDiagnosticBase & {\n      /**\n       * Spec code (`enums/error-code.json`): registry has family-level\n       * structural entries for this canonical (e.g., the VAST entries\n       * for `video_vast`), but none are invertible to a specific v1\n       * named format. Family is known, specific format isn't pickable.\n       * Correctable by the seller adding `v1_format_ref` to the\n       * declaration.\n       */\n      code: 'FORMAT_DECLARATION_V1_AMBIGUOUS';\n      error: {\n        details: {\n          format_kind: CanonicalFormatKind;\n          product_id: string;\n          format_option_id?: string;\n          registry_matches: number;\n        };\n      };\n    })\n  | (ProjectionDiagnosticBase & {\n      /**\n       * SDK-local code: declaration has `canonical_formats_only: true`.\n       * Seller explicitly opted out of v1 emission. Not a registry-\n       * coverage gap; not ambiguous. Informational so buyers can see\n       * why a product disappeared from a v1-only catalog.\n       */\n      code: 'FORMAT_DECLARATION_V1_NOT_APPLICABLE';\n      error: {\n        details: {\n          format_kind: CanonicalFormatKind;\n          product_id: string;\n          format_option_id?: string;\n          reason: 'canonical_formats_only';\n        };\n      };\n    })\n  | (ProjectionDiagnosticBase & {\n      /**\n       * SDK-local code: canonical declares `v1_translatable: false`.\n       * Structural v1-unreachability — no v1 form is possible for this\n       * canonical regardless of registry coverage. The 4 inherently-v2\n       * canonicals at 3.1 GA: `image_carousel`, `sponsored_placement`,\n       * `responsive_creative`, `agent_placement`. Spec is explicit:\n       * **SDKs MUST NOT emit `FORMAT_PROJECTION_FAILED`** for these\n       * (they're not coverage gaps).\n       */\n      code: 'CANONICAL_NOT_V1_TRANSLATABLE';\n      error: {\n        details: {\n          format_kind: CanonicalFormatKind;\n          product_id: string;\n          format_option_id?: string;\n        };\n      };\n    })\n  | (ProjectionDiagnosticBase & {\n      /**\n       * SDK-local code: v2 declaration uses multi-size (`sizes: [...]`)\n       * or responsive (`min_width`/`max_width`/`min_height`/`max_height`)\n       * params, but `v1_format_ref` is a single catalog entry that can\n       * only carry ONE fixed (width, height). The v1 wire emit\n       * represents only the seller-chosen representative size; the\n       * remaining sizes are **silently dropped on the v1 wire**.\n       *\n       * This diagnostic is emitted **alongside** the v1 format_id —\n       * not instead of it — so the v1 buyer still sees the product\n       * but the buyer code is told what coverage was lost. Different\n       * from FORMAT_DECLARATION_V1_AMBIGUOUS (no v1 emit) and\n       * FORMAT_DECLARATION_V1_NOT_APPLICABLE (seller opt-out).\n       *\n       * Surface follow-up: an SDK MAY (non-normative) expand multi-\n       * size to N v1 format_ids by looking up the catalog for each\n       * size. Today's prototype emits only the seller-asserted\n       * representative; multi-emit is a follow-up.\n       */\n      code: 'FORMAT_DECLARATION_V1_LOSSY_MULTI_SIZE';\n      error: {\n        details: {\n          format_kind: CanonicalFormatKind;\n          product_id: string;\n          format_option_id?: string;\n          size_mode: 'sizes' | 'responsive_range';\n          declared_sizes_count?: number;\n          /**\n           * How many v1 format_ids the SDK actually emitted. <\n           * `declared_sizes_count` when the catalog doesn't cover every\n           * declared size; equal when the catalog has full coverage.\n           * The fan-out is non-normative — when this equals 1, only the\n           * seller-asserted rep was emitted; v1 buyers lose the rest.\n           */\n          emitted_sizes_count?: number;\n          v1_emit_represents_size?: { width?: number; height?: number };\n        };\n      };\n    })\n  | (ProjectionDiagnosticBase & {\n      /**\n       * SDK-local code: canonical-only projection (`toCanonicalOnlyProduct`\n       * / `toCanonicalOnlyResponse`) found legacy routing metadata that no\n       * canonical format option covers. Emitted only on the\n       * v2-native pass-through path — a seller that sent `format_options[]`\n       * directly but also carried a `format_ids[]` entry with no canonical\n       * representation. Without it, canonical-only mode would silently\n       * discard a format the buyer could still have acted on via the v1\n       * path.\n       *\n       * On the v1 → v2 projection path an unmappable ref is already\n       * surfaced as `FORMAT_PROJECTION_FAILED`; this code covers the gap\n       * the projection path can't see (no projection runs when the seller\n       * is already v2-native).\n       */\n      code: 'LEGACY_FORMAT_ID_DROPPED_UNMAPPED';\n      error: {\n        details: {\n          product_id: string;\n          /** Stable category only; canonical diagnostics never echo routing identifiers. */\n          resolution_failure: 'unmapped_legacy_format';\n        };\n      };\n    });\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/lib/v2/projection/v1-to-v2.d.mts

@@ -45,11 +45,34 @@
  *     is the most adopter-relevant piece for actual creative
  *     submission flows and lands in a follow-up.
  */
-import type { V1Product, V2Product, V2ProductFormatDeclaration, ProjectionDiagnostic, CanonicalFormatKind } from './types.mjs';
+import type { V1Product, V1FormatId, V2Product, V2ProductFormatDeclaration, ProjectionDiagnostic, CanonicalFormatKind } from './types.mjs';
+import { type ProjectionCatalogSnapshot } from './catalog-snapshot.mjs';
 export interface V1ToV2Result {
     v2: V2Product;
     diagnostics: ProjectionDiagnostic[];
 }
+/** Context passed to an adopter's seller-specific legacy format converter. */
+export interface LegacyFormatConversionContext {
+    formatId: Readonly<V1FormatId>;
+    productId: string;
+    field: string;
+}
+/**
+ * Escape hatch for legacy formats owned by a custom creative agent. The
+ * converter returns the canonical product declaration that the legacy ref
+ * represents. For bespoke shapes, return `format_kind: 'custom'` with both
+ * `format_shape` and an immutable `format_schema` reference.
+ *
+ * The SDK adds the source `formatId` as `v1_format_ref`; converters must not
+ * set `canonical_formats_only: true` because a legacy source is, by
+ * definition, round-trippable to that ref.
+ */
+export type LegacyFormatConverter = (context: LegacyFormatConversionContext) => V2ProductFormatDeclaration | null | undefined;
+export interface V1ToV2ProjectionOptions {
+    legacyFormatConverter?: LegacyFormatConverter;
+    /** Pre-resolved exact-owner publisher/community catalogs, highest precedence first. */
+    projectionCatalogs?: readonly ProjectionCatalogSnapshot[];
+}
 /**
  * Project a v1 Product to a v2 Product. Drops `format_ids` from the
  * public output and rebuilds `format_options` per the resolution order.
@@ -63,17 +86,17 @@ export interface V1ToV2Result {
  * @see canonicalDeclarationFromBareId — resolve a single bare format-id
  * string (no surrounding Product) to a declaration or `format_kind`.
  */
-export declare function projectV1ProductToV2(v1: V1Product): V1ToV2Result;
+export declare function projectV1ProductToV2(v1: V1Product, options?: V1ToV2ProjectionOptions): V1ToV2Result;
 export interface BareFormatIdResolveOptions {
     /**
      * `agent_url` to attach when lifting the bare `id` to a structured
      * {@link V1FormatId} for resolution. Defaults to the canonical AAO host
      * (`https://creative.adcontextprotocol.org/`) — the publisher of every
      * AAO catalog id, and the source of essentially all bare ids persisted
-     * before the `{ agent_url, id }` convention. Override only when the bare
-     * id was minted under a different agent's catalog — for an AAO catalog id,
-     * leave this unset; passing a non-AAO `agentUrl` won't match the AAO-keyed
-     * catalog and resolves to `null`.
+     * before the `{ agent_url, id }` convention. When an exact ID has one
+     * unique AAO-published meaning, a valid non-AAO `agentUrl` is accepted as
+     * a legacy owner alias and is preserved in `v1_format_ref`. Unknown or
+     * colliding IDs still resolve to `null`.
      */
     agentUrl?: string;
     /**

package/dist/lib/v2/projection/v1-to-v2.d.ts

@@ -45,11 +45,34 @@
  *     is the most adopter-relevant piece for actual creative
  *     submission flows and lands in a follow-up.
  */
-import type { V1Product, V2Product, V2ProductFormatDeclaration, ProjectionDiagnostic, CanonicalFormatKind } from './types';
+import type { V1Product, V1FormatId, V2Product, V2ProductFormatDeclaration, ProjectionDiagnostic, CanonicalFormatKind } from './types';
+import { type ProjectionCatalogSnapshot } from './catalog-snapshot';
 export interface V1ToV2Result {
     v2: V2Product;
     diagnostics: ProjectionDiagnostic[];
 }
+/** Context passed to an adopter's seller-specific legacy format converter. */
+export interface LegacyFormatConversionContext {
+    formatId: Readonly<V1FormatId>;
+    productId: string;
+    field: string;
+}
+/**
+ * Escape hatch for legacy formats owned by a custom creative agent. The
+ * converter returns the canonical product declaration that the legacy ref
+ * represents. For bespoke shapes, return `format_kind: 'custom'` with both
+ * `format_shape` and an immutable `format_schema` reference.
+ *
+ * The SDK adds the source `formatId` as `v1_format_ref`; converters must not
+ * set `canonical_formats_only: true` because a legacy source is, by
+ * definition, round-trippable to that ref.
+ */
+export type LegacyFormatConverter = (context: LegacyFormatConversionContext) => V2ProductFormatDeclaration | null | undefined;
+export interface V1ToV2ProjectionOptions {
+    legacyFormatConverter?: LegacyFormatConverter;
+    /** Pre-resolved exact-owner publisher/community catalogs, highest precedence first. */
+    projectionCatalogs?: readonly ProjectionCatalogSnapshot[];
+}
 /**
  * Project a v1 Product to a v2 Product. Drops `format_ids` from the
  * public output and rebuilds `format_options` per the resolution order.
@@ -63,17 +86,17 @@ export interface V1ToV2Result {
  * @see canonicalDeclarationFromBareId — resolve a single bare format-id
  * string (no surrounding Product) to a declaration or `format_kind`.
  */
-export declare function projectV1ProductToV2(v1: V1Product): V1ToV2Result;
+export declare function projectV1ProductToV2(v1: V1Product, options?: V1ToV2ProjectionOptions): V1ToV2Result;
 export interface BareFormatIdResolveOptions {
     /**
      * `agent_url` to attach when lifting the bare `id` to a structured
      * {@link V1FormatId} for resolution. Defaults to the canonical AAO host
      * (`https://creative.adcontextprotocol.org/`) — the publisher of every
      * AAO catalog id, and the source of essentially all bare ids persisted
-     * before the `{ agent_url, id }` convention. Override only when the bare
-     * id was minted under a different agent's catalog — for an AAO catalog id,
-     * leave this unset; passing a non-AAO `agentUrl` won't match the AAO-keyed
-     * catalog and resolves to `null`.
+     * before the `{ agent_url, id }` convention. When an exact ID has one
+     * unique AAO-published meaning, a valid non-AAO `agentUrl` is accepted as
+     * a legacy owner alias and is preserved in `v1_format_ref`. Unknown or
+     * colliding IDs still resolve to `null`.
      */
     agentUrl?: string;
     /**

package/dist/lib/v2/projection/v1-to-v2.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"v1-to-v2.d.ts","sourceRoot":"","sources":["../../../../src/lib/v2/projection/v1-to-v2.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,OAAO,KAAK,EACV,SAAS,EAET,SAAS,EACT,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,SAAS,CAAC;AAQjB,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,SAAS,CAAC;IACd,WAAW,EAAE,oBAAoB,EAAE,CAAC;CACrC;AAwID;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,SAAS,GAAG,YAAY,CAoBhE;AAED,MAAM,WAAW,0BAA0B;IACzC;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,8BAA8B,CAC5C,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,0BAA0B,GACnC,0BAA0B,GAAG,IAAI,CAwBnC;AAkBD;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,0BAA0B,GACnC,mBAAmB,GAAG,IAAI,CAE5B"}
+{"version":3,"file":"v1-to-v2.d.ts","sourceRoot":"","sources":["../../../../src/lib/v2/projection/v1-to-v2.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,OAAO,KAAK,EACV,SAAS,EACT,UAAU,EACV,SAAS,EACT,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,SAAS,CAAC;AAMjB,OAAO,EAA6C,KAAK,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAqC/G,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,SAAS,CAAC;IACd,WAAW,EAAE,oBAAoB,EAAE,CAAC;CACrC;AAED,8EAA8E;AAC9E,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAClC,OAAO,EAAE,6BAA6B,KACnC,0BAA0B,GAAG,IAAI,GAAG,SAAS,CAAC;AAEnD,MAAM,WAAW,uBAAuB;IACtC,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;IAC9C,uFAAuF;IACvF,kBAAkB,CAAC,EAAE,SAAS,yBAAyB,EAAE,CAAC;CAG3D;AAoZD;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,uBAAuB,GAAG,YAAY,CA0BnG;AAED,MAAM,WAAW,0BAA0B;IACzC;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,8BAA8B,CAC5C,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,0BAA0B,GACnC,0BAA0B,GAAG,IAAI,CAwBnC;AAkBD;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,0BAA0B,GACnC,mBAAmB,GAAG,IAAI,CAE5B"}