@adcp/sdk 16.2.0 → 16.4.0

package/dist/lib/adapters/version/schema-projection.js

@@ -0,0 +1,294 @@
+"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 schema_projection_exports = {};
+__export(schema_projection_exports, {
+  projectToolPayload: () => projectToolPayload,
+  releaseDefinesTool: () => releaseDefinesTool
+});
+module.exports = __toCommonJS(schema_projection_exports);
+var import_schema_loader = require('../../validation/schema-loader.js');
+const OMIT = /* @__PURE__ */ Symbol("omit");
+const MAX_DEPTH = 64;
+const SCHEMA_HOST = "https://adcontextprotocol.org";
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function absoluteBase(id) {
+  if (typeof id !== "string" || id.length === 0) return `${SCHEMA_HOST}/schemas/unknown/root.json`;
+  if (id.startsWith("/")) return `${SCHEMA_HOST}${id}`;
+  return id;
+}
+function documentFor(version, ref) {
+  let url;
+  try {
+    url = new URL(ref);
+  } catch {
+    return void 0;
+  }
+  const match = /^\/schemas\/[^/]+\/(.+)$/.exec(url.pathname);
+  if (!match?.[1]) return void 0;
+  const resolved = (0, import_schema_loader.getSchemaDocumentByRef)(match[1], version);
+  if (!resolved) return void 0;
+  return { root: resolved.schema, base: url.origin + url.pathname, version };
+}
+function pointer(root, fragment) {
+  if (fragment === "" || fragment === "/") return root;
+  let current = root;
+  for (const encoded of fragment.replace(/^\//, "").split("/")) {
+    if (!isObject(current)) return void 0;
+    current = current[decodeURIComponent(encoded).replace(/~1/g, "/").replace(/~0/g, "~")];
+  }
+  return isObject(current) ? current : void 0;
+}
+function resolveRef(node, depth) {
+  let current = node;
+  for (let hop = 0; hop < 16 && depth + hop < MAX_DEPTH; hop++) {
+    const ref = current.schema.$ref;
+    if (typeof ref !== "string") return current;
+    if (ref.startsWith("#")) {
+      const target2 = pointer(current.doc.root, ref.slice(1));
+      if (!target2) return current;
+      current = { schema: target2, doc: current.doc };
+      continue;
+    }
+    let absolute;
+    try {
+      absolute = new URL(ref, current.doc.base);
+    } catch {
+      return current;
+    }
+    const doc = documentFor(current.doc.version, absolute.origin + absolute.pathname);
+    if (!doc) return current;
+    const target = pointer(doc.root, absolute.hash.replace(/^#/, ""));
+    if (!target) return current;
+    current = { schema: target, doc };
+  }
+  return current;
+}
+function child(node, value) {
+  return isObject(value) ? { schema: value, doc: node.doc } : void 0;
+}
+function discriminatorMatch(node, value, depth) {
+  if (!isObject(value)) return void 0;
+  const resolved = resolveRef(node, depth);
+  const properties = resolved.schema.properties;
+  if (!isObject(properties)) return void 0;
+  let found = false;
+  for (const [key, propertySchema] of Object.entries(properties)) {
+    if (!isObject(propertySchema)) continue;
+    const prop = resolveRef({ schema: propertySchema, doc: resolved.doc }, depth + 1).schema;
+    if (!Object.hasOwn(prop, "const")) continue;
+    found = true;
+    if (!Object.hasOwn(value, key) || value[key] !== prop.const) return false;
+  }
+  return found ? true : void 0;
+}
+function expand(node, value, depth = 0) {
+  if (depth > MAX_DEPTH) return { nodes: [], unmatchedVariant: false };
+  const resolved = resolveRef(node, depth);
+  const nodes = [resolved];
+  let unmatchedVariant = false;
+  const add = (expansion) => {
+    nodes.push(...expansion.nodes);
+    unmatchedVariant ||= expansion.unmatchedVariant;
+  };
+  for (const keyword of ["allOf"]) {
+    const branches = resolved.schema[keyword];
+    if (!Array.isArray(branches)) continue;
+    for (const branch of branches) {
+      const branchNode = child(resolved, branch);
+      if (branchNode) add(expand(branchNode, value, depth + 1));
+    }
+  }
+  for (const keyword of ["then", "else"]) {
+    const branchNode = child(resolved, resolved.schema[keyword]);
+    if (branchNode) add(expand(branchNode, value, depth + 1));
+  }
+  for (const keyword of ["oneOf", "anyOf"]) {
+    const branches = resolved.schema[keyword];
+    if (!Array.isArray(branches)) continue;
+    const branchNodes = branches.map((branch) => child(resolved, branch)).filter((b) => !!b);
+    const matches = branchNodes.map((branch) => discriminatorMatch(branch, value, depth + 1));
+    const matched = branchNodes.filter((_, index) => matches[index] === true);
+    const discriminated = matches.some((match) => match !== void 0);
+    if (discriminated && matched.length === 0 && matches.every((match) => match === false)) unmatchedVariant = true;
+    for (const branch of matched.length > 0 ? matched : branchNodes) add(expand(branch, value, depth + 1));
+  }
+  return { nodes, unmatchedVariant };
+}
+function allowedScalars(nodes) {
+  let values;
+  for (const { schema } of nodes) {
+    if (Array.isArray(schema.enum)) values = [...values ?? [], ...schema.enum];
+    if (Object.hasOwn(schema, "const")) values = [...values ?? [], schema.const];
+  }
+  return values;
+}
+function hasScalarConstraint(nodes) {
+  return nodes.some(({ schema }) => Array.isArray(schema.enum) || Object.hasOwn(schema, "const"));
+}
+function scalarType(value) {
+  if (value === null) return "null";
+  if (typeof value === "number") return Number.isInteger(value) ? "integer" : "number";
+  return typeof value;
+}
+function acceptsScalarOpenly(nodes, value) {
+  const type = scalarType(value);
+  return nodes.some(({ schema }) => {
+    if (Array.isArray(schema.enum) || Object.hasOwn(schema, "const")) return false;
+    const declared = Array.isArray(schema.type) ? schema.type : schema.type === void 0 ? [] : [schema.type];
+    return declared.includes(type) || type === "integer" && declared.includes("number");
+  });
+}
+function indexProperties(nodes) {
+  const index = { declares: false, schemas: /* @__PURE__ */ new Map(), patterns: [], additional: [] };
+  for (const node of nodes) {
+    const { properties, patternProperties, additionalProperties } = node.schema;
+    if (isObject(properties)) {
+      index.declares = true;
+      for (const [key, value] of Object.entries(properties)) {
+        const propertyNode = child(node, value);
+        if (!propertyNode) continue;
+        index.schemas.set(key, [...index.schemas.get(key) ?? [], propertyNode]);
+      }
+    }
+    if (isObject(patternProperties)) {
+      index.declares = true;
+      for (const [pattern, value] of Object.entries(patternProperties)) {
+        const propertyNode = child(node, value);
+        if (!propertyNode) continue;
+        try {
+          index.patterns.push({ pattern: new RegExp(pattern, "u"), node: propertyNode });
+        } catch {
+        }
+      }
+    }
+    const additionalNode = child(node, additionalProperties);
+    if (additionalNode) index.additional.push(additionalNode);
+  }
+  return index;
+}
+function schemasForKey(index, key) {
+  const declared = index.schemas.get(key);
+  const patterned = index.patterns.filter(({ pattern }) => pattern.test(key)).map(({ node }) => node);
+  if (declared || patterned.length > 0) return [...declared ?? [], ...patterned];
+  return void 0;
+}
+function nonEmpty(values) {
+  return values.length > 0 ? values : void 0;
+}
+function joinPath(path, key) {
+  return path ? `${path}.${key}` : key;
+}
+function project(value, source, target, path, dropped, depth) {
+  if (depth > MAX_DEPTH || source.length === 0 || target.length === 0) return value;
+  const sourceExpansions = source.map((node) => expand(node, value, depth));
+  const targetExpansions = target.map((node) => expand(node, value, depth));
+  const sourceNodes = sourceExpansions.flatMap((e) => e.nodes);
+  const targetNodes = targetExpansions.flatMap((e) => e.nodes);
+  if (targetExpansions.some((e) => e.unmatchedVariant) && !sourceExpansions.some((e) => e.unmatchedVariant) && path !== "") {
+    dropped.push({ path, kind: "variant" });
+    return OMIT;
+  }
+  if (!isObject(value) && !Array.isArray(value)) {
+    if (!hasScalarConstraint(targetNodes) || acceptsScalarOpenly(targetNodes, value)) return value;
+    const targetAllowed = allowedScalars(targetNodes) ?? [];
+    if (targetAllowed.some((allowed) => Object.is(allowed, value))) return value;
+    const sourceAllowed = allowedScalars(sourceNodes);
+    if (sourceAllowed?.some((allowed) => Object.is(allowed, value))) {
+      dropped.push({ path, kind: "enum_value" });
+      return OMIT;
+    }
+    return value;
+  }
+  if (Array.isArray(value)) {
+    const sourceItems = sourceNodes.map((node) => child(node, node.schema.items)).filter((n) => !!n);
+    const targetItems = targetNodes.map((node) => child(node, node.schema.items)).filter((n) => !!n);
+    if (sourceItems.length === 0 || targetItems.length === 0) return value;
+    let changed2 = false;
+    const items = [];
+    value.forEach((item, index) => {
+      const projected = project(item, sourceItems, targetItems, `${path}[${index}]`, dropped, depth + 1);
+      if (projected !== item) changed2 = true;
+      if (projected !== OMIT) items.push(projected);
+    });
+    return changed2 ? items : value;
+  }
+  const sourceIndex = indexProperties(sourceNodes);
+  const targetIndex = indexProperties(targetNodes);
+  let changed = false;
+  const out = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (entry === void 0) {
+      out[key] = entry;
+      continue;
+    }
+    const sourceSchemas = schemasForKey(sourceIndex, key) ?? nonEmpty(sourceIndex.additional);
+    const targetSchemas = schemasForKey(targetIndex, key) ?? nonEmpty(targetIndex.additional);
+    const entryPath = joinPath(path, key);
+    if (sourceIndex.declares && targetIndex.declares && schemasForKey(sourceIndex, key) && !targetSchemas) {
+      dropped.push({ path: entryPath, kind: "field" });
+      changed = true;
+      continue;
+    }
+    if (!sourceSchemas?.length || !targetSchemas?.length) {
+      out[key] = entry;
+      continue;
+    }
+    const projected = project(entry, sourceSchemas, targetSchemas, entryPath, dropped, depth + 1);
+    if (projected === OMIT) {
+      changed = true;
+      continue;
+    }
+    if (projected !== entry) changed = true;
+    out[key] = projected;
+  }
+  return changed ? out : value;
+}
+function toolRoot(toolName, direction, version) {
+  let document;
+  try {
+    document = (0, import_schema_loader.getToolSchemaDocument)(toolName, direction, version);
+  } catch {
+    return void 0;
+  }
+  if (!document) return void 0;
+  const root = document.schema;
+  return { schema: root, doc: { root, base: absoluteBase(root.$id), version } };
+}
+function projectToolPayload(toolName, direction, payload, fromVersion, toVersion) {
+  const source = toolRoot(toolName, direction, fromVersion);
+  const target = toolRoot(toolName, direction, toVersion);
+  if (!source || !target || !isObject(payload)) return { value: payload, dropped: [] };
+  const dropped = [];
+  const projected = project(payload, [source], [target], "", dropped, 0);
+  return { value: projected === OMIT ? payload : projected, dropped };
+}
+function releaseDefinesTool(toolName, version) {
+  try {
+    return (0, import_schema_loader.getToolSchemaDocument)(toolName, "request", version) !== void 0;
+  } catch {
+    return false;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  projectToolPayload,
+  releaseDefinesTool
+});

package/dist/lib/adapters/version/schema-projection.mjs

@@ -0,0 +1,269 @@
+import { getSchemaDocumentByRef, getToolSchemaDocument } from "../../validation/schema-loader.mjs";
+const OMIT = /* @__PURE__ */ Symbol("omit");
+const MAX_DEPTH = 64;
+const SCHEMA_HOST = "https://adcontextprotocol.org";
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function absoluteBase(id) {
+  if (typeof id !== "string" || id.length === 0) return `${SCHEMA_HOST}/schemas/unknown/root.json`;
+  if (id.startsWith("/")) return `${SCHEMA_HOST}${id}`;
+  return id;
+}
+function documentFor(version, ref) {
+  let url;
+  try {
+    url = new URL(ref);
+  } catch {
+    return void 0;
+  }
+  const match = /^\/schemas\/[^/]+\/(.+)$/.exec(url.pathname);
+  if (!match?.[1]) return void 0;
+  const resolved = getSchemaDocumentByRef(match[1], version);
+  if (!resolved) return void 0;
+  return { root: resolved.schema, base: url.origin + url.pathname, version };
+}
+function pointer(root, fragment) {
+  if (fragment === "" || fragment === "/") return root;
+  let current = root;
+  for (const encoded of fragment.replace(/^\//, "").split("/")) {
+    if (!isObject(current)) return void 0;
+    current = current[decodeURIComponent(encoded).replace(/~1/g, "/").replace(/~0/g, "~")];
+  }
+  return isObject(current) ? current : void 0;
+}
+function resolveRef(node, depth) {
+  let current = node;
+  for (let hop = 0; hop < 16 && depth + hop < MAX_DEPTH; hop++) {
+    const ref = current.schema.$ref;
+    if (typeof ref !== "string") return current;
+    if (ref.startsWith("#")) {
+      const target2 = pointer(current.doc.root, ref.slice(1));
+      if (!target2) return current;
+      current = { schema: target2, doc: current.doc };
+      continue;
+    }
+    let absolute;
+    try {
+      absolute = new URL(ref, current.doc.base);
+    } catch {
+      return current;
+    }
+    const doc = documentFor(current.doc.version, absolute.origin + absolute.pathname);
+    if (!doc) return current;
+    const target = pointer(doc.root, absolute.hash.replace(/^#/, ""));
+    if (!target) return current;
+    current = { schema: target, doc };
+  }
+  return current;
+}
+function child(node, value) {
+  return isObject(value) ? { schema: value, doc: node.doc } : void 0;
+}
+function discriminatorMatch(node, value, depth) {
+  if (!isObject(value)) return void 0;
+  const resolved = resolveRef(node, depth);
+  const properties = resolved.schema.properties;
+  if (!isObject(properties)) return void 0;
+  let found = false;
+  for (const [key, propertySchema] of Object.entries(properties)) {
+    if (!isObject(propertySchema)) continue;
+    const prop = resolveRef({ schema: propertySchema, doc: resolved.doc }, depth + 1).schema;
+    if (!Object.hasOwn(prop, "const")) continue;
+    found = true;
+    if (!Object.hasOwn(value, key) || value[key] !== prop.const) return false;
+  }
+  return found ? true : void 0;
+}
+function expand(node, value, depth = 0) {
+  if (depth > MAX_DEPTH) return { nodes: [], unmatchedVariant: false };
+  const resolved = resolveRef(node, depth);
+  const nodes = [resolved];
+  let unmatchedVariant = false;
+  const add = (expansion) => {
+    nodes.push(...expansion.nodes);
+    unmatchedVariant ||= expansion.unmatchedVariant;
+  };
+  for (const keyword of ["allOf"]) {
+    const branches = resolved.schema[keyword];
+    if (!Array.isArray(branches)) continue;
+    for (const branch of branches) {
+      const branchNode = child(resolved, branch);
+      if (branchNode) add(expand(branchNode, value, depth + 1));
+    }
+  }
+  for (const keyword of ["then", "else"]) {
+    const branchNode = child(resolved, resolved.schema[keyword]);
+    if (branchNode) add(expand(branchNode, value, depth + 1));
+  }
+  for (const keyword of ["oneOf", "anyOf"]) {
+    const branches = resolved.schema[keyword];
+    if (!Array.isArray(branches)) continue;
+    const branchNodes = branches.map((branch) => child(resolved, branch)).filter((b) => !!b);
+    const matches = branchNodes.map((branch) => discriminatorMatch(branch, value, depth + 1));
+    const matched = branchNodes.filter((_, index) => matches[index] === true);
+    const discriminated = matches.some((match) => match !== void 0);
+    if (discriminated && matched.length === 0 && matches.every((match) => match === false)) unmatchedVariant = true;
+    for (const branch of matched.length > 0 ? matched : branchNodes) add(expand(branch, value, depth + 1));
+  }
+  return { nodes, unmatchedVariant };
+}
+function allowedScalars(nodes) {
+  let values;
+  for (const { schema } of nodes) {
+    if (Array.isArray(schema.enum)) values = [...values ?? [], ...schema.enum];
+    if (Object.hasOwn(schema, "const")) values = [...values ?? [], schema.const];
+  }
+  return values;
+}
+function hasScalarConstraint(nodes) {
+  return nodes.some(({ schema }) => Array.isArray(schema.enum) || Object.hasOwn(schema, "const"));
+}
+function scalarType(value) {
+  if (value === null) return "null";
+  if (typeof value === "number") return Number.isInteger(value) ? "integer" : "number";
+  return typeof value;
+}
+function acceptsScalarOpenly(nodes, value) {
+  const type = scalarType(value);
+  return nodes.some(({ schema }) => {
+    if (Array.isArray(schema.enum) || Object.hasOwn(schema, "const")) return false;
+    const declared = Array.isArray(schema.type) ? schema.type : schema.type === void 0 ? [] : [schema.type];
+    return declared.includes(type) || type === "integer" && declared.includes("number");
+  });
+}
+function indexProperties(nodes) {
+  const index = { declares: false, schemas: /* @__PURE__ */ new Map(), patterns: [], additional: [] };
+  for (const node of nodes) {
+    const { properties, patternProperties, additionalProperties } = node.schema;
+    if (isObject(properties)) {
+      index.declares = true;
+      for (const [key, value] of Object.entries(properties)) {
+        const propertyNode = child(node, value);
+        if (!propertyNode) continue;
+        index.schemas.set(key, [...index.schemas.get(key) ?? [], propertyNode]);
+      }
+    }
+    if (isObject(patternProperties)) {
+      index.declares = true;
+      for (const [pattern, value] of Object.entries(patternProperties)) {
+        const propertyNode = child(node, value);
+        if (!propertyNode) continue;
+        try {
+          index.patterns.push({ pattern: new RegExp(pattern, "u"), node: propertyNode });
+        } catch {
+        }
+      }
+    }
+    const additionalNode = child(node, additionalProperties);
+    if (additionalNode) index.additional.push(additionalNode);
+  }
+  return index;
+}
+function schemasForKey(index, key) {
+  const declared = index.schemas.get(key);
+  const patterned = index.patterns.filter(({ pattern }) => pattern.test(key)).map(({ node }) => node);
+  if (declared || patterned.length > 0) return [...declared ?? [], ...patterned];
+  return void 0;
+}
+function nonEmpty(values) {
+  return values.length > 0 ? values : void 0;
+}
+function joinPath(path, key) {
+  return path ? `${path}.${key}` : key;
+}
+function project(value, source, target, path, dropped, depth) {
+  if (depth > MAX_DEPTH || source.length === 0 || target.length === 0) return value;
+  const sourceExpansions = source.map((node) => expand(node, value, depth));
+  const targetExpansions = target.map((node) => expand(node, value, depth));
+  const sourceNodes = sourceExpansions.flatMap((e) => e.nodes);
+  const targetNodes = targetExpansions.flatMap((e) => e.nodes);
+  if (targetExpansions.some((e) => e.unmatchedVariant) && !sourceExpansions.some((e) => e.unmatchedVariant) && path !== "") {
+    dropped.push({ path, kind: "variant" });
+    return OMIT;
+  }
+  if (!isObject(value) && !Array.isArray(value)) {
+    if (!hasScalarConstraint(targetNodes) || acceptsScalarOpenly(targetNodes, value)) return value;
+    const targetAllowed = allowedScalars(targetNodes) ?? [];
+    if (targetAllowed.some((allowed) => Object.is(allowed, value))) return value;
+    const sourceAllowed = allowedScalars(sourceNodes);
+    if (sourceAllowed?.some((allowed) => Object.is(allowed, value))) {
+      dropped.push({ path, kind: "enum_value" });
+      return OMIT;
+    }
+    return value;
+  }
+  if (Array.isArray(value)) {
+    const sourceItems = sourceNodes.map((node) => child(node, node.schema.items)).filter((n) => !!n);
+    const targetItems = targetNodes.map((node) => child(node, node.schema.items)).filter((n) => !!n);
+    if (sourceItems.length === 0 || targetItems.length === 0) return value;
+    let changed2 = false;
+    const items = [];
+    value.forEach((item, index) => {
+      const projected = project(item, sourceItems, targetItems, `${path}[${index}]`, dropped, depth + 1);
+      if (projected !== item) changed2 = true;
+      if (projected !== OMIT) items.push(projected);
+    });
+    return changed2 ? items : value;
+  }
+  const sourceIndex = indexProperties(sourceNodes);
+  const targetIndex = indexProperties(targetNodes);
+  let changed = false;
+  const out = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (entry === void 0) {
+      out[key] = entry;
+      continue;
+    }
+    const sourceSchemas = schemasForKey(sourceIndex, key) ?? nonEmpty(sourceIndex.additional);
+    const targetSchemas = schemasForKey(targetIndex, key) ?? nonEmpty(targetIndex.additional);
+    const entryPath = joinPath(path, key);
+    if (sourceIndex.declares && targetIndex.declares && schemasForKey(sourceIndex, key) && !targetSchemas) {
+      dropped.push({ path: entryPath, kind: "field" });
+      changed = true;
+      continue;
+    }
+    if (!sourceSchemas?.length || !targetSchemas?.length) {
+      out[key] = entry;
+      continue;
+    }
+    const projected = project(entry, sourceSchemas, targetSchemas, entryPath, dropped, depth + 1);
+    if (projected === OMIT) {
+      changed = true;
+      continue;
+    }
+    if (projected !== entry) changed = true;
+    out[key] = projected;
+  }
+  return changed ? out : value;
+}
+function toolRoot(toolName, direction, version) {
+  let document;
+  try {
+    document = getToolSchemaDocument(toolName, direction, version);
+  } catch {
+    return void 0;
+  }
+  if (!document) return void 0;
+  const root = document.schema;
+  return { schema: root, doc: { root, base: absoluteBase(root.$id), version } };
+}
+function projectToolPayload(toolName, direction, payload, fromVersion, toVersion) {
+  const source = toolRoot(toolName, direction, fromVersion);
+  const target = toolRoot(toolName, direction, toVersion);
+  if (!source || !target || !isObject(payload)) return { value: payload, dropped: [] };
+  const dropped = [];
+  const projected = project(payload, [source], [target], "", dropped, 0);
+  return { value: projected === OMIT ? payload : projected, dropped };
+}
+function releaseDefinesTool(toolName, version) {
+  try {
+    return getToolSchemaDocument(toolName, "request", version) !== void 0;
+  } catch {
+    return false;
+  }
+}
+export {
+  projectToolPayload,
+  releaseDefinesTool
+};

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

@@ -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.mjs';
+/**
+ * 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 {};