@adcp/sdk 16.3.0 → 16.5.0

package/dist/lib/schemas-data/3.2/trusted-match/publisher-tmpx-config.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://adcontextprotocol.org/schemas/3.2.5/trusted-match/publisher-tmpx-config.json",
+  "$id": "https://adcontextprotocol.org/schemas/3.2.7/trusted-match/publisher-tmpx-config.json",
   "title": "Publisher TMPX Macro Mapping",
   "description": "Publisher-owned deployment configuration that maps each identity provider's TMPX slots to the ad-server macro names (or targeting keys, VAST substitutions, DOOH play-log fields) the publisher wants those chunks fired into on this surface. Mapping is authored by the publisher — the same operator who trafficks the corresponding ad-server line items — and never travels on the wire between identity provider and router. This keeps macro naming a deployment concern rather than a protocol identifier: providers emit chunks as `{slot_id, value}` pairs (see provider-identity-match-response.json), the router preserves ordering and slot IDs under the emitting `provider_id` (see identity-match-response.json), and this configuration resolves each `(provider_id, slot_id)` to a local destination on the way to the ad server. A publisher may map the same provider to different destinations across surfaces (GAM key-values vs. VAST macros vs. DOOH play-log fields) by carrying one instance of this configuration per surface.",
   "x-status": "experimental",

