@adcp/sdk 16.2.0 → 16.4.0

package/dist/lib/negotiation/version.js

@@ -0,0 +1,60 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var version_exports = {};
+__export(version_exports, {
+  applicableRefinementServedVersion: () => applicableRefinementServedVersion,
+  compareProposalRefinementVersions: () => compareProposalRefinementVersions,
+  describeRefinementVersion: () => describeRefinementVersion,
+  isProposalRefinementVersion: () => isProposalRefinementVersion
+});
+module.exports = __toCommonJS(version_exports);
+var import_semver = require("semver");
+var import_version = require('../version.js');
+function isProposalRefinementVersion(value) {
+  if (typeof value !== "string" || !/^3\.[23](?:-[A-Za-z0-9]+(?:[.-][A-Za-z0-9]+)*)?$/.test(value)) return false;
+  const comparable = value.replace(/^(3\.[23])(?=-|$)/, "$1.0");
+  return (0, import_semver.valid)(comparable) === comparable;
+}
+function applicableRefinementServedVersion(served, ceiling, discoveryCeiling = ceiling) {
+  if (!isProposalRefinementVersion(discoveryCeiling)) return void 0;
+  if (!isProposalRefinementVersion(ceiling) || compareProposalRefinementVersions(ceiling, discoveryCeiling) > 0)
+    return void 0;
+  if (typeof served !== "string" || !isProposalRefinementVersion(ceiling)) return void 0;
+  if (!isProposalRefinementVersion(served) && (0, import_semver.valid)(served) !== served) return void 0;
+  const release = (0, import_version.toReleasePrecisionVersion)(served);
+  return isProposalRefinementVersion(release) && compareProposalRefinementVersions(release, ceiling) <= 0 ? served : void 0;
+}
+function compareProposalRefinementVersions(left, right) {
+  const semver = (value) => value.replace(/^(3\.[23])(?=-|$)/, "$1.0");
+  return (0, import_semver.compare)(semver(left), semver(right));
+}
+function describeRefinementVersion(value) {
+  try {
+    return (JSON.stringify(value) ?? String(value)).slice(0, 160);
+  } catch {
+    return "[unserializable version]";
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  applicableRefinementServedVersion,
+  compareProposalRefinementVersions,
+  describeRefinementVersion,
+  isProposalRefinementVersion
+});

package/dist/lib/negotiation/version.mjs

@@ -0,0 +1,33 @@
+import { compare, valid } from "semver";
+import { toReleasePrecisionVersion } from "../version.mjs";
+function isProposalRefinementVersion(value) {
+  if (typeof value !== "string" || !/^3\.[23](?:-[A-Za-z0-9]+(?:[.-][A-Za-z0-9]+)*)?$/.test(value)) return false;
+  const comparable = value.replace(/^(3\.[23])(?=-|$)/, "$1.0");
+  return valid(comparable) === comparable;
+}
+function applicableRefinementServedVersion(served, ceiling, discoveryCeiling = ceiling) {
+  if (!isProposalRefinementVersion(discoveryCeiling)) return void 0;
+  if (!isProposalRefinementVersion(ceiling) || compareProposalRefinementVersions(ceiling, discoveryCeiling) > 0)
+    return void 0;
+  if (typeof served !== "string" || !isProposalRefinementVersion(ceiling)) return void 0;
+  if (!isProposalRefinementVersion(served) && valid(served) !== served) return void 0;
+  const release = toReleasePrecisionVersion(served);
+  return isProposalRefinementVersion(release) && compareProposalRefinementVersions(release, ceiling) <= 0 ? served : void 0;
+}
+function compareProposalRefinementVersions(left, right) {
+  const semver = (value) => value.replace(/^(3\.[23])(?=-|$)/, "$1.0");
+  return compare(semver(left), semver(right));
+}
+function describeRefinementVersion(value) {
+  try {
+    return (JSON.stringify(value) ?? String(value)).slice(0, 160);
+  } catch {
+    return "[unserializable version]";
+  }
+}
+export {
+  applicableRefinementServedVersion,
+  compareProposalRefinementVersions,
+  describeRefinementVersion,
+  isProposalRefinementVersion
+};

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

