@adcp/sdk 15.9.4 → 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/TaskExecutor.d.mts

@@ -435,6 +435,7 @@ export declare class TaskExecutor {
      * AJV runs.
      */
     private validateResponseSchema;
+    private validateResponseSchemaAgainst;
     private responseAdcpVersionForValidation;
     private effectiveResponseAdcpVersion;
     /**

package/dist/lib/core/TaskExecutor.d.ts

@@ -435,6 +435,7 @@ export declare class TaskExecutor {
      * AJV runs.
      */
     private validateResponseSchema;
+    private validateResponseSchemaAgainst;
     private responseAdcpVersionForValidation;
     private effectiveResponseAdcpVersion;
     /**

package/dist/lib/core/TaskExecutor.js

@@ -4398,41 +4398,22 @@ class TaskExecutor {
     const mode = this.responseValidationMode;
     const logViolations = this.config.logSchemaViolations !== false;
     try {
-      let validationVersion = (serverVersion ?? this.lastKnownServerVersion) === "v2" ? "v2.5" : this.responseAdcpVersionForValidation() ?? this.config.adcpVersion ?? import_version.ADCP_VERSION;
-      if (taskName === "get_adcp_capabilities" && validationVersion !== "v2.5") {
-        validationVersion = (0, import_schema_loader.resolveServedValidationVersion)(response, validationVersion);
-      }
-      const normalizedResponse = this.normalizeResponseForValidation(response, taskName, validationVersion === "v2.5");
-      const outcome = (0, import_client_hooks.validateIncomingResponse)(taskName, normalizedResponse, mode, void 0, validationVersion);
-      if (outcome.valid) return { valid: true, errors: [] };
-      const errorStrings = outcome.issues.map((i) => `${i.pointer}: ${i.message}`);
-      if (logViolations) {
-        debugLogs.push({
-          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-          type: mode === "strict" ? "error" : "warning",
-          message: `Schema validation ${mode === "strict" ? "failed" : "warning"} for ${taskName}: ${(0, import_schema_validator.formatIssues)(
-            outcome.issues
-          )}`,
-          errors: errorStrings,
-          issues: outcome.issues,
-          schemaVariant: outcome.variant,
-          schemaVersion: validationVersion,
-          mode
-        });
-      }
-      if (mode === "warn") {
-        if (logViolations) {
-          console.warn(
-            `Schema validation failed for ${taskName} against AdCP ${validationVersion} (non-blocking):`,
-            errorStrings
-          );
-        }
-        return { valid: true, errors: [] };
-      }
-      if (logViolations) {
-        console.error(`Schema validation failed for ${taskName} against AdCP ${validationVersion}:`, errorStrings);
+      const pinnedValidationVersion = (serverVersion ?? this.lastKnownServerVersion) === "v2" ? "v2.5" : this.responseAdcpVersionForValidation() ?? this.config.adcpVersion ?? import_version.ADCP_VERSION;
+      if (taskName === "get_adcp_capabilities" && pinnedValidationVersion !== "v2.5") {
+        return (0, import_schema_loader.withServedValidationVersion)(
+          response,
+          pinnedValidationVersion,
+          (validationVersion) => this.validateResponseSchemaAgainst(response, taskName, debugLogs, mode, logViolations, validationVersion)
+        );
       }
-      return { valid: false, errors: errorStrings };
+      return this.validateResponseSchemaAgainst(
+        response,
+        taskName,
+        debugLogs,
+        mode,
+        logViolations,
+        pinnedValidationVersion
+      );
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : "unknown error";
       console.error("Error during schema validation:", errorMessage);
@@ -4442,6 +4423,39 @@ class TaskExecutor {
       };
     }
   }
+  validateResponseSchemaAgainst(response, taskName, debugLogs, mode, logViolations, validationVersion) {
+    const normalizedResponse = this.normalizeResponseForValidation(response, taskName, validationVersion === "v2.5");
+    const outcome = (0, import_client_hooks.validateIncomingResponse)(taskName, normalizedResponse, mode, void 0, validationVersion);
+    if (outcome.valid) return { valid: true, errors: [] };
+    const errorStrings = outcome.issues.map((i) => `${i.pointer}: ${i.message}`);
+    if (logViolations) {
+      debugLogs.push({
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        type: mode === "strict" ? "error" : "warning",
+        message: `Schema validation ${mode === "strict" ? "failed" : "warning"} for ${taskName}: ${(0, import_schema_validator.formatIssues)(
+          outcome.issues
+        )}`,
+        errors: errorStrings,
+        issues: outcome.issues,
+        schemaVariant: outcome.variant,
+        schemaVersion: validationVersion,
+        mode
+      });
+    }
+    if (mode === "warn") {
+      if (logViolations) {
+        console.warn(
+          `Schema validation failed for ${taskName} against AdCP ${validationVersion} (non-blocking):`,
+          errorStrings
+        );
+      }
+      return { valid: true, errors: [] };
+    }
+    if (logViolations) {
+      console.error(`Schema validation failed for ${taskName} against AdCP ${validationVersion}:`, errorStrings);
+    }
+    return { valid: false, errors: errorStrings };
+  }
   responseAdcpVersionForValidation() {
     if (this.config.versionEnvelope === "major-only") return "3.0";
     return void 0;

package/dist/lib/core/TaskExecutor.mjs

@@ -15,7 +15,7 @@ import {
   resolveValidationModes
 } from "../validation/client-hooks.mjs";
 import { formatIssues } from "../validation/schema-validator.mjs";
-import { resolveServedValidationVersion } from "../validation/schema-loader.mjs";
+import { withServedValidationVersion } from "../validation/schema-loader.mjs";
 import { ADCP_VERSION } from "../version.mjs";
 import { unwrapProtocolResponse, isAdcpOperationSuccess } from "../utils/response-unwrapper.mjs";
 import { extractAdcpErrorInfo, extractCorrelationId } from "../utils/error-extraction.mjs";
@@ -4371,41 +4371,22 @@ class TaskExecutor {
     const mode = this.responseValidationMode;
     const logViolations = this.config.logSchemaViolations !== false;
     try {
-      let validationVersion = (serverVersion ?? this.lastKnownServerVersion) === "v2" ? "v2.5" : this.responseAdcpVersionForValidation() ?? this.config.adcpVersion ?? ADCP_VERSION;
-      if (taskName === "get_adcp_capabilities" && validationVersion !== "v2.5") {
-        validationVersion = resolveServedValidationVersion(response, validationVersion);
-      }
-      const normalizedResponse = this.normalizeResponseForValidation(response, taskName, validationVersion === "v2.5");
-      const outcome = validateIncomingResponse(taskName, normalizedResponse, mode, void 0, validationVersion);
-      if (outcome.valid) return { valid: true, errors: [] };
-      const errorStrings = outcome.issues.map((i) => `${i.pointer}: ${i.message}`);
-      if (logViolations) {
-        debugLogs.push({
-          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-          type: mode === "strict" ? "error" : "warning",
-          message: `Schema validation ${mode === "strict" ? "failed" : "warning"} for ${taskName}: ${formatIssues(
-            outcome.issues
-          )}`,
-          errors: errorStrings,
-          issues: outcome.issues,
-          schemaVariant: outcome.variant,
-          schemaVersion: validationVersion,
-          mode
-        });
-      }
-      if (mode === "warn") {
-        if (logViolations) {
-          console.warn(
-            `Schema validation failed for ${taskName} against AdCP ${validationVersion} (non-blocking):`,
-            errorStrings
-          );
-        }
-        return { valid: true, errors: [] };
-      }
-      if (logViolations) {
-        console.error(`Schema validation failed for ${taskName} against AdCP ${validationVersion}:`, errorStrings);
+      const pinnedValidationVersion = (serverVersion ?? this.lastKnownServerVersion) === "v2" ? "v2.5" : this.responseAdcpVersionForValidation() ?? this.config.adcpVersion ?? ADCP_VERSION;
+      if (taskName === "get_adcp_capabilities" && pinnedValidationVersion !== "v2.5") {
+        return withServedValidationVersion(
+          response,
+          pinnedValidationVersion,
+          (validationVersion) => this.validateResponseSchemaAgainst(response, taskName, debugLogs, mode, logViolations, validationVersion)
+        );
       }
-      return { valid: false, errors: errorStrings };
+      return this.validateResponseSchemaAgainst(
+        response,
+        taskName,
+        debugLogs,
+        mode,
+        logViolations,
+        pinnedValidationVersion
+      );
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : "unknown error";
       console.error("Error during schema validation:", errorMessage);
@@ -4415,6 +4396,39 @@ class TaskExecutor {
       };
     }
   }
+  validateResponseSchemaAgainst(response, taskName, debugLogs, mode, logViolations, validationVersion) {
+    const normalizedResponse = this.normalizeResponseForValidation(response, taskName, validationVersion === "v2.5");
+    const outcome = validateIncomingResponse(taskName, normalizedResponse, mode, void 0, validationVersion);
+    if (outcome.valid) return { valid: true, errors: [] };
+    const errorStrings = outcome.issues.map((i) => `${i.pointer}: ${i.message}`);
+    if (logViolations) {
+      debugLogs.push({
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        type: mode === "strict" ? "error" : "warning",
+        message: `Schema validation ${mode === "strict" ? "failed" : "warning"} for ${taskName}: ${formatIssues(
+          outcome.issues
+        )}`,
+        errors: errorStrings,
+        issues: outcome.issues,
+        schemaVariant: outcome.variant,
+        schemaVersion: validationVersion,
+        mode
+      });
+    }
+    if (mode === "warn") {
+      if (logViolations) {
+        console.warn(
+          `Schema validation failed for ${taskName} against AdCP ${validationVersion} (non-blocking):`,
+          errorStrings
+        );
+      }
+      return { valid: true, errors: [] };
+    }
+    if (logViolations) {
+      console.error(`Schema validation failed for ${taskName} against AdCP ${validationVersion}:`, errorStrings);
+    }
+    return { valid: false, errors: errorStrings };
+  }
   responseAdcpVersionForValidation() {
     if (this.config.versionEnvelope === "major-only") return "3.0";
     return void 0;

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'];