@adcp/sdk 12.1.1 → 13.0.0-rc.0

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

@@ -1 +1 @@
-{"version":3,"sources":["../../../../src/lib/v2/projection/builders.ts"],"sourcesContent":["import type { FormatReferenceStructuredObject } from '../../types/core.generated';\nimport type {\n  AgentPlacementFormatDeclaration,\n  CustomFormatDeclaration,\n  DAASTAudioFormatDeclaration,\n  DisplayTagFormatDeclaration,\n  HTML5FormatDeclaration,\n  HostedAudioFormatDeclaration,\n  HostedVideoFormatDeclaration,\n  ImageAsset,\n  ImageCarouselFormatDeclaration,\n  ImageFormatDeclaration,\n  NativeInFeedFormatDeclaration,\n  ProductFormatDeclaration,\n  ResponsiveCreativeFormatDeclaration,\n  SponsoredPlacementFormatDeclaration,\n  VASTVideoFormatDeclaration,\n} from '../../types/tools.generated';\n\ntype WithCommonDeclaration<T> = ProductFormatDeclaration & T;\n\ninterface CanonicalFormatDeclarationMap {\n  image: WithCommonDeclaration<ImageFormatDeclaration>;\n  html5: WithCommonDeclaration<HTML5FormatDeclaration>;\n  display_tag: WithCommonDeclaration<DisplayTagFormatDeclaration>;\n  image_carousel: WithCommonDeclaration<ImageCarouselFormatDeclaration>;\n  video_hosted: WithCommonDeclaration<HostedVideoFormatDeclaration>;\n  video_vast: WithCommonDeclaration<VASTVideoFormatDeclaration>;\n  audio_hosted: WithCommonDeclaration<HostedAudioFormatDeclaration>;\n  audio_daast: WithCommonDeclaration<DAASTAudioFormatDeclaration>;\n  sponsored_placement: WithCommonDeclaration<SponsoredPlacementFormatDeclaration>;\n  native_in_feed: WithCommonDeclaration<NativeInFeedFormatDeclaration>;\n  responsive_creative: WithCommonDeclaration<ResponsiveCreativeFormatDeclaration>;\n  agent_placement: WithCommonDeclaration<AgentPlacementFormatDeclaration>;\n  custom: WithCommonDeclaration<CustomFormatDeclaration>;\n}\n\nexport type CanonicalFormatKind = keyof CanonicalFormatDeclarationMap;\nexport type CanonicalFormatDeclaration<K extends CanonicalFormatKind = CanonicalFormatKind> =\n  CanonicalFormatDeclarationMap[K];\nexport type CanonicalFormatParams<K extends CanonicalFormatKind> = CanonicalFormatDeclaration<K>['params'];\nexport type CanonicalFormatDeclarationFields<K extends CanonicalFormatKind = CanonicalFormatKind> = Omit<\n  CanonicalFormatDeclaration<K>,\n  'format_kind' | 'params'\n>;\n\nexport type FormatReferenceInput = FormatReferenceStructuredObject & Record<string, unknown>;\n\nexport interface ProductCardFields {\n  image?: ImageAsset;\n  title?: string;\n  description?: string;\n  price_label?: string;\n  cta_label?: string;\n}\n\nexport interface ProductCardDetailedFields {\n  hero_image?: ImageAsset;\n  carousel_images?: ImageAsset[];\n  title?: string;\n  description?: string;\n  specifications?: Array<{ label: string; value: string }>;\n  price_label?: string;\n  cta_label?: string;\n}\n\n/**\n * Build the structured v1 format_id reference shape. Use this instead of a\n * bare string when populating Product.format_ids, ProductFormatDeclaration\n * v1_format_ref, or list_creative_formats filters.\n */\nexport function formatRef(\n  agent_url: string,\n  id: string,\n  fields: Omit<Partial<FormatReferenceStructuredObject>, 'agent_url' | 'id'> & Record<string, unknown> = {}\n): FormatReferenceStructuredObject {\n  return { ...fields, agent_url, id };\n}\n\nexport function formatRefs(...refs: FormatReferenceInput[]): FormatReferenceStructuredObject[] {\n  return refs.map(ref => ({ ...ref }));\n}\n\n/**\n * Generic canonical-format declaration builder. It sets the format_kind\n * discriminator and keeps common declaration metadata in the third argument.\n */\nexport function canonicalFormatDeclaration<K extends CanonicalFormatKind>(\n  format_kind: K,\n  params: CanonicalFormatParams<K>,\n  fields: CanonicalFormatDeclarationFields<K> = {} as CanonicalFormatDeclarationFields<K>\n): CanonicalFormatDeclaration<K> {\n  return { ...fields, format_kind, params } as CanonicalFormatDeclaration<K>;\n}\n\nexport function imageFormatDeclaration(\n  params: CanonicalFormatParams<'image'>,\n  fields: CanonicalFormatDeclarationFields<'image'> = {}\n): CanonicalFormatDeclaration<'image'> {\n  return canonicalFormatDeclaration('image', params, fields);\n}\n\nexport function html5FormatDeclaration(\n  params: CanonicalFormatParams<'html5'>,\n  fields: CanonicalFormatDeclarationFields<'html5'> = {}\n): CanonicalFormatDeclaration<'html5'> {\n  return canonicalFormatDeclaration('html5', params, fields);\n}\n\nexport function displayTagFormatDeclaration(\n  params: CanonicalFormatParams<'display_tag'>,\n  fields: CanonicalFormatDeclarationFields<'display_tag'> = {}\n): CanonicalFormatDeclaration<'display_tag'> {\n  return canonicalFormatDeclaration('display_tag', params, fields);\n}\n\nexport function imageCarouselFormatDeclaration(\n  params: CanonicalFormatParams<'image_carousel'>,\n  fields: CanonicalFormatDeclarationFields<'image_carousel'> = {}\n): CanonicalFormatDeclaration<'image_carousel'> {\n  return canonicalFormatDeclaration('image_carousel', params, fields);\n}\n\nexport function videoHostedFormatDeclaration(\n  params: CanonicalFormatParams<'video_hosted'>,\n  fields: CanonicalFormatDeclarationFields<'video_hosted'> = {}\n): CanonicalFormatDeclaration<'video_hosted'> {\n  return canonicalFormatDeclaration('video_hosted', params, fields);\n}\n\nexport function videoVastFormatDeclaration(\n  params: CanonicalFormatParams<'video_vast'>,\n  fields: CanonicalFormatDeclarationFields<'video_vast'> = {}\n): CanonicalFormatDeclaration<'video_vast'> {\n  return canonicalFormatDeclaration('video_vast', params, fields);\n}\n\nexport function audioHostedFormatDeclaration(\n  params: CanonicalFormatParams<'audio_hosted'>,\n  fields: CanonicalFormatDeclarationFields<'audio_hosted'> = {}\n): CanonicalFormatDeclaration<'audio_hosted'> {\n  return canonicalFormatDeclaration('audio_hosted', params, fields);\n}\n\nexport function audioDaastFormatDeclaration(\n  params: CanonicalFormatParams<'audio_daast'>,\n  fields: CanonicalFormatDeclarationFields<'audio_daast'> = {}\n): CanonicalFormatDeclaration<'audio_daast'> {\n  return canonicalFormatDeclaration('audio_daast', params, fields);\n}\n\nexport function sponsoredPlacementFormatDeclaration(\n  params: CanonicalFormatParams<'sponsored_placement'>,\n  fields: CanonicalFormatDeclarationFields<'sponsored_placement'> = {}\n): CanonicalFormatDeclaration<'sponsored_placement'> {\n  return canonicalFormatDeclaration('sponsored_placement', params, fields);\n}\n\nexport function nativeInFeedFormatDeclaration(\n  params: CanonicalFormatParams<'native_in_feed'>,\n  fields: CanonicalFormatDeclarationFields<'native_in_feed'> = {}\n): CanonicalFormatDeclaration<'native_in_feed'> {\n  return canonicalFormatDeclaration('native_in_feed', params, fields);\n}\n\nexport function responsiveCreativeFormatDeclaration(\n  params: CanonicalFormatParams<'responsive_creative'>,\n  fields: CanonicalFormatDeclarationFields<'responsive_creative'> = {}\n): CanonicalFormatDeclaration<'responsive_creative'> {\n  return canonicalFormatDeclaration('responsive_creative', params, fields);\n}\n\nexport function agentPlacementFormatDeclaration(\n  params: CanonicalFormatParams<'agent_placement'>,\n  fields: CanonicalFormatDeclarationFields<'agent_placement'> = {}\n): CanonicalFormatDeclaration<'agent_placement'> {\n  return canonicalFormatDeclaration('agent_placement', params, fields);\n}\n\nexport function customFormatDeclaration(\n  format_shape: string,\n  format_schema: NonNullable<CanonicalFormatDeclarationFields<'custom'>['format_schema']>,\n  params: CanonicalFormatParams<'custom'>,\n  fields: Omit<CanonicalFormatDeclarationFields<'custom'>, 'format_shape' | 'format_schema'> = {}\n): CanonicalFormatDeclaration<'custom'> {\n  return canonicalFormatDeclaration('custom', params, { ...fields, format_shape, format_schema });\n}\n\n/**\n * Product cards describe the merchandising UI for a product. They do not carry\n * format_id and are intentionally separate from creative format declarations.\n */\nexport function productCard(fields: ProductCardFields): ProductCardFields {\n  return { ...fields };\n}\n\nexport function productCardDetailed(fields: ProductCardDetailedFields): ProductCardDetailedFields {\n  return {\n    ...fields,\n    carousel_images: fields.carousel_images?.map(image => ({ ...image })),\n    specifications: fields.specifications?.map(spec => ({ ...spec })),\n  };\n}\n\nexport const CanonicalFormat = {\n  ref: formatRef,\n  refs: formatRefs,\n  declaration: canonicalFormatDeclaration,\n  image: imageFormatDeclaration,\n  html5: html5FormatDeclaration,\n  displayTag: displayTagFormatDeclaration,\n  imageCarousel: imageCarouselFormatDeclaration,\n  videoHosted: videoHostedFormatDeclaration,\n  videoVast: videoVastFormatDeclaration,\n  audioHosted: audioHostedFormatDeclaration,\n  audioDaast: audioDaastFormatDeclaration,\n  sponsoredPlacement: sponsoredPlacementFormatDeclaration,\n  nativeInFeed: nativeInFeedFormatDeclaration,\n  responsiveCreative: responsiveCreativeFormatDeclaration,\n  agentPlacement: agentPlacementFormatDeclaration,\n  custom: customFormatDeclaration,\n  productCard,\n  productCardDetailed,\n} as const;\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAuEO,SAAS,UACd,WACA,IACA,SAAuG,CAAC,GACvE;AACjC,SAAO,EAAE,GAAG,QAAQ,WAAW,GAAG;AACpC;AAEO,SAAS,cAAc,MAAiE;AAC7F,SAAO,KAAK,IAAI,UAAQ,EAAE,GAAG,IAAI,EAAE;AACrC;AAMO,SAAS,2BACd,aACA,QACA,SAA8C,CAAC,GAChB;AAC/B,SAAO,EAAE,GAAG,QAAQ,aAAa,OAAO;AAC1C;AAEO,SAAS,uBACd,QACA,SAAoD,CAAC,GAChB;AACrC,SAAO,2BAA2B,SAAS,QAAQ,MAAM;AAC3D;AAEO,SAAS,uBACd,QACA,SAAoD,CAAC,GAChB;AACrC,SAAO,2BAA2B,SAAS,QAAQ,MAAM;AAC3D;AAEO,SAAS,4BACd,QACA,SAA0D,CAAC,GAChB;AAC3C,SAAO,2BAA2B,eAAe,QAAQ,MAAM;AACjE;AAEO,SAAS,+BACd,QACA,SAA6D,CAAC,GAChB;AAC9C,SAAO,2BAA2B,kBAAkB,QAAQ,MAAM;AACpE;AAEO,SAAS,6BACd,QACA,SAA2D,CAAC,GAChB;AAC5C,SAAO,2BAA2B,gBAAgB,QAAQ,MAAM;AAClE;AAEO,SAAS,2BACd,QACA,SAAyD,CAAC,GAChB;AAC1C,SAAO,2BAA2B,cAAc,QAAQ,MAAM;AAChE;AAEO,SAAS,6BACd,QACA,SAA2D,CAAC,GAChB;AAC5C,SAAO,2BAA2B,gBAAgB,QAAQ,MAAM;AAClE;AAEO,SAAS,4BACd,QACA,SAA0D,CAAC,GAChB;AAC3C,SAAO,2BAA2B,eAAe,QAAQ,MAAM;AACjE;AAEO,SAAS,oCACd,QACA,SAAkE,CAAC,GAChB;AACnD,SAAO,2BAA2B,uBAAuB,QAAQ,MAAM;AACzE;AAEO,SAAS,8BACd,QACA,SAA6D,CAAC,GAChB;AAC9C,SAAO,2BAA2B,kBAAkB,QAAQ,MAAM;AACpE;AAEO,SAAS,oCACd,QACA,SAAkE,CAAC,GAChB;AACnD,SAAO,2BAA2B,uBAAuB,QAAQ,MAAM;AACzE;AAEO,SAAS,gCACd,QACA,SAA8D,CAAC,GAChB;AAC/C,SAAO,2BAA2B,mBAAmB,QAAQ,MAAM;AACrE;AAEO,SAAS,wBACd,cACA,eACA,QACA,SAA6F,CAAC,GACxD;AACtC,SAAO,2BAA2B,UAAU,QAAQ,EAAE,GAAG,QAAQ,cAAc,cAAc,CAAC;AAChG;AAMO,SAAS,YAAY,QAA8C;AACxE,SAAO,EAAE,GAAG,OAAO;AACrB;AAEO,SAAS,oBAAoB,QAA8D;AAChG,SAAO;AAAA,IACL,GAAG;AAAA,IACH,iBAAiB,OAAO,iBAAiB,IAAI,YAAU,EAAE,GAAG,MAAM,EAAE;AAAA,IACpE,gBAAgB,OAAO,gBAAgB,IAAI,WAAS,EAAE,GAAG,KAAK,EAAE;AAAA,EAClE;AACF;AAEO,MAAM,kBAAkB;AAAA,EAC7B,KAAK;AAAA,EACL,MAAM;AAAA,EACN,aAAa;AAAA,EACb,OAAO;AAAA,EACP,OAAO;AAAA,EACP,YAAY;AAAA,EACZ,eAAe;AAAA,EACf,aAAa;AAAA,EACb,WAAW;AAAA,EACX,aAAa;AAAA,EACb,YAAY;AAAA,EACZ,oBAAoB;AAAA,EACpB,cAAc;AAAA,EACd,oBAAoB;AAAA,EACpB,gBAAgB;AAAA,EAChB,QAAQ;AAAA,EACR;AAAA,EACA;AACF;","names":[]}
+{"version":3,"sources":["../../../../src/lib/v2/projection/builders.ts"],"sourcesContent":["import type { FormatReferenceStructuredObject } from '../../types/core.generated';\nimport type {\n  AgentPlacementFormatDeclaration,\n  CustomFormatDeclaration,\n  DAASTAudioFormatDeclaration,\n  DisplayTagFormatDeclaration,\n  HTML5FormatDeclaration,\n  HostedAudioFormatDeclaration,\n  HostedVideoFormatDeclaration,\n  ImageAsset,\n  ImageCarouselFormatDeclaration,\n  ImageFormatDeclaration,\n  NativeInFeedFormatDeclaration,\n  ResponsiveCreativeFormatDeclaration,\n  SponsoredPlacementFormatDeclaration,\n  VASTVideoFormatDeclaration,\n} from '../../types/tools.generated';\nimport type { CanonicalFormatDeclaration as CanonicalBaseFormatDeclaration } from './legacy-metadata';\n\ntype WithCommonDeclaration<T> = CanonicalBaseFormatDeclaration &\n  Omit<T, 'v1_format_ref'> & {\n    v1_format_ref?: never;\n  };\n\ninterface CanonicalFormatDeclarationMap {\n  image: WithCommonDeclaration<ImageFormatDeclaration>;\n  html5: WithCommonDeclaration<HTML5FormatDeclaration>;\n  display_tag: WithCommonDeclaration<DisplayTagFormatDeclaration>;\n  image_carousel: WithCommonDeclaration<ImageCarouselFormatDeclaration>;\n  video_hosted: WithCommonDeclaration<HostedVideoFormatDeclaration>;\n  video_vast: WithCommonDeclaration<VASTVideoFormatDeclaration>;\n  audio_hosted: WithCommonDeclaration<HostedAudioFormatDeclaration>;\n  audio_daast: WithCommonDeclaration<DAASTAudioFormatDeclaration>;\n  sponsored_placement: WithCommonDeclaration<SponsoredPlacementFormatDeclaration>;\n  native_in_feed: WithCommonDeclaration<NativeInFeedFormatDeclaration>;\n  responsive_creative: WithCommonDeclaration<ResponsiveCreativeFormatDeclaration>;\n  agent_placement: WithCommonDeclaration<AgentPlacementFormatDeclaration>;\n  custom: WithCommonDeclaration<CustomFormatDeclaration>;\n}\n\nexport type CanonicalFormatKind = keyof CanonicalFormatDeclarationMap;\nexport type CanonicalFormatDeclaration<K extends CanonicalFormatKind = CanonicalFormatKind> =\n  CanonicalFormatDeclarationMap[K];\nexport type CanonicalFormatParams<K extends CanonicalFormatKind> = CanonicalFormatDeclaration<K>['params'];\nexport type CanonicalFormatDeclarationFields<K extends CanonicalFormatKind = CanonicalFormatKind> = Omit<\n  CanonicalFormatDeclaration<K>,\n  'format_kind' | 'params'\n>;\n\nexport type FormatReferenceInput = FormatReferenceStructuredObject & Record<string, unknown>;\n\nexport interface ProductCardFields {\n  image?: ImageAsset;\n  title?: string;\n  description?: string;\n  price_label?: string;\n  cta_label?: string;\n}\n\nexport interface ProductCardDetailedFields {\n  hero_image?: ImageAsset;\n  carousel_images?: ImageAsset[];\n  title?: string;\n  description?: string;\n  specifications?: Array<{ label: string; value: string }>;\n  price_label?: string;\n  cta_label?: string;\n}\n\n/**\n * Build the structured v1 format_id reference shape. Use this instead of a\n * bare string when populating Product.format_ids, ProductFormatDeclaration\n * v1_format_ref, or list_creative_formats filters.\n */\nexport function legacyFormatRef(\n  agent_url: string,\n  id: string,\n  fields: Omit<Partial<FormatReferenceStructuredObject>, 'agent_url' | 'id'> & Record<string, unknown> = {}\n): FormatReferenceStructuredObject {\n  return { ...fields, agent_url, id };\n}\n\nexport function legacyFormatRefs(...refs: FormatReferenceInput[]): FormatReferenceStructuredObject[] {\n  return refs.map(ref => ({ ...ref }));\n}\n\n/**\n * Generic canonical-format declaration builder. It sets the format_kind\n * discriminator and keeps common declaration metadata in the third argument.\n */\nexport function canonicalFormatDeclaration<K extends CanonicalFormatKind>(\n  format_kind: K,\n  params: CanonicalFormatParams<K>,\n  fields: CanonicalFormatDeclarationFields<K> = {} as CanonicalFormatDeclarationFields<K>\n): CanonicalFormatDeclaration<K> {\n  if (Reflect.has(fields as object, 'v1_format_ref')) {\n    throw new Error(\n      'canonicalFormatDeclaration does not accept legacy routing references; use explicitly named legacy migration helpers outside the canonical surface'\n    );\n  }\n  return { ...fields, format_kind, params } as CanonicalFormatDeclaration<K>;\n}\n\nexport function imageFormatDeclaration(\n  params: CanonicalFormatParams<'image'>,\n  fields: CanonicalFormatDeclarationFields<'image'> = {}\n): CanonicalFormatDeclaration<'image'> {\n  return canonicalFormatDeclaration('image', params, fields);\n}\n\nexport function html5FormatDeclaration(\n  params: CanonicalFormatParams<'html5'>,\n  fields: CanonicalFormatDeclarationFields<'html5'> = {}\n): CanonicalFormatDeclaration<'html5'> {\n  return canonicalFormatDeclaration('html5', params, fields);\n}\n\nexport function displayTagFormatDeclaration(\n  params: CanonicalFormatParams<'display_tag'>,\n  fields: CanonicalFormatDeclarationFields<'display_tag'> = {}\n): CanonicalFormatDeclaration<'display_tag'> {\n  return canonicalFormatDeclaration('display_tag', params, fields);\n}\n\nexport function imageCarouselFormatDeclaration(\n  params: CanonicalFormatParams<'image_carousel'>,\n  fields: CanonicalFormatDeclarationFields<'image_carousel'> = {}\n): CanonicalFormatDeclaration<'image_carousel'> {\n  return canonicalFormatDeclaration('image_carousel', params, fields);\n}\n\nexport function videoHostedFormatDeclaration(\n  params: CanonicalFormatParams<'video_hosted'>,\n  fields: CanonicalFormatDeclarationFields<'video_hosted'> = {}\n): CanonicalFormatDeclaration<'video_hosted'> {\n  return canonicalFormatDeclaration('video_hosted', params, fields);\n}\n\nexport function videoVastFormatDeclaration(\n  params: CanonicalFormatParams<'video_vast'>,\n  fields: CanonicalFormatDeclarationFields<'video_vast'> = {}\n): CanonicalFormatDeclaration<'video_vast'> {\n  return canonicalFormatDeclaration('video_vast', params, fields);\n}\n\nexport function audioHostedFormatDeclaration(\n  params: CanonicalFormatParams<'audio_hosted'>,\n  fields: CanonicalFormatDeclarationFields<'audio_hosted'> = {}\n): CanonicalFormatDeclaration<'audio_hosted'> {\n  return canonicalFormatDeclaration('audio_hosted', params, fields);\n}\n\nexport function audioDaastFormatDeclaration(\n  params: CanonicalFormatParams<'audio_daast'>,\n  fields: CanonicalFormatDeclarationFields<'audio_daast'> = {}\n): CanonicalFormatDeclaration<'audio_daast'> {\n  return canonicalFormatDeclaration('audio_daast', params, fields);\n}\n\nexport function sponsoredPlacementFormatDeclaration(\n  params: CanonicalFormatParams<'sponsored_placement'>,\n  fields: CanonicalFormatDeclarationFields<'sponsored_placement'> = {}\n): CanonicalFormatDeclaration<'sponsored_placement'> {\n  return canonicalFormatDeclaration('sponsored_placement', params, fields);\n}\n\nexport function nativeInFeedFormatDeclaration(\n  params: CanonicalFormatParams<'native_in_feed'>,\n  fields: CanonicalFormatDeclarationFields<'native_in_feed'> = {}\n): CanonicalFormatDeclaration<'native_in_feed'> {\n  return canonicalFormatDeclaration('native_in_feed', params, fields);\n}\n\nexport function responsiveCreativeFormatDeclaration(\n  params: CanonicalFormatParams<'responsive_creative'>,\n  fields: CanonicalFormatDeclarationFields<'responsive_creative'> = {}\n): CanonicalFormatDeclaration<'responsive_creative'> {\n  return canonicalFormatDeclaration('responsive_creative', params, fields);\n}\n\nexport function agentPlacementFormatDeclaration(\n  params: CanonicalFormatParams<'agent_placement'>,\n  fields: CanonicalFormatDeclarationFields<'agent_placement'> = {}\n): CanonicalFormatDeclaration<'agent_placement'> {\n  return canonicalFormatDeclaration('agent_placement', params, fields);\n}\n\nexport function customFormatDeclaration(\n  format_shape: string,\n  format_schema: NonNullable<CanonicalFormatDeclarationFields<'custom'>['format_schema']>,\n  params: CanonicalFormatParams<'custom'>,\n  fields: Omit<CanonicalFormatDeclarationFields<'custom'>, 'format_shape' | 'format_schema'> = {}\n): CanonicalFormatDeclaration<'custom'> {\n  return canonicalFormatDeclaration('custom', params, { ...fields, format_shape, format_schema });\n}\n\n/**\n * Product cards describe the merchandising UI for a product. They do not carry\n * format_id and are intentionally separate from creative format declarations.\n */\nexport function productCard(fields: ProductCardFields): ProductCardFields {\n  return { ...fields };\n}\n\nexport function productCardDetailed(fields: ProductCardDetailedFields): ProductCardDetailedFields {\n  return {\n    ...fields,\n    carousel_images: fields.carousel_images?.map(image => ({ ...image })),\n    specifications: fields.specifications?.map(spec => ({ ...spec })),\n  };\n}\n\nexport const CanonicalFormat = {\n  declaration: canonicalFormatDeclaration,\n  image: imageFormatDeclaration,\n  html5: html5FormatDeclaration,\n  displayTag: displayTagFormatDeclaration,\n  imageCarousel: imageCarouselFormatDeclaration,\n  videoHosted: videoHostedFormatDeclaration,\n  videoVast: videoVastFormatDeclaration,\n  audioHosted: audioHostedFormatDeclaration,\n  audioDaast: audioDaastFormatDeclaration,\n  sponsoredPlacement: sponsoredPlacementFormatDeclaration,\n  nativeInFeed: nativeInFeedFormatDeclaration,\n  responsiveCreative: responsiveCreativeFormatDeclaration,\n  agentPlacement: agentPlacementFormatDeclaration,\n  custom: customFormatDeclaration,\n  productCard,\n  productCardDetailed,\n} as const;\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA0EO,SAAS,gBACd,WACA,IACA,SAAuG,CAAC,GACvE;AACjC,SAAO,EAAE,GAAG,QAAQ,WAAW,GAAG;AACpC;AAEO,SAAS,oBAAoB,MAAiE;AACnG,SAAO,KAAK,IAAI,UAAQ,EAAE,GAAG,IAAI,EAAE;AACrC;AAMO,SAAS,2BACd,aACA,QACA,SAA8C,CAAC,GAChB;AAC/B,MAAI,QAAQ,IAAI,QAAkB,eAAe,GAAG;AAClD,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACA,SAAO,EAAE,GAAG,QAAQ,aAAa,OAAO;AAC1C;AAEO,SAAS,uBACd,QACA,SAAoD,CAAC,GAChB;AACrC,SAAO,2BAA2B,SAAS,QAAQ,MAAM;AAC3D;AAEO,SAAS,uBACd,QACA,SAAoD,CAAC,GAChB;AACrC,SAAO,2BAA2B,SAAS,QAAQ,MAAM;AAC3D;AAEO,SAAS,4BACd,QACA,SAA0D,CAAC,GAChB;AAC3C,SAAO,2BAA2B,eAAe,QAAQ,MAAM;AACjE;AAEO,SAAS,+BACd,QACA,SAA6D,CAAC,GAChB;AAC9C,SAAO,2BAA2B,kBAAkB,QAAQ,MAAM;AACpE;AAEO,SAAS,6BACd,QACA,SAA2D,CAAC,GAChB;AAC5C,SAAO,2BAA2B,gBAAgB,QAAQ,MAAM;AAClE;AAEO,SAAS,2BACd,QACA,SAAyD,CAAC,GAChB;AAC1C,SAAO,2BAA2B,cAAc,QAAQ,MAAM;AAChE;AAEO,SAAS,6BACd,QACA,SAA2D,CAAC,GAChB;AAC5C,SAAO,2BAA2B,gBAAgB,QAAQ,MAAM;AAClE;AAEO,SAAS,4BACd,QACA,SAA0D,CAAC,GAChB;AAC3C,SAAO,2BAA2B,eAAe,QAAQ,MAAM;AACjE;AAEO,SAAS,oCACd,QACA,SAAkE,CAAC,GAChB;AACnD,SAAO,2BAA2B,uBAAuB,QAAQ,MAAM;AACzE;AAEO,SAAS,8BACd,QACA,SAA6D,CAAC,GAChB;AAC9C,SAAO,2BAA2B,kBAAkB,QAAQ,MAAM;AACpE;AAEO,SAAS,oCACd,QACA,SAAkE,CAAC,GAChB;AACnD,SAAO,2BAA2B,uBAAuB,QAAQ,MAAM;AACzE;AAEO,SAAS,gCACd,QACA,SAA8D,CAAC,GAChB;AAC/C,SAAO,2BAA2B,mBAAmB,QAAQ,MAAM;AACrE;AAEO,SAAS,wBACd,cACA,eACA,QACA,SAA6F,CAAC,GACxD;AACtC,SAAO,2BAA2B,UAAU,QAAQ,EAAE,GAAG,QAAQ,cAAc,cAAc,CAAC;AAChG;AAMO,SAAS,YAAY,QAA8C;AACxE,SAAO,EAAE,GAAG,OAAO;AACrB;AAEO,SAAS,oBAAoB,QAA8D;AAChG,SAAO;AAAA,IACL,GAAG;AAAA,IACH,iBAAiB,OAAO,iBAAiB,IAAI,YAAU,EAAE,GAAG,MAAM,EAAE;AAAA,IACpE,gBAAgB,OAAO,gBAAgB,IAAI,WAAS,EAAE,GAAG,KAAK,EAAE;AAAA,EAClE;AACF;AAEO,MAAM,kBAAkB;AAAA,EAC7B,aAAa;AAAA,EACb,OAAO;AAAA,EACP,OAAO;AAAA,EACP,YAAY;AAAA,EACZ,eAAe;AAAA,EACf,aAAa;AAAA,EACb,WAAW;AAAA,EACX,aAAa;AAAA,EACb,YAAY;AAAA,EACZ,oBAAoB;AAAA,EACpB,cAAc;AAAA,EACd,oBAAoB;AAAA,EACpB,gBAAgB;AAAA,EAChB,QAAQ;AAAA,EACR;AAAA,EACA;AACF;","names":[]}

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

@@ -1,10 +1,15 @@
-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 = {}) {
@@ -57,8 +62,6 @@ function productCardDetailed(fields) {
   };
 }
 const CanonicalFormat = {
-  ref: formatRef,
-  refs: formatRefs,
   declaration: canonicalFormatDeclaration,
   image: imageFormatDeclaration,
   html5: html5FormatDeclaration,
@@ -84,11 +87,11 @@ export {
   canonicalFormatDeclaration,
   customFormatDeclaration,
   displayTagFormatDeclaration,
-  formatRef,
-  formatRefs,
   html5FormatDeclaration,
   imageCarouselFormatDeclaration,
   imageFormatDeclaration,
+  legacyFormatRef,
+  legacyFormatRefs,
   nativeInFeedFormatDeclaration,
   productCard,
   productCardDetailed,

package/dist/lib/v2/projection/builders.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../src/lib/v2/projection/builders.ts"],"sourcesContent":["import type { FormatReferenceStructuredObject } from '../../types/core.generated';\nimport type {\n  AgentPlacementFormatDeclaration,\n  CustomFormatDeclaration,\n  DAASTAudioFormatDeclaration,\n  DisplayTagFormatDeclaration,\n  HTML5FormatDeclaration,\n  HostedAudioFormatDeclaration,\n  HostedVideoFormatDeclaration,\n  ImageAsset,\n  ImageCarouselFormatDeclaration,\n  ImageFormatDeclaration,\n  NativeInFeedFormatDeclaration,\n  ProductFormatDeclaration,\n  ResponsiveCreativeFormatDeclaration,\n  SponsoredPlacementFormatDeclaration,\n  VASTVideoFormatDeclaration,\n} from '../../types/tools.generated';\n\ntype WithCommonDeclaration<T> = ProductFormatDeclaration & T;\n\ninterface CanonicalFormatDeclarationMap {\n  image: WithCommonDeclaration<ImageFormatDeclaration>;\n  html5: WithCommonDeclaration<HTML5FormatDeclaration>;\n  display_tag: WithCommonDeclaration<DisplayTagFormatDeclaration>;\n  image_carousel: WithCommonDeclaration<ImageCarouselFormatDeclaration>;\n  video_hosted: WithCommonDeclaration<HostedVideoFormatDeclaration>;\n  video_vast: WithCommonDeclaration<VASTVideoFormatDeclaration>;\n  audio_hosted: WithCommonDeclaration<HostedAudioFormatDeclaration>;\n  audio_daast: WithCommonDeclaration<DAASTAudioFormatDeclaration>;\n  sponsored_placement: WithCommonDeclaration<SponsoredPlacementFormatDeclaration>;\n  native_in_feed: WithCommonDeclaration<NativeInFeedFormatDeclaration>;\n  responsive_creative: WithCommonDeclaration<ResponsiveCreativeFormatDeclaration>;\n  agent_placement: WithCommonDeclaration<AgentPlacementFormatDeclaration>;\n  custom: WithCommonDeclaration<CustomFormatDeclaration>;\n}\n\nexport type CanonicalFormatKind = keyof CanonicalFormatDeclarationMap;\nexport type CanonicalFormatDeclaration<K extends CanonicalFormatKind = CanonicalFormatKind> =\n  CanonicalFormatDeclarationMap[K];\nexport type CanonicalFormatParams<K extends CanonicalFormatKind> = CanonicalFormatDeclaration<K>['params'];\nexport type CanonicalFormatDeclarationFields<K extends CanonicalFormatKind = CanonicalFormatKind> = Omit<\n  CanonicalFormatDeclaration<K>,\n  'format_kind' | 'params'\n>;\n\nexport type FormatReferenceInput = FormatReferenceStructuredObject & Record<string, unknown>;\n\nexport interface ProductCardFields {\n  image?: ImageAsset;\n  title?: string;\n  description?: string;\n  price_label?: string;\n  cta_label?: string;\n}\n\nexport interface ProductCardDetailedFields {\n  hero_image?: ImageAsset;\n  carousel_images?: ImageAsset[];\n  title?: string;\n  description?: string;\n  specifications?: Array<{ label: string; value: string }>;\n  price_label?: string;\n  cta_label?: string;\n}\n\n/**\n * Build the structured v1 format_id reference shape. Use this instead of a\n * bare string when populating Product.format_ids, ProductFormatDeclaration\n * v1_format_ref, or list_creative_formats filters.\n */\nexport function formatRef(\n  agent_url: string,\n  id: string,\n  fields: Omit<Partial<FormatReferenceStructuredObject>, 'agent_url' | 'id'> & Record<string, unknown> = {}\n): FormatReferenceStructuredObject {\n  return { ...fields, agent_url, id };\n}\n\nexport function formatRefs(...refs: FormatReferenceInput[]): FormatReferenceStructuredObject[] {\n  return refs.map(ref => ({ ...ref }));\n}\n\n/**\n * Generic canonical-format declaration builder. It sets the format_kind\n * discriminator and keeps common declaration metadata in the third argument.\n */\nexport function canonicalFormatDeclaration<K extends CanonicalFormatKind>(\n  format_kind: K,\n  params: CanonicalFormatParams<K>,\n  fields: CanonicalFormatDeclarationFields<K> = {} as CanonicalFormatDeclarationFields<K>\n): CanonicalFormatDeclaration<K> {\n  return { ...fields, format_kind, params } as CanonicalFormatDeclaration<K>;\n}\n\nexport function imageFormatDeclaration(\n  params: CanonicalFormatParams<'image'>,\n  fields: CanonicalFormatDeclarationFields<'image'> = {}\n): CanonicalFormatDeclaration<'image'> {\n  return canonicalFormatDeclaration('image', params, fields);\n}\n\nexport function html5FormatDeclaration(\n  params: CanonicalFormatParams<'html5'>,\n  fields: CanonicalFormatDeclarationFields<'html5'> = {}\n): CanonicalFormatDeclaration<'html5'> {\n  return canonicalFormatDeclaration('html5', params, fields);\n}\n\nexport function displayTagFormatDeclaration(\n  params: CanonicalFormatParams<'display_tag'>,\n  fields: CanonicalFormatDeclarationFields<'display_tag'> = {}\n): CanonicalFormatDeclaration<'display_tag'> {\n  return canonicalFormatDeclaration('display_tag', params, fields);\n}\n\nexport function imageCarouselFormatDeclaration(\n  params: CanonicalFormatParams<'image_carousel'>,\n  fields: CanonicalFormatDeclarationFields<'image_carousel'> = {}\n): CanonicalFormatDeclaration<'image_carousel'> {\n  return canonicalFormatDeclaration('image_carousel', params, fields);\n}\n\nexport function videoHostedFormatDeclaration(\n  params: CanonicalFormatParams<'video_hosted'>,\n  fields: CanonicalFormatDeclarationFields<'video_hosted'> = {}\n): CanonicalFormatDeclaration<'video_hosted'> {\n  return canonicalFormatDeclaration('video_hosted', params, fields);\n}\n\nexport function videoVastFormatDeclaration(\n  params: CanonicalFormatParams<'video_vast'>,\n  fields: CanonicalFormatDeclarationFields<'video_vast'> = {}\n): CanonicalFormatDeclaration<'video_vast'> {\n  return canonicalFormatDeclaration('video_vast', params, fields);\n}\n\nexport function audioHostedFormatDeclaration(\n  params: CanonicalFormatParams<'audio_hosted'>,\n  fields: CanonicalFormatDeclarationFields<'audio_hosted'> = {}\n): CanonicalFormatDeclaration<'audio_hosted'> {\n  return canonicalFormatDeclaration('audio_hosted', params, fields);\n}\n\nexport function audioDaastFormatDeclaration(\n  params: CanonicalFormatParams<'audio_daast'>,\n  fields: CanonicalFormatDeclarationFields<'audio_daast'> = {}\n): CanonicalFormatDeclaration<'audio_daast'> {\n  return canonicalFormatDeclaration('audio_daast', params, fields);\n}\n\nexport function sponsoredPlacementFormatDeclaration(\n  params: CanonicalFormatParams<'sponsored_placement'>,\n  fields: CanonicalFormatDeclarationFields<'sponsored_placement'> = {}\n): CanonicalFormatDeclaration<'sponsored_placement'> {\n  return canonicalFormatDeclaration('sponsored_placement', params, fields);\n}\n\nexport function nativeInFeedFormatDeclaration(\n  params: CanonicalFormatParams<'native_in_feed'>,\n  fields: CanonicalFormatDeclarationFields<'native_in_feed'> = {}\n): CanonicalFormatDeclaration<'native_in_feed'> {\n  return canonicalFormatDeclaration('native_in_feed', params, fields);\n}\n\nexport function responsiveCreativeFormatDeclaration(\n  params: CanonicalFormatParams<'responsive_creative'>,\n  fields: CanonicalFormatDeclarationFields<'responsive_creative'> = {}\n): CanonicalFormatDeclaration<'responsive_creative'> {\n  return canonicalFormatDeclaration('responsive_creative', params, fields);\n}\n\nexport function agentPlacementFormatDeclaration(\n  params: CanonicalFormatParams<'agent_placement'>,\n  fields: CanonicalFormatDeclarationFields<'agent_placement'> = {}\n): CanonicalFormatDeclaration<'agent_placement'> {\n  return canonicalFormatDeclaration('agent_placement', params, fields);\n}\n\nexport function customFormatDeclaration(\n  format_shape: string,\n  format_schema: NonNullable<CanonicalFormatDeclarationFields<'custom'>['format_schema']>,\n  params: CanonicalFormatParams<'custom'>,\n  fields: Omit<CanonicalFormatDeclarationFields<'custom'>, 'format_shape' | 'format_schema'> = {}\n): CanonicalFormatDeclaration<'custom'> {\n  return canonicalFormatDeclaration('custom', params, { ...fields, format_shape, format_schema });\n}\n\n/**\n * Product cards describe the merchandising UI for a product. They do not carry\n * format_id and are intentionally separate from creative format declarations.\n */\nexport function productCard(fields: ProductCardFields): ProductCardFields {\n  return { ...fields };\n}\n\nexport function productCardDetailed(fields: ProductCardDetailedFields): ProductCardDetailedFields {\n  return {\n    ...fields,\n    carousel_images: fields.carousel_images?.map(image => ({ ...image })),\n    specifications: fields.specifications?.map(spec => ({ ...spec })),\n  };\n}\n\nexport const CanonicalFormat = {\n  ref: formatRef,\n  refs: formatRefs,\n  declaration: canonicalFormatDeclaration,\n  image: imageFormatDeclaration,\n  html5: html5FormatDeclaration,\n  displayTag: displayTagFormatDeclaration,\n  imageCarousel: imageCarouselFormatDeclaration,\n  videoHosted: videoHostedFormatDeclaration,\n  videoVast: videoVastFormatDeclaration,\n  audioHosted: audioHostedFormatDeclaration,\n  audioDaast: audioDaastFormatDeclaration,\n  sponsoredPlacement: sponsoredPlacementFormatDeclaration,\n  nativeInFeed: nativeInFeedFormatDeclaration,\n  responsiveCreative: responsiveCreativeFormatDeclaration,\n  agentPlacement: agentPlacementFormatDeclaration,\n  custom: customFormatDeclaration,\n  productCard,\n  productCardDetailed,\n} as const;\n"],"mappings":"AAuEO,SAAS,UACd,WACA,IACA,SAAuG,CAAC,GACvE;AACjC,SAAO,EAAE,GAAG,QAAQ,WAAW,GAAG;AACpC;AAEO,SAAS,cAAc,MAAiE;AAC7F,SAAO,KAAK,IAAI,UAAQ,EAAE,GAAG,IAAI,EAAE;AACrC;AAMO,SAAS,2BACd,aACA,QACA,SAA8C,CAAC,GAChB;AAC/B,SAAO,EAAE,GAAG,QAAQ,aAAa,OAAO;AAC1C;AAEO,SAAS,uBACd,QACA,SAAoD,CAAC,GAChB;AACrC,SAAO,2BAA2B,SAAS,QAAQ,MAAM;AAC3D;AAEO,SAAS,uBACd,QACA,SAAoD,CAAC,GAChB;AACrC,SAAO,2BAA2B,SAAS,QAAQ,MAAM;AAC3D;AAEO,SAAS,4BACd,QACA,SAA0D,CAAC,GAChB;AAC3C,SAAO,2BAA2B,eAAe,QAAQ,MAAM;AACjE;AAEO,SAAS,+BACd,QACA,SAA6D,CAAC,GAChB;AAC9C,SAAO,2BAA2B,kBAAkB,QAAQ,MAAM;AACpE;AAEO,SAAS,6BACd,QACA,SAA2D,CAAC,GAChB;AAC5C,SAAO,2BAA2B,gBAAgB,QAAQ,MAAM;AAClE;AAEO,SAAS,2BACd,QACA,SAAyD,CAAC,GAChB;AAC1C,SAAO,2BAA2B,cAAc,QAAQ,MAAM;AAChE;AAEO,SAAS,6BACd,QACA,SAA2D,CAAC,GAChB;AAC5C,SAAO,2BAA2B,gBAAgB,QAAQ,MAAM;AAClE;AAEO,SAAS,4BACd,QACA,SAA0D,CAAC,GAChB;AAC3C,SAAO,2BAA2B,eAAe,QAAQ,MAAM;AACjE;AAEO,SAAS,oCACd,QACA,SAAkE,CAAC,GAChB;AACnD,SAAO,2BAA2B,uBAAuB,QAAQ,MAAM;AACzE;AAEO,SAAS,8BACd,QACA,SAA6D,CAAC,GAChB;AAC9C,SAAO,2BAA2B,kBAAkB,QAAQ,MAAM;AACpE;AAEO,SAAS,oCACd,QACA,SAAkE,CAAC,GAChB;AACnD,SAAO,2BAA2B,uBAAuB,QAAQ,MAAM;AACzE;AAEO,SAAS,gCACd,QACA,SAA8D,CAAC,GAChB;AAC/C,SAAO,2BAA2B,mBAAmB,QAAQ,MAAM;AACrE;AAEO,SAAS,wBACd,cACA,eACA,QACA,SAA6F,CAAC,GACxD;AACtC,SAAO,2BAA2B,UAAU,QAAQ,EAAE,GAAG,QAAQ,cAAc,cAAc,CAAC;AAChG;AAMO,SAAS,YAAY,QAA8C;AACxE,SAAO,EAAE,GAAG,OAAO;AACrB;AAEO,SAAS,oBAAoB,QAA8D;AAChG,SAAO;AAAA,IACL,GAAG;AAAA,IACH,iBAAiB,OAAO,iBAAiB,IAAI,YAAU,EAAE,GAAG,MAAM,EAAE;AAAA,IACpE,gBAAgB,OAAO,gBAAgB,IAAI,WAAS,EAAE,GAAG,KAAK,EAAE;AAAA,EAClE;AACF;AAEO,MAAM,kBAAkB;AAAA,EAC7B,KAAK;AAAA,EACL,MAAM;AAAA,EACN,aAAa;AAAA,EACb,OAAO;AAAA,EACP,OAAO;AAAA,EACP,YAAY;AAAA,EACZ,eAAe;AAAA,EACf,aAAa;AAAA,EACb,WAAW;AAAA,EACX,aAAa;AAAA,EACb,YAAY;AAAA,EACZ,oBAAoB;AAAA,EACpB,cAAc;AAAA,EACd,oBAAoB;AAAA,EACpB,gBAAgB;AAAA,EAChB,QAAQ;AAAA,EACR;AAAA,EACA;AACF;","names":[]}
+{"version":3,"sources":["../../../../src/lib/v2/projection/builders.ts"],"sourcesContent":["import type { FormatReferenceStructuredObject } from '../../types/core.generated';\nimport type {\n  AgentPlacementFormatDeclaration,\n  CustomFormatDeclaration,\n  DAASTAudioFormatDeclaration,\n  DisplayTagFormatDeclaration,\n  HTML5FormatDeclaration,\n  HostedAudioFormatDeclaration,\n  HostedVideoFormatDeclaration,\n  ImageAsset,\n  ImageCarouselFormatDeclaration,\n  ImageFormatDeclaration,\n  NativeInFeedFormatDeclaration,\n  ResponsiveCreativeFormatDeclaration,\n  SponsoredPlacementFormatDeclaration,\n  VASTVideoFormatDeclaration,\n} from '../../types/tools.generated';\nimport type { CanonicalFormatDeclaration as CanonicalBaseFormatDeclaration } from './legacy-metadata';\n\ntype WithCommonDeclaration<T> = CanonicalBaseFormatDeclaration &\n  Omit<T, 'v1_format_ref'> & {\n    v1_format_ref?: never;\n  };\n\ninterface CanonicalFormatDeclarationMap {\n  image: WithCommonDeclaration<ImageFormatDeclaration>;\n  html5: WithCommonDeclaration<HTML5FormatDeclaration>;\n  display_tag: WithCommonDeclaration<DisplayTagFormatDeclaration>;\n  image_carousel: WithCommonDeclaration<ImageCarouselFormatDeclaration>;\n  video_hosted: WithCommonDeclaration<HostedVideoFormatDeclaration>;\n  video_vast: WithCommonDeclaration<VASTVideoFormatDeclaration>;\n  audio_hosted: WithCommonDeclaration<HostedAudioFormatDeclaration>;\n  audio_daast: WithCommonDeclaration<DAASTAudioFormatDeclaration>;\n  sponsored_placement: WithCommonDeclaration<SponsoredPlacementFormatDeclaration>;\n  native_in_feed: WithCommonDeclaration<NativeInFeedFormatDeclaration>;\n  responsive_creative: WithCommonDeclaration<ResponsiveCreativeFormatDeclaration>;\n  agent_placement: WithCommonDeclaration<AgentPlacementFormatDeclaration>;\n  custom: WithCommonDeclaration<CustomFormatDeclaration>;\n}\n\nexport type CanonicalFormatKind = keyof CanonicalFormatDeclarationMap;\nexport type CanonicalFormatDeclaration<K extends CanonicalFormatKind = CanonicalFormatKind> =\n  CanonicalFormatDeclarationMap[K];\nexport type CanonicalFormatParams<K extends CanonicalFormatKind> = CanonicalFormatDeclaration<K>['params'];\nexport type CanonicalFormatDeclarationFields<K extends CanonicalFormatKind = CanonicalFormatKind> = Omit<\n  CanonicalFormatDeclaration<K>,\n  'format_kind' | 'params'\n>;\n\nexport type FormatReferenceInput = FormatReferenceStructuredObject & Record<string, unknown>;\n\nexport interface ProductCardFields {\n  image?: ImageAsset;\n  title?: string;\n  description?: string;\n  price_label?: string;\n  cta_label?: string;\n}\n\nexport interface ProductCardDetailedFields {\n  hero_image?: ImageAsset;\n  carousel_images?: ImageAsset[];\n  title?: string;\n  description?: string;\n  specifications?: Array<{ label: string; value: string }>;\n  price_label?: string;\n  cta_label?: string;\n}\n\n/**\n * Build the structured v1 format_id reference shape. Use this instead of a\n * bare string when populating Product.format_ids, ProductFormatDeclaration\n * v1_format_ref, or list_creative_formats filters.\n */\nexport function legacyFormatRef(\n  agent_url: string,\n  id: string,\n  fields: Omit<Partial<FormatReferenceStructuredObject>, 'agent_url' | 'id'> & Record<string, unknown> = {}\n): FormatReferenceStructuredObject {\n  return { ...fields, agent_url, id };\n}\n\nexport function legacyFormatRefs(...refs: FormatReferenceInput[]): FormatReferenceStructuredObject[] {\n  return refs.map(ref => ({ ...ref }));\n}\n\n/**\n * Generic canonical-format declaration builder. It sets the format_kind\n * discriminator and keeps common declaration metadata in the third argument.\n */\nexport function canonicalFormatDeclaration<K extends CanonicalFormatKind>(\n  format_kind: K,\n  params: CanonicalFormatParams<K>,\n  fields: CanonicalFormatDeclarationFields<K> = {} as CanonicalFormatDeclarationFields<K>\n): CanonicalFormatDeclaration<K> {\n  if (Reflect.has(fields as object, 'v1_format_ref')) {\n    throw new Error(\n      'canonicalFormatDeclaration does not accept legacy routing references; use explicitly named legacy migration helpers outside the canonical surface'\n    );\n  }\n  return { ...fields, format_kind, params } as CanonicalFormatDeclaration<K>;\n}\n\nexport function imageFormatDeclaration(\n  params: CanonicalFormatParams<'image'>,\n  fields: CanonicalFormatDeclarationFields<'image'> = {}\n): CanonicalFormatDeclaration<'image'> {\n  return canonicalFormatDeclaration('image', params, fields);\n}\n\nexport function html5FormatDeclaration(\n  params: CanonicalFormatParams<'html5'>,\n  fields: CanonicalFormatDeclarationFields<'html5'> = {}\n): CanonicalFormatDeclaration<'html5'> {\n  return canonicalFormatDeclaration('html5', params, fields);\n}\n\nexport function displayTagFormatDeclaration(\n  params: CanonicalFormatParams<'display_tag'>,\n  fields: CanonicalFormatDeclarationFields<'display_tag'> = {}\n): CanonicalFormatDeclaration<'display_tag'> {\n  return canonicalFormatDeclaration('display_tag', params, fields);\n}\n\nexport function imageCarouselFormatDeclaration(\n  params: CanonicalFormatParams<'image_carousel'>,\n  fields: CanonicalFormatDeclarationFields<'image_carousel'> = {}\n): CanonicalFormatDeclaration<'image_carousel'> {\n  return canonicalFormatDeclaration('image_carousel', params, fields);\n}\n\nexport function videoHostedFormatDeclaration(\n  params: CanonicalFormatParams<'video_hosted'>,\n  fields: CanonicalFormatDeclarationFields<'video_hosted'> = {}\n): CanonicalFormatDeclaration<'video_hosted'> {\n  return canonicalFormatDeclaration('video_hosted', params, fields);\n}\n\nexport function videoVastFormatDeclaration(\n  params: CanonicalFormatParams<'video_vast'>,\n  fields: CanonicalFormatDeclarationFields<'video_vast'> = {}\n): CanonicalFormatDeclaration<'video_vast'> {\n  return canonicalFormatDeclaration('video_vast', params, fields);\n}\n\nexport function audioHostedFormatDeclaration(\n  params: CanonicalFormatParams<'audio_hosted'>,\n  fields: CanonicalFormatDeclarationFields<'audio_hosted'> = {}\n): CanonicalFormatDeclaration<'audio_hosted'> {\n  return canonicalFormatDeclaration('audio_hosted', params, fields);\n}\n\nexport function audioDaastFormatDeclaration(\n  params: CanonicalFormatParams<'audio_daast'>,\n  fields: CanonicalFormatDeclarationFields<'audio_daast'> = {}\n): CanonicalFormatDeclaration<'audio_daast'> {\n  return canonicalFormatDeclaration('audio_daast', params, fields);\n}\n\nexport function sponsoredPlacementFormatDeclaration(\n  params: CanonicalFormatParams<'sponsored_placement'>,\n  fields: CanonicalFormatDeclarationFields<'sponsored_placement'> = {}\n): CanonicalFormatDeclaration<'sponsored_placement'> {\n  return canonicalFormatDeclaration('sponsored_placement', params, fields);\n}\n\nexport function nativeInFeedFormatDeclaration(\n  params: CanonicalFormatParams<'native_in_feed'>,\n  fields: CanonicalFormatDeclarationFields<'native_in_feed'> = {}\n): CanonicalFormatDeclaration<'native_in_feed'> {\n  return canonicalFormatDeclaration('native_in_feed', params, fields);\n}\n\nexport function responsiveCreativeFormatDeclaration(\n  params: CanonicalFormatParams<'responsive_creative'>,\n  fields: CanonicalFormatDeclarationFields<'responsive_creative'> = {}\n): CanonicalFormatDeclaration<'responsive_creative'> {\n  return canonicalFormatDeclaration('responsive_creative', params, fields);\n}\n\nexport function agentPlacementFormatDeclaration(\n  params: CanonicalFormatParams<'agent_placement'>,\n  fields: CanonicalFormatDeclarationFields<'agent_placement'> = {}\n): CanonicalFormatDeclaration<'agent_placement'> {\n  return canonicalFormatDeclaration('agent_placement', params, fields);\n}\n\nexport function customFormatDeclaration(\n  format_shape: string,\n  format_schema: NonNullable<CanonicalFormatDeclarationFields<'custom'>['format_schema']>,\n  params: CanonicalFormatParams<'custom'>,\n  fields: Omit<CanonicalFormatDeclarationFields<'custom'>, 'format_shape' | 'format_schema'> = {}\n): CanonicalFormatDeclaration<'custom'> {\n  return canonicalFormatDeclaration('custom', params, { ...fields, format_shape, format_schema });\n}\n\n/**\n * Product cards describe the merchandising UI for a product. They do not carry\n * format_id and are intentionally separate from creative format declarations.\n */\nexport function productCard(fields: ProductCardFields): ProductCardFields {\n  return { ...fields };\n}\n\nexport function productCardDetailed(fields: ProductCardDetailedFields): ProductCardDetailedFields {\n  return {\n    ...fields,\n    carousel_images: fields.carousel_images?.map(image => ({ ...image })),\n    specifications: fields.specifications?.map(spec => ({ ...spec })),\n  };\n}\n\nexport const CanonicalFormat = {\n  declaration: canonicalFormatDeclaration,\n  image: imageFormatDeclaration,\n  html5: html5FormatDeclaration,\n  displayTag: displayTagFormatDeclaration,\n  imageCarousel: imageCarouselFormatDeclaration,\n  videoHosted: videoHostedFormatDeclaration,\n  videoVast: videoVastFormatDeclaration,\n  audioHosted: audioHostedFormatDeclaration,\n  audioDaast: audioDaastFormatDeclaration,\n  sponsoredPlacement: sponsoredPlacementFormatDeclaration,\n  nativeInFeed: nativeInFeedFormatDeclaration,\n  responsiveCreative: responsiveCreativeFormatDeclaration,\n  agentPlacement: agentPlacementFormatDeclaration,\n  custom: customFormatDeclaration,\n  productCard,\n  productCardDetailed,\n} as const;\n"],"mappings":"AA0EO,SAAS,gBACd,WACA,IACA,SAAuG,CAAC,GACvE;AACjC,SAAO,EAAE,GAAG,QAAQ,WAAW,GAAG;AACpC;AAEO,SAAS,oBAAoB,MAAiE;AACnG,SAAO,KAAK,IAAI,UAAQ,EAAE,GAAG,IAAI,EAAE;AACrC;AAMO,SAAS,2BACd,aACA,QACA,SAA8C,CAAC,GAChB;AAC/B,MAAI,QAAQ,IAAI,QAAkB,eAAe,GAAG;AAClD,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACA,SAAO,EAAE,GAAG,QAAQ,aAAa,OAAO;AAC1C;AAEO,SAAS,uBACd,QACA,SAAoD,CAAC,GAChB;AACrC,SAAO,2BAA2B,SAAS,QAAQ,MAAM;AAC3D;AAEO,SAAS,uBACd,QACA,SAAoD,CAAC,GAChB;AACrC,SAAO,2BAA2B,SAAS,QAAQ,MAAM;AAC3D;AAEO,SAAS,4BACd,QACA,SAA0D,CAAC,GAChB;AAC3C,SAAO,2BAA2B,eAAe,QAAQ,MAAM;AACjE;AAEO,SAAS,+BACd,QACA,SAA6D,CAAC,GAChB;AAC9C,SAAO,2BAA2B,kBAAkB,QAAQ,MAAM;AACpE;AAEO,SAAS,6BACd,QACA,SAA2D,CAAC,GAChB;AAC5C,SAAO,2BAA2B,gBAAgB,QAAQ,MAAM;AAClE;AAEO,SAAS,2BACd,QACA,SAAyD,CAAC,GAChB;AAC1C,SAAO,2BAA2B,cAAc,QAAQ,MAAM;AAChE;AAEO,SAAS,6BACd,QACA,SAA2D,CAAC,GAChB;AAC5C,SAAO,2BAA2B,gBAAgB,QAAQ,MAAM;AAClE;AAEO,SAAS,4BACd,QACA,SAA0D,CAAC,GAChB;AAC3C,SAAO,2BAA2B,eAAe,QAAQ,MAAM;AACjE;AAEO,SAAS,oCACd,QACA,SAAkE,CAAC,GAChB;AACnD,SAAO,2BAA2B,uBAAuB,QAAQ,MAAM;AACzE;AAEO,SAAS,8BACd,QACA,SAA6D,CAAC,GAChB;AAC9C,SAAO,2BAA2B,kBAAkB,QAAQ,MAAM;AACpE;AAEO,SAAS,oCACd,QACA,SAAkE,CAAC,GAChB;AACnD,SAAO,2BAA2B,uBAAuB,QAAQ,MAAM;AACzE;AAEO,SAAS,gCACd,QACA,SAA8D,CAAC,GAChB;AAC/C,SAAO,2BAA2B,mBAAmB,QAAQ,MAAM;AACrE;AAEO,SAAS,wBACd,cACA,eACA,QACA,SAA6F,CAAC,GACxD;AACtC,SAAO,2BAA2B,UAAU,QAAQ,EAAE,GAAG,QAAQ,cAAc,cAAc,CAAC;AAChG;AAMO,SAAS,YAAY,QAA8C;AACxE,SAAO,EAAE,GAAG,OAAO;AACrB;AAEO,SAAS,oBAAoB,QAA8D;AAChG,SAAO;AAAA,IACL,GAAG;AAAA,IACH,iBAAiB,OAAO,iBAAiB,IAAI,YAAU,EAAE,GAAG,MAAM,EAAE;AAAA,IACpE,gBAAgB,OAAO,gBAAgB,IAAI,WAAS,EAAE,GAAG,KAAK,EAAE;AAAA,EAClE;AACF;AAEO,MAAM,kBAAkB;AAAA,EAC7B,aAAa;AAAA,EACb,OAAO;AAAA,EACP,OAAO;AAAA,EACP,YAAY;AAAA,EACZ,eAAe;AAAA,EACf,aAAa;AAAA,EACb,WAAW;AAAA,EACX,aAAa;AAAA,EACb,YAAY;AAAA,EACZ,oBAAoB;AAAA,EACpB,cAAc;AAAA,EACd,oBAAoB;AAAA,EACpB,gBAAgB;AAAA,EAChB,QAAQ;AAAA,EACR;AAAA,EACA;AACF;","names":[]}

package/dist/lib/v2/projection/catalog-snapshot.d.mts

@@ -0,0 +1,47 @@
+import type { LegacyFormatConverter } from './v1-to-v2.mjs';
+import type { V2ProductFormatDeclaration } from './types.mjs';
+import type { CanonicalFormatLegacyResolver } from './v2-to-v1.mjs';
+/** Provenance tier for a pre-resolved immutable format catalog snapshot. */
+export type ProjectionCatalogSource = 'publisher' | 'aao_mirror' | 'agent_derived' | 'configured';
+/**
+ * Canonical catalog data resolved outside the pure projector.
+ *
+ * Network discovery deliberately does not happen inside projection. Callers
+ * may resolve publisher/community catalogs asynchronously, then inject the
+ * immutable result here for synchronous reads, writes, continuations, and
+ * webhook handling. Array order is precedence order (most specific first).
+ */
+export interface ProjectionCatalogSnapshot {
+    source: ProjectionCatalogSource;
+    /** Canonical publisher scope applied when declarations omit it. */
+    publisher_domain?: string;
+    formats: readonly V2ProductFormatDeclaration[];
+}
+/**
+ * Convert exact, catalog-authored `v1_format_ref` aliases into the existing
+ * converter seam. Canonical-only declarations never become legacy aliases,
+ * and matching is always owner + id + dimensional discriminators—never ID
+ * alone. Duplicate aliases at the same precedence tier fail closed.
+ */
+export declare function legacyFormatConverterFromCatalogSnapshots(snapshots: readonly ProjectionCatalogSnapshot[] | undefined, fallback?: LegacyFormatConverter): LegacyFormatConverter | undefined;
+/**
+ * Build the canonical → legacy half of an exact catalog-authored adapter.
+ *
+ * Only stable `format_option_id` references participate. Snapshot precedence
+ * mirrors the forward projector, duplicate declarations at one tier fail
+ * closed, and a multi-option selector is returned only when every option has
+ * an exact mapping. This makes the resolver safe to use after canonical
+ * objects have crossed a process or persistence boundary and lost the SDK's
+ * private in-memory route metadata.
+ */
+export declare function canonicalFormatLegacyResolverFromCatalogSnapshots(snapshots: readonly ProjectionCatalogSnapshot[] | undefined, fallback?: CanonicalFormatLegacyResolver): CanonicalFormatLegacyResolver | undefined;
+/** Client configuration generated from one bidirectional, owner-scoped catalog. */
+export interface ProjectionCatalogAdapters {
+    projectionCatalogs: readonly ProjectionCatalogSnapshot[];
+    canonicalFormatLegacyResolver: CanonicalFormatLegacyResolver;
+}
+/**
+ * Configure both discovery upgrade and legacy delivery downgrade from one
+ * immutable catalog. Spread the result into `AgentClient` configuration.
+ */
+export declare function projectionAdaptersFromCatalogSnapshots(snapshots: readonly ProjectionCatalogSnapshot[], fallbackCanonicalResolver?: CanonicalFormatLegacyResolver): ProjectionCatalogAdapters;

package/dist/lib/v2/projection/catalog-snapshot.d.ts

@@ -0,0 +1,48 @@
+import type { LegacyFormatConverter } from './v1-to-v2';
+import type { V2ProductFormatDeclaration } from './types';
+import type { CanonicalFormatLegacyResolver } from './v2-to-v1';
+/** Provenance tier for a pre-resolved immutable format catalog snapshot. */
+export type ProjectionCatalogSource = 'publisher' | 'aao_mirror' | 'agent_derived' | 'configured';
+/**
+ * Canonical catalog data resolved outside the pure projector.
+ *
+ * Network discovery deliberately does not happen inside projection. Callers
+ * may resolve publisher/community catalogs asynchronously, then inject the
+ * immutable result here for synchronous reads, writes, continuations, and
+ * webhook handling. Array order is precedence order (most specific first).
+ */
+export interface ProjectionCatalogSnapshot {
+    source: ProjectionCatalogSource;
+    /** Canonical publisher scope applied when declarations omit it. */
+    publisher_domain?: string;
+    formats: readonly V2ProductFormatDeclaration[];
+}
+/**
+ * Convert exact, catalog-authored `v1_format_ref` aliases into the existing
+ * converter seam. Canonical-only declarations never become legacy aliases,
+ * and matching is always owner + id + dimensional discriminators—never ID
+ * alone. Duplicate aliases at the same precedence tier fail closed.
+ */
+export declare function legacyFormatConverterFromCatalogSnapshots(snapshots: readonly ProjectionCatalogSnapshot[] | undefined, fallback?: LegacyFormatConverter): LegacyFormatConverter | undefined;
+/**
+ * Build the canonical → legacy half of an exact catalog-authored adapter.
+ *
+ * Only stable `format_option_id` references participate. Snapshot precedence
+ * mirrors the forward projector, duplicate declarations at one tier fail
+ * closed, and a multi-option selector is returned only when every option has
+ * an exact mapping. This makes the resolver safe to use after canonical
+ * objects have crossed a process or persistence boundary and lost the SDK's
+ * private in-memory route metadata.
+ */
+export declare function canonicalFormatLegacyResolverFromCatalogSnapshots(snapshots: readonly ProjectionCatalogSnapshot[] | undefined, fallback?: CanonicalFormatLegacyResolver): CanonicalFormatLegacyResolver | undefined;
+/** Client configuration generated from one bidirectional, owner-scoped catalog. */
+export interface ProjectionCatalogAdapters {
+    projectionCatalogs: readonly ProjectionCatalogSnapshot[];
+    canonicalFormatLegacyResolver: CanonicalFormatLegacyResolver;
+}
+/**
+ * Configure both discovery upgrade and legacy delivery downgrade from one
+ * immutable catalog. Spread the result into `AgentClient` configuration.
+ */
+export declare function projectionAdaptersFromCatalogSnapshots(snapshots: readonly ProjectionCatalogSnapshot[], fallbackCanonicalResolver?: CanonicalFormatLegacyResolver): ProjectionCatalogAdapters;
+//# sourceMappingURL=catalog-snapshot.d.ts.map

package/dist/lib/v2/projection/catalog-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-snapshot.d.ts","sourceRoot":"","sources":["../../../../src/lib/v2/projection/catalog-snapshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,KAAK,EAAc,0BAA0B,EAAE,MAAM,SAAS,CAAC;AACtE,OAAO,KAAK,EAA0C,6BAA6B,EAAE,MAAM,YAAY,CAAC;AAIxG,4EAA4E;AAC5E,MAAM,MAAM,uBAAuB,GAAG,WAAW,GAAG,YAAY,GAAG,eAAe,GAAG,YAAY,CAAC;AAElG;;;;;;;GAOG;AACH,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,uBAAuB,CAAC;IAChC,mEAAmE;IACnE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,SAAS,0BAA0B,EAAE,CAAC;CAChD;AA8OD;;;;;GAKG;AACH,wBAAgB,yCAAyC,CACvD,SAAS,EAAE,SAAS,yBAAyB,EAAE,GAAG,SAAS,EAC3D,QAAQ,CAAC,EAAE,qBAAqB,GAC/B,qBAAqB,GAAG,SAAS,CAgBnC;AAED;;;;;;;;;GASG;AACH,wBAAgB,iDAAiD,CAC/D,SAAS,EAAE,SAAS,yBAAyB,EAAE,GAAG,SAAS,EAC3D,QAAQ,CAAC,EAAE,6BAA6B,GACvC,6BAA6B,GAAG,SAAS,CA4B3C;AAED,mFAAmF;AACnF,MAAM,WAAW,yBAAyB;IACxC,kBAAkB,EAAE,SAAS,yBAAyB,EAAE,CAAC;IACzD,6BAA6B,EAAE,6BAA6B,CAAC;CAC9D;AAoDD;;;GAGG;AACH,wBAAgB,sCAAsC,CACpD,SAAS,EAAE,SAAS,yBAAyB,EAAE,EAC/C,yBAAyB,CAAC,EAAE,6BAA6B,GACxD,yBAAyB,CAU3B"}

package/dist/lib/v2/projection/catalog-snapshot.js

@@ -0,0 +1,291 @@
+"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 catalog_snapshot_exports = {};
+__export(catalog_snapshot_exports, {
+  canonicalFormatLegacyResolverFromCatalogSnapshots: () => canonicalFormatLegacyResolverFromCatalogSnapshots,
+  legacyFormatConverterFromCatalogSnapshots: () => legacyFormatConverterFromCatalogSnapshots,
+  projectionAdaptersFromCatalogSnapshots: () => projectionAdaptersFromCatalogSnapshots
+});
+module.exports = __toCommonJS(catalog_snapshot_exports);
+var import_resolve_agent_properties = require('../../discovery/resolve-agent-properties.js');
+var import_canonical_properties = require('./canonical-properties.js');
+const compiledSnapshotCache = /* @__PURE__ */ new WeakMap();
+function normalizedAgentUrl(value) {
+  return (0, import_resolve_agent_properties.canonicalizeAgentUrl)(value) ?? value;
+}
+function legacyRefKey(ref) {
+  return JSON.stringify([
+    normalizedAgentUrl(ref.agent_url),
+    ref.id,
+    ref.width ?? null,
+    ref.height ?? null,
+    ref.duration_ms ?? null
+  ]);
+}
+function normalizedPublisherDomain(value) {
+  return (value ?? "").trim().toLowerCase().replace(/\.$/, "");
+}
+function formatOptionRefKey(formatOptionId, publisherDomain) {
+  return JSON.stringify([normalizedPublisherDomain(publisherDomain), formatOptionId]);
+}
+function formatOptionRefFromValue(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const record = value;
+  if (typeof record.format_option_id !== "string" || record.format_option_id.length === 0) return void 0;
+  if (record.scope === "publisher" || record.scope === void 0 && typeof record.publisher_domain === "string") {
+    if (typeof record.publisher_domain !== "string" || record.publisher_domain.length === 0) return void 0;
+    return { format_option_id: record.format_option_id, publisher_domain: record.publisher_domain };
+  }
+  return { format_option_id: record.format_option_id };
+}
+function semanticFields(value) {
+  return {
+    ...typeof value.format_kind === "string" ? { format_kind: value.format_kind } : {},
+    ...value.params !== null && typeof value.params === "object" && !Array.isArray(value.params) ? { params: value.params } : {}
+  };
+}
+function collectFormatOptionRefs(value, seen = /* @__PURE__ */ new WeakSet()) {
+  if (value === null || typeof value !== "object" || seen.has(value)) return [];
+  seen.add(value);
+  const record = value;
+  const refs = [];
+  const direct = formatOptionRefFromValue(record.format_option_ref);
+  if (direct) refs.push({ ...direct, ...semanticFields(record) });
+  for (const key of ["format_option_refs", "format_options"]) {
+    if (!Array.isArray(record[key])) continue;
+    for (const item of record[key]) {
+      const ref = formatOptionRefFromValue(item);
+      const itemRecord = item !== null && typeof item === "object" && !Array.isArray(item) ? item : record;
+      if (ref) refs.push({ ...ref, ...semanticFields(itemRecord) });
+    }
+  }
+  if (Array.isArray(record.selector_containers)) {
+    for (const container of record.selector_containers) refs.push(...collectFormatOptionRefs(container, seen));
+  }
+  return refs;
+}
+function resolutionContextFormatOptionRefs(context) {
+  if (context.source === "product") {
+    const declaration = context.declaration;
+    if (typeof declaration.format_option_id !== "string" || declaration.format_option_id.length === 0) return [];
+    return [
+      {
+        format_option_id: declaration.format_option_id,
+        ...typeof declaration.publisher_domain === "string" ? { publisher_domain: declaration.publisher_domain } : {},
+        format_kind: declaration.format_kind,
+        params: declaration.params
+      }
+    ];
+  }
+  if (context.source === "creative") {
+    const creativeRefs = collectFormatOptionRefs(context.creative);
+    return creativeRefs.length > 0 ? creativeRefs : collectFormatOptionRefs(context.selector);
+  }
+  return collectFormatOptionRefs(context.selector);
+}
+function dataValuesEqual(left, right) {
+  if (Object.is(left, right)) return true;
+  if (Array.isArray(left) || Array.isArray(right)) {
+    return Array.isArray(left) && Array.isArray(right) && left.length === right.length && left.every((item, index) => dataValuesEqual(item, right[index]));
+  }
+  if (left === null || right === null || typeof left !== "object" || typeof right !== "object") return false;
+  const leftRecord = left;
+  const rightRecord = right;
+  const leftKeys = Object.keys(leftRecord).sort();
+  const rightKeys = Object.keys(rightRecord).sort();
+  return leftKeys.length === rightKeys.length && leftKeys.every((key, index) => key === rightKeys[index] && dataValuesEqual(leftRecord[key], rightRecord[key]));
+}
+function sharedParamsAgree(declarationParams, contextParams) {
+  if (!contextParams) return true;
+  return Object.keys(contextParams).every(
+    (key) => !(key in declarationParams) || dataValuesEqual(declarationParams[key], contextParams[key])
+  );
+}
+function routeMatchesContext(route, ref, context) {
+  if (ref.format_kind !== void 0 && ref.format_kind !== route.declaration.format_kind) return false;
+  if (!sharedParamsAgree(route.declaration.params, ref.params)) return false;
+  const records = context.source === "creative" ? [context.creative, context.selector] : context.source === "selector" ? [context.selector] : [];
+  return records.every((record) => {
+    const fields = semanticFields(record);
+    return (fields.format_kind === void 0 || fields.format_kind === route.declaration.format_kind) && sharedParamsAgree(route.declaration.params, fields.params);
+  });
+}
+function immutableClone(value) {
+  const clone = structuredClone(value);
+  const freeze = (candidate, seen = /* @__PURE__ */ new WeakSet()) => {
+    if (candidate === null || typeof candidate !== "object" || seen.has(candidate)) return;
+    seen.add(candidate);
+    for (const child of Object.values(candidate)) freeze(child, seen);
+    Object.freeze(candidate);
+  };
+  freeze(clone);
+  return clone;
+}
+function declarationWithoutLegacyIdentity(declaration, publisherDomain) {
+  const { v1_format_ref: _dropRefs, canonical_formats_only: _dropCanonicalOnly, ...canonical } = declaration;
+  void _dropRefs;
+  void _dropCanonicalOnly;
+  return {
+    ...canonical,
+    ...canonical.publisher_domain === void 0 && publisherDomain ? { publisher_domain: publisherDomain } : {}
+  };
+}
+function compileProjectionCatalogSnapshots(snapshots) {
+  const cached = compiledSnapshotCache.get(snapshots);
+  if (cached) return cached;
+  const compiled = snapshots.map((snapshot) => {
+    const byLegacyRef = /* @__PURE__ */ new Map();
+    const byFormatOptionRef = /* @__PURE__ */ new Map();
+    for (const sourceDeclaration of snapshot.formats) {
+      const declaration = immutableClone(sourceDeclaration);
+      if (declaration.canonical_formats_only === true || !(0, import_canonical_properties.isCanonicalV1Translatable)(declaration.format_kind) || !Array.isArray(declaration.v1_format_ref) || declaration.v1_format_ref.length === 0) {
+        continue;
+      }
+      const canonical = immutableClone(declarationWithoutLegacyIdentity(declaration, snapshot.publisher_domain));
+      const legacyRefs = immutableClone([
+        ...new Map(declaration.v1_format_ref.map((ref) => [legacyRefKey(ref), { ...ref }])).values()
+      ]);
+      const declarationKeys = new Set(declaration.v1_format_ref.map(legacyRefKey));
+      for (const key of declarationKeys) {
+        const matches = byLegacyRef.get(key) ?? [];
+        matches.push(canonical);
+        byLegacyRef.set(key, matches);
+      }
+      if (typeof canonical.format_option_id === "string" && canonical.format_option_id.length > 0 && typeof canonical.publisher_domain === "string" && canonical.publisher_domain.length > 0) {
+        const key = formatOptionRefKey(canonical.format_option_id, canonical.publisher_domain);
+        const matches = byFormatOptionRef.get(key) ?? [];
+        matches.push(Object.freeze({ declaration: canonical, legacyRefs }));
+        byFormatOptionRef.set(key, matches);
+      }
+    }
+    for (const matches of byLegacyRef.values()) Object.freeze(matches);
+    for (const matches of byFormatOptionRef.values()) Object.freeze(matches);
+    return Object.freeze({ byLegacyRef, byFormatOptionRef });
+  });
+  Object.freeze(compiled);
+  compiledSnapshotCache.set(snapshots, compiled);
+  return compiled;
+}
+function legacyFormatConverterFromCatalogSnapshots(snapshots, fallback) {
+  if (!snapshots || snapshots.length === 0) return fallback;
+  const compiled = compileProjectionCatalogSnapshots(snapshots);
+  return (context) => {
+    const key = legacyRefKey(context.formatId);
+    for (const snapshot of compiled) {
+      const matches = snapshot.byLegacyRef.get(key) ?? [];
+      if (matches.length > 1) {
+        throw new Error("projection catalog contains ambiguous legacy aliases");
+      }
+      if (matches.length === 1) {
+        return matches[0];
+      }
+    }
+    return fallback?.(context);
+  };
+}
+function canonicalFormatLegacyResolverFromCatalogSnapshots(snapshots, fallback) {
+  if (!snapshots || snapshots.length === 0) return fallback;
+  const compiled = compileProjectionCatalogSnapshots(snapshots);
+  return (context) => {
+    const refs = resolutionContextFormatOptionRefs(context);
+    if (refs.length === 0) return fallback?.(context);
+    const resolved = [];
+    for (const ref of refs) {
+      const key = formatOptionRefKey(ref.format_option_id, ref.publisher_domain);
+      let matched;
+      for (const snapshot of compiled) {
+        const matches = snapshot.byFormatOptionRef.get(key) ?? [];
+        if (matches.length > 1) {
+          throw new Error("projection catalog contains ambiguous canonical format option aliases");
+        }
+        if (matches.length === 1) {
+          matched = matches[0];
+          break;
+        }
+      }
+      if (!matched) return fallback?.(context);
+      if (!routeMatchesContext(matched, ref, context)) return fallback?.(context);
+      resolved.push(...matched.legacyRefs.map((item) => ({ ...item })));
+    }
+    return [...new Map(resolved.map((ref) => [legacyRefKey(ref), ref])).values()];
+  };
+}
+function assertBidirectionalProjectionCatalogs(snapshots) {
+  const routeByCanonicalOption = /* @__PURE__ */ new Map();
+  const canonicalOptionByLegacyRoute = /* @__PURE__ */ new Map();
+  for (const snapshot of snapshots) {
+    const declarationsAtThisTier = /* @__PURE__ */ new Set();
+    for (const declaration of snapshot.formats) {
+      if (declaration.canonical_formats_only === true || !Array.isArray(declaration.v1_format_ref) || declaration.v1_format_ref.length === 0) {
+        continue;
+      }
+      if (!(0, import_canonical_properties.isCanonicalV1Translatable)(declaration.format_kind)) {
+        throw new Error("bidirectional projection adapters cannot downgrade a canonical-only format kind");
+      }
+      const canonical = declarationWithoutLegacyIdentity(declaration, snapshot.publisher_domain);
+      if (typeof canonical.format_option_id !== "string" || canonical.format_option_id.length === 0) {
+        throw new Error("bidirectional projection adapters require a stable format_option_id");
+      }
+      if (typeof canonical.publisher_domain !== "string" || canonical.publisher_domain.length === 0) {
+        throw new Error("bidirectional projection adapters require publisher-scoped format options");
+      }
+      const uniqueLegacyKeys = new Set(declaration.v1_format_ref.map(legacyRefKey));
+      if (uniqueLegacyKeys.size !== 1) {
+        throw new Error(
+          "bidirectional projection adapters require exactly one legacy route per canonical format option"
+        );
+      }
+      const canonicalKey = formatOptionRefKey(canonical.format_option_id, canonical.publisher_domain);
+      const legacyKey = [...uniqueLegacyKeys][0];
+      const declarationKey = JSON.stringify([canonicalKey, legacyKey]);
+      if (declarationsAtThisTier.has(declarationKey)) {
+        throw new Error("bidirectional projection adapters contain duplicate declarations at one precedence tier");
+      }
+      declarationsAtThisTier.add(declarationKey);
+      const existing = routeByCanonicalOption.get(canonicalKey);
+      if (existing !== void 0 && existing !== legacyKey) {
+        throw new Error("bidirectional projection adapters contain conflicting reverse routes");
+      }
+      const existingCanonical = canonicalOptionByLegacyRoute.get(legacyKey);
+      if (existingCanonical !== void 0 && existingCanonical !== canonicalKey) {
+        throw new Error("bidirectional projection adapters contain conflicting forward routes");
+      }
+      routeByCanonicalOption.set(canonicalKey, legacyKey);
+      canonicalOptionByLegacyRoute.set(legacyKey, canonicalKey);
+    }
+  }
+}
+function projectionAdaptersFromCatalogSnapshots(snapshots, fallbackCanonicalResolver) {
+  assertBidirectionalProjectionCatalogs(snapshots);
+  const canonicalFormatLegacyResolver = canonicalFormatLegacyResolverFromCatalogSnapshots(
+    snapshots,
+    fallbackCanonicalResolver
+  );
+  if (!canonicalFormatLegacyResolver) {
+    throw new Error("projection adapters require at least one catalog snapshot or a fallback resolver");
+  }
+  return { projectionCatalogs: snapshots, canonicalFormatLegacyResolver };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  canonicalFormatLegacyResolverFromCatalogSnapshots,
+  legacyFormatConverterFromCatalogSnapshots,
+  projectionAdaptersFromCatalogSnapshots
+});
+//# sourceMappingURL=catalog-snapshot.js.map

package/dist/lib/v2/projection/catalog-snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/lib/v2/projection/catalog-snapshot.ts"],"sourcesContent":["import type { LegacyFormatConverter } from './v1-to-v2';\nimport type { V1FormatId, V2ProductFormatDeclaration } from './types';\nimport type { CanonicalFormatLegacyResolutionContext, CanonicalFormatLegacyResolver } from './v2-to-v1';\nimport { canonicalizeAgentUrl } from '../../discovery/resolve-agent-properties';\nimport { isCanonicalV1Translatable } from './canonical-properties';\n\n/** Provenance tier for a pre-resolved immutable format catalog snapshot. */\nexport type ProjectionCatalogSource = 'publisher' | 'aao_mirror' | 'agent_derived' | 'configured';\n\n/**\n * Canonical catalog data resolved outside the pure projector.\n *\n * Network discovery deliberately does not happen inside projection. Callers\n * may resolve publisher/community catalogs asynchronously, then inject the\n * immutable result here for synchronous reads, writes, continuations, and\n * webhook handling. Array order is precedence order (most specific first).\n */\nexport interface ProjectionCatalogSnapshot {\n  source: ProjectionCatalogSource;\n  /** Canonical publisher scope applied when declarations omit it. */\n  publisher_domain?: string;\n  formats: readonly V2ProductFormatDeclaration[];\n}\n\ninterface CompiledProjectionCatalogSnapshot {\n  byLegacyRef: ReadonlyMap<string, readonly V2ProductFormatDeclaration[]>;\n  byFormatOptionRef: ReadonlyMap<string, readonly CompiledReverseRoute[]>;\n}\n\ninterface CompiledReverseRoute {\n  declaration: Readonly<V2ProductFormatDeclaration>;\n  legacyRefs: readonly V1FormatId[];\n}\n\ninterface ContextFormatOptionRef {\n  format_option_id: string;\n  publisher_domain?: string;\n  format_kind?: string;\n  params?: Readonly<Record<string, unknown>>;\n}\n\nconst compiledSnapshotCache = new WeakMap<object, readonly CompiledProjectionCatalogSnapshot[]>();\n\n/** Preserve protocol URL identity, including a distinct terminal slash. */\nfunction normalizedAgentUrl(value: string): string {\n  return canonicalizeAgentUrl(value) ?? value;\n}\n\nfunction legacyRefKey(ref: V1FormatId): string {\n  return JSON.stringify([\n    normalizedAgentUrl(ref.agent_url),\n    ref.id,\n    ref.width ?? null,\n    ref.height ?? null,\n    ref.duration_ms ?? null,\n  ]);\n}\n\nfunction normalizedPublisherDomain(value: string | undefined): string {\n  return (value ?? '').trim().toLowerCase().replace(/\\.$/, '');\n}\n\nfunction formatOptionRefKey(formatOptionId: string, publisherDomain?: string): string {\n  return JSON.stringify([normalizedPublisherDomain(publisherDomain), formatOptionId]);\n}\n\nfunction formatOptionRefFromValue(value: unknown): { format_option_id: string; publisher_domain?: string } | undefined {\n  if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined;\n  const record = value as Record<string, unknown>;\n  if (typeof record.format_option_id !== 'string' || record.format_option_id.length === 0) return undefined;\n  if (record.scope === 'publisher' || (record.scope === undefined && typeof record.publisher_domain === 'string')) {\n    if (typeof record.publisher_domain !== 'string' || record.publisher_domain.length === 0) return undefined;\n    return { format_option_id: record.format_option_id, publisher_domain: record.publisher_domain };\n  }\n  return { format_option_id: record.format_option_id };\n}\n\nfunction semanticFields(value: Record<string, unknown>): Pick<ContextFormatOptionRef, 'format_kind' | 'params'> {\n  return {\n    ...(typeof value.format_kind === 'string' ? { format_kind: value.format_kind } : {}),\n    ...(value.params !== null && typeof value.params === 'object' && !Array.isArray(value.params)\n      ? { params: value.params as Record<string, unknown> }\n      : {}),\n  };\n}\n\nfunction collectFormatOptionRefs(value: unknown, seen = new WeakSet<object>()): ContextFormatOptionRef[] {\n  if (value === null || typeof value !== 'object' || seen.has(value as object)) return [];\n  seen.add(value as object);\n  const record = value as Record<string, unknown>;\n  const refs: ContextFormatOptionRef[] = [];\n  const direct = formatOptionRefFromValue(record.format_option_ref);\n  if (direct) refs.push({ ...direct, ...semanticFields(record) });\n  for (const key of ['format_option_refs', 'format_options'] as const) {\n    if (!Array.isArray(record[key])) continue;\n    for (const item of record[key]) {\n      const ref = formatOptionRefFromValue(item);\n      const itemRecord = item !== null && typeof item === 'object' && !Array.isArray(item) ? item : record;\n      if (ref) refs.push({ ...ref, ...semanticFields(itemRecord as Record<string, unknown>) });\n    }\n  }\n  if (Array.isArray(record.selector_containers)) {\n    for (const container of record.selector_containers) refs.push(...collectFormatOptionRefs(container, seen));\n  }\n  return refs;\n}\n\nfunction resolutionContextFormatOptionRefs(context: CanonicalFormatLegacyResolutionContext): ContextFormatOptionRef[] {\n  if (context.source === 'product') {\n    const declaration = context.declaration;\n    if (typeof declaration.format_option_id !== 'string' || declaration.format_option_id.length === 0) return [];\n    return [\n      {\n        format_option_id: declaration.format_option_id,\n        ...(typeof declaration.publisher_domain === 'string' ? { publisher_domain: declaration.publisher_domain } : {}),\n        format_kind: declaration.format_kind,\n        params: declaration.params,\n      },\n    ];\n  }\n  if (context.source === 'creative') {\n    const creativeRefs = collectFormatOptionRefs(context.creative);\n    return creativeRefs.length > 0 ? creativeRefs : collectFormatOptionRefs(context.selector);\n  }\n  return collectFormatOptionRefs(context.selector);\n}\n\nfunction dataValuesEqual(left: unknown, right: unknown): boolean {\n  if (Object.is(left, right)) return true;\n  if (Array.isArray(left) || Array.isArray(right)) {\n    return (\n      Array.isArray(left) &&\n      Array.isArray(right) &&\n      left.length === right.length &&\n      left.every((item, index) => dataValuesEqual(item, right[index]))\n    );\n  }\n  if (left === null || right === null || typeof left !== 'object' || typeof right !== 'object') return false;\n  const leftRecord = left as Record<string, unknown>;\n  const rightRecord = right as Record<string, unknown>;\n  const leftKeys = Object.keys(leftRecord).sort();\n  const rightKeys = Object.keys(rightRecord).sort();\n  return (\n    leftKeys.length === rightKeys.length &&\n    leftKeys.every((key, index) => key === rightKeys[index] && dataValuesEqual(leftRecord[key], rightRecord[key]))\n  );\n}\n\nfunction sharedParamsAgree(\n  declarationParams: Readonly<Record<string, unknown>>,\n  contextParams: Readonly<Record<string, unknown>> | undefined\n): boolean {\n  if (!contextParams) return true;\n  return Object.keys(contextParams).every(\n    key => !(key in declarationParams) || dataValuesEqual(declarationParams[key], contextParams[key])\n  );\n}\n\nfunction routeMatchesContext(\n  route: CompiledReverseRoute,\n  ref: ContextFormatOptionRef,\n  context: CanonicalFormatLegacyResolutionContext\n): boolean {\n  if (ref.format_kind !== undefined && ref.format_kind !== route.declaration.format_kind) return false;\n  if (!sharedParamsAgree(route.declaration.params, ref.params)) return false;\n\n  const records =\n    context.source === 'creative'\n      ? [context.creative, context.selector]\n      : context.source === 'selector'\n        ? [context.selector]\n        : [];\n  return records.every(record => {\n    const fields = semanticFields(record as Record<string, unknown>);\n    return (\n      (fields.format_kind === undefined || fields.format_kind === route.declaration.format_kind) &&\n      sharedParamsAgree(route.declaration.params, fields.params)\n    );\n  });\n}\n\nfunction immutableClone<T>(value: T): T {\n  const clone = structuredClone(value);\n  const freeze = (candidate: unknown, seen = new WeakSet<object>()): void => {\n    if (candidate === null || typeof candidate !== 'object' || seen.has(candidate)) return;\n    seen.add(candidate);\n    for (const child of Object.values(candidate)) freeze(child, seen);\n    Object.freeze(candidate);\n  };\n  freeze(clone);\n  return clone;\n}\n\nfunction declarationWithoutLegacyIdentity(\n  declaration: V2ProductFormatDeclaration,\n  publisherDomain?: string\n): V2ProductFormatDeclaration {\n  const { v1_format_ref: _dropRefs, canonical_formats_only: _dropCanonicalOnly, ...canonical } = declaration;\n  void _dropRefs;\n  void _dropCanonicalOnly;\n  return {\n    ...canonical,\n    ...(canonical.publisher_domain === undefined && publisherDomain ? { publisher_domain: publisherDomain } : {}),\n  };\n}\n\nfunction compileProjectionCatalogSnapshots(\n  snapshots: readonly ProjectionCatalogSnapshot[]\n): readonly CompiledProjectionCatalogSnapshot[] {\n  const cached = compiledSnapshotCache.get(snapshots);\n  if (cached) return cached;\n\n  const compiled = snapshots.map(snapshot => {\n    const byLegacyRef = new Map<string, V2ProductFormatDeclaration[]>();\n    const byFormatOptionRef = new Map<string, CompiledReverseRoute[]>();\n    for (const sourceDeclaration of snapshot.formats) {\n      const declaration = immutableClone(sourceDeclaration);\n      if (\n        declaration.canonical_formats_only === true ||\n        !isCanonicalV1Translatable(declaration.format_kind) ||\n        !Array.isArray(declaration.v1_format_ref) ||\n        declaration.v1_format_ref.length === 0\n      ) {\n        continue;\n      }\n\n      const canonical = immutableClone(declarationWithoutLegacyIdentity(declaration, snapshot.publisher_domain));\n      const legacyRefs = immutableClone([\n        ...new Map(declaration.v1_format_ref.map(ref => [legacyRefKey(ref), { ...ref }])).values(),\n      ]);\n      // Repeating one alias on a declaration does not make it ambiguous. Two\n      // distinct declarations at the same precedence tier still do.\n      const declarationKeys = new Set(declaration.v1_format_ref.map(legacyRefKey));\n      for (const key of declarationKeys) {\n        const matches = byLegacyRef.get(key) ?? [];\n        matches.push(canonical);\n        byLegacyRef.set(key, matches);\n      }\n      if (\n        typeof canonical.format_option_id === 'string' &&\n        canonical.format_option_id.length > 0 &&\n        typeof canonical.publisher_domain === 'string' &&\n        canonical.publisher_domain.length > 0\n      ) {\n        const key = formatOptionRefKey(canonical.format_option_id, canonical.publisher_domain);\n        const matches = byFormatOptionRef.get(key) ?? [];\n        matches.push(Object.freeze({ declaration: canonical, legacyRefs }));\n        byFormatOptionRef.set(key, matches);\n      }\n    }\n    for (const matches of byLegacyRef.values()) Object.freeze(matches);\n    for (const matches of byFormatOptionRef.values()) Object.freeze(matches);\n    return Object.freeze({ byLegacyRef, byFormatOptionRef });\n  });\n\n  Object.freeze(compiled);\n  compiledSnapshotCache.set(snapshots, compiled);\n  return compiled;\n}\n\n/**\n * Convert exact, catalog-authored `v1_format_ref` aliases into the existing\n * converter seam. Canonical-only declarations never become legacy aliases,\n * and matching is always owner + id + dimensional discriminators—never ID\n * alone. Duplicate aliases at the same precedence tier fail closed.\n */\nexport function legacyFormatConverterFromCatalogSnapshots(\n  snapshots: readonly ProjectionCatalogSnapshot[] | undefined,\n  fallback?: LegacyFormatConverter\n): LegacyFormatConverter | undefined {\n  if (!snapshots || snapshots.length === 0) return fallback;\n  const compiled = compileProjectionCatalogSnapshots(snapshots);\n  return context => {\n    const key = legacyRefKey(context.formatId);\n    for (const snapshot of compiled) {\n      const matches = snapshot.byLegacyRef.get(key) ?? [];\n      if (matches.length > 1) {\n        throw new Error('projection catalog contains ambiguous legacy aliases');\n      }\n      if (matches.length === 1) {\n        return matches[0];\n      }\n    }\n    return fallback?.(context);\n  };\n}\n\n/**\n * Build the canonical → legacy half of an exact catalog-authored adapter.\n *\n * Only stable `format_option_id` references participate. Snapshot precedence\n * mirrors the forward projector, duplicate declarations at one tier fail\n * closed, and a multi-option selector is returned only when every option has\n * an exact mapping. This makes the resolver safe to use after canonical\n * objects have crossed a process or persistence boundary and lost the SDK's\n * private in-memory route metadata.\n */\nexport function canonicalFormatLegacyResolverFromCatalogSnapshots(\n  snapshots: readonly ProjectionCatalogSnapshot[] | undefined,\n  fallback?: CanonicalFormatLegacyResolver\n): CanonicalFormatLegacyResolver | undefined {\n  if (!snapshots || snapshots.length === 0) return fallback;\n  const compiled = compileProjectionCatalogSnapshots(snapshots);\n  return context => {\n    const refs = resolutionContextFormatOptionRefs(context);\n    if (refs.length === 0) return fallback?.(context);\n\n    const resolved: V1FormatId[] = [];\n    for (const ref of refs) {\n      const key = formatOptionRefKey(ref.format_option_id, ref.publisher_domain);\n      let matched: CompiledReverseRoute | undefined;\n      for (const snapshot of compiled) {\n        const matches = snapshot.byFormatOptionRef.get(key) ?? [];\n        if (matches.length > 1) {\n          throw new Error('projection catalog contains ambiguous canonical format option aliases');\n        }\n        if (matches.length === 1) {\n          matched = matches[0];\n          break;\n        }\n      }\n      if (!matched) return fallback?.(context);\n      if (!routeMatchesContext(matched, ref, context)) return fallback?.(context);\n      resolved.push(...matched.legacyRefs.map(item => ({ ...item })));\n    }\n\n    return [...new Map(resolved.map(ref => [legacyRefKey(ref), ref])).values()];\n  };\n}\n\n/** Client configuration generated from one bidirectional, owner-scoped catalog. */\nexport interface ProjectionCatalogAdapters {\n  projectionCatalogs: readonly ProjectionCatalogSnapshot[];\n  canonicalFormatLegacyResolver: CanonicalFormatLegacyResolver;\n}\n\nfunction assertBidirectionalProjectionCatalogs(snapshots: readonly ProjectionCatalogSnapshot[]): void {\n  const routeByCanonicalOption = new Map<string, string>();\n  const canonicalOptionByLegacyRoute = new Map<string, string>();\n  for (const snapshot of snapshots) {\n    const declarationsAtThisTier = new Set<string>();\n    for (const declaration of snapshot.formats) {\n      if (\n        declaration.canonical_formats_only === true ||\n        !Array.isArray(declaration.v1_format_ref) ||\n        declaration.v1_format_ref.length === 0\n      ) {\n        continue;\n      }\n      if (!isCanonicalV1Translatable(declaration.format_kind)) {\n        throw new Error('bidirectional projection adapters cannot downgrade a canonical-only format kind');\n      }\n      const canonical = declarationWithoutLegacyIdentity(declaration, snapshot.publisher_domain);\n      if (typeof canonical.format_option_id !== 'string' || canonical.format_option_id.length === 0) {\n        throw new Error('bidirectional projection adapters require a stable format_option_id');\n      }\n      if (typeof canonical.publisher_domain !== 'string' || canonical.publisher_domain.length === 0) {\n        throw new Error('bidirectional projection adapters require publisher-scoped format options');\n      }\n      const uniqueLegacyKeys = new Set(declaration.v1_format_ref.map(legacyRefKey));\n      if (uniqueLegacyKeys.size !== 1) {\n        throw new Error(\n          'bidirectional projection adapters require exactly one legacy route per canonical format option'\n        );\n      }\n      const canonicalKey = formatOptionRefKey(canonical.format_option_id, canonical.publisher_domain);\n      const legacyKey = [...uniqueLegacyKeys][0]!;\n      const declarationKey = JSON.stringify([canonicalKey, legacyKey]);\n      if (declarationsAtThisTier.has(declarationKey)) {\n        throw new Error('bidirectional projection adapters contain duplicate declarations at one precedence tier');\n      }\n      declarationsAtThisTier.add(declarationKey);\n      const existing = routeByCanonicalOption.get(canonicalKey);\n      if (existing !== undefined && existing !== legacyKey) {\n        throw new Error('bidirectional projection adapters contain conflicting reverse routes');\n      }\n      const existingCanonical = canonicalOptionByLegacyRoute.get(legacyKey);\n      if (existingCanonical !== undefined && existingCanonical !== canonicalKey) {\n        throw new Error('bidirectional projection adapters contain conflicting forward routes');\n      }\n      routeByCanonicalOption.set(canonicalKey, legacyKey);\n      canonicalOptionByLegacyRoute.set(legacyKey, canonicalKey);\n    }\n  }\n}\n\n/**\n * Configure both discovery upgrade and legacy delivery downgrade from one\n * immutable catalog. Spread the result into `AgentClient` configuration.\n */\nexport function projectionAdaptersFromCatalogSnapshots(\n  snapshots: readonly ProjectionCatalogSnapshot[],\n  fallbackCanonicalResolver?: CanonicalFormatLegacyResolver\n): ProjectionCatalogAdapters {\n  assertBidirectionalProjectionCatalogs(snapshots);\n  const canonicalFormatLegacyResolver = canonicalFormatLegacyResolverFromCatalogSnapshots(\n    snapshots,\n    fallbackCanonicalResolver\n  );\n  if (!canonicalFormatLegacyResolver) {\n    throw new Error('projection adapters require at least one catalog snapshot or a fallback resolver');\n  }\n  return { projectionCatalogs: snapshots, canonicalFormatLegacyResolver };\n}\n"],"mappings":"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","names":[]}