@adcp/sdk 16.2.0 → 16.4.0

package/dist/lib/adapters/version/translate.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Chained conversion between AdCP minor releases.
+ *
+ * Application code builds requests in the shape of the client's own release
+ * and reads responses in that shape. When the negotiated wire release is
+ * older, requests are converted down one minor at a time (3.2 → 3.1 → 3.0)
+ * and responses are converted back up the same steps in reverse.
+ *
+ * Each downward step runs the step's hand-written adapter (renames and moves)
+ * and then the schema projection, which removes whatever the older release
+ * cannot express and reports it. Upward steps run hand-written adapters only:
+ * a field an older seller sends that the newer release dropped is left for
+ * the caller rather than silently discarded.
+ */
+import type { VersionAdapter, VersionDrift } from './types';
+/**
+ * How to convert a request whose account key uses fields the target release
+ * cannot express (AdCP 3.2 added `operator_unit`, `currency` and `timezone`
+ * to the account natural key, and `countries` to brand references).
+ *
+ * - `'refuse'`: fail the call before it is sent.
+ * - `'reduce'`: send the older key when that is unambiguous, and refuse when
+ *   it would merge accounts. The client claims each reduced key for the one
+ *   buyer key it came from; a second buyer key that would reach the same
+ *   seller account is refused with `account_identity_collision`, so no two
+ *   buyer accounts ever share one seller account. Every reduction is reported
+ *   as an `account_identity_reduced` drift entry.
+ */
+export type AccountIdentityDowngrade = 'refuse' | 'reduce';
+export interface TranslationStep {
+    /** Release the step converts from (downward) / to (upward). */
+    upper: string;
+    /** Release the step converts to (downward) / from (upward). Also the adapter key. */
+    lower: string;
+    /** Registry key for the step's hand-written adapters, e.g. `'3.1'`. */
+    key: string;
+}
+export interface RequestTranslation<T = unknown> {
+    params: T;
+    drifts: VersionDrift[];
+    /**
+     * Account-identity fields the target release cannot express, with the
+     * release line that introduced each. Under `'refuse'` the caller must not
+     * send the request when this is non-empty.
+     */
+    identityFields: Array<{
+        path: string;
+        introducedIn: string;
+    }>;
+    /**
+     * Fields of a mutating request the target release cannot express and whose
+     * loss would change what the seller does. The caller must not send the
+     * request when this is non-empty.
+     */
+    refusedFields: Array<{
+        path: string;
+        introducedIn: string;
+    }>;
+}
+export interface ResponseTranslation<T = unknown> {
+    data: T;
+    drifts: VersionDrift[];
+}
+type AdapterLookup = (key: string, toolName: string) => VersionAdapter | undefined;
+/**
+ * Steps between two releases, newest first. Empty when both are on the same
+ * minor line or `lower` is not older than `upper`.
+ */
+export declare function translationSteps(upperVersion: string, lowerVersion: string): TranslationStep[];
+/**
+ * Convert a request from `fromVersion` down to `toVersion`.
+ *
+ * Returns the original params reference when nothing changes. Identity
+ * fields are always reported in `identityFields`; they are removed only under
+ * `'reduce'`, which is also the only policy that emits
+ * `account_identity_reduced` drift.
+ */
+export declare function convertRequestToRelease<T>(toolName: string, params: T, options: {
+    fromVersion: string;
+    toVersion: string;
+    accountIdentity: AccountIdentityDowngrade;
+    adapters: AdapterLookup;
+    /** Whether the request changes seller state (`isMutatingTask`). */
+    mutating: boolean;
+}): RequestTranslation<T>;
+/**
+ * Convert a response from the wire release `fromVersion` up to the client's
+ * `toVersion` through each step's hand-written `adaptResponse`.
+ */
+export declare function convertResponseFromRelease<T>(toolName: string, data: T, options: {
+    fromVersion: string;
+    toVersion: string;
+    adapters: AdapterLookup;
+}): ResponseTranslation<T>;
+/**
+ * Server side: convert an older buyer's request from the served release
+ * `fromVersion` up to the server's release `toVersion` through each step's
+ * `upgradeRequest`. Upward steps never remove fields.
+ */
+export declare function convertRequestFromRelease<T>(toolName: string, params: T, options: {
+    fromVersion: string;
+    toVersion: string;
+    adapters: AdapterLookup;
+}): {
+    params: T;
+    drifts: VersionDrift[];
+};
+/**
+ * Server side: convert a handler's response from the server's release
+ * `fromVersion` down to the served release `toVersion`. Each step runs the
+ * hand-written `downgradeResponse`, then removes and reports what the older
+ * release's response schema cannot express.
+ */
+export declare function convertResponseToRelease<T>(toolName: string, data: T, options: {
+    fromVersion: string;
+    toVersion: string;
+    adapters: AdapterLookup;
+}): {
+    data: T;
+    drifts: VersionDrift[];
+};
+export {};

