@adcp/sdk 15.8.1 → 15.9.0

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,8 @@ export interface MediaBuyFeatures {
  * Account management capabilities declared by the seller
  */
 export interface AccountCapabilities {
+    /** 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,8 @@ export interface MediaBuyFeatures {
  * Account management capabilities declared by the seller
  */
 export interface AccountCapabilities {
+    /** 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,6 +309,9 @@ 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 ?? [],

package/dist/lib/utils/capabilities.mjs

@@ -253,6 +253,9 @@ 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 ?? [],

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
@@ -258,13 +259,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 +276,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
@@ -258,13 +259,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 +276,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/legacy-routes.d.mts

@@ -13,12 +13,50 @@ 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;
+    };
 }
+/** 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;
+};
 /** Extract persistable routes from canonical declarations, including concealed migration metadata. */
 export declare function legacyRoutesForProduct(productId: string, declarations: readonly V2ProductFormatDeclaration[]): 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,50 @@ 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;
+    };
 }
+/** 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;
+};
 /** Extract persistable routes from canonical declarations, including concealed migration metadata. */
 export declare function legacyRoutesForProduct(productId: string, declarations: readonly V2ProductFormatDeclaration[]): 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.js

@@ -19,10 +19,28 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var legacy_routes_exports = {};
 __export(legacy_routes_exports, {
   canonicalFormatLegacyResolverFromRoutes: () => canonicalFormatLegacyResolverFromRoutes,
-  legacyRoutesForProduct: () => legacyRoutesForProduct
+  formatOptionOriginFromRoutes: () => formatOptionOriginFromRoutes,
+  legacyRoutesForProduct: () => legacyRoutesForProduct,
+  undeclaredFormatOptionSelector: () => undeclaredFormatOptionSelector
 });
 module.exports = __toCommonJS(legacy_routes_exports);
 var import_legacy_metadata = require('./legacy-metadata.js');
+function undeclaredFormatOptionSelector(declaration) {
+  return {
+    format_kind: typeof declaration.format_kind === "string" ? declaration.format_kind : "",
+    ...declaration.params !== void 0 && { params: structuredClone(declaration.params) },
+    ...(typeof declaration.format_kind !== "string" || declaration.format_kind === "custom" || declaration.format_shape !== void 0 || declaration.format_schema !== void 0) && { unrepresentable: true }
+  };
+}
+function routeOrigin(route) {
+  if (route.seller_declared === true) return { seller_declared: true };
+  if (route.seller_declared !== false) return void 0;
+  const selector = route.canonical_selector;
+  return {
+    seller_declared: false,
+    selector: selector && typeof selector.format_kind === "string" && selector.format_kind.length > 0 ? undeclaredFormatOptionSelector(selector) : { format_kind: "", unrepresentable: true }
+  };
+}
 function routeRef(value) {
   if (value === null || typeof value !== "object" || Array.isArray(value)) return void 0;
   const record = value;
@@ -75,7 +93,23 @@ function legacyRoutesForProduct(productId, declarations) {
   return declarations.flatMap((declaration) => {
     const formatOptionRef = routeRef(declaration);
     const formatIds = uniqueFormatIds((0, import_legacy_metadata.legacyFormatRefsForDeclaration)(declaration));
-    return formatOptionRef && formatIds.length > 0 ? [{ product_id: productId, format_option_ref: formatOptionRef, format_ids: formatIds }] : [];
+    if (!formatOptionRef || formatIds.length === 0) return [];
+    const declared = (0, import_legacy_metadata.sellerDeclaredFormatOption)(declaration);
+    const selector = declared === false ? undeclaredFormatOptionSelector(declaration) : void 0;
+    return [
+      {
+        product_id: productId,
+        format_option_ref: formatOptionRef,
+        format_ids: formatIds,
+        ...declared !== void 0 && { seller_declared: declared },
+        ...selector && !selector.unrepresentable && {
+          canonical_selector: {
+            format_kind: selector.format_kind,
+            ...selector.params !== void 0 && { params: selector.params }
+          }
+        }
+      }
+    ];
   });
 }
 function refsFromSelector(selector) {
@@ -130,8 +164,25 @@ function routeLookupContext(context) {
   const lookups = selectorRouteLookups(selector);
   return lookups && lookups.length > 0 ? lookups : void 0;
 }
+const originsByResolver = /* @__PURE__ */ new WeakMap();
+function sameRouteRef(left, right) {
+  return routeKey("", left) === routeKey("", right);
+}
+function formatOptionOriginFromRoutes(resolver, ref, productId) {
+  const origins = resolver ? originsByResolver.get(resolver) : void 0;
+  if (!origins) return void 0;
+  const matching = origins.filter(
+    (entry) => sameRouteRef(entry.ref, ref) && (productId === void 0 || entry.productId === productId)
+  );
+  if (matching.length === 0) return void 0;
+  const declared = matching.find((entry) => entry.origin?.seller_declared);
+  if (declared) return declared.origin;
+  if (matching.some((entry) => entry.origin === void 0)) return void 0;
+  return matching[0].origin;
+}
 function canonicalFormatLegacyResolverFromRoutes(routes) {
   const index = /* @__PURE__ */ new Map();
+  const origins = [];
   for (const route of routes) {
     const ref = routeRef(route.format_option_ref);
     if (typeof route.product_id !== "string" || route.product_id.length === 0 || !ref || !Array.isArray(route.format_ids)) {
@@ -139,8 +190,10 @@ function canonicalFormatLegacyResolverFromRoutes(routes) {
     }
     const key = routeKey(route.product_id, ref);
     index.set(key, uniqueFormatIds([...index.get(key) ?? [], ...route.format_ids]));
+    const origin = routeOrigin(route);
+    origins.push({ productId: route.product_id, ref, origin });
   }
-  return (context) => {
+  const resolver = (context) => {
     const lookups = routeLookupContext(context);
     if (!lookups) return void 0;
     const resolved = [];
@@ -154,9 +207,13 @@ function canonicalFormatLegacyResolverFromRoutes(routes) {
     const formatIds = uniqueFormatIds(resolved);
     return formatIds.length > 0 ? formatIds : void 0;
   };
+  originsByResolver.set(resolver, Object.freeze(origins));
+  return resolver;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   canonicalFormatLegacyResolverFromRoutes,
-  legacyRoutesForProduct
+  formatOptionOriginFromRoutes,
+  legacyRoutesForProduct,
+  undeclaredFormatOptionSelector
 });

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

@@ -1,4 +1,20 @@
-import { legacyFormatRefsForDeclaration } from "./legacy-metadata.mjs";
+import { legacyFormatRefsForDeclaration, sellerDeclaredFormatOption } from "./legacy-metadata.mjs";
+function undeclaredFormatOptionSelector(declaration) {
+  return {
+    format_kind: typeof declaration.format_kind === "string" ? declaration.format_kind : "",
+    ...declaration.params !== void 0 && { params: structuredClone(declaration.params) },
+    ...(typeof declaration.format_kind !== "string" || declaration.format_kind === "custom" || declaration.format_shape !== void 0 || declaration.format_schema !== void 0) && { unrepresentable: true }
+  };
+}
+function routeOrigin(route) {
+  if (route.seller_declared === true) return { seller_declared: true };
+  if (route.seller_declared !== false) return void 0;
+  const selector = route.canonical_selector;
+  return {
+    seller_declared: false,
+    selector: selector && typeof selector.format_kind === "string" && selector.format_kind.length > 0 ? undeclaredFormatOptionSelector(selector) : { format_kind: "", unrepresentable: true }
+  };
+}
 function routeRef(value) {
   if (value === null || typeof value !== "object" || Array.isArray(value)) return void 0;
   const record = value;
@@ -51,7 +67,23 @@ function legacyRoutesForProduct(productId, declarations) {
   return declarations.flatMap((declaration) => {
     const formatOptionRef = routeRef(declaration);
     const formatIds = uniqueFormatIds(legacyFormatRefsForDeclaration(declaration));
-    return formatOptionRef && formatIds.length > 0 ? [{ product_id: productId, format_option_ref: formatOptionRef, format_ids: formatIds }] : [];
+    if (!formatOptionRef || formatIds.length === 0) return [];
+    const declared = sellerDeclaredFormatOption(declaration);
+    const selector = declared === false ? undeclaredFormatOptionSelector(declaration) : void 0;
+    return [
+      {
+        product_id: productId,
+        format_option_ref: formatOptionRef,
+        format_ids: formatIds,
+        ...declared !== void 0 && { seller_declared: declared },
+        ...selector && !selector.unrepresentable && {
+          canonical_selector: {
+            format_kind: selector.format_kind,
+            ...selector.params !== void 0 && { params: selector.params }
+          }
+        }
+      }
+    ];
   });
 }
 function refsFromSelector(selector) {
@@ -106,8 +138,25 @@ function routeLookupContext(context) {
   const lookups = selectorRouteLookups(selector);
   return lookups && lookups.length > 0 ? lookups : void 0;
 }
+const originsByResolver = /* @__PURE__ */ new WeakMap();
+function sameRouteRef(left, right) {
+  return routeKey("", left) === routeKey("", right);
+}
+function formatOptionOriginFromRoutes(resolver, ref, productId) {
+  const origins = resolver ? originsByResolver.get(resolver) : void 0;
+  if (!origins) return void 0;
+  const matching = origins.filter(
+    (entry) => sameRouteRef(entry.ref, ref) && (productId === void 0 || entry.productId === productId)
+  );
+  if (matching.length === 0) return void 0;
+  const declared = matching.find((entry) => entry.origin?.seller_declared);
+  if (declared) return declared.origin;
+  if (matching.some((entry) => entry.origin === void 0)) return void 0;
+  return matching[0].origin;
+}
 function canonicalFormatLegacyResolverFromRoutes(routes) {
   const index = /* @__PURE__ */ new Map();
+  const origins = [];
   for (const route of routes) {
     const ref = routeRef(route.format_option_ref);
     if (typeof route.product_id !== "string" || route.product_id.length === 0 || !ref || !Array.isArray(route.format_ids)) {
@@ -115,8 +164,10 @@ function canonicalFormatLegacyResolverFromRoutes(routes) {
     }
     const key = routeKey(route.product_id, ref);
     index.set(key, uniqueFormatIds([...index.get(key) ?? [], ...route.format_ids]));
+    const origin = routeOrigin(route);
+    origins.push({ productId: route.product_id, ref, origin });
   }
-  return (context) => {
+  const resolver = (context) => {
     const lookups = routeLookupContext(context);
     if (!lookups) return void 0;
     const resolved = [];
@@ -130,8 +181,12 @@ function canonicalFormatLegacyResolverFromRoutes(routes) {
     const formatIds = uniqueFormatIds(resolved);
     return formatIds.length > 0 ? formatIds : void 0;
   };
+  originsByResolver.set(resolver, Object.freeze(origins));
+  return resolver;
 }
 export {
   canonicalFormatLegacyResolverFromRoutes,
-  legacyRoutesForProduct
+  formatOptionOriginFromRoutes,
+  legacyRoutesForProduct,
+  undeclaredFormatOptionSelector
 };

package/dist/lib/validation/sync-creatives.d.mts

@@ -247,7 +247,7 @@ export declare const SyncCreativesItemSchema: z.ZodObject<{
             }, z.core.$loose>>;
             issues: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 issue_id: z.ZodString;
-                code: z.ZodUnion<readonly [z.ZodLiteral<"REPORT_OVERDUE">, z.ZodLiteral<"PRODUCTION_FAILED">, z.ZodLiteral<"DELIVERY_FAILED">, z.ZodLiteral<"ACCESS_REQUIRED">, z.ZodLiteral<"CONFIGURATION_REQUIRED">, z.ZodLiteral<"REPORTING_COVERAGE_INCOMPLETE">, z.ZodLiteral<"RESOURCE_EXPIRED">, z.ZodLiteral<"READER_INCOMPATIBLE">, z.ZodLiteral<"HISTORY_UNAVAILABLE">, z.ZodLiteral<"RECEIPT_REQUIRED">, z.ZodLiteral<"RECEIPT_REJECTED">, z.ZodLiteral<"ADJUSTMENT_RECEIPT_REQUIRED">, z.ZodLiteral<"ADJUSTMENT_RECEIPT_REJECTED">, z.ZodLiteral<"CONSUMER_STATUS_MISMATCH">]>;
+                code: z.ZodUnion<readonly [z.ZodLiteral<"REPORT_OVERDUE">, z.ZodLiteral<"PRODUCTION_FAILED">, z.ZodLiteral<"DELIVERY_FAILED">, z.ZodLiteral<"ACCESS_REQUIRED">, z.ZodLiteral<"CONFIGURATION_REQUIRED">, z.ZodLiteral<"REPORTING_COVERAGE_INCOMPLETE">, z.ZodLiteral<"RESOURCE_EXPIRED">, z.ZodLiteral<"READER_INCOMPATIBLE">, z.ZodLiteral<"HISTORY_UNAVAILABLE">, z.ZodLiteral<"REVISION_UNREADABLE">, z.ZodLiteral<"RECEIPT_REQUIRED">, z.ZodLiteral<"RECEIPT_REJECTED">, z.ZodLiteral<"ADJUSTMENT_RECEIPT_REQUIRED">, z.ZodLiteral<"ADJUSTMENT_RECEIPT_REJECTED">, z.ZodLiteral<"CONSUMER_STATUS_MISMATCH">]>;
                 severity: z.ZodUnion<readonly [z.ZodLiteral<"delayed">, z.ZodLiteral<"action_required">]>;
                 opened_at: z.ZodOptional<z.ZodString>;
                 issue_state: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"open">, z.ZodLiteral<"acknowledged">, z.ZodLiteral<"resolved">, z.ZodLiteral<"waived">]>>;
@@ -256,6 +256,7 @@ export declare const SyncCreativesItemSchema: z.ZodObject<{
                 recommended_action: z.ZodUnion<readonly [z.ZodLiteral<"wait_for_retry">, z.ZodLiteral<"contact_buyer">, z.ZodLiteral<"contact_seller">, z.ZodLiteral<"contact_provider">, z.ZodLiteral<"repair_access">, z.ZodLiteral<"update_configuration">, z.ZodLiteral<"change_reporting_scope">, z.ZodLiteral<"use_supported_reader">]>;
                 message: z.ZodOptional<z.ZodString>;
                 reporting_obligation_id: z.ZodOptional<z.ZodString>;
+                reporting_revision_id: z.ZodOptional<z.ZodString>;
                 reporting_status_id: z.ZodOptional<z.ZodString>;
                 delivery_config_id: z.ZodOptional<z.ZodString>;
                 delivery_config_version: z.ZodOptional<z.ZodNumber>;
@@ -598,7 +599,7 @@ export declare const SyncCreativesSuccessStrictSchema: z.ZodObject<{
                 }, z.core.$loose>>;
                 issues: z.ZodOptional<z.ZodArray<z.ZodObject<{
                     issue_id: z.ZodString;
-                    code: z.ZodUnion<readonly [z.ZodLiteral<"REPORT_OVERDUE">, z.ZodLiteral<"PRODUCTION_FAILED">, z.ZodLiteral<"DELIVERY_FAILED">, z.ZodLiteral<"ACCESS_REQUIRED">, z.ZodLiteral<"CONFIGURATION_REQUIRED">, z.ZodLiteral<"REPORTING_COVERAGE_INCOMPLETE">, z.ZodLiteral<"RESOURCE_EXPIRED">, z.ZodLiteral<"READER_INCOMPATIBLE">, z.ZodLiteral<"HISTORY_UNAVAILABLE">, z.ZodLiteral<"RECEIPT_REQUIRED">, z.ZodLiteral<"RECEIPT_REJECTED">, z.ZodLiteral<"ADJUSTMENT_RECEIPT_REQUIRED">, z.ZodLiteral<"ADJUSTMENT_RECEIPT_REJECTED">, z.ZodLiteral<"CONSUMER_STATUS_MISMATCH">]>;
+                    code: z.ZodUnion<readonly [z.ZodLiteral<"REPORT_OVERDUE">, z.ZodLiteral<"PRODUCTION_FAILED">, z.ZodLiteral<"DELIVERY_FAILED">, z.ZodLiteral<"ACCESS_REQUIRED">, z.ZodLiteral<"CONFIGURATION_REQUIRED">, z.ZodLiteral<"REPORTING_COVERAGE_INCOMPLETE">, z.ZodLiteral<"RESOURCE_EXPIRED">, z.ZodLiteral<"READER_INCOMPATIBLE">, z.ZodLiteral<"HISTORY_UNAVAILABLE">, z.ZodLiteral<"REVISION_UNREADABLE">, z.ZodLiteral<"RECEIPT_REQUIRED">, z.ZodLiteral<"RECEIPT_REJECTED">, z.ZodLiteral<"ADJUSTMENT_RECEIPT_REQUIRED">, z.ZodLiteral<"ADJUSTMENT_RECEIPT_REJECTED">, z.ZodLiteral<"CONSUMER_STATUS_MISMATCH">]>;
                     severity: z.ZodUnion<readonly [z.ZodLiteral<"delayed">, z.ZodLiteral<"action_required">]>;
                     opened_at: z.ZodOptional<z.ZodString>;
                     issue_state: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"open">, z.ZodLiteral<"acknowledged">, z.ZodLiteral<"resolved">, z.ZodLiteral<"waived">]>>;
@@ -607,6 +608,7 @@ export declare const SyncCreativesSuccessStrictSchema: z.ZodObject<{
                     recommended_action: z.ZodUnion<readonly [z.ZodLiteral<"wait_for_retry">, z.ZodLiteral<"contact_buyer">, z.ZodLiteral<"contact_seller">, z.ZodLiteral<"contact_provider">, z.ZodLiteral<"repair_access">, z.ZodLiteral<"update_configuration">, z.ZodLiteral<"change_reporting_scope">, z.ZodLiteral<"use_supported_reader">]>;
                     message: z.ZodOptional<z.ZodString>;
                     reporting_obligation_id: z.ZodOptional<z.ZodString>;
+                    reporting_revision_id: z.ZodOptional<z.ZodString>;
                     reporting_status_id: z.ZodOptional<z.ZodString>;
                     delivery_config_id: z.ZodOptional<z.ZodString>;
                     delivery_config_version: z.ZodOptional<z.ZodNumber>;
@@ -961,7 +963,7 @@ export declare const SyncCreativesResponseStrictSchema: z.ZodUnion<readonly [z.Z
                 }, z.core.$loose>>;
                 issues: z.ZodOptional<z.ZodArray<z.ZodObject<{
                     issue_id: z.ZodString;
-                    code: z.ZodUnion<readonly [z.ZodLiteral<"REPORT_OVERDUE">, z.ZodLiteral<"PRODUCTION_FAILED">, z.ZodLiteral<"DELIVERY_FAILED">, z.ZodLiteral<"ACCESS_REQUIRED">, z.ZodLiteral<"CONFIGURATION_REQUIRED">, z.ZodLiteral<"REPORTING_COVERAGE_INCOMPLETE">, z.ZodLiteral<"RESOURCE_EXPIRED">, z.ZodLiteral<"READER_INCOMPATIBLE">, z.ZodLiteral<"HISTORY_UNAVAILABLE">, z.ZodLiteral<"RECEIPT_REQUIRED">, z.ZodLiteral<"RECEIPT_REJECTED">, z.ZodLiteral<"ADJUSTMENT_RECEIPT_REQUIRED">, z.ZodLiteral<"ADJUSTMENT_RECEIPT_REJECTED">, z.ZodLiteral<"CONSUMER_STATUS_MISMATCH">]>;
+                    code: z.ZodUnion<readonly [z.ZodLiteral<"REPORT_OVERDUE">, z.ZodLiteral<"PRODUCTION_FAILED">, z.ZodLiteral<"DELIVERY_FAILED">, z.ZodLiteral<"ACCESS_REQUIRED">, z.ZodLiteral<"CONFIGURATION_REQUIRED">, z.ZodLiteral<"REPORTING_COVERAGE_INCOMPLETE">, z.ZodLiteral<"RESOURCE_EXPIRED">, z.ZodLiteral<"READER_INCOMPATIBLE">, z.ZodLiteral<"HISTORY_UNAVAILABLE">, z.ZodLiteral<"REVISION_UNREADABLE">, z.ZodLiteral<"RECEIPT_REQUIRED">, z.ZodLiteral<"RECEIPT_REJECTED">, z.ZodLiteral<"ADJUSTMENT_RECEIPT_REQUIRED">, z.ZodLiteral<"ADJUSTMENT_RECEIPT_REJECTED">, z.ZodLiteral<"CONSUMER_STATUS_MISMATCH">]>;
                     severity: z.ZodUnion<readonly [z.ZodLiteral<"delayed">, z.ZodLiteral<"action_required">]>;
                     opened_at: z.ZodOptional<z.ZodString>;
                     issue_state: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"open">, z.ZodLiteral<"acknowledged">, z.ZodLiteral<"resolved">, z.ZodLiteral<"waived">]>>;
@@ -970,6 +972,7 @@ export declare const SyncCreativesResponseStrictSchema: z.ZodUnion<readonly [z.Z
                     recommended_action: z.ZodUnion<readonly [z.ZodLiteral<"wait_for_retry">, z.ZodLiteral<"contact_buyer">, z.ZodLiteral<"contact_seller">, z.ZodLiteral<"contact_provider">, z.ZodLiteral<"repair_access">, z.ZodLiteral<"update_configuration">, z.ZodLiteral<"change_reporting_scope">, z.ZodLiteral<"use_supported_reader">]>;
                     message: z.ZodOptional<z.ZodString>;
                     reporting_obligation_id: z.ZodOptional<z.ZodString>;
+                    reporting_revision_id: z.ZodOptional<z.ZodString>;
                     reporting_status_id: z.ZodOptional<z.ZodString>;
                     delivery_config_id: z.ZodOptional<z.ZodString>;
                     delivery_config_version: z.ZodOptional<z.ZodNumber>;