@adcp/sdk 15.9.5 → 15.9.6

package/dist/lib/core/SingleAgentClient.mjs

@@ -159,6 +159,7 @@ import { resolvePropertyList } from "../server/targeting-helpers.mjs";
 import {
   CreativeFormatCapabilityError,
   CreativeFormatProjectionError,
+  canUseProductOptionsForCreativeWire,
   projectMediaBuyCreativesForDelivery,
   projectCreativeForDelivery,
   projectSyncCreativesForDelivery,
@@ -176,6 +177,10 @@ import {
 import { toCanonicalOnlyResponse } from "../v2/projection/augment-response.mjs";
 import {
   legacyFormatRefsForDeclaration,
+  isSynthesizedFormatOption,
+  selectedFormatOptions,
+  rememberSellerFormatEvidence,
+  sellerFormatEvidence,
   rememberSellerDeclaredFormatOption,
   sellerDeclaredFormatOption,
   structuredCloneWithLegacyCreativeMetadata
@@ -299,6 +304,56 @@ const RECORDLESS_HMAC_READ_ONLY_TASKS = /* @__PURE__ */ new Set([
 ]);
 const TASK_SCOPED_STATE_LIMIT = 1e4;
 const WEBHOOK_JWKS_RESOLVER_LIMIT = 1024;
+function creativeMatchesProductOption(creative, declaration) {
+  const params = isPlainRecord(declaration.params) ? declaration.params : {};
+  const assets = isPlainRecord(creative.assets) ? creative.assets : {};
+  const slots = Array.isArray(params.slots) ? params.slots : [];
+  if (!slots.every((slot) => {
+    if (!isPlainRecord(slot) || typeof slot.asset_group_id !== "string") return false;
+    const value = assets[slot.asset_group_id];
+    const entries = value === void 0 ? [] : Array.isArray(value) ? value : [value];
+    const minimum = Math.max(typeof slot.min === "number" ? slot.min : 0, slot.required === true ? 1 : 0);
+    if (entries.length < minimum || typeof slot.max === "number" && entries.length > slot.max) return false;
+    return entries.every(
+      (asset) => isPlainRecord(asset) && (typeof slot.asset_type !== "string" || asset.asset_type === slot.asset_type)
+    );
+  }))
+    return false;
+  const formatParams = isPlainRecord(creative.format_parameters) ? creative.format_parameters : {};
+  const kind = String(creative.format_kind);
+  const mediaType = kind.startsWith("image") ? "image" : kind.startsWith("video") ? "video" : kind.startsWith("audio") ? "audio" : kind === "html5" ? "html" : void 0;
+  const assetTypes = mediaType === "video" ? ["video", "vast"] : mediaType === "audio" ? ["audio", "vast", "daast"] : mediaType === "html" ? ["html", "zip"] : mediaType ? [mediaType] : ["image", "video", "audio", "html", "zip", "vast", "daast"];
+  const requiredMediaSlots = slots.filter(
+    (slot) => isPlainRecord(slot) && (slot.required === true || typeof slot.min === "number" && slot.min > 0) && assetTypes.includes(String(slot.asset_type))
+  );
+  const preferredGroups = mediaType ? [`${mediaType}_main`, mediaType, kind, ...assetTypes] : [];
+  const primaryGroup = (requiredMediaSlots.length === 1 ? String(requiredMediaSlots[0].asset_group_id) : void 0) ?? preferredGroups.find((group) => assets[group] !== void 0);
+  const sourceAssets = primaryGroup ? [assets[primaryGroup]] : Object.values(assets);
+  const dimensionalAssets = sourceAssets.flatMap((value) => Array.isArray(value) ? value : [value]).filter(
+    (value) => isPlainRecord(value) && assetTypes.includes(String(value.asset_type))
+  );
+  return (dimensionalAssets.length > 0 ? dimensionalAssets : [{}]).every((asset) => {
+    const actual = { ...asset, ...formatParams };
+    for (const key of ["width", "height"]) {
+      if (typeof params[key] === "number" && actual[key] !== params[key]) return false;
+      const min = params[`min_${key}`];
+      const max = params[`max_${key}`];
+      if (typeof min === "number" && (typeof actual[key] !== "number" || actual[key] < min)) return false;
+      if (typeof max === "number" && (typeof actual[key] !== "number" || actual[key] > max)) return false;
+    }
+    if (Array.isArray(params.sizes) && !params.sizes.some((size) => isPlainRecord(size) && size.width === actual.width && size.height === actual.height))
+      return false;
+    const duration = actual.duration_ms ?? actual.duration_ms_exact;
+    const exact = params.duration_ms_exact ?? params.duration_ms;
+    if (typeof exact === "number" && duration !== exact) return false;
+    if (typeof exact !== "number" && Array.isArray(params.duration_ms_range)) {
+      const [min, max] = params.duration_ms_range;
+      if (typeof duration !== "number" || typeof min === "number" && duration < min || typeof max === "number" && duration > max)
+        return false;
+    }
+    return true;
+  });
+}
 function isDeferredClientFinalizationContext(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
   const context = value;
@@ -1431,7 +1486,7 @@ class SingleAgentClient {
       }
     }
   }
-  rememberCanonicalProductRoutes(products, account, authoritativeProducts) {
+  rememberCanonicalProductRoutes(products, account, authoritativeProducts, evidence) {
     this.invalidateCanonicalProductRoutes(authoritativeProducts ?? products, account);
     const accountScope = this.canonicalAccountScope(account);
     const declaredOptions = authoritativeProducts ? this.sellerDeclaredFormatOptions(authoritativeProducts) : void 0;
@@ -1451,12 +1506,15 @@ class SingleAgentClient {
         const refs = legacyFormatRefsForDeclaration(option);
         const declared = declaredOptions ? declaredOptions.get(product.product_id)?.some((declaredRef) => this.sameCanonicalOptionRef(declaredRef, ref)) : sellerDeclaredFormatOption(option);
         if (declared !== void 0) rememberSellerDeclaredFormatOption(option, declared);
+        if (declared === true && evidence)
+          rememberSellerFormatEvidence(option, { ...evidence, productId: product.product_id });
         this.rememberCanonicalLegacyRoute(this.canonicalLegacyRouteKey(account, product.product_id, ref), {
           kind: "product",
           accountScope,
           productId: product.product_id,
           optionRef: ref,
           refs,
+          ...declared === true && sellerFormatEvidence(option) ? { declaration: structuredCloneWithLegacyCreativeMetadata(option) } : {},
           ...declared === false ? { undeclaredSelector: undeclaredFormatOptionSelector(option) } : {}
         });
       }
@@ -4666,6 +4724,13 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         }
       }
       const conditionalSnapshot = skipCacheRead ? void 0 : cache?.read(cacheScope, cacheParams, true);
+      const productEvidence = this.usesScopedDiscoveryTransport(
+        effectiveOptions
+      ) ? void 0 : {
+        scopeKey: this.getCapabilityEvidenceScope().scopeKey,
+        accountScope: this.canonicalAccountScope(account),
+        expiresAt: Date.now() + resolveAgentDiscoveryTtlMs(this.config.discoveryCache?.ttlMs)
+      };
       const result = await this.executeAndHandle(
         "get_products",
         "onGetProductsStatusChange",
@@ -4678,7 +4743,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
             projectionCatalogs: projectionCatalogs ?? this.config.projectionCatalogs
           });
           const authoritativeProducts = Array.isArray(data.products) ? data.products : response.products;
-          this.rememberCanonicalProductRoutes(response.products, account, authoritativeProducts);
+          this.rememberCanonicalProductRoutes(response.products, account, authoritativeProducts, productEvidence);
           const { _message: _dropLegacyMessage, ...canonical } = response;
           void _dropLegacyMessage;
           return { ...canonical, projection: { diagnostics } };
@@ -4689,7 +4754,9 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       );
       const finishCache = async (completed) => {
         if (!cache) return completed;
-        const cachedResult = cache.write(cacheScope, cacheParams, completed, conditionalSnapshot);
+        const cachedResult = cache.write(cacheScope, cacheParams, completed, conditionalSnapshot, (materialized) => {
+          this.rememberCanonicalProductRoutes(materialized.data?.products ?? [], account, void 0, productEvidence);
+        });
         if (cachedResult.success && cachedResult.status === "completed") {
           if (!skipCacheRead && cacheParams.if_wholesale_feed_version === void 0 && cacheParams.if_pricing_version === void 0 && cachedResult.data.unchanged === true) {
             return this.getProducts(params, inputHandler, {
@@ -4849,7 +4916,12 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     if (hasCreativeFormatData) {
       this.validateBeforeCreativeCapabilityProbe("create_media_buy", params, taskOptions);
     }
-    const wireMode = hasCreativeFormatData ? await this.resolveCreativeFormatWireMode("create_media_buy", taskOptions) : "canonical";
+    const wireMode = hasCreativeFormatData ? await this.resolveCreativeWireMode(
+      "create_media_buy",
+      taskOptions,
+      true,
+      () => this.productOptionsSupportCanonicalWire("create_media_buy", params, [], options)
+    ) : "canonical";
     const wireParams = params;
     const result = await this.executeAndHandle(
       "create_media_buy",
@@ -4937,7 +5009,12 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     if (hasCreativeFormatData) {
       this.validateBeforeCreativeCapabilityProbe("update_media_buy", params, taskOptions);
     }
-    const wireMode = hasCreativeFormatData ? await this.resolveCreativeFormatWireMode("update_media_buy", taskOptions) : "canonical";
+    const wireMode = hasCreativeFormatData ? await this.resolveCreativeWireMode(
+      "update_media_buy",
+      taskOptions,
+      true,
+      () => this.productOptionsSupportCanonicalWire("update_media_buy", params, [], options)
+    ) : "canonical";
     const result = await this.executeAndHandle(
       "update_media_buy",
       "onUpdateMediaBuyStatusChange",
@@ -5026,7 +5103,6 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       projectionCatalogs ?? this.config.projectionCatalogs
     );
     this.validateBeforeCreativeCapabilityProbe("sync_creatives", params, taskOptions);
-    const wireMode = await this.resolveCreativeFormatWireMode("sync_creatives", taskOptions);
     const configuredSelectorContainers = [
       ...creativeFormatProjection?.selectorContainers ?? []
     ];
@@ -5038,10 +5114,17 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     const assignmentPackageContainers = Array.isArray(params.assignments) ? params.assignments.flatMap(
       (assignment) => typeof assignment.package_id === "string" && !configuredPackageIds.has(assignment.package_id) ? [{ package_id: assignment.package_id }] : []
     ) : [];
+    const selectorContainers = [...configuredSelectorContainers, ...assignmentPackageContainers];
+    const wireMode = await this.resolveCreativeWireMode(
+      "sync_creatives",
+      taskOptions,
+      true,
+      () => this.productOptionsSupportCanonicalWire("sync_creatives", params, selectorContainers, options)
+    );
     const wireParams = this.projectUndeclaredFormatOptions(
       projectSyncCreativesForDelivery(
         params,
-        [...configuredSelectorContainers, ...assignmentPackageContainers],
+        selectorContainers,
         wireMode,
         effectiveLegacyFormatConverter,
         effectiveCanonicalFormatLegacyResolver
@@ -5081,16 +5164,17 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
    * sending a mutation. Discovers capabilities and the current tool's input
    * schema, or reuses fresh cached/primed evidence, with this client's wire pin.
    *
-   * `unknown` preserves the conservative legacy projection for older peers
-   * whose capabilities and schema do not establish support. Projection still
-   * requires an unambiguous legacy reference for each creative in that case.
+   * This context-free check returns `unknown` when capabilities and schema do
+   * not establish support. A write to a proven 3.1 seller can still select
+   * canonical delivery from matching seller-advertised product options;
+   * otherwise projection requires an unambiguous legacy reference.
    * Conflicting evidence and unproven support with a 3.2+ buyer pin throw
    * `CreativeFormatCapabilityError`, just as they do during a write.
    */
   async resolveCreativeFormatWireMode(taskType, options) {
     return this.resolveCreativeWireMode(taskType, options, true);
   }
-  async resolveCreativeWireMode(taskType, options, canRediscover) {
+  async resolveCreativeWireMode(taskType, options, canRediscover, matchingProductOptions) {
     const discoveryContext = {};
     const capabilities = await this.getCapabilities({
       ...options,
@@ -5109,13 +5193,16 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         `Seller capability and ${taskType} input schema disagree about canonical creative support`
       );
     }
-    const resolved = declared !== "unknown" ? declared : schema;
+    let resolved = declared !== "unknown" ? declared : schema;
+    if (resolved === "unknown" && canUseProductOptionsForCreativeWire(capabilities, wireRelease) && matchingProductOptions?.()) {
+      resolved = "canonical";
+    }
     const release = /^v?(\d+)\.(\d+)(?:\.|-|$)/.exec(wireRelease.trim());
     const canonicalRequiredByBuyerPin = release !== null && (Number(release[1]) > 3 || Number(release[1]) === 3 && Number(release[2]) >= 2);
     if (resolved === "unknown" && canonicalRequiredByBuyerPin) {
       if (canRediscover && !usesScopedFetch && this.normalizedAgent.protocol === "mcp" && this.capabilitiesFromSharedCache && toolSchemas?.has(taskType) && !toolInputSchemasByProperties.has(toolSchemas)) {
         await this.invalidateDiscoveryCache(options);
-        return this.resolveCreativeWireMode(taskType, options, false);
+        return this.resolveCreativeWireMode(taskType, options, false, matchingProductOptions);
       }
       throw new CreativeFormatCapabilityError(
         `Cannot prove which AdCP release the seller serves for ${taskType}; a 3.2+ client will not guess a legacy creative wire shape`
@@ -5123,6 +5210,115 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     }
     return resolved;
   }
+  usesScopedDiscoveryTransport(options) {
+    return normalizeTransportOptions(options?.transport ?? this.config.transport)?.trustedFetchFn !== void 0;
+  }
+  /** Product evidence applies to this request only; it must never prime a tool-wide capability. */
+  productOptionsSupportCanonicalWire(taskType, request, selectorContainers = [], options) {
+    if (!isPlainRecord(request) || this.usesScopedDiscoveryTransport(options)) return false;
+    const scopeKey = this.getCapabilityEvidenceScope().scopeKey;
+    const accountScope = this.canonicalAccountScope(request.account);
+    const optionRef = (value) => {
+      if (!isPlainRecord(value) || typeof value.format_option_id !== "string" || !value.format_option_id) {
+        return void 0;
+      }
+      if (typeof value.publisher_domain === "string") {
+        return {
+          scope: "publisher",
+          publisher_domain: value.publisher_domain,
+          format_option_id: value.format_option_id
+        };
+      }
+      if (value.scope !== void 0 && value.scope !== "product") return void 0;
+      return { scope: "product", format_option_id: value.format_option_id };
+    };
+    const accepts = (container, creative, depth = 0) => {
+      if (depth > 32) return false;
+      if (Array.isArray(container.selector_containers)) {
+        return container.selector_containers.length > 0 && container.selector_containers.every((nested) => accepts(nested, creative, depth + 1));
+      }
+      const refs = Array.isArray(container.format_option_refs) ? container.format_option_refs.map(optionRef) : [];
+      if (refs.some((ref) => ref === void 0)) return false;
+      const creativeRef = isPlainRecord(creative) ? optionRef(creative.format_option_ref) : void 0;
+      if (isPlainRecord(creative) && creative.format_option_ref !== void 0 && !creativeRef) return false;
+      const isSellerDeclaration = (value) => {
+        if (!isPlainRecord(value) || sellerDeclaredFormatOption(value) !== true || isSynthesizedFormatOption(value)) {
+          return false;
+        }
+        const evidence2 = sellerFormatEvidence(value);
+        if (!evidence2 || evidence2.scopeKey !== scopeKey || typeof container.product_id === "string" && evidence2.productId !== container.product_id || evidence2.expiresAt <= Date.now() || evidence2.accountScope !== accountScope && evidence2.accountScope !== "none")
+          return false;
+        const ref = optionRef(value);
+        if (ref && formatOptionOriginFromRoutes(
+          options?.canonicalFormatLegacyResolver,
+          ref,
+          typeof container.product_id === "string" ? container.product_id : void 0
+        )?.seller_declared === false)
+          return false;
+        return !ref || typeof container.product_id !== "string" || this.cachedFormatOptionOrigin(request.account, ref, container.product_id)?.seller_declared !== false;
+      };
+      const declarations = [
+        ...(Array.isArray(container.format_options) ? container.format_options : []).filter(isSellerDeclaration),
+        ...selectedFormatOptions(container).filter(isSellerDeclaration)
+      ];
+      if (typeof container.product_id === "string") {
+        for (const ref of [...refs, ...creativeRef ? [creativeRef] : []]) {
+          if (!ref) continue;
+          const route = this.routeForOption(request.account, container.product_id, ref);
+          if (route?.kind === "product" && route.declaration && isSellerDeclaration(route.declaration))
+            declarations.push(route.declaration);
+        }
+      }
+      const available = declarations.filter((declaration) => declaration.experimental !== true);
+      const matchesRef = (declaration, ref) => {
+        const declaredRef = optionRef(declaration);
+        return declaredRef !== void 0 && this.sameCanonicalOptionRef(declaredRef, ref);
+      };
+      if (!refs.every((ref) => available.some((declaration) => matchesRef(declaration, ref)))) return false;
+      const selected = available.filter(
+        (declaration) => refs.length === 0 || refs.some((ref) => matchesRef(declaration, ref))
+      );
+      if (creative === void 0) return refs.length > 0 && selected.length > 0;
+      if (!isPlainRecord(creative) || typeof creative.format_kind !== "string" || creative.format_id !== void 0)
+        return false;
+      return selected.some(
+        (declaration) => declaration.format_kind === creative.format_kind && (!creativeRef || matchesRef(declaration, creativeRef)) && creativeMatchesProductOption(creative, declaration)
+      );
+    };
+    if (taskType === "sync_creatives") {
+      if (!Array.isArray(request.creatives) || request.creatives.length === 0) return false;
+      const creatives = request.creatives;
+      const assignments = Array.isArray(request.assignments) ? request.assignments : [];
+      if (!assignments.every(
+        (value) => isPlainRecord(value) && typeof value.package_id === "string" && typeof value.creative_id === "string" && creatives.some((creative) => isPlainRecord(creative) && creative.creative_id === value.creative_id)
+      ))
+        return false;
+      return creatives.every((creative) => {
+        if (!isPlainRecord(creative)) return false;
+        const assigned = new Set(
+          assignments.flatMap(
+            (value) => isPlainRecord(value) && value.creative_id === creative.creative_id && typeof value.package_id === "string" ? [value.package_id] : []
+          )
+        );
+        const relevant = assigned.size === 0 ? selectorContainers : selectorContainers.filter(
+          (container) => typeof container.package_id === "string" && assigned.has(container.package_id)
+        );
+        return relevant.length > 0 && [...assigned].every((id) => relevant.some((container) => container.package_id === id)) && relevant.every((container) => accepts(container, creative));
+      });
+    }
+    const packages = ["packages", "new_packages"].flatMap((key) => Array.isArray(request[key]) ? request[key] : []);
+    let evidence = false;
+    return packages.length > 0 && packages.every((pkg) => {
+      if (!isPlainRecord(pkg)) return false;
+      const creatives = Array.isArray(pkg.creatives) ? pkg.creatives : [];
+      const hasSelectors = Array.isArray(pkg.format_option_refs) && pkg.format_option_refs.length > 0;
+      if (!hasSelectors && creatives.length === 0) {
+        return pkg.format_kind === void 0 && pkg.format_ids === void 0;
+      }
+      evidence = true;
+      return (!hasSelectors || accepts(pkg)) && creatives.every((creative) => accepts(pkg, creative));
+    }) && evidence;
+  }
   /** Validate malformed creative payloads before capability discovery can perform I/O. */
   validateBeforeCreativeCapabilityProbe(taskType, params, options) {
     if (options.skipIdempotencyAutoInject || options.skipAccountValidation || options.skipRequestValidation) return;

package/dist/lib/core/product-cache.d.mts

@@ -12,7 +12,9 @@ export declare class ProductCache {
     private key;
     read<T>(scope: string, params: Record<string, unknown>, allowExpired?: boolean): TaskResult<T> | undefined;
     conditionalParams(scope: string, params: Record<string, unknown>): Record<string, unknown>;
-    write<T>(scope: string, params: Record<string, unknown>, result: TaskResult<T>, conditionalSnapshot?: TaskResult<T>): TaskResult<T>;
+    write<T>(scope: string, params: Record<string, unknown>, result: TaskResult<T>, conditionalSnapshot?: TaskResult<T>, 
+    /** @internal Refresh private discovery evidence before a confirmed snapshot is cloned into storage. */
+    onRevalidated?: (materialized: TaskResult<T>) => void): TaskResult<T>;
     clear(): void;
 }
 export declare function createProductCache(options?: ProductCacheOptions): ProductCache;

package/dist/lib/core/product-cache.d.ts

@@ -12,7 +12,9 @@ export declare class ProductCache {
     private key;
     read<T>(scope: string, params: Record<string, unknown>, allowExpired?: boolean): TaskResult<T> | undefined;
     conditionalParams(scope: string, params: Record<string, unknown>): Record<string, unknown>;
-    write<T>(scope: string, params: Record<string, unknown>, result: TaskResult<T>, conditionalSnapshot?: TaskResult<T>): TaskResult<T>;
+    write<T>(scope: string, params: Record<string, unknown>, result: TaskResult<T>, conditionalSnapshot?: TaskResult<T>, 
+    /** @internal Refresh private discovery evidence before a confirmed snapshot is cloned into storage. */
+    onRevalidated?: (materialized: TaskResult<T>) => void): TaskResult<T>;
     clear(): void;
 }
 export declare function createProductCache(options?: ProductCacheOptions): ProductCache;

package/dist/lib/core/product-cache.js

@@ -86,7 +86,7 @@ class ProductCache {
       ...typeof data.pricing_version === "string" && { if_pricing_version: data.pricing_version }
     };
   }
-  write(scope, params, result, conditionalSnapshot) {
+  write(scope, params, result, conditionalSnapshot, onRevalidated) {
     const key = this.key(scope, params);
     if (!key) return result;
     if (!result.success || result.status !== "completed" || !result.data || typeof result.data !== "object")
@@ -109,6 +109,7 @@ class ProductCache {
         return result;
       if (params.if_wholesale_feed_version !== void 0 || params.if_pricing_version !== void 0) return result;
       completed = { ...result, data: (0, import_legacy_metadata.structuredCloneWithLegacyCreativeMetadata)(oldData) };
+      onRevalidated?.(completed);
     } else if (!Array.isArray(data.products)) return result;
     if (!this.entries.has(key) && this.entries.size >= (this.options.maxEntries ?? 1e3))
       this.entries.delete(this.entries.keys().next().value);

package/dist/lib/core/product-cache.mjs

@@ -62,7 +62,7 @@ class ProductCache {
       ...typeof data.pricing_version === "string" && { if_pricing_version: data.pricing_version }
     };
   }
-  write(scope, params, result, conditionalSnapshot) {
+  write(scope, params, result, conditionalSnapshot, onRevalidated) {
     const key = this.key(scope, params);
     if (!key) return result;
     if (!result.success || result.status !== "completed" || !result.data || typeof result.data !== "object")
@@ -85,6 +85,7 @@ class ProductCache {
         return result;
       if (params.if_wholesale_feed_version !== void 0 || params.if_pricing_version !== void 0) return result;
       completed = { ...result, data: structuredCloneWithLegacyCreativeMetadata(oldData) };
+      onRevalidated?.(completed);
     } else if (!Array.isArray(data.products)) return result;
     if (!this.entries.has(key) && this.entries.size >= (this.options.maxEntries ?? 1e3))
       this.entries.delete(this.entries.keys().next().value);

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

@@ -144,9 +144,10 @@ export type SavePropertyRequest = Omit<RegistrySavePropertyRequest, 'authorized_
 /** Response from POST /api/properties/save (200) */
 export type SavePropertyResponse = operations['saveProperty']['responses']['200']['content']['application/json'];
 type RegistryResolveIdentifiersRequest = NonNullable<operations['resolveIdentifiers']['requestBody']>['content']['application/json'];
-/** Request body for POST /api/registry/resolve. `mode` defaults to `resolve` server-side. */
-export type ResolveIdentifiersRequest = Omit<RegistryResolveIdentifiersRequest, 'mode'> & {
+/** Request body for POST /api/registry/resolve. Mode and sandbox use the registry's defaults when omitted. */
+export type ResolveIdentifiersRequest = Omit<RegistryResolveIdentifiersRequest, 'mode' | 'sandbox'> & {
     mode?: RegistryResolveIdentifiersRequest['mode'];
+    sandbox?: RegistryResolveIdentifiersRequest['sandbox'];
 };
 /** Response from POST /api/registry/resolve (200) */
 export type ResolveIdentifiersResponse = operations['resolveIdentifiers']['responses']['200']['content']['application/json'];

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

@@ -144,9 +144,10 @@ export type SavePropertyRequest = Omit<RegistrySavePropertyRequest, 'authorized_
 /** Response from POST /api/properties/save (200) */
 export type SavePropertyResponse = operations['saveProperty']['responses']['200']['content']['application/json'];
 type RegistryResolveIdentifiersRequest = NonNullable<operations['resolveIdentifiers']['requestBody']>['content']['application/json'];
-/** Request body for POST /api/registry/resolve. `mode` defaults to `resolve` server-side. */
-export type ResolveIdentifiersRequest = Omit<RegistryResolveIdentifiersRequest, 'mode'> & {
+/** Request body for POST /api/registry/resolve. Mode and sandbox use the registry's defaults when omitted. */
+export type ResolveIdentifiersRequest = Omit<RegistryResolveIdentifiersRequest, 'mode' | 'sandbox'> & {
     mode?: RegistryResolveIdentifiersRequest['mode'];
+    sandbox?: RegistryResolveIdentifiersRequest['sandbox'];
 };
 /** Response from POST /api/registry/resolve (200) */
 export type ResolveIdentifiersResponse = operations['resolveIdentifiers']['responses']['200']['content']['application/json'];

package/dist/lib/registry/types.generated.d.mts

@@ -283,7 +283,7 @@ export interface paths {
         put?: never;
         /**
          * Save property
-         * @description Save or update a hosted property in the registry. Requires authentication. For existing properties, creates a revision-tracked edit. For new properties, creates the property directly. Cannot edit authoritative properties managed via adagents.json.
+         * @description Save or update a hosted property in the registry. Requires authentication. For bulk identifier contributions use resolveIdentifiers instead (up to 10,000 identifiers per request). This endpoint is limited to 60 requests/hour per user/IP. publisher_domain must be a lowercase hostname without a URL, port, whitespace, wildcard, or trailing dot. Reserved test domains are rejected unless sandbox is true. With sandbox: true the request is validated and a simulated result is returned without reading or writing a hosted property; the ID is ephemeral. For existing properties, creates a revision-tracked edit. For new properties, creates the property directly. Cannot edit authoritative properties managed via adagents.json.
          *
          *     This is an identity-only write surface: the stored document always carries `authorized_agents: []`. Sales authorization lives solely in the publisher's own origin `adagents.json`; the community registry cannot mint or carry it. Any `authorized_agents` sent in the request body is ignored.
          */
@@ -4892,6 +4892,11 @@ export interface components {
          */
         OrganizationRevenueTier: "under_1m" | "1m_5m" | "5m_50m" | "50m_250m" | "250m_1b" | "1b_plus";
         ResolveResponse: {
+            /**
+             * @description Present for a non-persistent sandbox simulation. New property handles are ephemeral.
+             * @enum {boolean}
+             */
+            sandbox?: true;
             resolved: components["schemas"]["ResolvedEntry"][];
             summary: {
                 total: number;
@@ -4915,30 +4920,30 @@ export interface components {
         CatalogIdentifier: {
             /** @example domain */
             type: string;
-            /** @example nytimes.com */
+            /** @example streamhaus.com */
             value: string;
         };
+        /** @description Up to 10,000 identifiers plus provenance. resolve requires authentication and contributes unknown identifiers; lookup is read-only. Domain/subdomain values must follow core/identifier.json; production rejects reserved test domains. sandbox: true simulates contributions without writes. */
         ResolveRequest: {
             /** @description Identifiers to resolve (and, in resolve mode, contribute). Max 10,000 per call for all callers. */
             identifiers: components["schemas"]["CatalogIdentifier"][];
             provenance: components["schemas"]["FactProvenance"];
             /**
-             * @description `resolve` (default) contributes the identifiers, auto-creates missing catalog entries, logs demand activity, and returns rids — requires authentication. `lookup` is a pure read: no write, no activity log, no auth.
+             * @description resolve (default) contributes identifiers, creates missing catalog entries, and logs activity; authentication is required. lookup is a public read with no writes or activity logging.
              * @default resolve
              * @enum {string}
              */
             mode: "resolve" | "lookup";
+            /** @description Simulate contributions without storing properties, identifiers, facts, or activity. Reads existing catalog data; new handles are ephemeral. Reserved test domains are allowed only in sandbox mode. Defaults to false when omitted. */
+            sandbox?: boolean;
         };
         FactProvenance: {
             /**
-             * @description How the caller knows these identifiers — the trust/audit envelope on the fact. Determines the confidence the catalog assigns. `crawl` is reserved for server-side pipelines; callers use the others.
+             * @description How the caller knows these identifiers — the trust/audit envelope on the fact. Determines the confidence the catalog assigns. crawl is reserved for server-side pipelines; callers use the others.
              * @enum {string}
              */
             type: "agency_allowlist" | "publisher_declaration" | "impression_log" | "ssp_inventory" | "deal_history" | "crawl" | "data_partner" | "member_assertion";
-            /**
-             * @description Optional free-text annotation (campaign, dataset).
-             * @example unilever_q3
-             */
+            /** @description Optional free-text annotation (campaign, dataset). */
             context?: string;
         };
         CatalogDisputeTriageResult: {
@@ -5731,6 +5736,11 @@ export interface operations {
                 "application/json": {
                     /** @example examplepub.com */
                     publisher_domain: string;
+                    /**
+                     * @description Validate and simulate a save without persisting it. Allows reserved test hostnames.
+                     * @default false
+                     */
+                    sandbox?: boolean;
                     /**
                      * @description Ignored. Community-registry rows never assert sales authorization — the owner's origin adagents.json is the sole authorization source — so any value here is dropped and the stored document carries authorized_agents:[].
                      * @example []
@@ -5770,6 +5780,8 @@ export interface operations {
                         success: true;
                         message: string;
                         id: string;
+                        /** @enum {boolean} */
+                        sandbox?: true;
                         revision_number?: number;
                     };
                 };
@@ -8475,7 +8487,7 @@ export interface operations {
     getAgentAuthorizations: {
         parameters: {
             query: {
-                /** @description Agent URL to look up. Canonicalized server-side (lowercased, trailing slashes trimmed). */
+                /** @description Agent URL to look up. Canonicalized server-side per AdCP URL canonicalization: the scheme and host fold, the path does not. */
                 agent_url: string;
                 /** @description `effective` (default) applies override layer; `raw` reads base table. */
                 include?: "raw" | "effective";

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

@@ -283,7 +283,7 @@ export interface paths {
         put?: never;
         /**
          * Save property
-         * @description Save or update a hosted property in the registry. Requires authentication. For existing properties, creates a revision-tracked edit. For new properties, creates the property directly. Cannot edit authoritative properties managed via adagents.json.
+         * @description Save or update a hosted property in the registry. Requires authentication. For bulk identifier contributions use resolveIdentifiers instead (up to 10,000 identifiers per request). This endpoint is limited to 60 requests/hour per user/IP. publisher_domain must be a lowercase hostname without a URL, port, whitespace, wildcard, or trailing dot. Reserved test domains are rejected unless sandbox is true. With sandbox: true the request is validated and a simulated result is returned without reading or writing a hosted property; the ID is ephemeral. For existing properties, creates a revision-tracked edit. For new properties, creates the property directly. Cannot edit authoritative properties managed via adagents.json.
          *
          *     This is an identity-only write surface: the stored document always carries `authorized_agents: []`. Sales authorization lives solely in the publisher's own origin `adagents.json`; the community registry cannot mint or carry it. Any `authorized_agents` sent in the request body is ignored.
          */
@@ -4892,6 +4892,11 @@ export interface components {
          */
         OrganizationRevenueTier: "under_1m" | "1m_5m" | "5m_50m" | "50m_250m" | "250m_1b" | "1b_plus";
         ResolveResponse: {
+            /**
+             * @description Present for a non-persistent sandbox simulation. New property handles are ephemeral.
+             * @enum {boolean}
+             */
+            sandbox?: true;
             resolved: components["schemas"]["ResolvedEntry"][];
             summary: {
                 total: number;
@@ -4915,30 +4920,30 @@ export interface components {
         CatalogIdentifier: {
             /** @example domain */
             type: string;
-            /** @example nytimes.com */
+            /** @example streamhaus.com */
             value: string;
         };
+        /** @description Up to 10,000 identifiers plus provenance. resolve requires authentication and contributes unknown identifiers; lookup is read-only. Domain/subdomain values must follow core/identifier.json; production rejects reserved test domains. sandbox: true simulates contributions without writes. */
         ResolveRequest: {
             /** @description Identifiers to resolve (and, in resolve mode, contribute). Max 10,000 per call for all callers. */
             identifiers: components["schemas"]["CatalogIdentifier"][];
             provenance: components["schemas"]["FactProvenance"];
             /**
-             * @description `resolve` (default) contributes the identifiers, auto-creates missing catalog entries, logs demand activity, and returns rids — requires authentication. `lookup` is a pure read: no write, no activity log, no auth.
+             * @description resolve (default) contributes identifiers, creates missing catalog entries, and logs activity; authentication is required. lookup is a public read with no writes or activity logging.
              * @default resolve
              * @enum {string}
              */
             mode: "resolve" | "lookup";
+            /** @description Simulate contributions without storing properties, identifiers, facts, or activity. Reads existing catalog data; new handles are ephemeral. Reserved test domains are allowed only in sandbox mode. Defaults to false when omitted. */
+            sandbox?: boolean;
         };
         FactProvenance: {
             /**
-             * @description How the caller knows these identifiers — the trust/audit envelope on the fact. Determines the confidence the catalog assigns. `crawl` is reserved for server-side pipelines; callers use the others.
+             * @description How the caller knows these identifiers — the trust/audit envelope on the fact. Determines the confidence the catalog assigns. crawl is reserved for server-side pipelines; callers use the others.
              * @enum {string}
              */
             type: "agency_allowlist" | "publisher_declaration" | "impression_log" | "ssp_inventory" | "deal_history" | "crawl" | "data_partner" | "member_assertion";
-            /**
-             * @description Optional free-text annotation (campaign, dataset).
-             * @example unilever_q3
-             */
+            /** @description Optional free-text annotation (campaign, dataset). */
             context?: string;
         };
         CatalogDisputeTriageResult: {
@@ -5731,6 +5736,11 @@ export interface operations {
                 "application/json": {
                     /** @example examplepub.com */
                     publisher_domain: string;
+                    /**
+                     * @description Validate and simulate a save without persisting it. Allows reserved test hostnames.
+                     * @default false
+                     */
+                    sandbox?: boolean;
                     /**
                      * @description Ignored. Community-registry rows never assert sales authorization — the owner's origin adagents.json is the sole authorization source — so any value here is dropped and the stored document carries authorized_agents:[].
                      * @example []
@@ -5770,6 +5780,8 @@ export interface operations {
                         success: true;
                         message: string;
                         id: string;
+                        /** @enum {boolean} */
+                        sandbox?: true;
                         revision_number?: number;
                     };
                 };
@@ -8475,7 +8487,7 @@ export interface operations {
     getAgentAuthorizations: {
         parameters: {
             query: {
-                /** @description Agent URL to look up. Canonicalized server-side (lowercased, trailing slashes trimmed). */
+                /** @description Agent URL to look up. Canonicalized server-side per AdCP URL canonicalization: the scheme and host fold, the path does not. */
                 agent_url: string;
                 /** @description `effective` (default) applies override layer; `raw` reads base table. */
                 include?: "raw" | "effective";

package/dist/lib/schemas-data/v2.5/_provenance.json

@@ -4,5 +4,5 @@
   "source_sha": "4e553ad955f83b49c7d221ab5c3ff78237ad02e3",
   "source_tarball_sha256": "580656d6466ef9f0d1119985e6726c2efea718dc671e2ad30957fcb2fd54af0f",
   "upstream_adcp_version": "2.5.3",
-  "synced_at": "2026-10-17T14:53:03.023Z"
+  "synced_at": "2026-10-19T00:55:30.097Z"
 }