package/dist/lib/adapters/version/translate.js

@@ -0,0 +1,169 @@
+"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 translate_exports = {};
+__export(translate_exports, {
+  convertRequestFromRelease: () => convertRequestFromRelease,
+  convertRequestToRelease: () => convertRequestToRelease,
+  convertResponseFromRelease: () => convertResponseFromRelease,
+  convertResponseToRelease: () => convertResponseToRelease,
+  translationSteps: () => translationSteps
+});
+module.exports = __toCommonJS(translate_exports);
+var import_negotiate = require('./negotiate.js');
+var import_schema_projection = require('./schema-projection.js');
+function translationSteps(upperVersion, lowerVersion) {
+  const upper = (0, import_negotiate.parseAdcpRelease)(upperVersion);
+  const lower = (0, import_negotiate.parseAdcpRelease)(lowerVersion);
+  if (!upper || !lower || upper.major !== lower.major || upper.minor <= lower.minor) return [];
+  const steps = [];
+  for (let minor = upper.minor; minor > lower.minor; minor--) {
+    const key = `${upper.major}.${minor - 1}`;
+    steps.push({
+      upper: minor === upper.minor ? upperVersion : `${upper.major}.${minor}`,
+      lower: minor - 1 === lower.minor ? lowerVersion : key,
+      key
+    });
+  }
+  return steps;
+}
+const IDENTITY_FIELD_PATTERNS = [
+  // Account references anywhere in a request (`account`, `accounts[n]`,
+  // `filters.accounts[n]`), including sync_accounts rows. AdCP 3.2 brand
+  // country sets are part of the key inside an account reference.
+  /(?:^|[.\]])accounts?(?:\[\d+\])?\.(?:operator_unit|currency|timezone|brand\.countries)$/,
+  // ...and scope a rights licensee.
+  /^(?:buyer|buyer_brand)\.countries$/
+];
+function isIdentityDrop(drop) {
+  return drop.kind === "field" && IDENTITY_FIELD_PATTERNS.some((pattern) => pattern.test(drop.path));
+}
+const DESCRIPTIVE_FIELD_PATTERNS = [
+  /^(?:name|opportunity|governance_context)$/,
+  /^brand\.countries$/,
+  /(?:^|\.)pacing$/,
+  /\.creative_assignments\[\d+\]\.(?:rotation_mode|group_id|sequence_position)$/
+];
+const UPDATE_TOOLS = /* @__PURE__ */ new Set(["update_media_buy"]);
+function isDescriptiveDrop(toolName, drop) {
+  if (UPDATE_TOOLS.has(toolName)) return false;
+  return drop.kind === "field" && DESCRIPTIVE_FIELD_PATTERNS.some((pattern) => pattern.test(drop.path));
+}
+function droppedDrift(toolName, drops, step) {
+  const paths = drops.map((drop) => drop.path);
+  return {
+    type: "version_downgrade_fields_dropped",
+    message: `${toolName}: removed ${paths.length} field(s) AdCP ${(0, import_negotiate.adcpMinorLine)(step.lower) ?? step.lower} cannot express before sending to the seller: ${paths.join(", ")}.`,
+    strippedFields: paths,
+    fromVersion: step.upper,
+    toVersion: step.lower
+  };
+}
+function identityDrift(toolName, drops, step) {
+  const paths = drops.map((drop) => drop.path);
+  return {
+    type: "account_identity_reduced",
+    message: `${toolName}: account key reduced to AdCP ${(0, import_negotiate.adcpMinorLine)(step.lower) ?? step.lower} by removing ${paths.join(", ")}. The seller identifies the account by the reduced key; this buyer key is the only one allowed to use it.`,
+    strippedFields: paths,
+    fromVersion: step.upper,
+    toVersion: step.lower
+  };
+}
+function convertRequestToRelease(toolName, params, options) {
+  const drifts = [];
+  const identityFields = [];
+  const refusedFields = [];
+  let current = params;
+  for (const step of translationSteps(options.fromVersion, options.toVersion)) {
+    const adapter = options.adapters(step.key, toolName);
+    if (adapter?.adaptRequest) {
+      const adapted = adapter.adaptRequest(current);
+      current = adapted.params;
+      if (adapted.drift) drifts.push({ ...adapted.drift, fromVersion: step.upper, toVersion: step.lower });
+    }
+    const projected = (0, import_schema_projection.projectToolPayload)(toolName, "request", current, step.upper, step.lower);
+    if (projected.dropped.length === 0) continue;
+    const identity = projected.dropped.filter(isIdentityDrop);
+    const other = projected.dropped.filter((drop) => !isIdentityDrop(drop));
+    const introducedIn = (0, import_negotiate.adcpMinorLine)(step.upper) ?? step.upper;
+    identityFields.push(...identity.map((drop) => ({ path: drop.path, introducedIn })));
+    if (options.mutating) {
+      for (const drop of other) {
+        if (!isDescriptiveDrop(toolName, drop)) refusedFields.push({ path: drop.path, introducedIn });
+      }
+    }
+    current = projected.value;
+    if (other.length > 0) drifts.push(droppedDrift(toolName, other, step));
+    if (identity.length > 0 && options.accountIdentity === "reduce") {
+      drifts.push(identityDrift(toolName, identity, step));
+    }
+  }
+  return { params: current, drifts, identityFields, refusedFields };
+}
+function convertResponseFromRelease(toolName, data, options) {
+  const drifts = [];
+  let current = data;
+  for (const step of [...translationSteps(options.toVersion, options.fromVersion)].reverse()) {
+    const adapter = options.adapters(step.key, toolName);
+    if (!adapter?.adaptResponse) continue;
+    const adapted = adapter.adaptResponse(current);
+    current = adapted.data;
+    if (adapted.drift) drifts.push({ ...adapted.drift, fromVersion: step.lower, toVersion: step.upper });
+  }
+  return { data: current, drifts };
+}
+function convertRequestFromRelease(toolName, params, options) {
+  const drifts = [];
+  let current = params;
+  for (const step of [...translationSteps(options.toVersion, options.fromVersion)].reverse()) {
+    const adapter = options.adapters(step.key, toolName);
+    if (!adapter?.upgradeRequest) continue;
+    const adapted = adapter.upgradeRequest(current);
+    current = adapted.params;
+    if (adapted.drift) drifts.push({ ...adapted.drift, fromVersion: step.lower, toVersion: step.upper });
+  }
+  return { params: current, drifts };
+}
+function convertResponseToRelease(toolName, data, options) {
+  const drifts = [];
+  let current = data;
+  for (const step of translationSteps(options.fromVersion, options.toVersion)) {
+    const adapter = options.adapters(step.key, toolName);
+    if (adapter?.downgradeResponse) {
+      const adapted = adapter.downgradeResponse(current);
+      current = adapted.data;
+      if (adapted.drift) drifts.push({ ...adapted.drift, fromVersion: step.upper, toVersion: step.lower });
+    }
+    const projected = (0, import_schema_projection.projectToolPayload)(toolName, "sync", current, step.upper, step.lower);
+    if (projected.dropped.length === 0) continue;
+    current = projected.value;
+    drifts.push({
+      ...droppedDrift(toolName, projected.dropped, step),
+      message: `${toolName}: removed ${projected.dropped.length} response field(s) AdCP ${(0, import_negotiate.adcpMinorLine)(step.lower) ?? step.lower} cannot express: ${projected.dropped.map((d) => d.path).join(", ")}.`
+    });
+  }
+  return { data: current, drifts };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  convertRequestFromRelease,
+  convertRequestToRelease,
+  convertResponseFromRelease,
+  convertResponseToRelease,
+  translationSteps
+});

