@adcp/sdk 15.9.3 → 15.9.5

package/dist/lib/testing/storyboard/validations.mjs

@@ -2,7 +2,11 @@ import { prepareResponseForSchemaValidation, TOOL_RESPONSE_SCHEMAS } from "../..
 import { injectLegacyEnvelopeStatus } from "../../utils/envelope-status-compat.mjs";
 import { TRANSPORT_SUFFIX_REGEX } from "../../utils/a2a-discovery.mjs";
 import { validateResponse } from "../../validation/schema-validator.mjs";
-import { hasSchemaBundle, isExternalSchemaRootActive } from "../../validation/schema-loader.mjs";
+import {
+  hasSchemaBundle,
+  isExternalSchemaRootActive,
+  withServedValidationVersion
+} from "../../validation/schema-loader.mjs";
 import { ADCP_VERSION, LIBRARY_VERSION } from "../../version.mjs";
 import { isPre31AdcpVersion } from "../../utils/adcp-version-config.mjs";
 import { gte as semverGte, valid as validSemver } from "semver";
@@ -234,6 +238,21 @@ function mapZodIssueToSchemaKeyword(issue) {
   }
 }
 function validateResponseSchema(validation, ctx, taskResult) {
+  const pinnedVersion = ctx.adcpVersion;
+  if (ctx.taskName === "get_adcp_capabilities" && pinnedVersion !== void 0) {
+    return withServedValidationVersion(
+      taskResult.data,
+      pinnedVersion,
+      (validationVersion) => validateResponseSchemaForVersion(
+        validation,
+        validationVersion === pinnedVersion ? ctx : { ...ctx, adcpVersion: validationVersion, responseAdcpVersion: validationVersion },
+        taskResult
+      )
+    );
+  }
+  return validateResponseSchemaForVersion(validation, ctx, taskResult);
+}
+function validateResponseSchemaForVersion(validation, ctx, taskResult) {
   const taskName = ctx.taskName;
   const schemaIdentityVersion = ctx.adcpVersion ?? ctx.responseAdcpVersion ?? ADCP_VERSION;
   const { schema_id, schema_url } = resolveSchemaIdentity(ctx.responseSchemaRef, schemaIdentityVersion);
@@ -331,7 +350,14 @@ function validateResponseSchema(validation, ctx, taskResult) {
 }
 function isExternalResponseSchemaAuthoritative(ctx) {
   const validationVersion = responseSchemaValidationVersion(ctx.adcpVersion, ctx.responseAdcpVersion);
-  return validationVersion !== void 0 && isExternalSchemaRootActive(validationVersion);
+  if (validationVersion !== void 0 && isExternalSchemaRootActive(validationVersion)) return true;
+  const pinnedVersion = ctx.adcpVersion;
+  if (ctx.taskName !== "get_adcp_capabilities" || pinnedVersion === void 0 || !ctx.taskResult) return false;
+  return withServedValidationVersion(
+    ctx.taskResult.data,
+    pinnedVersion,
+    (version) => version !== pinnedVersion && isExternalSchemaRootActive(version)
+  );
 }
 function responseSchemaValidationVersion(adcpVersion, responseAdcpVersion) {
   if (adcpVersion && isExternalSchemaRootActive(adcpVersion)) return adcpVersion;

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

@@ -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/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/types/manifest.generated.d.mts

@@ -1,5 +1,5 @@
 /**
- * Manifest-derived constants for AdCP 3.2.4.
+ * Manifest-derived constants for AdCP 3.2.5.
  *
  * Single source of truth for tool↔protocol grouping, error-code metadata
  * (description + recovery + suggestion), and specialism→required-tools
@@ -9,8 +9,8 @@
  * previously lived in `src/lib/utils/capabilities.ts` and
  * `src/lib/types/error-codes.ts`.
  *
- * Source: `schemas/cache/3.2.4/manifest.json` (adcp_version: 3.2.4, generated_at:
- * 2026-10-11T21:23:01.435Z). Re-run `npm run sync-schemas` then
+ * Source: `schemas/cache/3.2.5/manifest.json` (adcp_version: 3.2.5, generated_at:
+ * 2026-10-16T16:46:24.874Z). Re-run `npm run sync-schemas` then
  * `npm run generate-manifest-derived` to refresh after a spec bump.
  */
 export type ErrorRecovery = 'transient' | 'correctable' | 'terminal';

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

@@ -1,5 +1,5 @@
 /**
- * Manifest-derived constants for AdCP 3.2.4.
+ * Manifest-derived constants for AdCP 3.2.5.
  *
  * Single source of truth for tool↔protocol grouping, error-code metadata
  * (description + recovery + suggestion), and specialism→required-tools
@@ -9,8 +9,8 @@
  * previously lived in `src/lib/utils/capabilities.ts` and
  * `src/lib/types/error-codes.ts`.
  *
- * Source: `schemas/cache/3.2.4/manifest.json` (adcp_version: 3.2.4, generated_at:
- * 2026-10-11T21:23:01.435Z). Re-run `npm run sync-schemas` then
+ * Source: `schemas/cache/3.2.5/manifest.json` (adcp_version: 3.2.5, generated_at:
+ * 2026-10-16T16:46:24.874Z). Re-run `npm run sync-schemas` then
  * `npm run generate-manifest-derived` to refresh after a spec bump.
  */
 export type ErrorRecovery = 'transient' | 'correctable' | 'terminal';

package/dist/lib/types/per-tool-index.json

@@ -1,6 +1,6 @@
 {
   "$comment": "Index of per-tool .d.ts slices shipped under @adcp/sdk/types/<tool>. Agentic adopters use this to resolve spec snake_case tool names to the kebab-case subpath.",
-  "version": "3.2.4",
+  "version": "3.2.5",
   "tools": {
     "accept_proposal": {
       "subpath": "@adcp/sdk/types/accept-proposal",

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

@@ -168,6 +168,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

@@ -168,6 +168,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.js

@@ -51,7 +51,9 @@ __export(schema_loader_exports, {
   toReleasePrecisionWire: () => toReleasePrecisionWire,
   unregisterExternalSchemaRoot: () => unregisterExternalSchemaRoot,
   validateAdcpVersionWire: () => validateAdcpVersionWire,
-  withExternalSchemaRoot: () => withExternalSchemaRoot
+  withExternalSchemaRoot: () => withExternalSchemaRoot,
+  withServedReleaseSchemaRoots: () => withServedReleaseSchemaRoots,
+  withServedValidationVersion: () => withServedValidationVersion
 });
 module.exports = __toCommonJS(schema_loader_exports);
 var import_ajv = __toESM(require("ajv"));
@@ -719,28 +721,108 @@ function hasSchemaBundle(version) {
     return false;
   }
 }
-const SERVED_RELEASE_MAJOR = /^(\d+)\.\d+(?:-[a-zA-Z0-9.-]+)?$/;
-const NUMERIC_PIN_MAJOR = /^(\d+)\.\d+/;
-function resolveServedValidationVersion(response, pinnedVersion) {
-  const pinMajor = NUMERIC_PIN_MAJOR.exec(pinnedVersion)?.[1];
-  if (pinMajor === void 0) return pinnedVersion;
+const servedReleaseSchemaRootScope = new import_async_hooks.AsyncLocalStorage();
+const servedReleaseRootAliases = /* @__PURE__ */ new Map();
+function withServedReleaseSchemaRoots(roots, fn) {
+  if (roots === void 0) return fn();
+  if (roots === null || typeof roots !== "object" || Array.isArray(roots)) {
+    throw new TypeError("servedReleaseSchemaRoots must be an object mapping AdCP versions to schema roots");
+  }
+  const entries = [];
+  for (const [version, root] of Object.entries(roots)) {
+    resolveBundleKey(version);
+    if (typeof root !== "string" || root.length === 0) {
+      throw new TypeError(`servedReleaseSchemaRoots["${version}"] must be a non-empty schema root path`);
+    }
+    const memoKey = `${version}\0${root}`;
+    let aliases = servedReleaseRootAliases.get(memoKey);
+    if (!aliases) {
+      if (!hasSchemaRootShape(root)) {
+        throw new Error(`Served-release AdCP schema root for version "${version}" not found or empty at ${root}`);
+      }
+      aliases = assertSchemaRootMatchesVersion(version, root);
+      servedReleaseRootAliases.set(memoKey, aliases);
+    }
+    const conflict = entries.find((entry) => entry.root !== root && [...aliases].some((alias) => entry.aliases.has(alias)));
+    if (conflict) {
+      throw new Error(
+        `servedReleaseSchemaRoots["${version}"] and servedReleaseSchemaRoots["${conflict.version}"] name the same release with different schema roots (${root}, ${conflict.root})`
+      );
+    }
+    entries.push({ version, root, aliases });
+  }
+  if (entries.length === 0) return fn();
+  const parent = servedReleaseSchemaRootScope.getStore() ?? [];
+  return servedReleaseSchemaRootScope.run([...entries, ...parent], fn);
+}
+function findServedReleaseSchemaRoot(release) {
+  const entries = servedReleaseSchemaRootScope.getStore();
+  if (!entries?.length) return void 0;
+  let key;
   try {
-    if (isExternalSchemaRootActive(pinnedVersion)) return pinnedVersion;
+    key = resolveBundleKey(release);
   } catch {
-    return pinnedVersion;
+    return void 0;
   }
-  const echoed = response !== null && typeof response === "object" ? response.adcp_version : void 0;
-  if (typeof echoed !== "string") return pinnedVersion;
+  return entries.find((entry) => entry.aliases.has(key) || entry.aliases.has(release));
+}
+const SERVED_RELEASE_MAJOR = /^(\d+)\.\d+(?:-[a-zA-Z0-9.-]+)?$/;
+const NUMERIC_PIN_MAJOR = /^(\d+)\.\d+/;
+function listsSupportedRelease(response, release) {
+  const adcp = response.adcp;
+  if (adcp === null || typeof adcp !== "object") return false;
+  const supported = adcp.supported_versions;
+  if (!Array.isArray(supported)) return false;
+  return supported.some((entry) => {
+    if (typeof entry !== "string") return false;
+    if (entry === release) return true;
+    try {
+      return toReleasePrecisionWire(entry) === release;
+    } catch {
+      return false;
+    }
+  });
+}
+function selectServedValidationVersion(response, pinnedVersion) {
+  const pin = { version: pinnedVersion };
+  const pinMajor = NUMERIC_PIN_MAJOR.exec(pinnedVersion)?.[1];
+  if (pinMajor === void 0) return pin;
+  if (response === null || typeof response !== "object") return pin;
+  const echoed = response.adcp_version;
+  if (typeof echoed !== "string") return pin;
   const echoMajor = SERVED_RELEASE_MAJOR.exec(echoed)?.[1];
-  if (echoMajor === void 0 || echoMajor !== pinMajor) return pinnedVersion;
+  if (echoMajor === void 0 || echoMajor !== pinMajor) return pin;
   let pinnedRelease;
   try {
     pinnedRelease = toReleasePrecisionWire(pinnedVersion);
+  } catch {
+    return pin;
+  }
+  if (echoed === pinnedRelease) return pin;
+  if (!listsSupportedRelease(response, echoed)) return pin;
+  const served = findServedReleaseSchemaRoot(echoed);
+  if (served) return { version: echoed, served };
+  return hasSchemaBundle(echoed) ? { version: echoed } : pin;
+}
+function resolveServedValidationVersion(response, pinnedVersion) {
+  try {
+    return selectServedValidationVersion(response, pinnedVersion).version;
   } catch {
     return pinnedVersion;
   }
-  if (echoed === pinnedRelease) return pinnedVersion;
-  return hasSchemaBundle(echoed) ? echoed : pinnedVersion;
+}
+function withServedValidationVersion(response, pinnedVersion, fn) {
+  let selection;
+  try {
+    selection = selectServedValidationVersion(response, pinnedVersion);
+  } catch {
+    selection = { version: pinnedVersion };
+  }
+  const { version, served } = selection;
+  if (!served) return fn(version);
+  const next = new Map(scopedExternalSchemaRoots.getStore());
+  for (const alias of served.aliases) next.set(alias, served.root);
+  return scopedExternalSchemaRoots.run(next, () => fn(version));
 }
 const mcpToolSchemaCache = /* @__PURE__ */ new Map();
 const mcpToolSummaryCache = /* @__PURE__ */ new Map();
@@ -1010,5 +1092,7 @@ function cloneJsonValue(value) {
   toReleasePrecisionWire,
   unregisterExternalSchemaRoot,
   validateAdcpVersionWire,
-  withExternalSchemaRoot
+  withExternalSchemaRoot,
+  withServedReleaseSchemaRoots,
+  withServedValidationVersion
 });

package/dist/lib/validation/schema-loader.mjs

@@ -668,28 +668,108 @@ function hasSchemaBundle(version) {
     return false;
   }
 }
-const SERVED_RELEASE_MAJOR = /^(\d+)\.\d+(?:-[a-zA-Z0-9.-]+)?$/;
-const NUMERIC_PIN_MAJOR = /^(\d+)\.\d+/;
-function resolveServedValidationVersion(response, pinnedVersion) {
-  const pinMajor = NUMERIC_PIN_MAJOR.exec(pinnedVersion)?.[1];
-  if (pinMajor === void 0) return pinnedVersion;
+const servedReleaseSchemaRootScope = new AsyncLocalStorage();
+const servedReleaseRootAliases = /* @__PURE__ */ new Map();
+function withServedReleaseSchemaRoots(roots, fn) {
+  if (roots === void 0) return fn();
+  if (roots === null || typeof roots !== "object" || Array.isArray(roots)) {
+    throw new TypeError("servedReleaseSchemaRoots must be an object mapping AdCP versions to schema roots");
+  }
+  const entries = [];
+  for (const [version, root] of Object.entries(roots)) {
+    resolveBundleKey(version);
+    if (typeof root !== "string" || root.length === 0) {
+      throw new TypeError(`servedReleaseSchemaRoots["${version}"] must be a non-empty schema root path`);
+    }
+    const memoKey = `${version}\0${root}`;
+    let aliases = servedReleaseRootAliases.get(memoKey);
+    if (!aliases) {
+      if (!hasSchemaRootShape(root)) {
+        throw new Error(`Served-release AdCP schema root for version "${version}" not found or empty at ${root}`);
+      }
+      aliases = assertSchemaRootMatchesVersion(version, root);
+      servedReleaseRootAliases.set(memoKey, aliases);
+    }
+    const conflict = entries.find((entry) => entry.root !== root && [...aliases].some((alias) => entry.aliases.has(alias)));
+    if (conflict) {
+      throw new Error(
+        `servedReleaseSchemaRoots["${version}"] and servedReleaseSchemaRoots["${conflict.version}"] name the same release with different schema roots (${root}, ${conflict.root})`
+      );
+    }
+    entries.push({ version, root, aliases });
+  }
+  if (entries.length === 0) return fn();
+  const parent = servedReleaseSchemaRootScope.getStore() ?? [];
+  return servedReleaseSchemaRootScope.run([...entries, ...parent], fn);
+}
+function findServedReleaseSchemaRoot(release) {
+  const entries = servedReleaseSchemaRootScope.getStore();
+  if (!entries?.length) return void 0;
+  let key;
   try {
-    if (isExternalSchemaRootActive(pinnedVersion)) return pinnedVersion;
+    key = resolveBundleKey(release);
   } catch {
-    return pinnedVersion;
+    return void 0;
   }
-  const echoed = response !== null && typeof response === "object" ? response.adcp_version : void 0;
-  if (typeof echoed !== "string") return pinnedVersion;
+  return entries.find((entry) => entry.aliases.has(key) || entry.aliases.has(release));
+}
+const SERVED_RELEASE_MAJOR = /^(\d+)\.\d+(?:-[a-zA-Z0-9.-]+)?$/;
+const NUMERIC_PIN_MAJOR = /^(\d+)\.\d+/;
+function listsSupportedRelease(response, release) {
+  const adcp = response.adcp;
+  if (adcp === null || typeof adcp !== "object") return false;
+  const supported = adcp.supported_versions;
+  if (!Array.isArray(supported)) return false;
+  return supported.some((entry) => {
+    if (typeof entry !== "string") return false;
+    if (entry === release) return true;
+    try {
+      return toReleasePrecisionWire(entry) === release;
+    } catch {
+      return false;
+    }
+  });
+}
+function selectServedValidationVersion(response, pinnedVersion) {
+  const pin = { version: pinnedVersion };
+  const pinMajor = NUMERIC_PIN_MAJOR.exec(pinnedVersion)?.[1];
+  if (pinMajor === void 0) return pin;
+  if (response === null || typeof response !== "object") return pin;
+  const echoed = response.adcp_version;
+  if (typeof echoed !== "string") return pin;
   const echoMajor = SERVED_RELEASE_MAJOR.exec(echoed)?.[1];
-  if (echoMajor === void 0 || echoMajor !== pinMajor) return pinnedVersion;
+  if (echoMajor === void 0 || echoMajor !== pinMajor) return pin;
   let pinnedRelease;
   try {
     pinnedRelease = toReleasePrecisionWire(pinnedVersion);
+  } catch {
+    return pin;
+  }
+  if (echoed === pinnedRelease) return pin;
+  if (!listsSupportedRelease(response, echoed)) return pin;
+  const served = findServedReleaseSchemaRoot(echoed);
+  if (served) return { version: echoed, served };
+  return hasSchemaBundle(echoed) ? { version: echoed } : pin;
+}
+function resolveServedValidationVersion(response, pinnedVersion) {
+  try {
+    return selectServedValidationVersion(response, pinnedVersion).version;
   } catch {
     return pinnedVersion;
   }
-  if (echoed === pinnedRelease) return pinnedVersion;
-  return hasSchemaBundle(echoed) ? echoed : pinnedVersion;
+}
+function withServedValidationVersion(response, pinnedVersion, fn) {
+  let selection;
+  try {
+    selection = selectServedValidationVersion(response, pinnedVersion);
+  } catch {
+    selection = { version: pinnedVersion };
+  }
+  const { version, served } = selection;
+  if (!served) return fn(version);
+  const next = new Map(scopedExternalSchemaRoots.getStore());
+  for (const alias of served.aliases) next.set(alias, served.root);
+  return scopedExternalSchemaRoots.run(next, () => fn(version));
 }
 const mcpToolSchemaCache = /* @__PURE__ */ new Map();
 const mcpToolSummaryCache = /* @__PURE__ */ new Map();
@@ -958,5 +1038,7 @@ export {
   toReleasePrecisionWire,
   unregisterExternalSchemaRoot,
   validateAdcpVersionWire,
-  withExternalSchemaRoot
+  withExternalSchemaRoot,
+  withServedReleaseSchemaRoots,
+  withServedValidationVersion
 };

package/dist/lib/version.d.mts

@@ -1,11 +1,11 @@
 /**
  * AdCP SDK library version
  */
-export declare const LIBRARY_VERSION = "15.9.3";
+export declare const LIBRARY_VERSION = "15.9.5";
 /**
  * AdCP specification version this library is built for
  */
-export declare const ADCP_VERSION = "3.2.4";
+export declare const ADCP_VERSION = "3.2.5";
 /**
  * AdCP major version sent with every request (adcp_major_version field).
  * Sellers validate this against their supported versions and return
@@ -19,7 +19,7 @@ export declare const ADCP_MAJOR_VERSION = 3;
  * this list by hand; bumping the AdCP pin via `npm run sync-version`
  * extends it.
  */
-export declare const COMPATIBLE_ADCP_VERSIONS: readonly ["v2.5", "v2.6", "v3", "3.0.0", "3.0", "3.0.1", "3.0.2", "3.0.3", "3.0.4", "3.0.5", "3.0.6", "3.0.7", "3.0.8", "3.0.9", "3.0.10", "3.0.11", "3.0.12", "3.0.13", "3.0.14", "3.0.15", "3.0.16", "3.0.17", "3.0.18", "3.0.19", "3.0.20", "3.0.21", "3.0.22", "3.0.23", "3.0.24", "3.0.25", "3.1.0", "3.1", "3.1.1", "3.1.2", "3.1.3", "3.1.4", "3.1.5", "3.1.6", "3.1.7", "3.1.8", "3.1.9", "3.1.10", "3.1.11", "3.1.12", "3.1.13", "3.1.14", "3.1.15", "3.1.16", "3.1.17", "3.1.18", "3.1.19", "3.1.20", "3.1.21", "3.1.22", "3.1.23", "3.1.24", "3.2.1", "3.2", "3.2.2", "3.2.3", "3.2.4"];
+export declare const COMPATIBLE_ADCP_VERSIONS: readonly ["v2.5", "v2.6", "v3", "3.0.0", "3.0", "3.0.1", "3.0.2", "3.0.3", "3.0.4", "3.0.5", "3.0.6", "3.0.7", "3.0.8", "3.0.9", "3.0.10", "3.0.11", "3.0.12", "3.0.13", "3.0.14", "3.0.15", "3.0.16", "3.0.17", "3.0.18", "3.0.19", "3.0.20", "3.0.21", "3.0.22", "3.0.23", "3.0.24", "3.0.25", "3.1.0", "3.1", "3.1.1", "3.1.2", "3.1.3", "3.1.4", "3.1.5", "3.1.6", "3.1.7", "3.1.8", "3.1.9", "3.1.10", "3.1.11", "3.1.12", "3.1.13", "3.1.14", "3.1.15", "3.1.16", "3.1.17", "3.1.18", "3.1.19", "3.1.20", "3.1.21", "3.1.22", "3.1.23", "3.1.24", "3.1.25", "3.1.26", "3.1.27", "3.1.28", "3.1.29", "3.2.1", "3.2", "3.2.2", "3.2.3", "3.2.4", "3.2.5"];
 /**
  * String literal union of every AdCP version the SDK formally supports.
  *
@@ -33,10 +33,10 @@ export type AdcpVersion = (typeof COMPATIBLE_ADCP_VERSIONS)[number];
  * Full version information
  */
 export declare const VERSION_INFO: {
-    readonly library: "15.9.3";
-    readonly adcp: "3.2.4";
-    readonly compatibleVersions: readonly ["v2.5", "v2.6", "v3", "3.0.0", "3.0", "3.0.1", "3.0.2", "3.0.3", "3.0.4", "3.0.5", "3.0.6", "3.0.7", "3.0.8", "3.0.9", "3.0.10", "3.0.11", "3.0.12", "3.0.13", "3.0.14", "3.0.15", "3.0.16", "3.0.17", "3.0.18", "3.0.19", "3.0.20", "3.0.21", "3.0.22", "3.0.23", "3.0.24", "3.0.25", "3.1.0", "3.1", "3.1.1", "3.1.2", "3.1.3", "3.1.4", "3.1.5", "3.1.6", "3.1.7", "3.1.8", "3.1.9", "3.1.10", "3.1.11", "3.1.12", "3.1.13", "3.1.14", "3.1.15", "3.1.16", "3.1.17", "3.1.18", "3.1.19", "3.1.20", "3.1.21", "3.1.22", "3.1.23", "3.1.24", "3.2.1", "3.2", "3.2.2", "3.2.3", "3.2.4"];
-    readonly generatedAt: "2026-10-16T14:25:50.306Z";
+    readonly library: "15.9.5";
+    readonly adcp: "3.2.5";
+    readonly compatibleVersions: readonly ["v2.5", "v2.6", "v3", "3.0.0", "3.0", "3.0.1", "3.0.2", "3.0.3", "3.0.4", "3.0.5", "3.0.6", "3.0.7", "3.0.8", "3.0.9", "3.0.10", "3.0.11", "3.0.12", "3.0.13", "3.0.14", "3.0.15", "3.0.16", "3.0.17", "3.0.18", "3.0.19", "3.0.20", "3.0.21", "3.0.22", "3.0.23", "3.0.24", "3.0.25", "3.1.0", "3.1", "3.1.1", "3.1.2", "3.1.3", "3.1.4", "3.1.5", "3.1.6", "3.1.7", "3.1.8", "3.1.9", "3.1.10", "3.1.11", "3.1.12", "3.1.13", "3.1.14", "3.1.15", "3.1.16", "3.1.17", "3.1.18", "3.1.19", "3.1.20", "3.1.21", "3.1.22", "3.1.23", "3.1.24", "3.1.25", "3.1.26", "3.1.27", "3.1.28", "3.1.29", "3.2.1", "3.2", "3.2.2", "3.2.3", "3.2.4", "3.2.5"];
+    readonly generatedAt: "2026-10-17T14:24:48.482Z";
 };
 /**
  * Get the AdCP specification version this library is built for