@adcp/sdk 15.9.4 → 15.9.6

package/dist/lib/testing/types.d.mts

@@ -58,6 +58,45 @@ export interface TestOptions {
      * authoritative over the SDK's generated Zod snapshot for the run.
      */
     schemaRoot?: string;
+    /**
+     * Schema roots for releases the agent may echo in its
+     * `get_adcp_capabilities` response, keyed by AdCP version (`'3.2'`,
+     * `'3.2.5'`, `'3.3.0-beta.1'`). Values are schema-data roots in the same
+     * shape as `schemaRoot`.
+     *
+     * A 3.0 pin sends only `adcp_major_version`, so an agent may serve and echo
+     * a newer release in the same major (versioning spec, "Server echoes").
+     * The SDK validates that capabilities response against the echoed release
+     * when the echo is the pin's major, is listed in the response's
+     * `adcp.supported_versions`, and has a schema root: an entry here, an
+     * external root registered for it, or the SDK's bundled schemas. That
+     * applies to discovery's capability notices, `getAdcpCapabilities()` and
+     * storyboard `response_schema` checks on `get_adcp_capabilities`, including
+     * when `schemaRoot` is set for the pin. Otherwise validation stays on the
+     * pin.
+     *
+     * Entries are used for that capabilities validation only. Every other
+     * task's response, storyboard selection and grading stay on the pin. Each
+     * root is checked against its key once per process; a malformed map throws
+     * before the run starts. Honored by `comply()`, `runStoryboard()` and
+     * `runStoryboardStep()`; other callers can use `withServedReleaseSchemaRoots`.
+     * The echo is compared with the run's pin, so storyboard checks apply it
+     * only when the run has one (`adcpVersion`, or the storyboard or compliance
+     * bundle's `adcp_version`); `comply()` always does.
+     *
+     * @example
+     * ```ts
+     * await comply(agentUrl, {
+     *   complianceDir: hosted30.complianceDir,
+     *   schemaRoot: hosted30.schemaRoot,
+     *   servedReleaseSchemaRoots: {
+     *     '3.1.29': hosted31.schemaRoot,
+     *     '3.2.5': hosted32.schemaRoot,
+     *   },
+     * });
+     * ```
+     */
+    servedReleaseSchemaRoots?: Readonly<Record<string, string>>;
     /**
      * Whether strict AJV response-schema failures contribute to storyboard
      * grading. Defaults to `true`, matching the hosted compliance grader.

package/dist/lib/testing/types.d.ts

@@ -58,6 +58,45 @@ export interface TestOptions {
      * authoritative over the SDK's generated Zod snapshot for the run.
      */
     schemaRoot?: string;
+    /**
+     * Schema roots for releases the agent may echo in its
+     * `get_adcp_capabilities` response, keyed by AdCP version (`'3.2'`,
+     * `'3.2.5'`, `'3.3.0-beta.1'`). Values are schema-data roots in the same
+     * shape as `schemaRoot`.
+     *
+     * A 3.0 pin sends only `adcp_major_version`, so an agent may serve and echo
+     * a newer release in the same major (versioning spec, "Server echoes").
+     * The SDK validates that capabilities response against the echoed release
+     * when the echo is the pin's major, is listed in the response's
+     * `adcp.supported_versions`, and has a schema root: an entry here, an
+     * external root registered for it, or the SDK's bundled schemas. That
+     * applies to discovery's capability notices, `getAdcpCapabilities()` and
+     * storyboard `response_schema` checks on `get_adcp_capabilities`, including
+     * when `schemaRoot` is set for the pin. Otherwise validation stays on the
+     * pin.
+     *
+     * Entries are used for that capabilities validation only. Every other
+     * task's response, storyboard selection and grading stay on the pin. Each
+     * root is checked against its key once per process; a malformed map throws
+     * before the run starts. Honored by `comply()`, `runStoryboard()` and
+     * `runStoryboardStep()`; other callers can use `withServedReleaseSchemaRoots`.
+     * The echo is compared with the run's pin, so storyboard checks apply it
+     * only when the run has one (`adcpVersion`, or the storyboard or compliance
+     * bundle's `adcp_version`); `comply()` always does.
+     *
+     * @example
+     * ```ts
+     * await comply(agentUrl, {
+     *   complianceDir: hosted30.complianceDir,
+     *   schemaRoot: hosted30.schemaRoot,
+     *   servedReleaseSchemaRoots: {
+     *     '3.1.29': hosted31.schemaRoot,
+     *     '3.2.5': hosted32.schemaRoot,
+     *   },
+     * });
+     * ```
+     */
+    servedReleaseSchemaRoots?: Readonly<Record<string, string>>;
     /**
      * Whether strict AJV response-schema failures contribute to storyboard
      * grading. Defaults to `true`, matching the hosted compliance grader.

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

@@ -224,7 +224,10 @@ function toCanonicalFormatOptionsWithRoutes(productId, formatOptions) {
 }
 function toAdditiveCanonicalProduct(product, options) {
   const { product: augmented, diagnostics } = augmentProductWithFormatOptions(product, options);
-  const projected = toCanonicalFormatOptionsWithRoutes(product.product_id, augmented.format_options);
+  const projected = toCanonicalFormatOptionsWithRoutes(
+    product.product_id,
+    options?._inferDualEmissionLegacyRefs === false ? augmented.format_options : (0, import_v1_to_v2.withDualEmissionLegacyRefs)(augmented.format_options, product.format_ids)
+  );
   return {
     product: {
       ...augmented,
@@ -299,13 +302,13 @@ function formatRefCoverageKey(ref) {
 function toCanonicalOnlyProduct(product, options) {
   const existing = product.format_options;
   if (Array.isArray(existing)) {
-    const formatOptions = existing;
+    const formatOptions = options?._inferDualEmissionLegacyRefs === false ? existing : (0, import_v1_to_v2.withDualEmissionLegacyRefs)(existing, product.format_ids);
     const diagnostics2 = [];
     const inputIds = Array.isArray(product.format_ids) ? product.format_ids : [];
     if (inputIds.length > 0) {
       const covered = /* @__PURE__ */ new Set();
       for (const opt of formatOptions) {
-        const refs = Array.isArray(opt?.v1_format_ref) ? opt.v1_format_ref : [];
+        const refs = (0, import_legacy_metadata.legacyFormatRefsForDeclaration)(opt);
         for (const ref of refs) covered.add(formatRefCoverageKey(ref));
       }
       for (let k = 0; k < inputIds.length; k++) {

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

@@ -1,7 +1,7 @@
-import { projectV1ProductToV2 } from "./v1-to-v2.mjs";
+import { projectV1ProductToV2, withDualEmissionLegacyRefs } 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";
+import { concealLegacyFormatRefs, legacyFormatRefsForDeclaration } from "./legacy-metadata.mjs";
 import { legacyRoutesForProduct } from "./legacy-routes.mjs";
 const SDK_ID = `@adcp/sdk@${LIBRARY_VERSION}`;
 const DIRECT_LEGACY_FORMAT_IDENTITY_KEYS = /* @__PURE__ */ new Set(["agenturl", "formatid", "formatids", "v1formatref"]);
@@ -194,7 +194,10 @@ function toCanonicalFormatOptionsWithRoutes(productId, formatOptions) {
 }
 function toAdditiveCanonicalProduct(product, options) {
   const { product: augmented, diagnostics } = augmentProductWithFormatOptions(product, options);
-  const projected = toCanonicalFormatOptionsWithRoutes(product.product_id, augmented.format_options);
+  const projected = toCanonicalFormatOptionsWithRoutes(
+    product.product_id,
+    options?._inferDualEmissionLegacyRefs === false ? augmented.format_options : withDualEmissionLegacyRefs(augmented.format_options, product.format_ids)
+  );
   return {
     product: {
       ...augmented,
@@ -269,13 +272,13 @@ function formatRefCoverageKey(ref) {
 function toCanonicalOnlyProduct(product, options) {
   const existing = product.format_options;
   if (Array.isArray(existing)) {
-    const formatOptions = existing;
+    const formatOptions = options?._inferDualEmissionLegacyRefs === false ? existing : withDualEmissionLegacyRefs(existing, product.format_ids);
     const diagnostics2 = [];
     const inputIds = Array.isArray(product.format_ids) ? product.format_ids : [];
     if (inputIds.length > 0) {
       const covered = /* @__PURE__ */ new Set();
       for (const opt of formatOptions) {
-        const refs = Array.isArray(opt?.v1_format_ref) ? opt.v1_format_ref : [];
+        const refs = legacyFormatRefsForDeclaration(opt);
         for (const ref of refs) covered.add(formatRefCoverageKey(ref));
       }
       for (let k = 0; k < inputIds.length; k++) {

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

@@ -230,6 +230,8 @@ export interface CreativeFormatSelectorContainer {
 /** Canonical package/product selectors accepted by the primary sync API. */
 export interface CanonicalCreativeFormatSelectorContainer {
     package_id?: string;
+    /** Target product, used to recover seller declarations after serializing selectors. */
+    product_id?: string;
     format_options?: ReadonlyArray<CanonicalFormatDeclaration>;
     format_option_refs?: ReadonlyArray<FormatOptionReference>;
     format_kind?: CanonicalFormatKind;

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

@@ -230,6 +230,8 @@ export interface CreativeFormatSelectorContainer {
 /** Canonical package/product selectors accepted by the primary sync API. */
 export interface CanonicalCreativeFormatSelectorContainer {
     package_id?: string;
+    /** Target product, used to recover seller declarations after serializing selectors. */
+    product_id?: string;
     format_options?: ReadonlyArray<CanonicalFormatDeclaration>;
     format_option_refs?: ReadonlyArray<FormatOptionReference>;
     format_kind?: CanonicalFormatKind;

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

@@ -20,6 +20,7 @@ var creative_delivery_exports = {};
 __export(creative_delivery_exports, {
   CreativeFormatCapabilityError: () => CreativeFormatCapabilityError,
   CreativeFormatProjectionError: () => CreativeFormatProjectionError,
+  canUseProductOptionsForCreativeWire: () => canUseProductOptionsForCreativeWire,
   projectCreativeForDelivery: () => projectCreativeForDelivery,
   projectMediaBuyCreativesForDelivery: () => projectMediaBuyCreativesForDelivery,
   projectSyncCreativesForDelivery: () => projectSyncCreativesForDelivery,
@@ -378,26 +379,15 @@ function candidatesFromContainer(container, canonicalFormatLegacyResolver, opera
     );
   }
   const candidates = [];
-  const containerKind = typeof container.format_kind === "string" ? container.format_kind : void 0;
-  for (const key of ["format_ids", "formats"]) {
-    for (const ref of refsFromValue(container[key])) {
-      candidates.push({
-        ref,
-        formatKind: (0, import_v1_to_v2.resolveCanonicalFormatKind)(ref.id) ?? containerKind,
-        selectorParams: container.params
-      });
-    }
-  }
-  const formatOptions = [
-    ...Array.isArray(container.format_options) ? container.format_options : [],
-    ...(0, import_legacy_metadata.selectedFormatOptions)(container)
-  ];
-  for (const optionValue of formatOptions) {
+  const nativeOptions = Array.isArray(container.format_options) ? container.format_options : [];
+  const formatOptions = [...nativeOptions, ...(0, import_legacy_metadata.selectedFormatOptions)(container)];
+  const resolvedOptions = formatOptions.map((optionValue) => {
     const option = record(optionValue);
-    if (!option) continue;
+    if (!option) return optionValue;
     const formatKind = typeof option.format_kind === "string" ? option.format_kind : void 0;
     const formatOptionRef = optionReference(option);
     let refs = [...(0, import_legacy_metadata.legacyFormatRefsForDeclaration)(option)];
+    if (refs.length > 0) return optionValue;
     if (refs.length === 0 && option.canonical_formats_only !== true && formatKind) {
       try {
         refs = (0, import_v2_to_v1.resolveCanonicalFormatLegacyRefs)(canonicalFormatLegacyResolver, {
@@ -415,10 +405,33 @@ function candidatesFromContainer(container, canonicalFormatLegacyResolver, opera
         );
       }
     }
-    for (const ref of refs) {
+    return refs.length > 0 ? { ...option, v1_format_ref: refs } : optionValue;
+  });
+  const pairedOptions = [
+    ...(0, import_v1_to_v2.withDualEmissionLegacyRefs)(resolvedOptions.slice(0, nativeOptions.length), container.format_ids),
+    ...resolvedOptions.slice(nativeOptions.length)
+  ];
+  for (const optionValue of pairedOptions) {
+    const option = record(optionValue);
+    if (!option) continue;
+    const formatKind = typeof option.format_kind === "string" ? option.format_kind : void 0;
+    const formatOptionRef = optionReference(option);
+    for (const ref of (0, import_legacy_metadata.legacyFormatRefsForDeclaration)(option)) {
       candidates.push({ ref, formatKind, formatOptionRef, selectorParams: option.params ?? container.params });
     }
   }
+  const linkedRefs = new Set(candidates.map((candidate) => candidateKey({ ref: candidate.ref })));
+  const containerKind = typeof container.format_kind === "string" ? container.format_kind : void 0;
+  for (const key of ["format_ids", "formats"]) {
+    for (const ref of refsFromValue(container[key])) {
+      if (linkedRefs.has(candidateKey({ ref }))) continue;
+      candidates.push({
+        ref,
+        formatKind: (0, import_v1_to_v2.resolveCanonicalFormatKind)(ref.id) ?? containerKind,
+        selectorParams: container.params
+      });
+    }
+  }
   return uniqueCandidates(candidates);
 }
 function containerOptsOutOfLegacy(container, formatKind, formatOptionRef) {
@@ -1106,10 +1119,16 @@ function resolveCreativeFormatWireMode(capabilities, negotiatedVersion) {
   if (explicitCanonical === false) return "legacy";
   return "unknown";
 }
+function canUseProductOptionsForCreativeWire(capabilities, requestedVersion) {
+  const caps = record(capabilities);
+  const negotiated = mutuallyServedRelease(caps, record(caps?._raw), requestedVersion);
+  return negotiated?.major === 3 && negotiated.minor === 1;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CreativeFormatCapabilityError,
   CreativeFormatProjectionError,
+  canUseProductOptionsForCreativeWire,
   projectCreativeForDelivery,
   projectMediaBuyCreativesForDelivery,
   projectSyncCreativesForDelivery,

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

@@ -2,7 +2,8 @@ import {
   canonicalDeclarationFromBareId,
   migratedFormatOptionId,
   projectV1ProductToV2,
-  resolveCanonicalFormatKind
+  resolveCanonicalFormatKind,
+  withDualEmissionLegacyRefs
 } from "./v1-to-v2.mjs";
 import { CanonicalFormatLegacyResolutionError, resolveCanonicalFormatLegacyRefs } from "./v2-to-v1.mjs";
 import {
@@ -357,26 +358,15 @@ function candidatesFromContainer(container, canonicalFormatLegacyResolver, opera
     );
   }
   const candidates = [];
-  const containerKind = typeof container.format_kind === "string" ? container.format_kind : void 0;
-  for (const key of ["format_ids", "formats"]) {
-    for (const ref of refsFromValue(container[key])) {
-      candidates.push({
-        ref,
-        formatKind: resolveCanonicalFormatKind(ref.id) ?? containerKind,
-        selectorParams: container.params
-      });
-    }
-  }
-  const formatOptions = [
-    ...Array.isArray(container.format_options) ? container.format_options : [],
-    ...selectedFormatOptions(container)
-  ];
-  for (const optionValue of formatOptions) {
+  const nativeOptions = Array.isArray(container.format_options) ? container.format_options : [];
+  const formatOptions = [...nativeOptions, ...selectedFormatOptions(container)];
+  const resolvedOptions = formatOptions.map((optionValue) => {
     const option = record(optionValue);
-    if (!option) continue;
+    if (!option) return optionValue;
     const formatKind = typeof option.format_kind === "string" ? option.format_kind : void 0;
     const formatOptionRef = optionReference(option);
     let refs = [...legacyFormatRefsForDeclaration(option)];
+    if (refs.length > 0) return optionValue;
     if (refs.length === 0 && option.canonical_formats_only !== true && formatKind) {
       try {
         refs = resolveCanonicalFormatLegacyRefs(canonicalFormatLegacyResolver, {
@@ -394,10 +384,33 @@ function candidatesFromContainer(container, canonicalFormatLegacyResolver, opera
         );
       }
     }
-    for (const ref of refs) {
+    return refs.length > 0 ? { ...option, v1_format_ref: refs } : optionValue;
+  });
+  const pairedOptions = [
+    ...withDualEmissionLegacyRefs(resolvedOptions.slice(0, nativeOptions.length), container.format_ids),
+    ...resolvedOptions.slice(nativeOptions.length)
+  ];
+  for (const optionValue of pairedOptions) {
+    const option = record(optionValue);
+    if (!option) continue;
+    const formatKind = typeof option.format_kind === "string" ? option.format_kind : void 0;
+    const formatOptionRef = optionReference(option);
+    for (const ref of legacyFormatRefsForDeclaration(option)) {
       candidates.push({ ref, formatKind, formatOptionRef, selectorParams: option.params ?? container.params });
     }
   }
+  const linkedRefs = new Set(candidates.map((candidate) => candidateKey({ ref: candidate.ref })));
+  const containerKind = typeof container.format_kind === "string" ? container.format_kind : void 0;
+  for (const key of ["format_ids", "formats"]) {
+    for (const ref of refsFromValue(container[key])) {
+      if (linkedRefs.has(candidateKey({ ref }))) continue;
+      candidates.push({
+        ref,
+        formatKind: resolveCanonicalFormatKind(ref.id) ?? containerKind,
+        selectorParams: container.params
+      });
+    }
+  }
   return uniqueCandidates(candidates);
 }
 function containerOptsOutOfLegacy(container, formatKind, formatOptionRef) {
@@ -1085,9 +1098,15 @@ function resolveCreativeFormatWireMode(capabilities, negotiatedVersion) {
   if (explicitCanonical === false) return "legacy";
   return "unknown";
 }
+function canUseProductOptionsForCreativeWire(capabilities, requestedVersion) {
+  const caps = record(capabilities);
+  const negotiated = mutuallyServedRelease(caps, record(caps?._raw), requestedVersion);
+  return negotiated?.major === 3 && negotiated.minor === 1;
+}
 export {
   CreativeFormatCapabilityError,
   CreativeFormatProjectionError,
+  canUseProductOptionsForCreativeWire,
   projectCreativeForDelivery,
   projectMediaBuyCreativesForDelivery,
   projectSyncCreativesForDelivery,

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

@@ -12,9 +12,21 @@ type DeclarationWithMetadata = CanonicalFormatDeclaration;
 export type PackageSelectionMetadata = {
     format_option_refs?: readonly unknown[];
 };
+export interface SellerFormatEvidence {
+    scopeKey: string;
+    accountScope: string;
+    productId: string;
+    expiresAt: number;
+}
+/** Positive evidence is client/account-bound and cannot survive a JSON round trip on its own. */
+export declare function rememberSellerFormatEvidence(declaration: object, evidence: SellerFormatEvidence): void;
+export declare function sellerFormatEvidence(declaration: object): SellerFormatEvidence | undefined;
 /** Keep seller-origin evidence private while canonical products pass through the cache. */
 export declare function rememberSellerDeclaredFormatOption(declaration: object, declared: boolean): void;
 export declare function sellerDeclaredFormatOption(declaration: object): boolean | undefined;
+/** A pure legacy projection cannot establish what the original seller advertised. */
+export declare function rememberSynthesizedFormatOption(declaration: object): void;
+export declare function isSynthesizedFormatOption(declaration: object): boolean;
 export declare function concealLegacyFormatRefs(declaration: ProductFormatDeclaration | V2ProductFormatDeclaration | CanonicalFormatDeclaration): DeclarationWithMetadata;
 export declare function legacyFormatRefsForDeclaration(value: unknown): readonly V1FormatId[];
 export declare function selectedFormatOptions(value: unknown): readonly DeclarationWithMetadata[];

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

@@ -12,9 +12,21 @@ type DeclarationWithMetadata = CanonicalFormatDeclaration;
 export type PackageSelectionMetadata = {
     format_option_refs?: readonly unknown[];
 };
+export interface SellerFormatEvidence {
+    scopeKey: string;
+    accountScope: string;
+    productId: string;
+    expiresAt: number;
+}
+/** Positive evidence is client/account-bound and cannot survive a JSON round trip on its own. */
+export declare function rememberSellerFormatEvidence(declaration: object, evidence: SellerFormatEvidence): void;
+export declare function sellerFormatEvidence(declaration: object): SellerFormatEvidence | undefined;
 /** Keep seller-origin evidence private while canonical products pass through the cache. */
 export declare function rememberSellerDeclaredFormatOption(declaration: object, declared: boolean): void;
 export declare function sellerDeclaredFormatOption(declaration: object): boolean | undefined;
+/** A pure legacy projection cannot establish what the original seller advertised. */
+export declare function rememberSynthesizedFormatOption(declaration: object): void;
+export declare function isSynthesizedFormatOption(declaration: object): boolean;
 export declare function concealLegacyFormatRefs(declaration: ProductFormatDeclaration | V2ProductFormatDeclaration | CanonicalFormatDeclaration): DeclarationWithMetadata;
 export declare function legacyFormatRefsForDeclaration(value: unknown): readonly V1FormatId[];
 export declare function selectedFormatOptions(value: unknown): readonly DeclarationWithMetadata[];

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

@@ -20,22 +20,52 @@ var legacy_metadata_exports = {};
 __export(legacy_metadata_exports, {
   concealLegacyFormatRefs: () => concealLegacyFormatRefs,
   concealSelectedFormatOptions: () => concealSelectedFormatOptions,
+  isSynthesizedFormatOption: () => isSynthesizedFormatOption,
   legacyFormatRefsForDeclaration: () => legacyFormatRefsForDeclaration,
   rememberSellerDeclaredFormatOption: () => rememberSellerDeclaredFormatOption,
+  rememberSellerFormatEvidence: () => rememberSellerFormatEvidence,
+  rememberSynthesizedFormatOption: () => rememberSynthesizedFormatOption,
   selectedFormatOptions: () => selectedFormatOptions,
   sellerDeclaredFormatOption: () => sellerDeclaredFormatOption,
+  sellerFormatEvidence: () => sellerFormatEvidence,
   structuredCloneWithLegacyCreativeMetadata: () => structuredCloneWithLegacyCreativeMetadata,
   transferLegacyCreativeMetadata: () => transferLegacyCreativeMetadata
 });
 module.exports = __toCommonJS(legacy_metadata_exports);
+var import_jcs = require('../../utils/jcs.js');
 const legacyRefsByDeclaration = /* @__PURE__ */ new WeakMap();
 const selectedOptionsByRefs = /* @__PURE__ */ new WeakMap();
 const sellerDeclaredByDeclaration = /* @__PURE__ */ new WeakMap();
+const sellerEvidenceByDeclaration = /* @__PURE__ */ new WeakMap();
+function rememberSellerFormatEvidence(declaration, evidence) {
+  try {
+    sellerEvidenceByDeclaration.set(
+      declaration,
+      Object.freeze({ ...evidence, fingerprint: (0, import_jcs.canonicalize)(declaration) })
+    );
+  } catch {
+  }
+}
+function sellerFormatEvidence(declaration) {
+  const evidence = sellerEvidenceByDeclaration.get(declaration);
+  try {
+    return evidence?.fingerprint === (0, import_jcs.canonicalize)(declaration) ? evidence : void 0;
+  } catch {
+    return void 0;
+  }
+}
 function rememberSellerDeclaredFormatOption(declaration, declared) {
   sellerDeclaredByDeclaration.set(declaration, declared);
 }
 function sellerDeclaredFormatOption(declaration) {
-  return sellerDeclaredByDeclaration.get(declaration);
+  const origin = sellerDeclaredByDeclaration.get(declaration);
+  return typeof origin === "boolean" ? origin : void 0;
+}
+function rememberSynthesizedFormatOption(declaration) {
+  sellerDeclaredByDeclaration.set(declaration, "synthesized");
+}
+function isSynthesizedFormatOption(declaration) {
+  return sellerDeclaredByDeclaration.get(declaration) === "synthesized";
 }
 function concealLegacyFormatRefs(declaration) {
   const { v1_format_ref: refs, ...canonical } = declaration;
@@ -43,6 +73,8 @@ function concealLegacyFormatRefs(declaration) {
   const refsToConceal = Array.isArray(existingHidden) && existingHidden.length > 0 ? existingHidden : refs;
   const declared = sellerDeclaredByDeclaration.get(declaration);
   if (declared !== void 0) sellerDeclaredByDeclaration.set(canonical, declared);
+  const evidence = sellerEvidenceByDeclaration.get(declaration);
+  if (evidence) sellerEvidenceByDeclaration.set(canonical, evidence);
   if (Array.isArray(refsToConceal) && refsToConceal.length > 0) {
     legacyRefsByDeclaration.set(
       canonical,
@@ -75,6 +107,8 @@ function transferLegacyCreativeMetadata(source, target) {
   if (selected) selectedOptionsByRefs.set(target, selected);
   const declared = sellerDeclaredByDeclaration.get(source);
   if (declared !== void 0) sellerDeclaredByDeclaration.set(target, declared);
+  const evidence = sellerEvidenceByDeclaration.get(source);
+  if (evidence) sellerEvidenceByDeclaration.set(target, evidence);
 }
 function structuredCloneWithLegacyCreativeMetadata(value) {
   const clone = structuredClone(value);
@@ -82,6 +116,8 @@ function structuredCloneWithLegacyCreativeMetadata(value) {
   const snapshotMetadata = (source, target) => {
     const declared = sellerDeclaredByDeclaration.get(source);
     if (declared !== void 0) sellerDeclaredByDeclaration.set(target, declared);
+    const evidence = sellerEvidenceByDeclaration.get(source);
+    if (evidence) sellerEvidenceByDeclaration.set(target, evidence);
     const refs = legacyRefsByDeclaration.get(source);
     if (refs) legacyRefsByDeclaration.set(target, structuredClone(refs));
     const selected = selectedOptionsByRefs.get(source);
@@ -119,10 +155,14 @@ function structuredCloneWithLegacyCreativeMetadata(value) {
 0 && (module.exports = {
   concealLegacyFormatRefs,
   concealSelectedFormatOptions,
+  isSynthesizedFormatOption,
   legacyFormatRefsForDeclaration,
   rememberSellerDeclaredFormatOption,
+  rememberSellerFormatEvidence,
+  rememberSynthesizedFormatOption,
   selectedFormatOptions,
   sellerDeclaredFormatOption,
+  sellerFormatEvidence,
   structuredCloneWithLegacyCreativeMetadata,
   transferLegacyCreativeMetadata
 });

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

@@ -1,11 +1,37 @@
+import { canonicalize } from "../../utils/jcs.mjs";
 const legacyRefsByDeclaration = /* @__PURE__ */ new WeakMap();
 const selectedOptionsByRefs = /* @__PURE__ */ new WeakMap();
 const sellerDeclaredByDeclaration = /* @__PURE__ */ new WeakMap();
+const sellerEvidenceByDeclaration = /* @__PURE__ */ new WeakMap();
+function rememberSellerFormatEvidence(declaration, evidence) {
+  try {
+    sellerEvidenceByDeclaration.set(
+      declaration,
+      Object.freeze({ ...evidence, fingerprint: canonicalize(declaration) })
+    );
+  } catch {
+  }
+}
+function sellerFormatEvidence(declaration) {
+  const evidence = sellerEvidenceByDeclaration.get(declaration);
+  try {
+    return evidence?.fingerprint === canonicalize(declaration) ? evidence : void 0;
+  } catch {
+    return void 0;
+  }
+}
 function rememberSellerDeclaredFormatOption(declaration, declared) {
   sellerDeclaredByDeclaration.set(declaration, declared);
 }
 function sellerDeclaredFormatOption(declaration) {
-  return sellerDeclaredByDeclaration.get(declaration);
+  const origin = sellerDeclaredByDeclaration.get(declaration);
+  return typeof origin === "boolean" ? origin : void 0;
+}
+function rememberSynthesizedFormatOption(declaration) {
+  sellerDeclaredByDeclaration.set(declaration, "synthesized");
+}
+function isSynthesizedFormatOption(declaration) {
+  return sellerDeclaredByDeclaration.get(declaration) === "synthesized";
 }
 function concealLegacyFormatRefs(declaration) {
   const { v1_format_ref: refs, ...canonical } = declaration;
@@ -13,6 +39,8 @@ function concealLegacyFormatRefs(declaration) {
   const refsToConceal = Array.isArray(existingHidden) && existingHidden.length > 0 ? existingHidden : refs;
   const declared = sellerDeclaredByDeclaration.get(declaration);
   if (declared !== void 0) sellerDeclaredByDeclaration.set(canonical, declared);
+  const evidence = sellerEvidenceByDeclaration.get(declaration);
+  if (evidence) sellerEvidenceByDeclaration.set(canonical, evidence);
   if (Array.isArray(refsToConceal) && refsToConceal.length > 0) {
     legacyRefsByDeclaration.set(
       canonical,
@@ -45,6 +73,8 @@ function transferLegacyCreativeMetadata(source, target) {
   if (selected) selectedOptionsByRefs.set(target, selected);
   const declared = sellerDeclaredByDeclaration.get(source);
   if (declared !== void 0) sellerDeclaredByDeclaration.set(target, declared);
+  const evidence = sellerEvidenceByDeclaration.get(source);
+  if (evidence) sellerEvidenceByDeclaration.set(target, evidence);
 }
 function structuredCloneWithLegacyCreativeMetadata(value) {
   const clone = structuredClone(value);
@@ -52,6 +82,8 @@ function structuredCloneWithLegacyCreativeMetadata(value) {
   const snapshotMetadata = (source, target) => {
     const declared = sellerDeclaredByDeclaration.get(source);
     if (declared !== void 0) sellerDeclaredByDeclaration.set(target, declared);
+    const evidence = sellerEvidenceByDeclaration.get(source);
+    if (evidence) sellerEvidenceByDeclaration.set(target, evidence);
     const refs = legacyRefsByDeclaration.get(source);
     if (refs) legacyRefsByDeclaration.set(target, structuredClone(refs));
     const selected = selectedOptionsByRefs.get(source);
@@ -88,10 +120,14 @@ function structuredCloneWithLegacyCreativeMetadata(value) {
 export {
   concealLegacyFormatRefs,
   concealSelectedFormatOptions,
+  isSynthesizedFormatOption,
   legacyFormatRefsForDeclaration,
   rememberSellerDeclaredFormatOption,
+  rememberSellerFormatEvidence,
+  rememberSynthesizedFormatOption,
   selectedFormatOptions,
   sellerDeclaredFormatOption,
+  sellerFormatEvidence,
   structuredCloneWithLegacyCreativeMetadata,
   transferLegacyCreativeMetadata
 };

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

@@ -211,3 +211,10 @@ export declare function canonicalDeclarationFromBareId(id: string, options?: Bar
  * the `agentUrl` default, and the `assetType` disambiguator.
  */
 export declare function resolveCanonicalFormatKind(id: string, options?: BareFormatIdResolveOptions): CanonicalFormatKind | null;
+/**
+ * Preserve index pairing only when the whole seller-authored alignment is credible.
+ * AdCP 3.1.24 core/product.json defines this correspondence: "the format_options[i]
+ * narrows the canonical that the named format in format_ids[i] resolves to via the
+ * registry / explicit canonical field". Explicit routes remain authoritative.
+ */
+export declare function withDualEmissionLegacyRefs<T>(formatOptions: T[], formatIds: unknown): T[];

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

@@ -211,3 +211,10 @@ export declare function canonicalDeclarationFromBareId(id: string, options?: Bar
  * the `agentUrl` default, and the `assetType` disambiguator.
  */
 export declare function resolveCanonicalFormatKind(id: string, options?: BareFormatIdResolveOptions): CanonicalFormatKind | null;
+/**
+ * Preserve index pairing only when the whole seller-authored alignment is credible.
+ * AdCP 3.1.24 core/product.json defines this correspondence: "the format_options[i]
+ * narrows the canonical that the named format in format_ids[i] resolves to via the
+ * registry / explicit canonical field". Explicit routes remain authoritative.
+ */
+export declare function withDualEmissionLegacyRefs<T>(formatOptions: T[], formatIds: unknown): T[];