package/dist/lib/adapters/version/translate.mjs

@@ -0,0 +1,141 @@
+import { adcpMinorLine, parseAdcpRelease } from "./negotiate.mjs";
+import { projectToolPayload } from "./schema-projection.mjs";
+function translationSteps(upperVersion, lowerVersion) {
+  const upper = parseAdcpRelease(upperVersion);
+  const lower = parseAdcpRelease(lowerVersion);
+  if (!upper || !lower || upper.major !== lower.major || upper.minor <= lower.minor) return [];
+  const steps = [];
+  for (let minor = upper.minor; minor > lower.minor; minor--) {
+    const key = `${upper.major}.${minor - 1}`;
+    steps.push({
+      upper: minor === upper.minor ? upperVersion : `${upper.major}.${minor}`,
+      lower: minor - 1 === lower.minor ? lowerVersion : key,
+      key
+    });
+  }
+  return steps;
+}
+const IDENTITY_FIELD_PATTERNS = [
+  // Account references anywhere in a request (`account`, `accounts[n]`,
+  // `filters.accounts[n]`), including sync_accounts rows. AdCP 3.2 brand
+  // country sets are part of the key inside an account reference.
+  /(?:^|[.\]])accounts?(?:\[\d+\])?\.(?:operator_unit|currency|timezone|brand\.countries)$/,
+  // ...and scope a rights licensee.
+  /^(?:buyer|buyer_brand)\.countries$/
+];
+function isIdentityDrop(drop) {
+  return drop.kind === "field" && IDENTITY_FIELD_PATTERNS.some((pattern) => pattern.test(drop.path));
+}
+const DESCRIPTIVE_FIELD_PATTERNS = [
+  /^(?:name|opportunity|governance_context)$/,
+  /^brand\.countries$/,
+  /(?:^|\.)pacing$/,
+  /\.creative_assignments\[\d+\]\.(?:rotation_mode|group_id|sequence_position)$/
+];
+const UPDATE_TOOLS = /* @__PURE__ */ new Set(["update_media_buy"]);
+function isDescriptiveDrop(toolName, drop) {
+  if (UPDATE_TOOLS.has(toolName)) return false;
+  return drop.kind === "field" && DESCRIPTIVE_FIELD_PATTERNS.some((pattern) => pattern.test(drop.path));
+}
+function droppedDrift(toolName, drops, step) {
+  const paths = drops.map((drop) => drop.path);
+  return {
+    type: "version_downgrade_fields_dropped",
+    message: `${toolName}: removed ${paths.length} field(s) AdCP ${adcpMinorLine(step.lower) ?? step.lower} cannot express before sending to the seller: ${paths.join(", ")}.`,
+    strippedFields: paths,
+    fromVersion: step.upper,
+    toVersion: step.lower
+  };
+}
+function identityDrift(toolName, drops, step) {
+  const paths = drops.map((drop) => drop.path);
+  return {
+    type: "account_identity_reduced",
+    message: `${toolName}: account key reduced to AdCP ${adcpMinorLine(step.lower) ?? step.lower} by removing ${paths.join(", ")}. The seller identifies the account by the reduced key; this buyer key is the only one allowed to use it.`,
+    strippedFields: paths,
+    fromVersion: step.upper,
+    toVersion: step.lower
+  };
+}
+function convertRequestToRelease(toolName, params, options) {
+  const drifts = [];
+  const identityFields = [];
+  const refusedFields = [];
+  let current = params;
+  for (const step of translationSteps(options.fromVersion, options.toVersion)) {
+    const adapter = options.adapters(step.key, toolName);
+    if (adapter?.adaptRequest) {
+      const adapted = adapter.adaptRequest(current);
+      current = adapted.params;
+      if (adapted.drift) drifts.push({ ...adapted.drift, fromVersion: step.upper, toVersion: step.lower });
+    }
+    const projected = projectToolPayload(toolName, "request", current, step.upper, step.lower);
+    if (projected.dropped.length === 0) continue;
+    const identity = projected.dropped.filter(isIdentityDrop);
+    const other = projected.dropped.filter((drop) => !isIdentityDrop(drop));
+    const introducedIn = adcpMinorLine(step.upper) ?? step.upper;
+    identityFields.push(...identity.map((drop) => ({ path: drop.path, introducedIn })));
+    if (options.mutating) {
+      for (const drop of other) {
+        if (!isDescriptiveDrop(toolName, drop)) refusedFields.push({ path: drop.path, introducedIn });
+      }
+    }
+    current = projected.value;
+    if (other.length > 0) drifts.push(droppedDrift(toolName, other, step));
+    if (identity.length > 0 && options.accountIdentity === "reduce") {
+      drifts.push(identityDrift(toolName, identity, step));
+    }
+  }
+  return { params: current, drifts, identityFields, refusedFields };
+}
+function convertResponseFromRelease(toolName, data, options) {
+  const drifts = [];
+  let current = data;
+  for (const step of [...translationSteps(options.toVersion, options.fromVersion)].reverse()) {
+    const adapter = options.adapters(step.key, toolName);
+    if (!adapter?.adaptResponse) continue;
+    const adapted = adapter.adaptResponse(current);
+    current = adapted.data;
+    if (adapted.drift) drifts.push({ ...adapted.drift, fromVersion: step.lower, toVersion: step.upper });
+  }
+  return { data: current, drifts };
+}
+function convertRequestFromRelease(toolName, params, options) {
+  const drifts = [];
+  let current = params;
+  for (const step of [...translationSteps(options.toVersion, options.fromVersion)].reverse()) {
+    const adapter = options.adapters(step.key, toolName);
+    if (!adapter?.upgradeRequest) continue;
+    const adapted = adapter.upgradeRequest(current);
+    current = adapted.params;
+    if (adapted.drift) drifts.push({ ...adapted.drift, fromVersion: step.lower, toVersion: step.upper });
+  }
+  return { params: current, drifts };
+}
+function convertResponseToRelease(toolName, data, options) {
+  const drifts = [];
+  let current = data;
+  for (const step of translationSteps(options.fromVersion, options.toVersion)) {
+    const adapter = options.adapters(step.key, toolName);
+    if (adapter?.downgradeResponse) {
+      const adapted = adapter.downgradeResponse(current);
+      current = adapted.data;
+      if (adapted.drift) drifts.push({ ...adapted.drift, fromVersion: step.upper, toVersion: step.lower });
+    }
+    const projected = projectToolPayload(toolName, "sync", current, step.upper, step.lower);
+    if (projected.dropped.length === 0) continue;
+    current = projected.value;
+    drifts.push({
+      ...droppedDrift(toolName, projected.dropped, step),
+      message: `${toolName}: removed ${projected.dropped.length} response field(s) AdCP ${adcpMinorLine(step.lower) ?? step.lower} cannot express: ${projected.dropped.map((d) => d.path).join(", ")}.`
+    });
+  }
+  return { data: current, drifts };
+}
+export {
+  convertRequestFromRelease,
+  convertRequestToRelease,
+  convertResponseFromRelease,
+  convertResponseToRelease,
+  translationSteps
+};