@@ -3612,7 +3612,7 @@ export interface components {
                     } | {
                         /** @enum {string} */
                         kind: "targeting_restriction";
-                        restricted_attributes?: ("racial_ethnic_origin" | "political_opinions" | "religious_beliefs" | "trade_union_membership" | "health_data" | "sex_life_sexual_orientation" | "genetic_data" | "biometric_data" | "age" | "familial_status")[];
+                        restricted_attributes?: ("racial_ethnic_origin" | "political_opinions" | "religious_beliefs" | "trade_union_membership" | "health_data" | "sex_life_sexual_orientation" | "genetic_data" | "biometric_data" | "age" | "familial_status" | "sex_gender")[];
                         description?: string;
                     } | {
                         /** @enum {string} */

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

@@ -3612,7 +3612,7 @@ export interface components {
                     } | {
                         /** @enum {string} */
                         kind: "targeting_restriction";
-                        restricted_attributes?: ("racial_ethnic_origin" | "political_opinions" | "religious_beliefs" | "trade_union_membership" | "health_data" | "sex_life_sexual_orientation" | "genetic_data" | "biometric_data" | "age" | "familial_status")[];
+                        restricted_attributes?: ("racial_ethnic_origin" | "political_opinions" | "religious_beliefs" | "trade_union_membership" | "health_data" | "sex_life_sexual_orientation" | "genetic_data" | "biometric_data" | "age" | "familial_status" | "sex_gender")[];
                         description?: string;
                     } | {
                         /** @enum {string} */

package/dist/lib/server/create-adcp-server.d.mts

@@ -1,3 +1,4 @@
+import { type VersionDrift } from '../adapters/version/index.mjs';
 /**
  * Declarative AdCP server builder.
  *
@@ -1198,6 +1199,17 @@ export type WebhooksConfig = Pick<WebhookEmitterOptions, 'signerKey' | 'signerPr
     /** Observability: receives failures isolated from attempt observers. */
     onAttemptObserverError?: WebhookEmitterOptions['onAttemptObserverError'];
 };
+/** One request or response conversion between the server's release and a buyer's. */
+export interface AdcpVersionTranslationEvent {
+    tool: string;
+    direction: 'request' | 'response';
+    /** Release the payload was converted from. */
+    fromVersion: string;
+    /** Release the payload was converted to. */
+    toVersion: string;
+    /** What each conversion step removed or moved. */
+    drifts: VersionDrift[];
+}
 export interface AdcpServerConfig<TAccount = unknown> {
     /** Experimental 3.3 authorization, invoked before idempotency and handler side effects. */
     identity33?: {
@@ -1258,6 +1270,15 @@ export interface AdcpServerConfig<TAccount = unknown> {
      * releases, and no newer than `adcpVersion`.
      */
     defaultAdcpVersion?: AdcpVersion | (string & {});
+    /**
+     * Called each time the framework converts a request up from, or a
+     * handler's response down to, a buyer's older release. `drifts` lists every
+     * field the conversion removed or moved, with JSON paths, so a seller can
+     * record what an older buyer did not receive. The same events are logged
+     * at `debug` (requests) and `info` (responses). A throwing callback is
+     * logged and ignored.
+     */
+    onVersionTranslation?: (event: AdcpVersionTranslationEvent) => void;
     /**
      * Per-tool inclusive protocol-release availability. This narrows, but does
      * not replace, the server-wide releases declared through capabilities.

package/dist/lib/server/create-adcp-server.d.ts

@@ -1,3 +1,4 @@
+import { type VersionDrift } from '../adapters/version';
 /**
  * Declarative AdCP server builder.
  *
@@ -1198,6 +1199,17 @@ export type WebhooksConfig = Pick<WebhookEmitterOptions, 'signerKey' | 'signerPr
     /** Observability: receives failures isolated from attempt observers. */
     onAttemptObserverError?: WebhookEmitterOptions['onAttemptObserverError'];
 };
+/** One request or response conversion between the server's release and a buyer's. */
+export interface AdcpVersionTranslationEvent {
+    tool: string;
+    direction: 'request' | 'response';
+    /** Release the payload was converted from. */
+    fromVersion: string;
+    /** Release the payload was converted to. */
+    toVersion: string;
+    /** What each conversion step removed or moved. */
+    drifts: VersionDrift[];
+}
 export interface AdcpServerConfig<TAccount = unknown> {
     /** Experimental 3.3 authorization, invoked before idempotency and handler side effects. */
     identity33?: {
@@ -1258,6 +1270,15 @@ export interface AdcpServerConfig<TAccount = unknown> {
      * releases, and no newer than `adcpVersion`.
      */
     defaultAdcpVersion?: AdcpVersion | (string & {});
+    /**
+     * Called each time the framework converts a request up from, or a
+     * handler's response down to, a buyer's older release. `drifts` lists every
+     * field the conversion removed or moved, with JSON paths, so a seller can
+     * record what an older buyer did not receive. The same events are logged
+     * at `debug` (requests) and `info` (responses). A throwing callback is
+     * logged and ignored.
+     */
+    onVersionTranslation?: (event: AdcpVersionTranslationEvent) => void;
     /**
      * Per-tool inclusive protocol-release availability. This narrows, but does
      * not replace, the server-wide releases declared through capabilities.

package/dist/lib/server/create-adcp-server.js

@@ -31,6 +31,7 @@ __export(create_adcp_server_exports, {
 });
 module.exports = __toCommonJS(create_adcp_server_exports);
 var import_web_bot_auth = require('../signing/web-bot-auth.js');
+var import_version = require('../adapters/version/index.js');
 var import_schema_loader = require('../validation/schema-loader.js');
 var import_lifecycle = require('../identity-3.3/lifecycle.js');
 var import_server = require('../identity-3.3/server.js');
@@ -38,7 +39,7 @@ var import_web_bot_auth2 = require('../signing/web-bot-auth.js');
 var import_validation = require('../identity-3.3/validation.js');
 var import_trust = require('../identity-3.3/trust.js');
 var import_zod = require("zod");
-var import_version = require('../version.js');
+var import_version2 = require('../version.js');
 var import_adcp_version_config = require('../utils/adcp-version-config.js');
 var import_errors = require('../errors/index.js');
 var import_schema_loader2 = require('../validation/schema-loader.js');
@@ -79,7 +80,7 @@ var import_middleware = require('../signing/middleware.js');
 var import_operation_resolution = require('../signing/operation-resolution.js');
 var import_account_mode = require('./account-mode.js');
 var import_test_controller_bridge = require('./test-controller-bridge.js');
-var import_version2 = require('../version.js');
+var import_version3 = require('../version.js');
 var import_schemas2 = require('../types/schemas.generated.js');
 var import_error_codes = require('../types/error-codes.js');
 function hasIdempotencyClearAll(store) {
@@ -726,7 +727,7 @@ function validateFrameworkPayload(toolName, direction, payload, version, proposa
       };
     }
   }
-  const verification = (0, import_verification.validateRefineProposalsResponseShape)(payload);
+  const verification = (0, import_verification.validateRefineProposalsResponseShape)(payload, { adcpVersion: version });
   if (verification.ok) {
     return {
       valid: true,
@@ -1406,7 +1407,7 @@ function normalizeMediaBuyStatusCollision(response, toolName) {
 }
 function injectVersionIntoResponse(response, servedVersion) {
   if (!servedVersion) return;
-  const wireVersion = (0, import_version.toReleasePrecisionVersion)(servedVersion);
+  const wireVersion = (0, import_version2.toReleasePrecisionVersion)(servedVersion);
   const sc = response.structuredContent;
   if (sc && typeof sc === "object" && !("adcp_version" in sc)) {
     const mirrorsStructuredContent = contentTextMirrorsStructuredContent(response, sc);
@@ -1660,11 +1661,11 @@ function getAdvertisedSupportedMajors(capConfig, serverPin) {
     if (Number.isFinite(m)) out.add(m);
   }
   for (const v of capConfig?.supported_versions ?? []) {
-    const m = (0, import_version.parseAdcpMajorVersion)(v);
+    const m = (0, import_version2.parseAdcpMajorVersion)(v);
     if (Number.isFinite(m)) out.add(m);
   }
   if (out.size === 0) {
-    const pinMajor = (0, import_version.parseAdcpMajorVersion)(serverPin);
+    const pinMajor = (0, import_version2.parseAdcpMajorVersion)(serverPin);
     if (Number.isFinite(pinMajor)) out.add(pinMajor);
   }
   return out;
@@ -1676,7 +1677,7 @@ function buildSupportedVersionsList(capConfig, serverPin) {
   if (capConfig?.major_versions?.length) {
     return capConfig.major_versions.filter((m) => Number.isFinite(m)).map((m) => String(m));
   }
-  const pinMajor = (0, import_version.parseAdcpMajorVersion)(serverPin);
+  const pinMajor = (0, import_version2.parseAdcpMajorVersion)(serverPin);
   return Number.isFinite(pinMajor) ? [String(pinMajor)] : [];
 }
 function withImmutableServedAdcpVersion(context, servedAdcpVersion) {
@@ -1695,7 +1696,7 @@ function parseAdcpRelease(value) {
   if (typeof value !== "string") return void 0;
   let wire;
   try {
-    wire = (0, import_version.toReleasePrecisionVersion)(value);
+    wire = (0, import_version2.toReleasePrecisionVersion)(value);
   } catch {
     return void 0;
   }
@@ -1842,7 +1843,7 @@ let bundledCompatibleReleases;
 function bundledReleasesForMajors(majors, configured) {
   const acceptedMajors = new Set(majors);
   const releases = /* @__PURE__ */ new Map();
-  bundledCompatibleReleases ??= import_version.COMPATIBLE_ADCP_VERSIONS.flatMap((version) => {
+  bundledCompatibleReleases ??= import_version2.COMPATIBLE_ADCP_VERSIONS.flatMap((version) => {
     if (!(0, import_schema_loader2.hasSchemaBundle)(version)) return [];
     const parsed = parseAdcpRelease(version);
     return parsed ? [parsed] : [];
@@ -1993,7 +1994,7 @@ function createAdcpServer(config) {
     responseEnhancer,
     structuredContentTextFallback = "always"
   } = config;
-  if (capConfig?.major_versions?.some((major) => major < 3) || capConfig?.supported_versions?.some((version2) => (0, import_version.parseAdcpMajorVersion)(version2) < 3)) {
+  if (capConfig?.major_versions?.some((major) => major < 3) || capConfig?.supported_versions?.some((version2) => (0, import_version2.parseAdcpMajorVersion)(version2) < 3)) {
     throw new import_errors.ConfigurationError(
       "AdCP 2 reached end of life on 2026-08-01. Server capabilities must advertise AdCP 3 only.",
       "capabilities"
@@ -2058,14 +2059,14 @@ function createAdcpServer(config) {
   }
   const credentialPolicyPatterns = credentialPolicy === void 0 || typeof credentialPolicy === "string" ? void 0 : credentialPolicy.patterns;
   const adcpVersion = (0, import_adcp_version_config.resolveAdcpVersion)(
-    configuredAdcpVersion ?? (config.identity33 ? "3.3" : config.proposalNegotiation ? import_version2.ADCP_VERSION : void 0)
+    configuredAdcpVersion ?? (config.identity33 ? "3.3" : config.proposalNegotiation ? import_version3.ADCP_VERSION : void 0)
   );
   const toolVersionRanges = parseToolVersionRanges(config.toolVersions);
   const toolAvailableForRelease = (toolName, release) => toolIsAvailableInRelease(toolVersionRanges, toolName, release);
   const movingSupportedVersion = capConfig?.supported_versions?.find(import_adcp_version_config.isMovingAdcpPrereleaseFamilyAlias);
   if (movingSupportedVersion) {
     throw new Error(
-      `createAdcpServer: capabilities.supported_versions contains moving prerelease-family alias ${JSON.stringify(movingSupportedVersion)}; pin ${JSON.stringify((0, import_version.toReleasePrecisionVersion)(import_version2.ADCP_VERSION))} instead`
+      `createAdcpServer: capabilities.supported_versions contains moving prerelease-family alias ${JSON.stringify(movingSupportedVersion)}; pin ${JSON.stringify((0, import_version2.toReleasePrecisionVersion)(import_version3.ADCP_VERSION))} instead`
     );
   }
   const configuredDefaultVersion = configuredDefaultAdcpVersion === void 0 ? void 0 : (0, import_adcp_version_config.resolveAdcpVersion)(configuredDefaultAdcpVersion, "defaultAdcpVersion");
@@ -2351,6 +2352,43 @@ function createAdcpServer(config) {
     const selected = selectServedAdcpRelease(params, capConfig, adcpVersion, defaultAdcpVersion);
     return isMcpToolResponse(selected) ? void 0 : selected;
   };
+  const downgradeTaskStatusResult = (toolName, response, servedVersion) => {
+    if (toolName !== "get_task_status" || config.identity33) return response;
+    if ((0, import_version.translationSteps)(adcpVersion, servedVersion).length === 0) return response;
+    const body = response.structuredContent;
+    if (!body || typeof body.task_type !== "string" || !body.result || typeof body.result !== "object") return response;
+    const downgraded = (0, import_version.downgradeResponse)(body.task_type, body.result, {
+      fromVersion: adcpVersion,
+      toVersion: servedVersion
+    });
+    if (downgraded.drifts.length > 0) {
+      reportVersionTranslation({
+        tool: body.task_type,
+        direction: "response",
+        fromVersion: adcpVersion,
+        toVersion: servedVersion,
+        drifts: downgraded.drifts
+      });
+    }
+    if (downgraded.data === body.result) return response;
+    const mirrors = contentTextMirrorsStructuredContent(response, body);
+    const next = cloneFormattedResponse(response);
+    const nextBody = { ...next.structuredContent, result: downgraded.data };
+    next.structuredContent = nextBody;
+    syncContentJsonText(next, nextBody, mirrors);
+    return next;
+  };
+  const reportVersionTranslation = (event) => {
+    if (!config.onVersionTranslation) return;
+    try {
+      config.onVersionTranslation(event);
+    } catch (err) {
+      logger.warn("onVersionTranslation callback threw", {
+        tool: event.tool,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  };
   const releaseDefinesTool = (toolName, release) => {
     if (toolName === "refine_proposals") return true;
     try {
@@ -2367,6 +2405,7 @@ function createAdcpServer(config) {
     sanitizeAdcpErrorEnvelope(response);
     enrichErrorTwoLayer(response, toolName, (0, import_error_arm_tools.getToolsWithErrorArm)(release.validationVersion));
     if (!isErrorResponse(response)) {
+      response = downgradeTaskStatusResult(toolName, response, release.validationVersion);
       normalizeMediaBuyStatusCollision(response, toolName);
       injectEnvelopeStatusIntoResponse(response, toolName);
       const validationError = protocolTaskResponseValidationError(toolName, response, params);
@@ -2726,6 +2765,7 @@ function createAdcpServer(config) {
           requestRelease = releaseSelection;
         }
         const requestErrorArms = (0, import_error_arm_tools.getToolsWithErrorArm)(requestRelease.validationVersion);
+        const translatesRelease = !config.identity33 && toolName !== "get_adcp_capabilities" && (0, import_version.translationSteps)(adcpVersion, requestRelease.validationVersion).length > 0;
         const ctx = withImmutableServedAdcpVersion(
           {
             store: stateStore,
@@ -2868,7 +2908,7 @@ function createAdcpServer(config) {
         const reqAdcpMajorRaw = params.adcp_major_version;
         const reqAdcpMajor = typeof reqAdcpMajorRaw === "number" ? reqAdcpMajorRaw : typeof reqAdcpMajorRaw === "string" ? Number.parseInt(reqAdcpMajorRaw, 10) : void 0;
         if (typeof reqAdcpVersion === "string" && reqAdcpMajor !== void 0 && Number.isFinite(reqAdcpMajor)) {
-          const stringMajor = (0, import_version.parseAdcpMajorVersion)(reqAdcpVersion);
+          const stringMajor = (0, import_version2.parseAdcpMajorVersion)(reqAdcpVersion);
           if (Number.isFinite(stringMajor) && stringMajor !== reqAdcpMajor) {
             return finalize(
               (0, import_errors2.adcpError)("VERSION_UNSUPPORTED", {
@@ -2878,7 +2918,7 @@ function createAdcpServer(config) {
             );
           }
         }
-        const effectiveReqMajor = reqAdcpMajor !== void 0 && Number.isFinite(reqAdcpMajor) ? reqAdcpMajor : typeof reqAdcpVersion === "string" ? (0, import_version.parseAdcpMajorVersion)(reqAdcpVersion) : void 0;
+        const effectiveReqMajor = reqAdcpMajor !== void 0 && Number.isFinite(reqAdcpMajor) ? reqAdcpMajor : typeof reqAdcpVersion === "string" ? (0, import_version2.parseAdcpMajorVersion)(reqAdcpVersion) : void 0;
         if (effectiveReqMajor !== void 0 && Number.isFinite(effectiveReqMajor)) {
           const supportedMajors = getAdvertisedSupportedMajors(capConfig, adcpVersion);
           if (!supportedMajors.has(effectiveReqMajor)) {
@@ -3447,7 +3487,24 @@ function createAdcpServer(config) {
               (_entry, index) => !notificationFailureRows.has(index)
             )
           };
-          const result = notificationFailureRows.size > 0 && handlerParams.accounts.length === 0 ? { accounts: [], ...params.dry_run === true && { dry_run: true } } : await handler(handlerParams, ctx);
+          const upgraded = translatesRelease ? (0, import_version.upgradeRequest)(toolName, handlerParams, {
+            fromVersion: requestRelease.validationVersion,
+            toVersion: adcpVersion
+          }) : void 0;
+          if (upgraded && upgraded.drifts.length > 0) {
+            logger.debug(`Converted ${toolName} request up to AdCP ${adcpVersion}`, {
+              tool: toolName,
+              drifts: upgraded.drifts
+            });
+            reportVersionTranslation({
+              tool: toolName,
+              direction: "request",
+              fromVersion: requestRelease.validationVersion,
+              toVersion: adcpVersion,
+              drifts: upgraded.drifts
+            });
+          }
+          const result = notificationFailureRows.size > 0 && handlerParams.accounts.length === 0 ? { accounts: [], ...params.dry_run === true && { dry_run: true } } : await handler(upgraded ? upgraded.params : handlerParams, ctx);
           mutationHandlerCompleted = true;
           let formatted;
           if (isFormattedResponse(result)) {
@@ -3915,6 +3972,31 @@ function createAdcpServer(config) {
               injectEnvelopeStatusIntoResponse(formatted, toolName);
             }
           }
+          if (translatesRelease && !isErrorResponse(formatted) && formatted.structuredContent) {
+            const downgraded = (0, import_version.downgradeResponse)(toolName, formatted.structuredContent, {
+              fromVersion: adcpVersion,
+              toVersion: requestRelease.validationVersion
+            });
+            if (downgraded.data !== formatted.structuredContent) {
+              const mirrors = contentTextMirrorsStructuredContent(formatted, formatted.structuredContent);
+              formatted = cloneFormattedResponse(formatted);
+              formatted.structuredContent = downgraded.data;
+              syncContentJsonText(formatted, downgraded.data, mirrors);
+            }
+            if (downgraded.drifts.length > 0) {
+              logger.info(`Converted ${toolName} response down to AdCP ${requestRelease.validationVersion}`, {
+                tool: toolName,
+                drifts: downgraded.drifts
+              });
+              reportVersionTranslation({
+                tool: toolName,
+                direction: "response",
+                fromVersion: adcpVersion,
+                toVersion: requestRelease.validationVersion,
+                drifts: downgraded.drifts
+              });
+            }
+          }
           if (responseValidationMode !== "off" && !isErrorResponse(formatted)) {
             const payload = formatted.structuredContent;
             const outcome = validateFrameworkPayload(
@@ -4630,7 +4712,7 @@ function createAdcpServer(config) {
       "measurement"
     ];
   }
-  capabilitiesData.library_version = `@adcp/client@${import_version2.LIBRARY_VERSION}`;
+  capabilitiesData.library_version = `@adcp/client@${import_version3.LIBRARY_VERSION}`;
   async function authorizeAuxiliaryIdentityTool(toolName, params, extra) {
     const failure = (0, import_web_bot_auth2.getWebBotAuthAuthorizationFailure)(extra?.authInfo?.extra);
     if (failure) return (0, import_web_bot_auth2.webBotAuthToolFailure)(failure, servedAdcpVersion);

package/dist/lib/server/create-adcp-server.mjs

@@ -1,4 +1,5 @@
 import { assertWebBotAuthSigningKey, getWebBotAuthLegacyOriginGate } from "../signing/web-bot-auth.mjs";
+import { downgradeResponse, translationSteps, upgradeRequest } from "../adapters/version/index.mjs";
 import {
   isIdentity33SchemaScope,
   withIdentity33SchemaScope,
@@ -817,7 +818,7 @@ function validateFrameworkPayload(toolName, direction, payload, version, proposa
       };
     }
   }
-  const verification = validateRefineProposalsResponseShape(payload);
+  const verification = validateRefineProposalsResponseShape(payload, { adcpVersion: version });
   if (verification.ok) {
     return {
       valid: true,
@@ -2442,6 +2443,43 @@ function createAdcpServer(config) {
     const selected = selectServedAdcpRelease(params, capConfig, adcpVersion, defaultAdcpVersion);
     return isMcpToolResponse(selected) ? void 0 : selected;
   };
+  const downgradeTaskStatusResult = (toolName, response, servedVersion) => {
+    if (toolName !== "get_task_status" || config.identity33) return response;
+    if (translationSteps(adcpVersion, servedVersion).length === 0) return response;
+    const body = response.structuredContent;
+    if (!body || typeof body.task_type !== "string" || !body.result || typeof body.result !== "object") return response;
+    const downgraded = downgradeResponse(body.task_type, body.result, {
+      fromVersion: adcpVersion,
+      toVersion: servedVersion
+    });
+    if (downgraded.drifts.length > 0) {
+      reportVersionTranslation({
+        tool: body.task_type,
+        direction: "response",
+        fromVersion: adcpVersion,
+        toVersion: servedVersion,
+        drifts: downgraded.drifts
+      });
+    }
+    if (downgraded.data === body.result) return response;
+    const mirrors = contentTextMirrorsStructuredContent(response, body);
+    const next = cloneFormattedResponse(response);
+    const nextBody = { ...next.structuredContent, result: downgraded.data };
+    next.structuredContent = nextBody;
+    syncContentJsonText(next, nextBody, mirrors);
+    return next;
+  };
+  const reportVersionTranslation = (event) => {
+    if (!config.onVersionTranslation) return;
+    try {
+      config.onVersionTranslation(event);
+    } catch (err) {
+      logger.warn("onVersionTranslation callback threw", {
+        tool: event.tool,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  };
   const releaseDefinesTool = (toolName, release) => {
     if (toolName === "refine_proposals") return true;
     try {
@@ -2458,6 +2496,7 @@ function createAdcpServer(config) {
     sanitizeAdcpErrorEnvelope(response);
     enrichErrorTwoLayer(response, toolName, getToolsWithErrorArm(release.validationVersion));
     if (!isErrorResponse(response)) {
+      response = downgradeTaskStatusResult(toolName, response, release.validationVersion);
       normalizeMediaBuyStatusCollision(response, toolName);
       injectEnvelopeStatusIntoResponse(response, toolName);
       const validationError = protocolTaskResponseValidationError(toolName, response, params);
@@ -2817,6 +2856,7 @@ function createAdcpServer(config) {
           requestRelease = releaseSelection;
         }
         const requestErrorArms = getToolsWithErrorArm(requestRelease.validationVersion);
+        const translatesRelease = !config.identity33 && toolName !== "get_adcp_capabilities" && translationSteps(adcpVersion, requestRelease.validationVersion).length > 0;
         const ctx = withImmutableServedAdcpVersion(
           {
             store: stateStore,
@@ -3538,7 +3578,24 @@ function createAdcpServer(config) {
               (_entry, index) => !notificationFailureRows.has(index)
             )
           };
-          const result = notificationFailureRows.size > 0 && handlerParams.accounts.length === 0 ? { accounts: [], ...params.dry_run === true && { dry_run: true } } : await handler(handlerParams, ctx);
+          const upgraded = translatesRelease ? upgradeRequest(toolName, handlerParams, {
+            fromVersion: requestRelease.validationVersion,
+            toVersion: adcpVersion
+          }) : void 0;
+          if (upgraded && upgraded.drifts.length > 0) {
+            logger.debug(`Converted ${toolName} request up to AdCP ${adcpVersion}`, {
+              tool: toolName,
+              drifts: upgraded.drifts
+            });
+            reportVersionTranslation({
+              tool: toolName,
+              direction: "request",
+              fromVersion: requestRelease.validationVersion,
+              toVersion: adcpVersion,
+              drifts: upgraded.drifts
+            });
+          }
+          const result = notificationFailureRows.size > 0 && handlerParams.accounts.length === 0 ? { accounts: [], ...params.dry_run === true && { dry_run: true } } : await handler(upgraded ? upgraded.params : handlerParams, ctx);
           mutationHandlerCompleted = true;
           let formatted;
           if (isFormattedResponse(result)) {
@@ -4006,6 +4063,31 @@ function createAdcpServer(config) {
               injectEnvelopeStatusIntoResponse(formatted, toolName);
             }
           }
+          if (translatesRelease && !isErrorResponse(formatted) && formatted.structuredContent) {
+            const downgraded = downgradeResponse(toolName, formatted.structuredContent, {
+              fromVersion: adcpVersion,
+              toVersion: requestRelease.validationVersion
+            });
+            if (downgraded.data !== formatted.structuredContent) {
+              const mirrors = contentTextMirrorsStructuredContent(formatted, formatted.structuredContent);
+              formatted = cloneFormattedResponse(formatted);
+              formatted.structuredContent = downgraded.data;
+              syncContentJsonText(formatted, downgraded.data, mirrors);
+            }
+            if (downgraded.drifts.length > 0) {
+              logger.info(`Converted ${toolName} response down to AdCP ${requestRelease.validationVersion}`, {
+                tool: toolName,
+                drifts: downgraded.drifts
+              });
+              reportVersionTranslation({
+                tool: toolName,
+                direction: "response",
+                fromVersion: adcpVersion,
+                toVersion: requestRelease.validationVersion,
+                drifts: downgraded.drifts
+              });
+            }
+          }
           if (responseValidationMode !== "off" && !isErrorResponse(formatted)) {
             const payload = formatted.structuredContent;
             const outcome = validateFrameworkPayload(

package/dist/lib/server/error-arm-tools.d.mts

@@ -10,10 +10,11 @@
  * response schema doesn't define it would add a key the schema
  * doesn't expect.
  *
- * Built lazily at first use from the bundled schema cache (the same
- * tree `schema-loader.ts` reads). The set is computed once per bundle
- * key (`resolveBundleKey('3.0.0')` → `'3.0'`) and memoised — the schema
- * tree is read-only at runtime, so a single scan is sufficient.
+ * Derived from the active schema-loader authority. Bundle inventories are
+ * memoised by bundle key and resolved root, with loader-epoch invalidation
+ * so scoped or re-registered candidate bundles cannot leak.
+ * Raw external roots use the loader's response index when no bundled
+ * store exists.
  *
  * Spec basis: `error-code.json#GOVERNANCE_DENIED` and
  * `#GOVERNANCE_UNAVAILABLE` both prescribe "populate `errors[].code` in
@@ -44,12 +45,11 @@ export interface ErrorArmDescriptor {
  * gate for two-layer auto-emission, plus the per-arm constants the
  * dispatcher needs to set when synthesising the wrap.
  *
- * Scans the bundled schema cache lazily on first call per bundle key
- * (one read per minor version per process). Returns a frozen, empty map
- * when no schema bundle is reachable — the dispatcher early-returns on
- * `map.size === 0`, so a missing bundle silently disables the wrap
- * rather than breaking server startup.
+ * Scans the active schema authority lazily. Missing roots return an empty map
+ * without caching, so later external registration takes effect. Re-registering
+ * or entering another schema scope invalidates cached inventories, including
+ * replacements of candidate bundles at the same path.
  */
 export declare function getToolsWithErrorArm(version?: string): ReadonlyMap<string, ErrorArmDescriptor>;
-/** Test hook: clear the per-bundle-key cache. */
+/** Test hook: clear cached error-arm inventories. */
 export declare function _resetErrorArmToolsCache(): void;

package/dist/lib/server/error-arm-tools.d.ts

@@ -10,10 +10,11 @@
  * response schema doesn't define it would add a key the schema
  * doesn't expect.
  *
- * Built lazily at first use from the bundled schema cache (the same
- * tree `schema-loader.ts` reads). The set is computed once per bundle
- * key (`resolveBundleKey('3.0.0')` → `'3.0'`) and memoised — the schema
- * tree is read-only at runtime, so a single scan is sufficient.
+ * Derived from the active schema-loader authority. Bundle inventories are
+ * memoised by bundle key and resolved root, with loader-epoch invalidation
+ * so scoped or re-registered candidate bundles cannot leak.
+ * Raw external roots use the loader's response index when no bundled
+ * store exists.
  *
  * Spec basis: `error-code.json#GOVERNANCE_DENIED` and
  * `#GOVERNANCE_UNAVAILABLE` both prescribe "populate `errors[].code` in
@@ -44,12 +45,11 @@ export interface ErrorArmDescriptor {
  * gate for two-layer auto-emission, plus the per-arm constants the
  * dispatcher needs to set when synthesising the wrap.
  *
- * Scans the bundled schema cache lazily on first call per bundle key
- * (one read per minor version per process). Returns a frozen, empty map
- * when no schema bundle is reachable — the dispatcher early-returns on
- * `map.size === 0`, so a missing bundle silently disables the wrap
- * rather than breaking server startup.
+ * Scans the active schema authority lazily. Missing roots return an empty map
+ * without caching, so later external registration takes effect. Re-registering
+ * or entering another schema scope invalidates cached inventories, including
+ * replacements of candidate bundles at the same path.
  */
 export declare function getToolsWithErrorArm(version?: string): ReadonlyMap<string, ErrorArmDescriptor>;
-/** Test hook: clear the per-bundle-key cache. */
+/** Test hook: clear cached error-arm inventories. */
 export declare function _resetErrorArmToolsCache(): void;