@adcp/sdk 16.0.0-beta.6 → 16.0.0-beta.8

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

@@ -58,6 +58,45 @@ export interface TestOptions {
      * authoritative over the SDK's generated Zod snapshot for the run.
      */
     schemaRoot?: string;
+    /**
+     * Schema roots for releases the agent may echo in its
+     * `get_adcp_capabilities` response, keyed by AdCP version (`'3.2'`,
+     * `'3.2.5'`, `'3.3.0-beta.1'`). Values are schema-data roots in the same
+     * shape as `schemaRoot`.
+     *
+     * A 3.0 pin sends only `adcp_major_version`, so an agent may serve and echo
+     * a newer release in the same major (versioning spec, "Server echoes").
+     * The SDK validates that capabilities response against the echoed release
+     * when the echo is the pin's major, is listed in the response's
+     * `adcp.supported_versions`, and has a schema root: an entry here, an
+     * external root registered for it, or the SDK's bundled schemas. That
+     * applies to discovery's capability notices, `getAdcpCapabilities()` and
+     * storyboard `response_schema` checks on `get_adcp_capabilities`, including
+     * when `schemaRoot` is set for the pin. Otherwise validation stays on the
+     * pin.
+     *
+     * Entries are used for that capabilities validation only. Every other
+     * task's response, storyboard selection and grading stay on the pin. Each
+     * root is checked against its key once per process; a malformed map throws
+     * before the run starts. Honored by `comply()`, `runStoryboard()` and
+     * `runStoryboardStep()`; other callers can use `withServedReleaseSchemaRoots`.
+     * The echo is compared with the run's pin, so storyboard checks apply it
+     * only when the run has one (`adcpVersion`, or the storyboard or compliance
+     * bundle's `adcp_version`); `comply()` always does.
+     *
+     * @example
+     * ```ts
+     * await comply(agentUrl, {
+     *   complianceDir: hosted30.complianceDir,
+     *   schemaRoot: hosted30.schemaRoot,
+     *   servedReleaseSchemaRoots: {
+     *     '3.1.29': hosted31.schemaRoot,
+     *     '3.2.5': hosted32.schemaRoot,
+     *   },
+     * });
+     * ```
+     */
+    servedReleaseSchemaRoots?: Readonly<Record<string, string>>;
     /**
      * Whether strict AJV response-schema failures contribute to storyboard
      * grading. Defaults to `true`, matching the hosted compliance grader.

package/dist/lib/v2/projection/augment-response.js

@@ -224,7 +224,10 @@ function toCanonicalFormatOptionsWithRoutes(productId, formatOptions) {
 }
 function toAdditiveCanonicalProduct(product, options) {
   const { product: augmented, diagnostics } = augmentProductWithFormatOptions(product, options);
-  const projected = toCanonicalFormatOptionsWithRoutes(product.product_id, augmented.format_options);
+  const projected = toCanonicalFormatOptionsWithRoutes(
+    product.product_id,
+    options?._inferDualEmissionLegacyRefs === false ? augmented.format_options : (0, import_v1_to_v2.withDualEmissionLegacyRefs)(augmented.format_options, product.format_ids)
+  );
   return {
     product: {
       ...augmented,
@@ -299,13 +302,13 @@ function formatRefCoverageKey(ref) {
 function toCanonicalOnlyProduct(product, options) {
   const existing = product.format_options;
   if (Array.isArray(existing)) {
-    const formatOptions = existing;
+    const formatOptions = options?._inferDualEmissionLegacyRefs === false ? existing : (0, import_v1_to_v2.withDualEmissionLegacyRefs)(existing, product.format_ids);
     const diagnostics2 = [];
     const inputIds = Array.isArray(product.format_ids) ? product.format_ids : [];
     if (inputIds.length > 0) {
       const covered = /* @__PURE__ */ new Set();
       for (const opt of formatOptions) {
-        const refs = Array.isArray(opt?.v1_format_ref) ? opt.v1_format_ref : [];
+        const refs = (0, import_legacy_metadata.legacyFormatRefsForDeclaration)(opt);
         for (const ref of refs) covered.add(formatRefCoverageKey(ref));
       }
       for (let k = 0; k < inputIds.length; k++) {

package/dist/lib/v2/projection/augment-response.mjs

@@ -1,7 +1,7 @@
-import { projectV1ProductToV2 } from "./v1-to-v2.mjs";
+import { projectV1ProductToV2, withDualEmissionLegacyRefs } from "./v1-to-v2.mjs";
 import { LIBRARY_VERSION } from "../../version.mjs";
 import { canonicalize as canonicalizeJson } from "../../utils/jcs.mjs";
-import { concealLegacyFormatRefs } from "./legacy-metadata.mjs";
+import { concealLegacyFormatRefs, legacyFormatRefsForDeclaration } from "./legacy-metadata.mjs";
 import { legacyRoutesForProduct } from "./legacy-routes.mjs";
 const SDK_ID = `@adcp/sdk@${LIBRARY_VERSION}`;
 const DIRECT_LEGACY_FORMAT_IDENTITY_KEYS = /* @__PURE__ */ new Set(["agenturl", "formatid", "formatids", "v1formatref"]);
@@ -194,7 +194,10 @@ function toCanonicalFormatOptionsWithRoutes(productId, formatOptions) {
 }
 function toAdditiveCanonicalProduct(product, options) {
   const { product: augmented, diagnostics } = augmentProductWithFormatOptions(product, options);
-  const projected = toCanonicalFormatOptionsWithRoutes(product.product_id, augmented.format_options);
+  const projected = toCanonicalFormatOptionsWithRoutes(
+    product.product_id,
+    options?._inferDualEmissionLegacyRefs === false ? augmented.format_options : withDualEmissionLegacyRefs(augmented.format_options, product.format_ids)
+  );
   return {
     product: {
       ...augmented,
@@ -269,13 +272,13 @@ function formatRefCoverageKey(ref) {
 function toCanonicalOnlyProduct(product, options) {
   const existing = product.format_options;
   if (Array.isArray(existing)) {
-    const formatOptions = existing;
+    const formatOptions = options?._inferDualEmissionLegacyRefs === false ? existing : withDualEmissionLegacyRefs(existing, product.format_ids);
     const diagnostics2 = [];
     const inputIds = Array.isArray(product.format_ids) ? product.format_ids : [];
     if (inputIds.length > 0) {
       const covered = /* @__PURE__ */ new Set();
       for (const opt of formatOptions) {
-        const refs = Array.isArray(opt?.v1_format_ref) ? opt.v1_format_ref : [];
+        const refs = legacyFormatRefsForDeclaration(opt);
         for (const ref of refs) covered.add(formatRefCoverageKey(ref));
       }
       for (let k = 0; k < inputIds.length; k++) {

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

@@ -378,26 +378,15 @@ function candidatesFromContainer(container, canonicalFormatLegacyResolver, opera
     );
   }
   const candidates = [];
-  const containerKind = typeof container.format_kind === "string" ? container.format_kind : void 0;
-  for (const key of ["format_ids", "formats"]) {
-    for (const ref of refsFromValue(container[key])) {
-      candidates.push({
-        ref,
-        formatKind: (0, import_v1_to_v2.resolveCanonicalFormatKind)(ref.id) ?? containerKind,
-        selectorParams: container.params
-      });
-    }
-  }
-  const formatOptions = [
-    ...Array.isArray(container.format_options) ? container.format_options : [],
-    ...(0, import_legacy_metadata.selectedFormatOptions)(container)
-  ];
-  for (const optionValue of formatOptions) {
+  const nativeOptions = Array.isArray(container.format_options) ? container.format_options : [];
+  const formatOptions = [...nativeOptions, ...(0, import_legacy_metadata.selectedFormatOptions)(container)];
+  const resolvedOptions = formatOptions.map((optionValue) => {
     const option = record(optionValue);
-    if (!option) continue;
+    if (!option) return optionValue;
     const formatKind = typeof option.format_kind === "string" ? option.format_kind : void 0;
     const formatOptionRef = optionReference(option);
     let refs = [...(0, import_legacy_metadata.legacyFormatRefsForDeclaration)(option)];
+    if (refs.length > 0) return optionValue;
     if (refs.length === 0 && option.canonical_formats_only !== true && formatKind) {
       try {
         refs = (0, import_v2_to_v1.resolveCanonicalFormatLegacyRefs)(canonicalFormatLegacyResolver, {
@@ -415,10 +404,33 @@ function candidatesFromContainer(container, canonicalFormatLegacyResolver, opera
         );
       }
     }
-    for (const ref of refs) {
+    return refs.length > 0 ? { ...option, v1_format_ref: refs } : optionValue;
+  });
+  const pairedOptions = [
+    ...(0, import_v1_to_v2.withDualEmissionLegacyRefs)(resolvedOptions.slice(0, nativeOptions.length), container.format_ids),
+    ...resolvedOptions.slice(nativeOptions.length)
+  ];
+  for (const optionValue of pairedOptions) {
+    const option = record(optionValue);
+    if (!option) continue;
+    const formatKind = typeof option.format_kind === "string" ? option.format_kind : void 0;
+    const formatOptionRef = optionReference(option);
+    for (const ref of (0, import_legacy_metadata.legacyFormatRefsForDeclaration)(option)) {
       candidates.push({ ref, formatKind, formatOptionRef, selectorParams: option.params ?? container.params });
     }
   }
+  const linkedRefs = new Set(candidates.map((candidate) => candidateKey({ ref: candidate.ref })));
+  const containerKind = typeof container.format_kind === "string" ? container.format_kind : void 0;
+  for (const key of ["format_ids", "formats"]) {
+    for (const ref of refsFromValue(container[key])) {
+      if (linkedRefs.has(candidateKey({ ref }))) continue;
+      candidates.push({
+        ref,
+        formatKind: (0, import_v1_to_v2.resolveCanonicalFormatKind)(ref.id) ?? containerKind,
+        selectorParams: container.params
+      });
+    }
+  }
   return uniqueCandidates(candidates);
 }
 function containerOptsOutOfLegacy(container, formatKind, formatOptionRef) {

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

@@ -2,7 +2,8 @@ import {
   canonicalDeclarationFromBareId,
   migratedFormatOptionId,
   projectV1ProductToV2,
-  resolveCanonicalFormatKind
+  resolveCanonicalFormatKind,
+  withDualEmissionLegacyRefs
 } from "./v1-to-v2.mjs";
 import { CanonicalFormatLegacyResolutionError, resolveCanonicalFormatLegacyRefs } from "./v2-to-v1.mjs";
 import {
@@ -357,26 +358,15 @@ function candidatesFromContainer(container, canonicalFormatLegacyResolver, opera
     );
   }
   const candidates = [];
-  const containerKind = typeof container.format_kind === "string" ? container.format_kind : void 0;
-  for (const key of ["format_ids", "formats"]) {
-    for (const ref of refsFromValue(container[key])) {
-      candidates.push({
-        ref,
-        formatKind: resolveCanonicalFormatKind(ref.id) ?? containerKind,
-        selectorParams: container.params
-      });
-    }
-  }
-  const formatOptions = [
-    ...Array.isArray(container.format_options) ? container.format_options : [],
-    ...selectedFormatOptions(container)
-  ];
-  for (const optionValue of formatOptions) {
+  const nativeOptions = Array.isArray(container.format_options) ? container.format_options : [];
+  const formatOptions = [...nativeOptions, ...selectedFormatOptions(container)];
+  const resolvedOptions = formatOptions.map((optionValue) => {
     const option = record(optionValue);
-    if (!option) continue;
+    if (!option) return optionValue;
     const formatKind = typeof option.format_kind === "string" ? option.format_kind : void 0;
     const formatOptionRef = optionReference(option);
     let refs = [...legacyFormatRefsForDeclaration(option)];
+    if (refs.length > 0) return optionValue;
     if (refs.length === 0 && option.canonical_formats_only !== true && formatKind) {
       try {
         refs = resolveCanonicalFormatLegacyRefs(canonicalFormatLegacyResolver, {
@@ -394,10 +384,33 @@ function candidatesFromContainer(container, canonicalFormatLegacyResolver, opera
         );
       }
     }
-    for (const ref of refs) {
+    return refs.length > 0 ? { ...option, v1_format_ref: refs } : optionValue;
+  });
+  const pairedOptions = [
+    ...withDualEmissionLegacyRefs(resolvedOptions.slice(0, nativeOptions.length), container.format_ids),
+    ...resolvedOptions.slice(nativeOptions.length)
+  ];
+  for (const optionValue of pairedOptions) {
+    const option = record(optionValue);
+    if (!option) continue;
+    const formatKind = typeof option.format_kind === "string" ? option.format_kind : void 0;
+    const formatOptionRef = optionReference(option);
+    for (const ref of legacyFormatRefsForDeclaration(option)) {
       candidates.push({ ref, formatKind, formatOptionRef, selectorParams: option.params ?? container.params });
     }
   }
+  const linkedRefs = new Set(candidates.map((candidate) => candidateKey({ ref: candidate.ref })));
+  const containerKind = typeof container.format_kind === "string" ? container.format_kind : void 0;
+  for (const key of ["format_ids", "formats"]) {
+    for (const ref of refsFromValue(container[key])) {
+      if (linkedRefs.has(candidateKey({ ref }))) continue;
+      candidates.push({
+        ref,
+        formatKind: resolveCanonicalFormatKind(ref.id) ?? containerKind,
+        selectorParams: container.params
+      });
+    }
+  }
   return uniqueCandidates(candidates);
 }
 function containerOptsOutOfLegacy(container, formatKind, formatOptionRef) {

package/dist/lib/v2/projection/v1-to-v2.d.mts

@@ -211,3 +211,10 @@ export declare function canonicalDeclarationFromBareId(id: string, options?: Bar
  * the `agentUrl` default, and the `assetType` disambiguator.
  */
 export declare function resolveCanonicalFormatKind(id: string, options?: BareFormatIdResolveOptions): CanonicalFormatKind | null;
+/**
+ * Preserve index pairing only when the whole seller-authored alignment is credible.
+ * AdCP 3.1.24 core/product.json defines this correspondence: "the format_options[i]
+ * narrows the canonical that the named format in format_ids[i] resolves to via the
+ * registry / explicit canonical field". Explicit routes remain authoritative.
+ */
+export declare function withDualEmissionLegacyRefs<T>(formatOptions: T[], formatIds: unknown): T[];

package/dist/lib/v2/projection/v1-to-v2.d.ts

@@ -211,3 +211,10 @@ export declare function canonicalDeclarationFromBareId(id: string, options?: Bar
  * the `agentUrl` default, and the `assetType` disambiguator.
  */
 export declare function resolveCanonicalFormatKind(id: string, options?: BareFormatIdResolveOptions): CanonicalFormatKind | null;
+/**
+ * Preserve index pairing only when the whole seller-authored alignment is credible.
+ * AdCP 3.1.24 core/product.json defines this correspondence: "the format_options[i]
+ * narrows the canonical that the named format in format_ids[i] resolves to via the
+ * registry / explicit canonical field". Explicit routes remain authoritative.
+ */
+export declare function withDualEmissionLegacyRefs<T>(formatOptions: T[], formatIds: unknown): T[];

package/dist/lib/v2/projection/v1-to-v2.js

@@ -21,7 +21,8 @@ __export(v1_to_v2_exports, {
   canonicalDeclarationFromBareId: () => canonicalDeclarationFromBareId,
   migratedFormatOptionId: () => migratedFormatOptionId,
   projectV1ProductToV2: () => projectV1ProductToV2,
-  resolveCanonicalFormatKind: () => resolveCanonicalFormatKind
+  resolveCanonicalFormatKind: () => resolveCanonicalFormatKind,
+  withDualEmissionLegacyRefs: () => withDualEmissionLegacyRefs
 });
 module.exports = __toCommonJS(v1_to_v2_exports);
 var import_registry = require('./registry.js');
@@ -33,6 +34,7 @@ var import_resolve_agent_properties = require('../../discovery/resolve-agent-pro
 var import_address_guards = require('../../net/address-guards.js');
 var import_crypto = require("crypto");
 var import_legacy_routes = require('./legacy-routes.js');
+var import_legacy_metadata = require('./legacy-metadata.js');
 const SDK_ID = `@adcp/sdk@${import_version.LIBRARY_VERSION}`;
 class CatalogRequirementConflict extends Error {
 }
@@ -367,10 +369,76 @@ function normalizeAssetTypeSuffix(hint) {
 function resolveCanonicalFormatKind(id, options) {
   return canonicalDeclarationFromBareId(id, options)?.format_kind ?? null;
 }
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function sameIdentity(left, right) {
+  const url = (value) => {
+    try {
+      return new URL(value).href;
+    } catch {
+      return value;
+    }
+  };
+  return url(left.agent_url) === url(right.agent_url) && left.id === right.id && ["width", "height", "duration_ms"].every((key) => {
+    const field = key;
+    return left[field] === void 0 || right[field] === void 0 || left[field] === right[field];
+  });
+}
+function compatible(option, ref) {
+  const known = canonicalDeclarationFromBareId(ref.id, { agentUrl: ref.agent_url });
+  if (known && known.format_kind !== option.format_kind) return false;
+  const params = record(option.params) ?? {};
+  const knownParams = record(known?.params) ?? {};
+  const constraints = {
+    width: ref.width ?? knownParams.width,
+    height: ref.height ?? knownParams.height,
+    duration_ms_exact: ref.duration_ms ?? knownParams.duration_ms_exact
+  };
+  if (Object.entries(constraints).some(
+    ([key, value]) => typeof value === "number" && typeof params[key] === "number" && value !== params[key]
+  )) {
+    return false;
+  }
+  if (Array.isArray(params.sizes) && params.sizes.length > 0) {
+    return params.sizes.some((value) => {
+      const size = record(value);
+      return size && ["width", "height"].every((key) => {
+        const actual = constraints[key];
+        return typeof actual !== "number" || typeof size[key] !== "number" || actual === size[key];
+      });
+    });
+  }
+  return true;
+}
+function withDualEmissionLegacyRefs(formatOptions, formatIds) {
+  if (!Array.isArray(formatIds) || formatIds.length !== formatOptions.length) return formatOptions;
+  const aligned = formatOptions.every((value, index) => {
+    const option = record(value);
+    const ref = record(formatIds[index]);
+    if (!option || typeof option.format_kind !== "string" || option.canonical_formats_only === true || !ref || typeof ref.agent_url !== "string" || ref.agent_url.length === 0 || typeof ref.id !== "string" || ref.id.length === 0) {
+      return false;
+    }
+    const typedRef = ref;
+    const explicit = (0, import_legacy_metadata.legacyFormatRefsForDeclaration)(option);
+    return explicit.length > 0 ? explicit.some((existing) => sameIdentity(existing, typedRef)) : compatible(option, typedRef);
+  });
+  if (!aligned) return formatOptions;
+  return formatOptions.map((value, index) => {
+    if ((0, import_legacy_metadata.legacyFormatRefsForDeclaration)(value).length > 0) return value;
+    const paired = (0, import_legacy_metadata.concealLegacyFormatRefs)({
+      ...value,
+      v1_format_ref: [{ ...formatIds[index] }]
+    });
+    (0, import_legacy_metadata.transferLegacyCreativeMetadata)(value, paired);
+    return paired;
+  });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   canonicalDeclarationFromBareId,
   migratedFormatOptionId,
   projectV1ProductToV2,
-  resolveCanonicalFormatKind
+  resolveCanonicalFormatKind,
+  withDualEmissionLegacyRefs
 });

package/dist/lib/v2/projection/v1-to-v2.mjs

@@ -12,6 +12,11 @@ import { canonicalizeAgentUrl } from "../../discovery/resolve-agent-properties.m
 import { isLikelyPrivateUrl } from "../../net/address-guards.mjs";
 import { createHmac } from "crypto";
 import { legacyRoutesForProduct } from "./legacy-routes.mjs";
+import {
+  concealLegacyFormatRefs,
+  legacyFormatRefsForDeclaration,
+  transferLegacyCreativeMetadata
+} from "./legacy-metadata.mjs";
 const SDK_ID = `@adcp/sdk@${LIBRARY_VERSION}`;
 class CatalogRequirementConflict extends Error {
 }
@@ -346,9 +351,75 @@ function normalizeAssetTypeSuffix(hint) {
 function resolveCanonicalFormatKind(id, options) {
   return canonicalDeclarationFromBareId(id, options)?.format_kind ?? null;
 }
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function sameIdentity(left, right) {
+  const url = (value) => {
+    try {
+      return new URL(value).href;
+    } catch {
+      return value;
+    }
+  };
+  return url(left.agent_url) === url(right.agent_url) && left.id === right.id && ["width", "height", "duration_ms"].every((key) => {
+    const field = key;
+    return left[field] === void 0 || right[field] === void 0 || left[field] === right[field];
+  });
+}
+function compatible(option, ref) {
+  const known = canonicalDeclarationFromBareId(ref.id, { agentUrl: ref.agent_url });
+  if (known && known.format_kind !== option.format_kind) return false;
+  const params = record(option.params) ?? {};
+  const knownParams = record(known?.params) ?? {};
+  const constraints = {
+    width: ref.width ?? knownParams.width,
+    height: ref.height ?? knownParams.height,
+    duration_ms_exact: ref.duration_ms ?? knownParams.duration_ms_exact
+  };
+  if (Object.entries(constraints).some(
+    ([key, value]) => typeof value === "number" && typeof params[key] === "number" && value !== params[key]
+  )) {
+    return false;
+  }
+  if (Array.isArray(params.sizes) && params.sizes.length > 0) {
+    return params.sizes.some((value) => {
+      const size = record(value);
+      return size && ["width", "height"].every((key) => {
+        const actual = constraints[key];
+        return typeof actual !== "number" || typeof size[key] !== "number" || actual === size[key];
+      });
+    });
+  }
+  return true;
+}
+function withDualEmissionLegacyRefs(formatOptions, formatIds) {
+  if (!Array.isArray(formatIds) || formatIds.length !== formatOptions.length) return formatOptions;
+  const aligned = formatOptions.every((value, index) => {
+    const option = record(value);
+    const ref = record(formatIds[index]);
+    if (!option || typeof option.format_kind !== "string" || option.canonical_formats_only === true || !ref || typeof ref.agent_url !== "string" || ref.agent_url.length === 0 || typeof ref.id !== "string" || ref.id.length === 0) {
+      return false;
+    }
+    const typedRef = ref;
+    const explicit = legacyFormatRefsForDeclaration(option);
+    return explicit.length > 0 ? explicit.some((existing) => sameIdentity(existing, typedRef)) : compatible(option, typedRef);
+  });
+  if (!aligned) return formatOptions;
+  return formatOptions.map((value, index) => {
+    if (legacyFormatRefsForDeclaration(value).length > 0) return value;
+    const paired = concealLegacyFormatRefs({
+      ...value,
+      v1_format_ref: [{ ...formatIds[index] }]
+    });
+    transferLegacyCreativeMetadata(value, paired);
+    return paired;
+  });
+}
 export {
   canonicalDeclarationFromBareId,
   migratedFormatOptionId,
   projectV1ProductToV2,
-  resolveCanonicalFormatKind
+  resolveCanonicalFormatKind,
+  withDualEmissionLegacyRefs
 };

package/dist/lib/validation/index.d.mts

@@ -6,7 +6,7 @@ export { validateRequest, validateResponse, formatIssues } from './schema-valida
 export type { ValidationIssue, ValidationOutcome } from './schema-validator.mjs';
 export { buildValidationError, buildAdcpValidationErrorPayload } from './schema-errors.mjs';
 export type { ValidationErrorDetails, AdcpValidationErrorDetails } from './schema-errors.mjs';
-export { getValidator, listValidatorKeys, resolveBundleKey, hasSchemaBundle, registerExternalSchemaRoot, unregisterExternalSchemaRoot, withExternalSchemaRoot, } from './schema-loader.mjs';
+export { getValidator, listValidatorKeys, resolveBundleKey, hasSchemaBundle, registerExternalSchemaRoot, unregisterExternalSchemaRoot, withExternalSchemaRoot, withServedReleaseSchemaRoots, } from './schema-loader.mjs';
 export type { Direction, ResponseVariant } from './schema-loader.mjs';
 export { validateOutgoingRequest, validateIncomingResponse, resolveValidationModes } from './client-hooks.mjs';
 export type { ValidationMode, ValidationHookConfig } from './client-hooks.mjs';

package/dist/lib/validation/index.d.ts

@@ -6,7 +6,7 @@ export { validateRequest, validateResponse, formatIssues } from './schema-valida
 export type { ValidationIssue, ValidationOutcome } from './schema-validator';
 export { buildValidationError, buildAdcpValidationErrorPayload } from './schema-errors';
 export type { ValidationErrorDetails, AdcpValidationErrorDetails } from './schema-errors';
-export { getValidator, listValidatorKeys, resolveBundleKey, hasSchemaBundle, registerExternalSchemaRoot, unregisterExternalSchemaRoot, withExternalSchemaRoot, } from './schema-loader';
+export { getValidator, listValidatorKeys, resolveBundleKey, hasSchemaBundle, registerExternalSchemaRoot, unregisterExternalSchemaRoot, withExternalSchemaRoot, withServedReleaseSchemaRoots, } from './schema-loader';
 export type { Direction, ResponseVariant } from './schema-loader';
 export { validateOutgoingRequest, validateIncomingResponse, resolveValidationModes } from './client-hooks';
 export type { ValidationMode, ValidationHookConfig } from './client-hooks';

package/dist/lib/validation/index.js

@@ -36,7 +36,8 @@ __export(validation_exports, {
   validateOutgoingRequest: () => import_client_hooks.validateOutgoingRequest,
   validateRequest: () => import_schema_validator.validateRequest,
   validateResponse: () => import_schema_validator.validateResponse,
-  withExternalSchemaRoot: () => import_schema_loader.withExternalSchemaRoot
+  withExternalSchemaRoot: () => import_schema_loader.withExternalSchemaRoot,
+  withServedReleaseSchemaRoots: () => import_schema_loader.withServedReleaseSchemaRoots
 });
 module.exports = __toCommonJS(validation_exports);
 var import_probe_policy = require('../utils/probe-policy.js');
@@ -201,5 +202,6 @@ async function handleAdCPResponse(response, expectedSchema, agentName) {
   validateOutgoingRequest,
   validateRequest,
   validateResponse,
-  withExternalSchemaRoot
+  withExternalSchemaRoot,
+  withServedReleaseSchemaRoots
 });

package/dist/lib/validation/index.mjs

@@ -8,7 +8,8 @@ import {
   hasSchemaBundle,
   registerExternalSchemaRoot,
   unregisterExternalSchemaRoot,
-  withExternalSchemaRoot
+  withExternalSchemaRoot,
+  withServedReleaseSchemaRoots
 } from "./schema-loader.mjs";
 import { validateOutgoingRequest, validateIncomingResponse, resolveValidationModes } from "./client-hooks.mjs";
 function getExpectedSchema(toolName) {
@@ -167,5 +168,6 @@ export {
   validateOutgoingRequest,
   validateRequest,
   validateResponse,
-  withExternalSchemaRoot
+  withExternalSchemaRoot,
+  withServedReleaseSchemaRoots
 };

package/dist/lib/validation/schema-loader.d.mts

@@ -170,6 +170,32 @@ export { SCHEMA_FILENAME_SUFFIX };
  * we don't have schemas for.
  */
 export declare function hasSchemaBundle(version: string): boolean;
+/**
+ * Run `fn` with schema roots for the releases an agent may echo in its
+ * `get_adcp_capabilities` response.
+ *
+ * Keys are AdCP versions in any form the SDK accepts for a pin (`'3.2'`,
+ * `'3.2.5'`, `'3.3.0-beta.1'`); values are schema-data roots in the same
+ * shape as `schemaRoot` (a directory holding `bundled/`, e.g. a hosted
+ * `dist/schemas/3.2.5`). Each root is checked against its key the same way
+ * `withExternalSchemaRoot` checks one, and a malformed map throws before `fn`
+ * runs.
+ *
+ * The roots are consulted only when validating a `get_adcp_capabilities`
+ * response against the release the agent echoed (see
+ * {@link resolveServedValidationVersion}): discovery's capability notices,
+ * `getAdcpCapabilities()` response validation and storyboard
+ * `response_schema` checks on that task. They are not activated for any other
+ * task, so every other response, storyboard selection and grading stay on the
+ * pin. A supplied root takes precedence over an external root registered for
+ * the same release and over the SDK's bundled schemas for it.
+ *
+ * Scoped to the current async execution chain; nested calls add to the
+ * enclosing scope, with the innermost entry for a release winning.
+ * `comply()` and `runStoryboard()` accept the same map as
+ * `servedReleaseSchemaRoots` and call this for you.
+ */
+export declare function withServedReleaseSchemaRoots<T>(roots: Readonly<Record<string, string>> | undefined, fn: () => T): T;
 /** Load the exact self-contained request projection from an MCP role profile. */
 export declare function getMcpProfileInputSchema(toolName: string, profile: string, version?: string): Readonly<Record<string, unknown>> | undefined;
 /**

package/dist/lib/validation/schema-loader.d.ts

@@ -170,6 +170,32 @@ export { SCHEMA_FILENAME_SUFFIX };
  * we don't have schemas for.
  */
 export declare function hasSchemaBundle(version: string): boolean;
+/**
+ * Run `fn` with schema roots for the releases an agent may echo in its
+ * `get_adcp_capabilities` response.
+ *
+ * Keys are AdCP versions in any form the SDK accepts for a pin (`'3.2'`,
+ * `'3.2.5'`, `'3.3.0-beta.1'`); values are schema-data roots in the same
+ * shape as `schemaRoot` (a directory holding `bundled/`, e.g. a hosted
+ * `dist/schemas/3.2.5`). Each root is checked against its key the same way
+ * `withExternalSchemaRoot` checks one, and a malformed map throws before `fn`
+ * runs.
+ *
+ * The roots are consulted only when validating a `get_adcp_capabilities`
+ * response against the release the agent echoed (see
+ * {@link resolveServedValidationVersion}): discovery's capability notices,
+ * `getAdcpCapabilities()` response validation and storyboard
+ * `response_schema` checks on that task. They are not activated for any other
+ * task, so every other response, storyboard selection and grading stay on the
+ * pin. A supplied root takes precedence over an external root registered for
+ * the same release and over the SDK's bundled schemas for it.
+ *
+ * Scoped to the current async execution chain; nested calls add to the
+ * enclosing scope, with the innermost entry for a release winning.
+ * `comply()` and `runStoryboard()` accept the same map as
+ * `servedReleaseSchemaRoots` and call this for you.
+ */
+export declare function withServedReleaseSchemaRoots<T>(roots: Readonly<Record<string, string>> | undefined, fn: () => T): T;
 /** Load the exact self-contained request projection from an MCP role profile. */
 export declare function getMcpProfileInputSchema(toolName: string, profile: string, version?: string): Readonly<Record<string, unknown>> | undefined;
 /**