package/dist/lib/adapters/version/types.d.mts

@@ -1,10 +1,16 @@
 /**
- * Registry pattern for AdCP protocol-version request adapters.
+ * Registry pattern for AdCP protocol-version adapters.
  *
- * Each AdCP tool that needs adaptation when targeting a seller on an older
- * protocol version registers a `VersionAdapter`. The adapter's `adaptRequest`
- * strips or rewrites fields the target version does not accept, returning the
- * adapted params and an optional `VersionDrift` describing what changed.
+ * Each AdCP tool that needs hand-written adaptation between two consecutive
+ * minor releases registers a `VersionAdapter` under the older release's key.
+ * `adaptRequest` converts a request from the next minor down to the key's
+ * release, and `adaptResponse` converts a response from the key's release up
+ * to the next minor. Both return the (possibly modified) payload and an
+ * optional `VersionDrift` describing what changed.
+ *
+ * Hand-written adapters cover renames and moves. Fields the older release
+ * cannot express at all are removed by the schema-driven projection in
+ * `schema-projection.ts`, which runs after the adapter on each step.
  *
  * Adapters live in per-version directories (`version/<target>/`) and are
  * collected by the registry in `version/index.ts`. Adding support for a new
@@ -15,21 +21,56 @@ export interface VersionDrift {
     type: string;
     /** Human-readable description of what was stripped and why. */
     message: string;