package/dist/lib/schemas-data/3.2/trusted-match/tmpx-chunk.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://adcontextprotocol.org/schemas/3.2.5/trusted-match/tmpx-chunk.json",
+  "$id": "https://adcontextprotocol.org/schemas/3.2.7/trusted-match/tmpx-chunk.json",
   "title": "TMPX Chunk",
   "description": "A single provider TMPX chunk — the provider-local `slot_id` (declared at registration in `tmpx_slots`) and its opaque URL-safe `value`. Same shape on both hops of the Identity Match response: providers emit `tmpx_chunks[]` on the provider→router shape, the router forwards them under `tmpx_providers[provider_id].chunks[]` on the router→publisher shape. Publisher-local destination names never appear here — the publisher's deployment configuration resolves `(provider_id, slot_id)` → local destination via publisher-tmpx-config.json.",
   "x-status": "experimental",

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) {
@@ -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,
@@ -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/index.d.mts

@@ -61,7 +61,7 @@ export type { AdcpMcpResourceDefinition, McpAppResourceCsp, McpAppResourcePermis
 export { requireSessionKey, ADCP_PRE_TRANSPORT, ADCP_SIGNED_REQUESTS_STATE, ADCP_INSTRUCTIONS_FN, } from './create-adcp-server.mjs';
 export type { SessionContext, OnInstructionsError, MaybePromise, BridgeMarker } from './create-adcp-server.mjs';
 export type { AdcpServer, AdcpServerComplianceApi, AdcpServerTransport, AdcpTestRequest, AdcpTestToolsCallRequest, AdcpTestResponse, AdcpInvokeOptions, } from './adcp-server.mjs';
-export type { AdcpServerConfig as LegacyAdcpServerConfig, WebhooksConfig, AdcpToolMap as LegacyAdcpToolMap, AdcpServerToolName, AdcpCapabilitiesConfig, AdcpCapabilitiesOverrides, AdcpToolVersionRange, AdcpCustomToolConfig as LegacyAdcpCustomToolConfig, AdcpCustomToolHandler as LegacyAdcpCustomToolHandler, AdcpCustomToolHandlerExtra as LegacyAdcpCustomToolHandlerExtra, McpAppUiMeta, McpAppMeta, AdcpLogger, SignedRequestsConfig, AdcpPreTransport, AdcpSignedRequestsState, HandlerContext as LegacyHandlerContext, SessionKeyContext, MediaBuyHandlers as LegacyMediaBuyHandlers, ProposalNegotiationHandlers as LegacyProposalNegotiationHandlers, SignalsHandlers as LegacySignalsHandlers, CreativeHandlers as LegacyCreativeHandlers, GovernanceHandlers as LegacyGovernanceHandlers, AccountHandlers as LegacyAccountHandlers, EventTrackingHandlers as LegacyEventTrackingHandlers, SponsoredIntelligenceHandlers as LegacySponsoredIntelligenceHandlers, ResolveAccountContext as LegacyResolveAccountContext, } from './create-adcp-server.mjs';
+export type { AdcpServerConfig as LegacyAdcpServerConfig, WebhooksConfig, AdcpToolMap as LegacyAdcpToolMap, AdcpServerToolName, AdcpCapabilitiesConfig, AdcpCapabilitiesOverrides, AdcpToolVersionRange, AdcpVersionTranslationEvent, AdcpCustomToolConfig as LegacyAdcpCustomToolConfig, AdcpCustomToolHandler as LegacyAdcpCustomToolHandler, AdcpCustomToolHandlerExtra as LegacyAdcpCustomToolHandlerExtra, McpAppUiMeta, McpAppMeta, AdcpLogger, SignedRequestsConfig, AdcpPreTransport, AdcpSignedRequestsState, HandlerContext as LegacyHandlerContext, SessionKeyContext, MediaBuyHandlers as LegacyMediaBuyHandlers, ProposalNegotiationHandlers as LegacyProposalNegotiationHandlers, SignalsHandlers as LegacySignalsHandlers, CreativeHandlers as LegacyCreativeHandlers, GovernanceHandlers as LegacyGovernanceHandlers, AccountHandlers as LegacyAccountHandlers, EventTrackingHandlers as LegacyEventTrackingHandlers, SponsoredIntelligenceHandlers as LegacySponsoredIntelligenceHandlers, ResolveAccountContext as LegacyResolveAccountContext, } from './create-adcp-server.mjs';
 export { DEFAULT_REPORTING_CAPABILITIES } from './product-defaults.mjs';
 export { isSandboxRequest, mergeSeededProductsIntoResponse, filterValidSeededProducts, filterValidSeededCreatives, filterValidSeededMediaBuys, filterValidSeededAccounts, filterValidSeededAccountFinancials, filterValidSeededCreativeFormats, mergeSeededCreativesIntoResponse, mergeSeededMediaBuysIntoResponse, mergeSeededAccountsIntoResponse, mergeSeededCreativeFormatsIntoResponse, pickSeededAccountFinancialsForRequest, replaceAccountFinancialsIfSeeded, bridgeFromTestControllerStore, bridgeFromSessionStore, } from './test-controller-bridge.mjs';
 export type { TestControllerBridge, TestControllerBridgeContext, BridgeFromSessionStoreOptions, SeededCreative, SeededMediaBuy, SeededAccountFinancials, } from './test-controller-bridge.mjs';

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

@@ -61,7 +61,7 @@ export type { AdcpMcpResourceDefinition, McpAppResourceCsp, McpAppResourcePermis
 export { requireSessionKey, ADCP_PRE_TRANSPORT, ADCP_SIGNED_REQUESTS_STATE, ADCP_INSTRUCTIONS_FN, } from './create-adcp-server';
 export type { SessionContext, OnInstructionsError, MaybePromise, BridgeMarker } from './create-adcp-server';
 export type { AdcpServer, AdcpServerComplianceApi, AdcpServerTransport, AdcpTestRequest, AdcpTestToolsCallRequest, AdcpTestResponse, AdcpInvokeOptions, } from './adcp-server';
-export type { AdcpServerConfig as LegacyAdcpServerConfig, WebhooksConfig, AdcpToolMap as LegacyAdcpToolMap, AdcpServerToolName, AdcpCapabilitiesConfig, AdcpCapabilitiesOverrides, AdcpToolVersionRange, AdcpCustomToolConfig as LegacyAdcpCustomToolConfig, AdcpCustomToolHandler as LegacyAdcpCustomToolHandler, AdcpCustomToolHandlerExtra as LegacyAdcpCustomToolHandlerExtra, McpAppUiMeta, McpAppMeta, AdcpLogger, SignedRequestsConfig, AdcpPreTransport, AdcpSignedRequestsState, HandlerContext as LegacyHandlerContext, SessionKeyContext, MediaBuyHandlers as LegacyMediaBuyHandlers, ProposalNegotiationHandlers as LegacyProposalNegotiationHandlers, SignalsHandlers as LegacySignalsHandlers, CreativeHandlers as LegacyCreativeHandlers, GovernanceHandlers as LegacyGovernanceHandlers, AccountHandlers as LegacyAccountHandlers, EventTrackingHandlers as LegacyEventTrackingHandlers, SponsoredIntelligenceHandlers as LegacySponsoredIntelligenceHandlers, ResolveAccountContext as LegacyResolveAccountContext, } from './create-adcp-server';
+export type { AdcpServerConfig as LegacyAdcpServerConfig, WebhooksConfig, AdcpToolMap as LegacyAdcpToolMap, AdcpServerToolName, AdcpCapabilitiesConfig, AdcpCapabilitiesOverrides, AdcpToolVersionRange, AdcpVersionTranslationEvent, AdcpCustomToolConfig as LegacyAdcpCustomToolConfig, AdcpCustomToolHandler as LegacyAdcpCustomToolHandler, AdcpCustomToolHandlerExtra as LegacyAdcpCustomToolHandlerExtra, McpAppUiMeta, McpAppMeta, AdcpLogger, SignedRequestsConfig, AdcpPreTransport, AdcpSignedRequestsState, HandlerContext as LegacyHandlerContext, SessionKeyContext, MediaBuyHandlers as LegacyMediaBuyHandlers, ProposalNegotiationHandlers as LegacyProposalNegotiationHandlers, SignalsHandlers as LegacySignalsHandlers, CreativeHandlers as LegacyCreativeHandlers, GovernanceHandlers as LegacyGovernanceHandlers, AccountHandlers as LegacyAccountHandlers, EventTrackingHandlers as LegacyEventTrackingHandlers, SponsoredIntelligenceHandlers as LegacySponsoredIntelligenceHandlers, ResolveAccountContext as LegacyResolveAccountContext, } from './create-adcp-server';
 export { DEFAULT_REPORTING_CAPABILITIES } from './product-defaults';
 export { isSandboxRequest, mergeSeededProductsIntoResponse, filterValidSeededProducts, filterValidSeededCreatives, filterValidSeededMediaBuys, filterValidSeededAccounts, filterValidSeededAccountFinancials, filterValidSeededCreativeFormats, mergeSeededCreativesIntoResponse, mergeSeededMediaBuysIntoResponse, mergeSeededAccountsIntoResponse, mergeSeededCreativeFormatsIntoResponse, pickSeededAccountFinancialsForRequest, replaceAccountFinancialsIfSeeded, bridgeFromTestControllerStore, bridgeFromSessionStore, } from './test-controller-bridge';
 export type { TestControllerBridge, TestControllerBridgeContext, BridgeFromSessionStoreOptions, SeededCreative, SeededMediaBuy, SeededAccountFinancials, } from './test-controller-bridge';

package/dist/lib/server/targeting-helpers.d.mts

@@ -56,7 +56,7 @@ export declare const defaultResolvedListCache: ResolvedListCache;
 export declare function clearDefaultResolvedListCache(): void;
 export type ResolveListCallTool = (agentUrl: string, toolName: 'get_property_list' | 'get_collection_list', args: Record<string, unknown>, authToken?: string) => Promise<unknown>;
 export interface ResolveListOptions {
-    /** Require schema-valid property-list pages with identifiers when resolving. Used for certification. */
+    /** Require schema-valid list pages with resolved items. Used for certification. */
     strictResponseValidation?: boolean;
     /** Maximum page size when calling get_property_list / get_collection_list. Defaults to 1000. */
     pageSize?: number;

package/dist/lib/server/targeting-helpers.d.ts

@@ -56,7 +56,7 @@ export declare const defaultResolvedListCache: ResolvedListCache;
 export declare function clearDefaultResolvedListCache(): void;
 export type ResolveListCallTool = (agentUrl: string, toolName: 'get_property_list' | 'get_collection_list', args: Record<string, unknown>, authToken?: string) => Promise<unknown>;
 export interface ResolveListOptions {
-    /** Require schema-valid property-list pages with identifiers when resolving. Used for certification. */
+    /** Require schema-valid list pages with resolved items. Used for certification. */
     strictResponseValidation?: boolean;
     /** Maximum page size when calling get_property_list / get_collection_list. Defaults to 1000. */
     pageSize?: number;

package/dist/lib/server/targeting-helpers.js

@@ -45,6 +45,7 @@ var import_mcp = require('../protocols/mcp.js');
 var import_net = require('../net/index.js');
 var import_probe_policy = require('../utils/probe-policy.js');
 var import_pin_and_bind_fetch = require('./pin-and-bind-fetch.js');
+var import_response_unwrapper = require('../utils/response-unwrapper.js');
 const DEFAULT_RESOLVE_LIST_PAGE_SIZE = 1e3;
 class MemoryResolvedListCache {
   entries = /* @__PURE__ */ new Map();
@@ -80,6 +81,24 @@ function clearDefaultResolvedListCache() {
 const defaultResolveListFetchBase = (0, import_pin_and_bind_fetch.createPinAndBindFetch)();
 const defaultResolveListFetch = (input, init) => defaultResolveListFetchBase(input, { ...init, redirect: "manual" });
 const defaultResolveListCallTool = (agentUrl, toolName, args, authToken) => (0, import_mcp.callMCPTool)(agentUrl, toolName, args, authToken, [], void 0, void 0, defaultResolveListFetch);
+function resolvedListPayload(result, kind) {
+  if (!result || typeof result !== "object" || Array.isArray(result)) return result;
+  const envelope = result;
+  const isMcp = "structuredContent" in envelope || "content" in envelope || "isError" in envelope;
+  let payload;
+  try {
+    payload = isMcp ? (0, import_response_unwrapper.unwrapProtocolResponse)(envelope, void 0, "mcp") : envelope;
+  } catch (cause) {
+    throw new Error(`${kind}_list_invalid_response`, { cause });
+  }
+  const data = payload && typeof payload === "object" ? payload : void 0;
+  if (envelope.isError === true || data?.adcp_error !== void 0) {
+    throw Object.assign(new Error(`${kind}_list_invalid_response`, { cause: data?.adcp_error }), {
+      adcp_error: data?.adcp_error
+    });
+  }
+  return payload;
+}
 async function resolvePropertyList(ref, options = {}) {
   const structurallyNormalizedRef = await normalizePropertyListReference(ref, { resolveDns: false });
   const cache = cacheForOptions(options);
@@ -102,7 +121,10 @@ async function fetchResolvedPropertyList(ref, options) {
   const seenCursors = /* @__PURE__ */ new Set();
   for (let pageIndex = 0; pageIndex < maxPagesForOptions(options); pageIndex += 1) {
     const args = buildResolveListArgs(ref.list_id, pageSizeForOptions(options), cursor);
-    const raw = await callTool(ref.agent_url, "get_property_list", args, ref.auth_token);
+    const raw = resolvedListPayload(
+      await callTool(ref.agent_url, "get_property_list", args, ref.auth_token),
+      "property"
+    );
     if (!raw || typeof raw !== "object" || !("list" in raw)) {
       throw new Error("property_list_invalid_response");
     }
@@ -154,7 +176,7 @@ async function resolveCollectionList(ref, options = {}) {
   const cache = cacheForOptions(options);
   const nowMs = nowMsForOptions(options);
   const cacheKey = resolvedListCacheKey("collection", structurallyNormalizedRef, options);
-  const cached = cacheKey ? cache?.get(cacheKey, nowMs) : void 0;
+  const cached = cacheKey && !options.strictResponseValidation ? cache?.get(cacheKey, nowMs) : void 0;
   if (cached) return cached;
   const normalizedRef = options.callTool ? structurallyNormalizedRef : await normalizeCollectionListReference(structurallyNormalizedRef, { resolveDns: false });
   const result = await fetchResolvedCollectionList(normalizedRef, options);
@@ -170,11 +192,29 @@ async function fetchResolvedCollectionList(ref, options) {
   let cursor;
   for (let pageIndex = 0; pageIndex < maxPagesForOptions(options); pageIndex += 1) {
     const args = buildResolveListArgs(ref.list_id, pageSizeForOptions(options), cursor);
-    const raw = await callTool(ref.agent_url, "get_collection_list", args, ref.auth_token);
+    const raw = resolvedListPayload(
+      await callTool(ref.agent_url, "get_collection_list", args, ref.auth_token),
+      "collection"
+    );
     if (!raw || typeof raw !== "object" || !("list" in raw)) {
       throw new Error("collection_list_invalid_response");
     }
     const response = raw;
+    if (response.status !== void 0 && response.status !== "completed" || raw.errors !== void 0 && (!Array.isArray(raw.errors) || raw.errors.some((error) => !error || typeof error !== "object" || error.severity !== "warning")) || !response.list || response.list.list_id !== ref.list_id || !Array.isArray(response.collections) || response.collections.some(
+      (collection) => !collection || typeof collection !== "object" || Array.isArray(collection) || ["publisher_domain", "collection_id", "collection_rid", "name"].some(
+        (field) => field in collection && typeof collection[field] !== "string"
+      ) || collection.distribution_ids !== void 0 && (!Array.isArray(collection.distribution_ids) || collection.distribution_ids.some(
+        (identifier) => !identifier || typeof identifier !== "object" || typeof identifier.type !== "string" || typeof identifier.value !== "string"
+      ))
+    )) {
+      throw new Error("collection_list_invalid_response");
+    }
+    if (options.strictResponseValidation) {
+      const { GetCollectionListResponseSchema } = await import("../types/schemas.generated.js");
+      if (!GetCollectionListResponseSchema.safeParse(raw).success || response.status !== "completed" || response.collections.length > pageSizeForOptions(options)) {
+        throw new Error("collection_list_invalid_response");
+      }
+    }
     listId = response.list.list_id;
     collections.push(...response.collections ?? []);
     if (typeof response.cache_valid_until === "string") {