@adcp/sdk 16.3.0 → 16.5.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/compliance-fixtures/canonical-storyboards-provenance.json

@@ -1,10 +1,10 @@
 {
   "schema_version": 1,
-  "protocol_version": "3.2.5",
+  "protocol_version": "3.2.7",
   "source_repository": "adcontextprotocol/adcp",
-  "source_tag": "v3.2.5",
-  "source_commit": "3512882b67592622d2ae8bf5c853f565cf58043a",
-  "bundle_sha256": "5cc946062f3ed035f5332db7b1de68e3b6d2af8c01207e3959f2648addfe6e14",
+  "source_tag": "v3.2.7",
+  "source_commit": "8d1d3244b2ef33e1aeb6cfc0d332dbd79125955e",
+  "bundle_sha256": "01c913f1d4771f153c5a0de39450797efbef4145b6c535dd177f10b8df43f47d",
   "files": {
     "principal": {
       "source_path": "static/compliance/source/universal/principal.yaml",

package/dist/lib/compliance-fixtures/canonical-storyboards.d.mts

@@ -28,7 +28,7 @@ export interface CanonicalStoryboardFixture {
 }
 /** Load the deeply immutable provenance shared by the canonical storyboard fixtures. */
 export declare function loadCanonicalStoryboardFixtureProvenance(): CanonicalStoryboardFixtureProvenance;
-/** Load the exact AdCP 3.2.5 `universal/principal` storyboard. */
+/** Load the exact AdCP 3.2.7 `universal/principal` storyboard. */
 export declare function loadCanonicalPrincipalStoryboard(): CanonicalStoryboardFixture;
-/** Load the exact AdCP 3.2.5 `universal/reporting-core` storyboard. */
+/** Load the exact AdCP 3.2.7 `universal/reporting-core` storyboard. */
 export declare function loadCanonicalReportingCoreStoryboard(): CanonicalStoryboardFixture;

package/dist/lib/compliance-fixtures/canonical-storyboards.d.ts

@@ -28,7 +28,7 @@ export interface CanonicalStoryboardFixture {
 }
 /** Load the deeply immutable provenance shared by the canonical storyboard fixtures. */
 export declare function loadCanonicalStoryboardFixtureProvenance(): CanonicalStoryboardFixtureProvenance;
-/** Load the exact AdCP 3.2.5 `universal/principal` storyboard. */
+/** Load the exact AdCP 3.2.7 `universal/principal` storyboard. */
 export declare function loadCanonicalPrincipalStoryboard(): CanonicalStoryboardFixture;
-/** Load the exact AdCP 3.2.5 `universal/reporting-core` storyboard. */
+/** Load the exact AdCP 3.2.7 `universal/reporting-core` storyboard. */
 export declare function loadCanonicalReportingCoreStoryboard(): CanonicalStoryboardFixture;

package/dist/lib/conformance/oracle.js

@@ -35,6 +35,7 @@ module.exports = __toCommonJS(oracle_exports);
 var import_ajv = __toESM(require("ajv"));
 var import_ajv_formats = __toESM(require("ajv-formats"));
 var import_schemaLoader = require('./schemaLoader.js');
+var import_envelope_status_compat = require('../utils/envelope-status-compat.js');
 const STACK_TRACE_SIGNATURES = [
   "    at ",
   // V8 / Node
@@ -138,8 +139,9 @@ function evaluate(input) {
     return { verdict: "rejected", invariantFailures };
   }
   const validate = responseValidator(tool, schemas);
-  const payloadForValidation = responsePayloadForValidation(result);
-  if (!validate(payloadForValidation)) {
+  const data = result.data;
+  const payload = data && typeof data === "object" && !Array.isArray(data) && data.status === void 0 && typeof data.adcp_version === "string" && (0, import_envelope_status_compat.isLegacy30xPayload)(data) ? (0, import_envelope_status_compat.injectLegacyEnvelopeStatus)(data, { toolName: tool }) : result.data;
+  if (!validate(payload)) {
     const errors = (validate.errors ?? []).slice(0, 3).map(formatAjvError);
     invariantFailures.push(`response schema mismatch: ${errors.join("; ")}`);
     return { verdict: "invalid", invariantFailures };
@@ -149,11 +151,6 @@ function evaluate(input) {
     invariantFailures
   };
 }
-function responsePayloadForValidation(result) {
-  if (!result.data || typeof result.data !== "object" || Array.isArray(result.data)) return result.data;
-  const data = result.data;
-  return data.status === void 0 ? { status: result.status, ...data } : data;
-}
 function buildLeakHaystack(result) {
   const parts = [
     result.data,