-    /** Names of the fields removed from the request. */
+    /** Names (or JSON paths) of the fields removed from the payload. */
     strippedFields?: string[];
+    /** Fields whose values were moved or rewritten rather than removed. */
+    movedFields?: Array<{
+        from: string;
+        to: string;
+    }>;
     /** Individual drift types when one adaptation aggregates multiple changes. */
     constituentTypes?: string[];
+    /** Release the payload was converted from. Set by the translation chain. */
+    fromVersion?: string;
+    /** Release the payload was converted to. Set by the translation chain. */
+    toVersion?: string;
 }
 export interface VersionAdapter {
     /** AdCP tool name this adapter handles (snake_case, e.g. `create_media_buy`). */
     readonly toolName: string;
     /**
-     * Adapt a request for the target protocol version. Returns the (possibly
-     * modified) params and an optional drift description. When no adaptation is
-     * needed the original params reference is returned unchanged.
+     * Adapt a request from the next minor release down to this adapter's
+     * release. Returns the (possibly modified) params and an optional drift
+     * description. When no adaptation is needed the original params reference
+     * is returned unchanged.
+     */
+    adaptRequest?(params: unknown): {
+        params: unknown;
+        drift?: VersionDrift;
+    };
+    /**
+     * Adapt a response from this adapter's release up to the next minor
+     * release. Returns the original reference when nothing changes.
+     */
+    adaptResponse?(data: unknown): {
+        data: unknown;
+        drift?: VersionDrift;
+    };
+    /**
+     * Server side: adapt an older buyer's request from this adapter's release
+     * up to the next minor release, so handlers see one shape.
      */
-    adaptRequest(params: unknown): {
+    upgradeRequest?(params: unknown): {
         params: unknown;
         drift?: VersionDrift;
     };
+    /**
+     * Server side: adapt a handler's response from the next minor release down
+     * to this adapter's release, before the schema projection removes what
+     * this release cannot express.
+     */
+    downgradeResponse?(data: unknown): {
+        data: unknown;
+        drift?: VersionDrift;
+    };
 }

package/dist/lib/adapters/version/types.d.ts

@@ -1,10 +1,16 @@
 /**
- * Registry pattern for AdCP protocol-version request adapters.
+ * Registry pattern for AdCP protocol-version adapters.
  *
- * Each AdCP tool that needs adaptation when targeting a seller on an older
- * protocol version registers a `VersionAdapter`. The adapter's `adaptRequest`
- * strips or rewrites fields the target version does not accept, returning the
- * adapted params and an optional `VersionDrift` describing what changed.
+ * Each AdCP tool that needs hand-written adaptation between two consecutive
+ * minor releases registers a `VersionAdapter` under the older release's key.
+ * `adaptRequest` converts a request from the next minor down to the key's
+ * release, and `adaptResponse` converts a response from the key's release up
+ * to the next minor. Both return the (possibly modified) payload and an
+ * optional `VersionDrift` describing what changed.
+ *
+ * Hand-written adapters cover renames and moves. Fields the older release
+ * cannot express at all are removed by the schema-driven projection in
+ * `schema-projection.ts`, which runs after the adapter on each step.
  *
  * Adapters live in per-version directories (`version/<target>/`) and are
  * collected by the registry in `version/index.ts`. Adding support for a new
@@ -15,21 +21,56 @@ export interface VersionDrift {
     type: string;
     /** Human-readable description of what was stripped and why. */
     message: string;
-    /** Names of the fields removed from the request. */
+    /** Names (or JSON paths) of the fields removed from the payload. */
     strippedFields?: string[];
+    /** Fields whose values were moved or rewritten rather than removed. */
+    movedFields?: Array<{
+        from: string;
+        to: string;
+    }>;
     /** Individual drift types when one adaptation aggregates multiple changes. */
     constituentTypes?: string[];
+    /** Release the payload was converted from. Set by the translation chain. */
+    fromVersion?: string;
+    /** Release the payload was converted to. Set by the translation chain. */
+    toVersion?: string;
 }
 export interface VersionAdapter {
     /** AdCP tool name this adapter handles (snake_case, e.g. `create_media_buy`). */
     readonly toolName: string;
     /**
-     * Adapt a request for the target protocol version. Returns the (possibly
-     * modified) params and an optional drift description. When no adaptation is
-     * needed the original params reference is returned unchanged.
+     * Adapt a request from the next minor release down to this adapter's
+     * release. Returns the (possibly modified) params and an optional drift
+     * description. When no adaptation is needed the original params reference
+     * is returned unchanged.
+     */
+    adaptRequest?(params: unknown): {
+        params: unknown;
+        drift?: VersionDrift;
+    };
+    /**
+     * Adapt a response from this adapter's release up to the next minor
+     * release. Returns the original reference when nothing changes.
+     */
+    adaptResponse?(data: unknown): {
+        data: unknown;
+        drift?: VersionDrift;
+    };
+    /**
+     * Server side: adapt an older buyer's request from this adapter's release
+     * up to the next minor release, so handlers see one shape.
      */
-    adaptRequest(params: unknown): {
+    upgradeRequest?(params: unknown): {
         params: unknown;
         drift?: VersionDrift;
     };
+    /**
+     * Server side: adapt a handler's response from the next minor release down
+     * to this adapter's release, before the schema projection removes what
+     * this release cannot express.
+     */
+    downgradeResponse?(data: unknown): {
+        data: unknown;
+        drift?: VersionDrift;
+    };
 }

package/dist/lib/core/AgentClient.d.mts

@@ -160,7 +160,7 @@ export type TaskRequestFor<K extends AdcpTaskName> = TaskRequestTypeMap[K];
  * - `governance` — buyer-side governance config
  * - `requireV3ForMutations` — enforce AdCP v3 before dispatching mutating tools
  */
-export type InProcessAgentClientConfig = Pick<SingleAgentClientConfig, 'adcpVersion' | 'wireAdcpVersion' | 'versionEnvelope' | 'debug' | 'validation' | 'governance' | 'onActivity' | 'legacyFormatConverter' | 'projectionCatalogs' | 'canonicalFormatLegacyResolver' | 'validateFeatures' | 'requireV3ForMutations' | 'workingTimeout' | 'defaultMaxClarifications' | 'persistConversations' | 'deferredStorage' | 'resolveDeferredAgent' | 'deferredTaskTtlSeconds'> & {
+export type InProcessAgentClientConfig = Pick<SingleAgentClientConfig, 'adcpVersion' | 'wireAdcpVersion' | 'versionEnvelope' | 'debug' | 'validation' | 'governance' | 'onActivity' | 'legacyFormatConverter' | 'projectionCatalogs' | 'canonicalFormatLegacyResolver' | 'validateFeatures' | 'requireV3ForMutations' | 'accountIdentityDowngrade' | 'workingTimeout' | 'defaultMaxClarifications' | 'persistConversations' | 'deferredStorage' | 'resolveDeferredAgent' | 'deferredTaskTtlSeconds'> & {
     /**
      * Human-readable name for this agent, used in debug logs and
      * `getAgentName()`. Defaults to `'in-process'`.

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

@@ -160,7 +160,7 @@ export type TaskRequestFor<K extends AdcpTaskName> = TaskRequestTypeMap[K];
  * - `governance` — buyer-side governance config
  * - `requireV3ForMutations` — enforce AdCP v3 before dispatching mutating tools
  */
-export type InProcessAgentClientConfig = Pick<SingleAgentClientConfig, 'adcpVersion' | 'wireAdcpVersion' | 'versionEnvelope' | 'debug' | 'validation' | 'governance' | 'onActivity' | 'legacyFormatConverter' | 'projectionCatalogs' | 'canonicalFormatLegacyResolver' | 'validateFeatures' | 'requireV3ForMutations' | 'workingTimeout' | 'defaultMaxClarifications' | 'persistConversations' | 'deferredStorage' | 'resolveDeferredAgent' | 'deferredTaskTtlSeconds'> & {
+export type InProcessAgentClientConfig = Pick<SingleAgentClientConfig, 'adcpVersion' | 'wireAdcpVersion' | 'versionEnvelope' | 'debug' | 'validation' | 'governance' | 'onActivity' | 'legacyFormatConverter' | 'projectionCatalogs' | 'canonicalFormatLegacyResolver' | 'validateFeatures' | 'requireV3ForMutations' | 'accountIdentityDowngrade' | 'workingTimeout' | 'defaultMaxClarifications' | 'persistConversations' | 'deferredStorage' | 'resolveDeferredAgent' | 'deferredTaskTtlSeconds'> & {
     /**
      * Human-readable name for this agent, used in debug logs and
      * `getAgentName()`. Defaults to `'in-process'`.

package/dist/lib/core/AgentClient.js

@@ -37,6 +37,8 @@ var import_SingleAgentClient = require('./SingleAgentClient.js');
 var import_request_proposals_guard = require('./request-proposals-guard.js');
 var import_buyer = require('../negotiation/buyer.js');
 var import_verification = require('../negotiation/verification.js');
+var import_version = require('../negotiation/version.js');
+var import_version2 = require('../version.js');
 function stripRefineProposalsSdkAnnotations(data) {
   const canonical = { ...data };
   delete canonical.success;
@@ -179,6 +181,10 @@ class AgentClient {
   getAdcpVersion() {
     return this.client.getAdcpVersion();
   }
+  /** @internal Original envelope pin, separate from the validation schema pin. */
+  getWireAdcpVersion() {
+    return this.client.getWireAdcpVersion();
+  }
   /**
    * Negotiate one compact-first media-buy facade for this seller.
    *
@@ -512,7 +518,17 @@ class AgentClient {
     this.retainSession(result);
     if (result.success && result.status === "completed") {
       const data = stripRefineProposalsSdkAnnotations(result.data);
-      (0, import_verification.assertRefineProposalsResponse)(request, data);
+      const cachedServedVersion = this.client.getCachedServedAdcpVersion(taskOptions);
+      (0, import_verification.assertRefineProposalsResponse)(request, data, {
+        adcpVersion: this.client.getAdcpVersion(),
+        // Task metadata repeats the response echo. Independently discovered
+        // actual served evidence must constrain that seller-controlled value.
+        servedAdcpVersion: (0, import_version.applicableRefinementServedVersion)(
+          cachedServedVersion,
+          request.adcp_version,
+          (0, import_version2.toReleasePrecisionVersion)(this.client.getWireAdcpVersion())
+        ) ?? result.metadata.adcpVersion
+      });
       return { ...result, data };
     }
     return result;