@adcp/sdk 15.8.1 → 16.0.0-beta.1

package/dist/lib/types/tools.generated.d.ts

@@ -13253,12 +13253,12 @@ export type ReportingPackageID = string;
 /**
  * Structured reporting condition that explains delayed or action_required health without exposing credentials, provider response bodies, or internal stack traces.
  */
-export type ReportingStatusIssue = {} & {
+export type ReportingStatusIssue = {} & {} & {
     /**
      * Seller-issued stable identifier for this logical issue: re-emissions and later polls of the same unresolved condition reuse it, and resolution retires it, so consumers can project AdCP reporting issues into durable work items. A recurrence after resolution receives a new id.
      */
     issue_id: string;
-    code: 'REPORT_OVERDUE' | 'PRODUCTION_FAILED' | 'DELIVERY_FAILED' | 'ACCESS_REQUIRED' | 'CONFIGURATION_REQUIRED' | 'REPORTING_COVERAGE_INCOMPLETE' | 'RESOURCE_EXPIRED' | 'READER_INCOMPATIBLE' | 'HISTORY_UNAVAILABLE' | 'RECEIPT_REQUIRED' | 'RECEIPT_REJECTED' | 'ADJUSTMENT_RECEIPT_REQUIRED' | 'ADJUSTMENT_RECEIPT_REJECTED' | 'CONSUMER_STATUS_MISMATCH';
+    code: 'REPORT_OVERDUE' | 'PRODUCTION_FAILED' | 'DELIVERY_FAILED' | 'ACCESS_REQUIRED' | 'CONFIGURATION_REQUIRED' | 'REPORTING_COVERAGE_INCOMPLETE' | 'RESOURCE_EXPIRED' | 'READER_INCOMPATIBLE' | 'HISTORY_UNAVAILABLE' | 'REVISION_UNREADABLE' | 'RECEIPT_REQUIRED' | 'RECEIPT_REJECTED' | 'ADJUSTMENT_RECEIPT_REQUIRED' | 'ADJUSTMENT_RECEIPT_REJECTED' | 'CONSUMER_STATUS_MISMATCH';
     severity: ReportingStatusSeverity;
     /**
      * When the seller first observed this logical condition, carried unchanged across every re-emission until the issue is retired. It anchors the escalation clock advertised as consumer_mismatch_escalation_seconds and lets a consumer age an issue without keeping its own first-seen table. Required when code is CONSUMER_STATUS_MISMATCH.
@@ -13279,6 +13279,10 @@ export type ReportingStatusIssue = {} & {
      */
     message?: string;
     reporting_obligation_id?: string;
+    /**
+     * Published revision this issue concerns. Required when code is REVISION_UNREADABLE.
+     */
+    reporting_revision_id?: string;
     /**
      * Current authenticated consumer status statement that caused this mismatch.
      */
@@ -13302,7 +13306,7 @@ export type ReportingStatusIssue = {} & {
      * Seller-issued stable identifier for this logical issue: re-emissions and later polls of the same unresolved condition reuse it, and resolution retires it, so consumers can project AdCP reporting issues into durable work items. A recurrence after resolution receives a new id.
      */
     issue_id: string;
-    code: 'REPORT_OVERDUE' | 'PRODUCTION_FAILED' | 'DELIVERY_FAILED' | 'ACCESS_REQUIRED' | 'CONFIGURATION_REQUIRED' | 'REPORTING_COVERAGE_INCOMPLETE' | 'RESOURCE_EXPIRED' | 'READER_INCOMPATIBLE' | 'HISTORY_UNAVAILABLE' | 'RECEIPT_REQUIRED' | 'RECEIPT_REJECTED' | 'ADJUSTMENT_RECEIPT_REQUIRED' | 'ADJUSTMENT_RECEIPT_REJECTED' | 'CONSUMER_STATUS_MISMATCH';
+    code: 'REPORT_OVERDUE' | 'PRODUCTION_FAILED' | 'DELIVERY_FAILED' | 'ACCESS_REQUIRED' | 'CONFIGURATION_REQUIRED' | 'REPORTING_COVERAGE_INCOMPLETE' | 'RESOURCE_EXPIRED' | 'READER_INCOMPATIBLE' | 'HISTORY_UNAVAILABLE' | 'REVISION_UNREADABLE' | 'RECEIPT_REQUIRED' | 'RECEIPT_REJECTED' | 'ADJUSTMENT_RECEIPT_REQUIRED' | 'ADJUSTMENT_RECEIPT_REJECTED' | 'CONSUMER_STATUS_MISMATCH';
     severity: ReportingStatusSeverity;
     /**
      * When the seller first observed this logical condition, carried unchanged across every re-emission until the issue is retired. It anchors the escalation clock advertised as consumer_mismatch_escalation_seconds and lets a consumer age an issue without keeping its own first-seen table. Required when code is CONSUMER_STATUS_MISMATCH.
@@ -13323,6 +13327,10 @@ export type ReportingStatusIssue = {} & {
      */
     message?: string;
     reporting_obligation_id?: string;
+    /**
+     * Published revision this issue concerns. Required when code is REVISION_UNREADABLE.
+     */
+    reporting_revision_id?: string;
     /**
      * Current authenticated consumer status statement that caused this mismatch.
      */
@@ -32821,16 +32829,12 @@ export interface FailedPrincipalRead {
  */
 export interface ListAccountChangesRequest {
     /**
-     * Release-precision AdCP version. Flattened here so emitted MCP tool input schemas remain plain root objects for clients that reject top-level combinators.
-     * @pattern ^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[a-zA-Z0-9](?:[a-zA-Z0-9.-]*[a-zA-Z0-9])?)?$
+     * Release-precision AdCP version (VERSION.RELEASE, e.g. "3.0", "3.1", "3.1-beta"). On a request: the buyer's release pin — the seller validates against its supported_versions and returns VERSION_UNSUPPORTED on cross-major mismatch, or downshifts to the highest supported release within the same major. On a response: the release the seller actually served — clients SHOULD validate the response against that release's schema, not against their pin. Patches are not negotiated; surface them as build_version on capabilities for operational visibility. When omitted, falls back to adcp_major_version (deprecated) or server default. Buyers SHOULD emit both adcp_version and adcp_major_version through 3.x to remain compatible with sellers that only read the legacy field. NORMALIZATION: SDKs that read full-semver values from bundle metadata (e.g. ComplianceIndex.published_version = "3.1.0-beta.1") MUST normalize to release-precision ("3.1-beta.1") before emitting on the wire — meta-field values are NOT valid wire values.
      */
     adcp_version?: string;
     /**
      * @deprecated
-     * Deprecated major-only version pin retained through 3.x.
-     * @minimum 1
-     * @maximum 99
-     * @format int
+     * DEPRECATED in favor of adcp_version (release-precision string). Servers MUST continue to honor this field through 3.x. Removed in 4.0. Original semantics: the AdCP major version the buyer's payloads conform to. Sellers validate against their supported major_versions and return VERSION_UNSUPPORTED if unsupported. When omitted, the seller assumes its highest supported version.
      */
     adcp_major_version?: number;
     account: AccountReference;

package/dist/lib/types/update-media-buy.d.ts

@@ -351,7 +351,7 @@ export type ActivationKey = {
 };
 
 /**
- * Release-precision AdCP protocol version negotiation fields. Composed via `allOf` into every AdCP request and response schema so the version semantics live in exactly one place. Distinct from `core/protocol-envelope.json`, which wraps responses at the transport layer (context_id / task_id / status / payload). This envelope is part of the payload itself.
+ * Release-precision AdCP protocol version negotiation fields. Composed via `allOf` into AdCP request schemas and shared response components so the version semantics live in one place. Strict (`additionalProperties: false`) request schemas also redeclare these two fields in their own `properties` via `$ref`, because draft-07 does not evaluate properties across `allOf`. The Trusted Match match requests are the exception: they inline both fields for their strict privacy boundary. Distinct from `core/protocol-envelope.json`, which wraps responses at the transport layer (context_id / task_id / status / payload). This envelope is part of the payload itself.
  */
 export interface AdCPVersionEnvelope {
     /**

package/dist/lib/types/verify-brand-claim.d.ts

@@ -99,7 +99,7 @@ export interface VerifyBrandClaimError {
 }
 
 /**
- * Release-precision AdCP protocol version negotiation fields. Composed via `allOf` into every AdCP request and response schema so the version semantics live in exactly one place. Distinct from `core/protocol-envelope.json`, which wraps responses at the transport layer (context_id / task_id / status / payload). This envelope is part of the payload itself.
+ * Release-precision AdCP protocol version negotiation fields. Composed via `allOf` into AdCP request schemas and shared response components so the version semantics live in one place. Strict (`additionalProperties: false`) request schemas also redeclare these two fields in their own `properties` via `$ref`, because draft-07 does not evaluate properties across `allOf`. The Trusted Match match requests are the exception: they inline both fields for their strict privacy boundary. Distinct from `core/protocol-envelope.json`, which wraps responses at the transport layer (context_id / task_id / status / payload). This envelope is part of the payload itself.
  */
 export interface AdCPVersionEnvelope {
     /**

package/dist/lib/utils/capabilities.d.mts

@@ -53,6 +53,9 @@ export interface MediaBuyFeatures {
  * Account management capabilities declared by the seller
  */
 export interface AccountCapabilities {
+    agentOnboarding?: import('../identity-3.3/types.mjs').AgentOnboarding;
+    /** Seller-issued IDs are stable and accepted wherever an account reference is used. */
+    stableAccountId?: boolean;
     /** Optional account change feed; absence does not imply support. */
     changeFeed?: AccountChangeFeedCapabilities;
     /**

package/dist/lib/utils/capabilities.d.ts

@@ -53,6 +53,9 @@ export interface MediaBuyFeatures {
  * Account management capabilities declared by the seller
  */
 export interface AccountCapabilities {
+    agentOnboarding?: import('../identity-3.3/types').AgentOnboarding;
+    /** Seller-issued IDs are stable and accepted wherever an account reference is used. */
+    stableAccountId?: boolean;
     /** Optional account change feed; absence does not imply support. */
     changeFeed?: AccountChangeFeedCapabilities;
     /**

package/dist/lib/utils/capabilities.js

@@ -309,10 +309,18 @@ function parseCapabilitiesResponse(response) {
   let account;
   if (response.account) {
     account = {
+      ...typeof response.account.stable_account_id === "boolean" && {
+        stableAccountId: response.account.stable_account_id
+      },
       requireOperatorAuth: response.account.require_operator_auth ?? false,
       authorizationEndpoint: response.account.authorization_endpoint,
       supportedBilling: response.account.supported_billing ?? [],
       defaultBilling: response.account.default_billing,
+      ...response.account.agent_onboarding && {
+        agentOnboarding: structuredClone(
+          response.account.agent_onboarding
+        )
+      },
       supportedAccountCurrencyModes: response.account.supported_account_currency_modes,
       ...response.account.timezone && {
         timezone: {

package/dist/lib/utils/capabilities.mjs

@@ -253,10 +253,18 @@ function parseCapabilitiesResponse(response) {
   let account;
   if (response.account) {
     account = {
+      ...typeof response.account.stable_account_id === "boolean" && {
+        stableAccountId: response.account.stable_account_id
+      },
       requireOperatorAuth: response.account.require_operator_auth ?? false,
       authorizationEndpoint: response.account.authorization_endpoint,
       supportedBilling: response.account.supported_billing ?? [],
       defaultBilling: response.account.default_billing,
+      ...response.account.agent_onboarding && {
+        agentOnboarding: structuredClone(
+          response.account.agent_onboarding
+        )
+      },
       supportedAccountCurrencyModes: response.account.supported_account_currency_modes,
       ...response.account.timezone && {
         timezone: {

package/dist/lib/utils/reporting-status-response.js

@@ -52,6 +52,15 @@ function isReportingStatusIssue(value) {
     if (!isOffsetDateTime(value.opened_at)) return false;
     if (!isNonEmptyString(value.reporting_status_id)) return false;
   }
+  if (value.code === "REVISION_UNREADABLE") {
+    if (value.responsible_party !== "seller") return false;
+    const action = value.severity === "delayed" ? "wait_for_retry" : "contact_seller";
+    if (value.recommended_action !== action) return false;
+    for (const field of ["reporting_obligation_id", "reporting_revision_id"]) {
+      const id = value[field];
+      if (!isNonEmptyString(id) || !/^[A-Za-z0-9_.:-]{1,255}$/.test(id)) return false;
+    }
+  }
   if (value.issue_state !== void 0 && !["open", "acknowledged"].includes(String(value.issue_state))) return false;
   if (value.external_ref !== void 0 && (!isNonEmptyString(value.external_ref) || value.external_ref.length > 128 || !/^[A-Za-z0-9_.:-]+$/.test(value.external_ref))) {
     return false;
@@ -66,6 +75,7 @@ function isReportingStatusIssue(value) {
     "RESOURCE_EXPIRED",
     "READER_INCOMPATIBLE",
     "HISTORY_UNAVAILABLE",
+    "REVISION_UNREADABLE",
     "RECEIPT_REQUIRED",
     "RECEIPT_REJECTED",
     "ADJUSTMENT_RECEIPT_REQUIRED",

package/dist/lib/utils/reporting-status-response.mjs

@@ -34,6 +34,15 @@ function isReportingStatusIssue(value) {
     if (!isOffsetDateTime(value.opened_at)) return false;
     if (!isNonEmptyString(value.reporting_status_id)) return false;
   }
+  if (value.code === "REVISION_UNREADABLE") {
+    if (value.responsible_party !== "seller") return false;
+    const action = value.severity === "delayed" ? "wait_for_retry" : "contact_seller";
+    if (value.recommended_action !== action) return false;
+    for (const field of ["reporting_obligation_id", "reporting_revision_id"]) {
+      const id = value[field];
+      if (!isNonEmptyString(id) || !/^[A-Za-z0-9_.:-]{1,255}$/.test(id)) return false;
+    }
+  }
   if (value.issue_state !== void 0 && !["open", "acknowledged"].includes(String(value.issue_state))) return false;
   if (value.external_ref !== void 0 && (!isNonEmptyString(value.external_ref) || value.external_ref.length > 128 || !/^[A-Za-z0-9_.:-]+$/.test(value.external_ref))) {
     return false;
@@ -48,6 +57,7 @@ function isReportingStatusIssue(value) {
     "RESOURCE_EXPIRED",
     "READER_INCOMPATIBLE",
     "HISTORY_UNAVAILABLE",
+    "REVISION_UNREADABLE",
     "RECEIPT_REQUIRED",
     "RECEIPT_REJECTED",
     "ADJUSTMENT_RECEIPT_REQUIRED",

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

@@ -3,6 +3,7 @@ import type { LegacyFormatConverter } from './v1-to-v2.mjs';
 import type { CanonicalFormatLegacyResolver } from './v2-to-v1.mjs';
 import type { CanonicalFormatKind, ProjectionDiagnostic, V1FormatId } from './types.mjs';
 import type { CanonicalFormatDeclaration } from './legacy-metadata.mjs';
+import type { UndeclaredFormatOptionSelector } from './legacy-routes.mjs';
 type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, Extract<keyof T, K>> : never;
 /**
  * Primary SDK creative shape. Spell out the named fields rather than using
@@ -93,7 +94,9 @@ type ClientReportingWebhookInput = (ReportingWebhookPreferences & {
  * request remains a strict {@link CanonicalCreateMediaBuyRequest}.
  */
 export type CanonicalCreateMediaBuyInput = Omit<CanonicalCreateMediaBuyRequest, 'reporting_webhook'> & {
-    reporting_webhook?: ClientReportingWebhookInput;
+    reporting_webhook?: ClientReportingWebhookInput & {
+        signing_profile?: 'adcp/webhook-signing/v1' | 'web-bot-auth';
+    };
 };
 export type CanonicalUpdateMediaBuyRequest = Omit<CanonicalCreativeResponse<UpdateMediaBuyRequest>, 'packages' | 'new_packages'> & {
     packages?: CanonicalPackageUpdate[];
@@ -258,13 +261,7 @@ export declare function projectMediaBuyCreativesForDelivery<T>(request: T, wireM
 export declare function projectSyncCreativesForDelivery<T>(request: T, selectorContainers: ReadonlyArray<CreativeFormatSelectorContainer>, wireMode: 'canonical', legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver): ProjectedSyncCreativeRequest<T, 'canonical'>;
 export declare function projectSyncCreativesForDelivery<T>(request: T, selectorContainers: ReadonlyArray<CreativeFormatSelectorContainer>, wireMode: 'legacy' | 'unknown', legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver): ProjectedSyncCreativeRequest<T, 'legacy'>;
 export declare function projectSyncCreativesForDelivery<T>(request: T, selectorContainers: ReadonlyArray<CreativeFormatSelectorContainer>, wireMode: CreativeFormatWireMode, legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver): ProjectedSyncCreativeRequest<T, 'canonical'> | ProjectedSyncCreativeRequest<T, 'legacy'>;
-/** The direct canonical selector for a format option the seller did not declare. */
-export interface UndeclaredFormatOptionSelector {
-    format_kind: string;
-    params?: unknown;
-    /** Custom/schema-backed formats cannot retain identity in a direct selector. */
-    unrepresentable?: true;
-}
+export type { UndeclaredFormatOptionSelector } from './legacy-routes.mjs';
 /**
  * Looks up a format option the SDK derived from a seller's legacy `format_ids`.
  * Returns undefined for options the seller declared in its own `format_options[]`.
@@ -281,4 +278,3 @@ export type UndeclaredFormatOptionLookup = (ref: FormatOptionReference, productI
  */
 export declare function projectUndeclaredFormatOptionSelectors<T>(request: T, operation: 'create_media_buy' | 'update_media_buy' | 'sync_creatives', lookup: UndeclaredFormatOptionLookup): T;
 export declare function resolveCreativeFormatWireMode(capabilities: unknown, negotiatedVersion?: string): CreativeFormatWireMode;
-export {};

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

@@ -3,6 +3,7 @@ import type { LegacyFormatConverter } from './v1-to-v2';
 import type { CanonicalFormatLegacyResolver } from './v2-to-v1';
 import type { CanonicalFormatKind, ProjectionDiagnostic, V1FormatId } from './types';
 import type { CanonicalFormatDeclaration } from './legacy-metadata';
+import type { UndeclaredFormatOptionSelector } from './legacy-routes';
 type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, Extract<keyof T, K>> : never;
 /**
  * Primary SDK creative shape. Spell out the named fields rather than using
@@ -93,7 +94,9 @@ type ClientReportingWebhookInput = (ReportingWebhookPreferences & {
  * request remains a strict {@link CanonicalCreateMediaBuyRequest}.
  */
 export type CanonicalCreateMediaBuyInput = Omit<CanonicalCreateMediaBuyRequest, 'reporting_webhook'> & {
-    reporting_webhook?: ClientReportingWebhookInput;
+    reporting_webhook?: ClientReportingWebhookInput & {
+        signing_profile?: 'adcp/webhook-signing/v1' | 'web-bot-auth';
+    };
 };
 export type CanonicalUpdateMediaBuyRequest = Omit<CanonicalCreativeResponse<UpdateMediaBuyRequest>, 'packages' | 'new_packages'> & {
     packages?: CanonicalPackageUpdate[];
@@ -258,13 +261,7 @@ export declare function projectMediaBuyCreativesForDelivery<T>(request: T, wireM
 export declare function projectSyncCreativesForDelivery<T>(request: T, selectorContainers: ReadonlyArray<CreativeFormatSelectorContainer>, wireMode: 'canonical', legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver): ProjectedSyncCreativeRequest<T, 'canonical'>;
 export declare function projectSyncCreativesForDelivery<T>(request: T, selectorContainers: ReadonlyArray<CreativeFormatSelectorContainer>, wireMode: 'legacy' | 'unknown', legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver): ProjectedSyncCreativeRequest<T, 'legacy'>;
 export declare function projectSyncCreativesForDelivery<T>(request: T, selectorContainers: ReadonlyArray<CreativeFormatSelectorContainer>, wireMode: CreativeFormatWireMode, legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver): ProjectedSyncCreativeRequest<T, 'canonical'> | ProjectedSyncCreativeRequest<T, 'legacy'>;
-/** The direct canonical selector for a format option the seller did not declare. */
-export interface UndeclaredFormatOptionSelector {
-    format_kind: string;
-    params?: unknown;
-    /** Custom/schema-backed formats cannot retain identity in a direct selector. */
-    unrepresentable?: true;
-}
+export type { UndeclaredFormatOptionSelector } from './legacy-routes';
 /**
  * Looks up a format option the SDK derived from a seller's legacy `format_ids`.
  * Returns undefined for options the seller declared in its own `format_options[]`.
@@ -281,4 +278,3 @@ export type UndeclaredFormatOptionLookup = (ref: FormatOptionReference, productI
  */
 export declare function projectUndeclaredFormatOptionSelectors<T>(request: T, operation: 'create_media_buy' | 'update_media_buy' | 'sync_creatives', lookup: UndeclaredFormatOptionLookup): T;
 export declare function resolveCreativeFormatWireMode(capabilities: unknown, negotiatedVersion?: string): CreativeFormatWireMode;
-export {};

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

@@ -487,20 +487,32 @@ function creativeFormatParameterConstraints(creative) {
   if (width === void 0 && height === void 0 && durationMs === void 0) return void 0;
   return { width, height, durationMs };
 }
+function legacyRefParameterConstraints(ref) {
+  const params = typeof ref.width !== "number" || typeof ref.height !== "number" ? record((0, import_v1_to_v2.canonicalDeclarationFromBareId)(ref.id, { agentUrl: ref.agent_url })?.params) : void 0;
+  return {
+    width: typeof ref.width === "number" ? ref.width : typeof params?.width === "number" ? params.width : void 0,
+    height: typeof ref.height === "number" ? ref.height : typeof params?.height === "number" ? params.height : void 0,
+    durationMs: ref.duration_ms
+  };
+}
 function refContradictsConstraints(ref, constraints) {
-  if (constraints.width !== void 0 && typeof ref.width === "number" && ref.width !== constraints.width) return true;
-  if (constraints.height !== void 0 && typeof ref.height === "number" && ref.height !== constraints.height) {
+  const refConstraints = legacyRefParameterConstraints(ref);
+  if (constraints.width !== void 0 && refConstraints.width !== void 0 && refConstraints.width !== constraints.width) {
+    return true;
+  }
+  if (constraints.height !== void 0 && refConstraints.height !== void 0 && refConstraints.height !== constraints.height) {
     return true;
   }
-  if (constraints.durationMs !== void 0 && typeof ref.duration_ms === "number" && ref.duration_ms !== constraints.durationMs) {
+  if (constraints.durationMs !== void 0 && typeof refConstraints.durationMs === "number" && refConstraints.durationMs !== constraints.durationMs) {
     return true;
   }
   return false;
 }
 function refPinsConstraints(ref, constraints) {
-  if (constraints.width !== void 0 && typeof ref.width !== "number") return false;
-  if (constraints.height !== void 0 && typeof ref.height !== "number") return false;
-  if (constraints.durationMs !== void 0 && typeof ref.duration_ms !== "number") return false;
+  const refConstraints = legacyRefParameterConstraints(ref);
+  if (constraints.width !== void 0 && refConstraints.width === void 0) return false;
+  if (constraints.height !== void 0 && refConstraints.height === void 0) return false;
+  if (constraints.durationMs !== void 0 && typeof refConstraints.durationMs !== "number") return false;
   return true;
 }
 function legacyIdPinsDimensions(ref) {
@@ -510,15 +522,19 @@ function legacyIdPinsDimensions(ref) {
   return typeof params.width === "number" || typeof params.height === "number" || typeof params.duration_ms_exact === "number" || Array.isArray(params.sizes);
 }
 function refConstraintKey(ref) {
-  return [agentIdentity(ref.agent_url), ref.width ?? "", ref.height ?? "", ref.duration_ms ?? ""].join("|");
+  const constraints = legacyRefParameterConstraints(ref);
+  return [
+    agentIdentity(ref.agent_url),
+    constraints.width ?? "",
+    constraints.height ?? "",
+    constraints.durationMs ?? ""
+  ].join("|");
 }
 function preferMostConstrainedLegacyCandidates(candidates, creative) {
-  if (candidates.length <= 1) return candidates;
   let remaining = candidates;
   const constraints = creativeFormatParameterConstraints(creative);
   if (constraints) {
-    const compatible = remaining.filter((candidate) => !refContradictsConstraints(candidate.ref, constraints));
-    if (compatible.length > 0) remaining = compatible;
+    remaining = remaining.filter((candidate) => !refContradictsConstraints(candidate.ref, constraints));
     const pinned = remaining.filter((candidate) => refPinsConstraints(candidate.ref, constraints));
     if (pinned.length > 0) remaining = pinned;
   }

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

@@ -466,20 +466,32 @@ function creativeFormatParameterConstraints(creative) {
   if (width === void 0 && height === void 0 && durationMs === void 0) return void 0;
   return { width, height, durationMs };
 }
+function legacyRefParameterConstraints(ref) {
+  const params = typeof ref.width !== "number" || typeof ref.height !== "number" ? record(canonicalDeclarationFromBareId(ref.id, { agentUrl: ref.agent_url })?.params) : void 0;
+  return {
+    width: typeof ref.width === "number" ? ref.width : typeof params?.width === "number" ? params.width : void 0,
+    height: typeof ref.height === "number" ? ref.height : typeof params?.height === "number" ? params.height : void 0,
+    durationMs: ref.duration_ms
+  };
+}
 function refContradictsConstraints(ref, constraints) {
-  if (constraints.width !== void 0 && typeof ref.width === "number" && ref.width !== constraints.width) return true;
-  if (constraints.height !== void 0 && typeof ref.height === "number" && ref.height !== constraints.height) {
+  const refConstraints = legacyRefParameterConstraints(ref);
+  if (constraints.width !== void 0 && refConstraints.width !== void 0 && refConstraints.width !== constraints.width) {
+    return true;
+  }
+  if (constraints.height !== void 0 && refConstraints.height !== void 0 && refConstraints.height !== constraints.height) {
     return true;
   }
-  if (constraints.durationMs !== void 0 && typeof ref.duration_ms === "number" && ref.duration_ms !== constraints.durationMs) {
+  if (constraints.durationMs !== void 0 && typeof refConstraints.durationMs === "number" && refConstraints.durationMs !== constraints.durationMs) {
     return true;
   }
   return false;
 }
 function refPinsConstraints(ref, constraints) {
-  if (constraints.width !== void 0 && typeof ref.width !== "number") return false;
-  if (constraints.height !== void 0 && typeof ref.height !== "number") return false;
-  if (constraints.durationMs !== void 0 && typeof ref.duration_ms !== "number") return false;
+  const refConstraints = legacyRefParameterConstraints(ref);
+  if (constraints.width !== void 0 && refConstraints.width === void 0) return false;
+  if (constraints.height !== void 0 && refConstraints.height === void 0) return false;
+  if (constraints.durationMs !== void 0 && typeof refConstraints.durationMs !== "number") return false;
   return true;
 }
 function legacyIdPinsDimensions(ref) {
@@ -489,15 +501,19 @@ function legacyIdPinsDimensions(ref) {
   return typeof params.width === "number" || typeof params.height === "number" || typeof params.duration_ms_exact === "number" || Array.isArray(params.sizes);
 }
 function refConstraintKey(ref) {
-  return [agentIdentity(ref.agent_url), ref.width ?? "", ref.height ?? "", ref.duration_ms ?? ""].join("|");
+  const constraints = legacyRefParameterConstraints(ref);
+  return [
+    agentIdentity(ref.agent_url),
+    constraints.width ?? "",
+    constraints.height ?? "",
+    constraints.durationMs ?? ""
+  ].join("|");
 }
 function preferMostConstrainedLegacyCandidates(candidates, creative) {
-  if (candidates.length <= 1) return candidates;
   let remaining = candidates;
   const constraints = creativeFormatParameterConstraints(creative);
   if (constraints) {
-    const compatible = remaining.filter((candidate) => !refContradictsConstraints(candidate.ref, constraints));
-    if (compatible.length > 0) remaining = compatible;
+    remaining = remaining.filter((candidate) => !refContradictsConstraints(candidate.ref, constraints));
     const pinned = remaining.filter((candidate) => refPinsConstraints(candidate.ref, constraints));
     if (pinned.length > 0) remaining = pinned;
   }

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

@@ -43,7 +43,7 @@ export { projectV1ProductToV2, canonicalDeclarationFromBareId, resolveCanonicalF
 export type { V1ToV2Result, V1ToV2ProjectionOptions, BareFormatIdResolveOptions, LegacyFormatConversionContext, LegacyFormatConverter, LegacyFormatResolutionContext, LegacyFormatResolver, } from './v1-to-v2.mjs';
 export { projectV2ProductToV1 } from './v2-to-v1.mjs';
 export type { V2ToV1Result, V2ToV1ProjectionOptions, CanonicalFormatLegacyResolver, CanonicalFormatLegacyResolutionContext, CanonicalProductFormatLegacyResolutionContext, CanonicalCreativeFormatLegacyResolutionContext, CanonicalSelectorFormatLegacyResolutionContext, } from './v2-to-v1.mjs';
-export { canonicalFormatLegacyResolverFromRoutes, legacyRoutesForProduct, type CanonicalFormatLegacyRoute, } from './legacy-routes.mjs';
+export { canonicalFormatLegacyResolverFromRoutes, legacyRoutesForProduct, type CanonicalFormatLegacyRoute, type LegacyRoutesForProductOptions, } from './legacy-routes.mjs';
 export { augmentProductWithFormatOptions, withFormatOptions, toCanonicalFormatOptionsWithRoutes, toAdditiveCanonicalProduct, withAdditiveCanonicalFormatOptions, toCanonicalOnlyProduct, toCanonicalOnlyResponse, type V2AugmentedProduct, type AdditiveCanonicalProduct, type CanonicalOnlyProduct, } from './augment-response.mjs';
 export { CanonicalFormat, audioDaastFormatDeclaration, audioHostedFormatDeclaration, audioVastFormatDeclaration, agentPlacementFormatDeclaration, canonicalFormatDeclaration, customFormatDeclaration, displayTagFormatDeclaration, legacyFormatRef, legacyFormatRefs, html5FormatDeclaration, imageCarouselFormatDeclaration, imageFormatDeclaration, nativeInFeedFormatDeclaration, productCard, productCardDetailed, responsiveCreativeFormatDeclaration, sellerRenderedStatefulDisplayFormatDeclaration, sponsoredPlacementFormatDeclaration, coordinatedPlacementsFormatDeclaration, videoHostedFormatDeclaration, videoVastFormatDeclaration, type CanonicalFormatDeclaration, type CanonicalFormatDeclarationFields, type CanonicalFormatKind, type CanonicalFormatParams, type FormatReferenceInput, type ProductCardDetailedFields, type ProductCardFields, } from './builders.mjs';
 export { packageRefsForFormatOptions, packageRefsForCapabilities, legacyFormatIdsFromOptions, tryLegacyFormatIdsFromOptions, legacyFormatIdsForFormatOption, legacyFormatIdsForCapability, lintPackageFormatSelectorDimensions, FormatOptionRefsLookupError, CapabilityIdsLookupError, type PackageFormatRefs, type PackageCapabilityRefs, type FormatOptionRef, type FormatOptionSelector, type FormatOptionRefsLookupErrorCode, type CapabilityIdsLookupErrorCode, type PackageFormatSelectorInput, type PackageFormatSelectorDimensionOptions, type FixedSizeDimensions, type PackageFormatSelectorDimensionDiagnosticCode, type PackageFormatSelectorDimensionDiagnostic, } from './write-side.mjs';

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

@@ -43,7 +43,7 @@ export { projectV1ProductToV2, canonicalDeclarationFromBareId, resolveCanonicalF
 export type { V1ToV2Result, V1ToV2ProjectionOptions, BareFormatIdResolveOptions, LegacyFormatConversionContext, LegacyFormatConverter, LegacyFormatResolutionContext, LegacyFormatResolver, } from './v1-to-v2';
 export { projectV2ProductToV1 } from './v2-to-v1';
 export type { V2ToV1Result, V2ToV1ProjectionOptions, CanonicalFormatLegacyResolver, CanonicalFormatLegacyResolutionContext, CanonicalProductFormatLegacyResolutionContext, CanonicalCreativeFormatLegacyResolutionContext, CanonicalSelectorFormatLegacyResolutionContext, } from './v2-to-v1';
-export { canonicalFormatLegacyResolverFromRoutes, legacyRoutesForProduct, type CanonicalFormatLegacyRoute, } from './legacy-routes';
+export { canonicalFormatLegacyResolverFromRoutes, legacyRoutesForProduct, type CanonicalFormatLegacyRoute, type LegacyRoutesForProductOptions, } from './legacy-routes';
 export { augmentProductWithFormatOptions, withFormatOptions, toCanonicalFormatOptionsWithRoutes, toAdditiveCanonicalProduct, withAdditiveCanonicalFormatOptions, toCanonicalOnlyProduct, toCanonicalOnlyResponse, type V2AugmentedProduct, type AdditiveCanonicalProduct, type CanonicalOnlyProduct, } from './augment-response';
 export { CanonicalFormat, audioDaastFormatDeclaration, audioHostedFormatDeclaration, audioVastFormatDeclaration, agentPlacementFormatDeclaration, canonicalFormatDeclaration, customFormatDeclaration, displayTagFormatDeclaration, legacyFormatRef, legacyFormatRefs, html5FormatDeclaration, imageCarouselFormatDeclaration, imageFormatDeclaration, nativeInFeedFormatDeclaration, productCard, productCardDetailed, responsiveCreativeFormatDeclaration, sellerRenderedStatefulDisplayFormatDeclaration, sponsoredPlacementFormatDeclaration, coordinatedPlacementsFormatDeclaration, videoHostedFormatDeclaration, videoVastFormatDeclaration, type CanonicalFormatDeclaration, type CanonicalFormatDeclarationFields, type CanonicalFormatKind, type CanonicalFormatParams, type FormatReferenceInput, type ProductCardDetailedFields, type ProductCardFields, } from './builders';
 export { packageRefsForFormatOptions, packageRefsForCapabilities, legacyFormatIdsFromOptions, tryLegacyFormatIdsFromOptions, legacyFormatIdsForFormatOption, legacyFormatIdsForCapability, lintPackageFormatSelectorDimensions, FormatOptionRefsLookupError, CapabilityIdsLookupError, type PackageFormatRefs, type PackageCapabilityRefs, type FormatOptionRef, type FormatOptionSelector, type FormatOptionRefsLookupErrorCode, type CapabilityIdsLookupErrorCode, type PackageFormatSelectorInput, type PackageFormatSelectorDimensionOptions, type FixedSizeDimensions, type PackageFormatSelectorDimensionDiagnosticCode, type PackageFormatSelectorDimensionDiagnostic, } from './write-side';

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

@@ -13,12 +13,72 @@ export interface CanonicalFormatLegacyRoute {
     product_id: string;
     format_option_ref: FormatOptionReference;
     format_ids: V1FormatId[];
+    /**
+     * Whether the seller declared this option in its own `format_options[]`.
+     * `false` means the SDK derived the option from the seller's legacy
+     * `format_ids`, so the seller cannot resolve its `format_option_id` and a
+     * canonical-wire write addresses it by `canonical_selector` instead. Absent
+     * when the origin is unknown; such routes leave canonical writes unchanged.
+     */
+    seller_declared?: boolean;
+    /**
+     * The direct `format_kind` + `params` selector for an option the seller did
+     * not declare. Absent when no direct selector keeps the option's identity,
+     * such as a custom or schema-backed format, so a write selecting it fails
+     * before dispatch.
+     */
+    canonical_selector?: {
+        format_kind: string;
+        params?: unknown;
+    };
 }
-/** Extract persistable routes from canonical declarations, including concealed migration metadata. */
-export declare function legacyRoutesForProduct(productId: string, declarations: readonly V2ProductFormatDeclaration[]): CanonicalFormatLegacyRoute[];
+/** The direct canonical selector for a format option the seller did not declare. */
+export interface UndeclaredFormatOptionSelector {
+    format_kind: string;
+    params?: unknown;
+    /** Custom/schema-backed formats cannot retain identity in a direct selector. */
+    unrepresentable?: true;
+}
+/** Build the direct selector a canonical write sends for an option the seller did not declare. */
+export declare function undeclaredFormatOptionSelector(declaration: Readonly<Record<string, unknown>>): UndeclaredFormatOptionSelector;
+/**
+ * What a route says about one option's origin: unknown (`undefined`), declared
+ * by the seller, or derived from legacy `format_ids` with its direct selector.
+ */
+export type FormatOptionOrigin = {
+    seller_declared: true;
+} | {
+    seller_declared: false;
+    selector: UndeclaredFormatOptionSelector;
+};
+/** Whether two option refs name the same format option. Publisher domains compare case-insensitively. */
+export declare function sameFormatOptionRef(left: FormatOptionReference, right: FormatOptionReference): boolean;
+/**
+ * Option refs a product declares in its own `format_options[]`, read from the
+ * product exactly as the seller returned it. Options the SDK derives from the
+ * seller's legacy `format_ids` never appear here.
+ */
+export declare function sellerDeclaredFormatOptionRefs(sellerProduct: unknown): FormatOptionReference[];
+export interface LegacyRoutesForProductOptions {
+    /**
+     * The product exactly as the seller returned it from `get_products`. When
+     * given, an option is seller-declared exactly when this product's own
+     * `format_options[]` names it. Use it when the declarations were projected
+     * from a stored seller response in a process that never ran discovery, so
+     * the SDK holds no origin metadata for them.
+     */
+    sellerProduct?: unknown;
+}
+/**
+ * Extract persistable routes from canonical declarations, including concealed
+ * migration metadata. Pass `sellerProduct` to record each option's origin from
+ * the seller's own response instead of that metadata.
+ */
+export declare function legacyRoutesForProduct(productId: string, declarations: readonly V2ProductFormatDeclaration[], options?: LegacyRoutesForProductOptions): CanonicalFormatLegacyRoute[];
 /**
- * Build the existing resolver callback from routes restored from durable
- * storage. Inputs are snapshotted so later caller mutation cannot redirect a
- * creative delivery operation.
+ * The origin a resolver built by {@link canonicalFormatLegacyResolverFromRoutes}
+ * recorded for one option. Without a product id, every route for the option
+ * must agree that the seller did not declare it.
  */
+export declare function formatOptionOriginFromRoutes(resolver: CanonicalFormatLegacyResolver | undefined, ref: FormatOptionReference, productId: string | undefined): FormatOptionOrigin | undefined;
 export declare function canonicalFormatLegacyResolverFromRoutes(routes: readonly CanonicalFormatLegacyRoute[]): CanonicalFormatLegacyResolver;

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

@@ -13,12 +13,72 @@ export interface CanonicalFormatLegacyRoute {
     product_id: string;
     format_option_ref: FormatOptionReference;
     format_ids: V1FormatId[];
+    /**
+     * Whether the seller declared this option in its own `format_options[]`.
+     * `false` means the SDK derived the option from the seller's legacy
+     * `format_ids`, so the seller cannot resolve its `format_option_id` and a
+     * canonical-wire write addresses it by `canonical_selector` instead. Absent
+     * when the origin is unknown; such routes leave canonical writes unchanged.
+     */
+    seller_declared?: boolean;
+    /**
+     * The direct `format_kind` + `params` selector for an option the seller did
+     * not declare. Absent when no direct selector keeps the option's identity,
+     * such as a custom or schema-backed format, so a write selecting it fails
+     * before dispatch.
+     */
+    canonical_selector?: {
+        format_kind: string;
+        params?: unknown;
+    };
 }
-/** Extract persistable routes from canonical declarations, including concealed migration metadata. */
-export declare function legacyRoutesForProduct(productId: string, declarations: readonly V2ProductFormatDeclaration[]): CanonicalFormatLegacyRoute[];
+/** The direct canonical selector for a format option the seller did not declare. */
+export interface UndeclaredFormatOptionSelector {
+    format_kind: string;
+    params?: unknown;
+    /** Custom/schema-backed formats cannot retain identity in a direct selector. */
+    unrepresentable?: true;
+}
+/** Build the direct selector a canonical write sends for an option the seller did not declare. */
+export declare function undeclaredFormatOptionSelector(declaration: Readonly<Record<string, unknown>>): UndeclaredFormatOptionSelector;
+/**
+ * What a route says about one option's origin: unknown (`undefined`), declared
+ * by the seller, or derived from legacy `format_ids` with its direct selector.
+ */
+export type FormatOptionOrigin = {
+    seller_declared: true;
+} | {
+    seller_declared: false;
+    selector: UndeclaredFormatOptionSelector;
+};
+/** Whether two option refs name the same format option. Publisher domains compare case-insensitively. */
+export declare function sameFormatOptionRef(left: FormatOptionReference, right: FormatOptionReference): boolean;
+/**
+ * Option refs a product declares in its own `format_options[]`, read from the
+ * product exactly as the seller returned it. Options the SDK derives from the
+ * seller's legacy `format_ids` never appear here.
+ */
+export declare function sellerDeclaredFormatOptionRefs(sellerProduct: unknown): FormatOptionReference[];
+export interface LegacyRoutesForProductOptions {
+    /**
+     * The product exactly as the seller returned it from `get_products`. When
+     * given, an option is seller-declared exactly when this product's own
+     * `format_options[]` names it. Use it when the declarations were projected
+     * from a stored seller response in a process that never ran discovery, so
+     * the SDK holds no origin metadata for them.
+     */
+    sellerProduct?: unknown;
+}
+/**
+ * Extract persistable routes from canonical declarations, including concealed
+ * migration metadata. Pass `sellerProduct` to record each option's origin from
+ * the seller's own response instead of that metadata.
+ */
+export declare function legacyRoutesForProduct(productId: string, declarations: readonly V2ProductFormatDeclaration[], options?: LegacyRoutesForProductOptions): CanonicalFormatLegacyRoute[];
 /**
- * Build the existing resolver callback from routes restored from durable
- * storage. Inputs are snapshotted so later caller mutation cannot redirect a
- * creative delivery operation.
+ * The origin a resolver built by {@link canonicalFormatLegacyResolverFromRoutes}
+ * recorded for one option. Without a product id, every route for the option
+ * must agree that the seller did not declare it.
  */
+export declare function formatOptionOriginFromRoutes(resolver: CanonicalFormatLegacyResolver | undefined, ref: FormatOptionReference, productId: string | undefined): FormatOptionOrigin | undefined;
 export declare function canonicalFormatLegacyResolverFromRoutes(routes: readonly CanonicalFormatLegacyRoute[]): CanonicalFormatLegacyResolver;