@adcp/sdk 16.3.0 → 16.4.0

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

@@ -1,20 +1,31 @@
 /**
- * Registry of per-version request adapters, keyed by target AdCP version string.
+ * Registry of per-version adapters, keyed by the older AdCP release of each
+ * consecutive minor pair (`'3.1'` holds the 3.2 ↔ 3.1 adapters, `'3.0'` the
+ * 3.1 ↔ 3.0 adapters).
  *
- * `resolveAdapterKey` maps a (clientVersion, sellerCaps) pair to the adapter
- * key whose adapters should be applied. `getVersionAdapter` looks up the
- * per-tool adapter for that key. The dispatch in `SingleAgentClient` calls
- * both; tools without a registered adapter for the resolved key pass through
- * unchanged.
+ * `negotiateAdcpRelease` picks the wire release for a seller.
+ * `convertRequest` / `convertResponse` then chain the adapters and the
+ * schema projection across every step between the client's release and the
+ * wire release. `resolveAdapterKey` remains for sellers whose release cannot
+ * be negotiated (synthetic capabilities), where only the 3.0 adapters apply.
  *
  * Add a new version transition by:
- *   1. Create a `version/<target>/` directory with per-tool adapter modules.
+ *   1. Create a `version/<target>/` directory with per-tool adapter modules
+ *      for renames and moves. Pure additions need no adapter: the schema
+ *      projection removes and reports them.
  *   2. Collect them in `version/<target>/index.ts` as a `ReadonlyArray<VersionAdapter>`.
  *   3. Register below.
  *   4. Add tests to the conformance suite.
  */
 import type { VersionAdapter } from './types';
+import { type AccountIdentityDowngrade, type RequestTranslation, type ResponseTranslation } from './translate';
 export type { VersionAdapter, VersionDrift } from './types';
+export type { AccountIdentityDowngrade, RequestTranslation, ResponseTranslation, TranslationStep } from './translate';
+export { translationSteps } from './translate';
+export { negotiateAdcpRelease, isNegotiationFailure, parseAdcpRelease, adcpMinorLine, compareAdcpMinorLines, } from './negotiate';
+export type { NegotiatedAdcpRelease, AdcpNegotiationFailure, AdcpNegotiationSource } from './negotiate';
+export { projectToolPayload, releaseDefinesTool } from './schema-projection';
+export type { ProjectionDrop, ProjectionResult } from './schema-projection';
 /**
  * Look up the version adapter for a given (adapterKey, toolName) pair.
  * Returns `undefined` when no adapter is registered — caller passes through.
@@ -36,3 +47,44 @@ export declare function resolveAdapterKey(clientVersion: string | undefined, cap
  * Used by the conformance test suite as the authoritative list.
  */
 export declare function listVersionAdapterTools(adapterKey: string): string[];
+/**
+ * Convert a request built for `fromVersion` (the client's release) down to
+ * the negotiated wire release `toVersion`.
+ */
+export declare function convertRequest<T>(toolName: string, params: T, options: {
+    fromVersion: string;
+    toVersion: string;
+    accountIdentity?: AccountIdentityDowngrade;
+    /** Defaults to `isMutatingTask(toolName)`. */
+    mutating?: boolean;
+}): RequestTranslation<T>;
+/**
+ * Convert a response served at the wire release `fromVersion` up to the
+ * client's release `toVersion`.
+ */
+export declare function convertResponse<T>(toolName: string, data: T, options: {
+    fromVersion: string;
+    toVersion: string;
+}): ResponseTranslation<T>;
+/**
+ * Server side: convert an older buyer's request from the served release
+ * `fromVersion` up to the server's release `toVersion`.
+ */
+export declare function upgradeRequest<T>(toolName: string, params: T, options: {
+    fromVersion: string;
+    toVersion: string;
+}): {
+    params: T;
+    drifts: import('./types').VersionDrift[];
+};
+/**
+ * Server side: convert a handler's response from the server's release
+ * `fromVersion` down to the served release `toVersion`.
+ */
+export declare function downgradeResponse<T>(toolName: string, data: T, options: {
+    fromVersion: string;
+    toVersion: string;
+}): {
+    data: T;
+    drifts: import('./types').VersionDrift[];
+};

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

@@ -18,18 +18,37 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var version_exports = {};
 __export(version_exports, {
+  adcpMinorLine: () => import_negotiate.adcpMinorLine,
+  compareAdcpMinorLines: () => import_negotiate.compareAdcpMinorLines,
+  convertRequest: () => convertRequest,
+  convertResponse: () => convertResponse,
+  downgradeResponse: () => downgradeResponse,
   getVersionAdapter: () => getVersionAdapter,
+  isNegotiationFailure: () => import_negotiate.isNegotiationFailure,
   listVersionAdapterTools: () => listVersionAdapterTools,
-  resolveAdapterKey: () => resolveAdapterKey
+  negotiateAdcpRelease: () => import_negotiate.negotiateAdcpRelease,
+  parseAdcpRelease: () => import_negotiate.parseAdcpRelease,
+  projectToolPayload: () => import_schema_projection.projectToolPayload,
+  releaseDefinesTool: () => import_schema_projection.releaseDefinesTool,
+  resolveAdapterKey: () => resolveAdapterKey,
+  translationSteps: () => import_translate2.translationSteps,
+  upgradeRequest: () => upgradeRequest
 });
 module.exports = __toCommonJS(version_exports);
 var import_adcp_version_config = require('../../utils/adcp-version-config.js');
+var import_idempotency = require('../../utils/idempotency.js');
 var import__ = require('./3.0/index.js');
+var import__2 = require('./3.1/index.js');
+var import_translate = require('./translate.js');
+var import_translate2 = require('./translate.js');
+var import_negotiate = require('./negotiate.js');
+var import_schema_projection = require('./schema-projection.js');
 const REGISTRY = /* @__PURE__ */ new Map();
 function register(version, adapters) {
   REGISTRY.set(version, new Map(adapters.map((a) => [a.toolName, a])));
 }
 register("3.0", import__.v30Adapters);
+register("3.1", import__2.v31Adapters);
 function getVersionAdapter(adapterKey, toolName) {
   return REGISTRY.get(adapterKey)?.get(toolName);
 }
@@ -40,9 +59,39 @@ function resolveAdapterKey(clientVersion, caps) {
 function listVersionAdapterTools(adapterKey) {
   return [...REGISTRY.get(adapterKey)?.keys() ?? []];
 }
+function convertRequest(toolName, params, options) {
+  return (0, import_translate.convertRequestToRelease)(toolName, params, {
+    fromVersion: options.fromVersion,
+    toVersion: options.toVersion,
+    accountIdentity: options.accountIdentity ?? "refuse",
+    mutating: options.mutating ?? (0, import_idempotency.isMutatingTask)(toolName),
+    adapters: getVersionAdapter
+  });
+}
+function convertResponse(toolName, data, options) {
+  return (0, import_translate.convertResponseFromRelease)(toolName, data, { ...options, adapters: getVersionAdapter });
+}
+function upgradeRequest(toolName, params, options) {
+  return (0, import_translate.convertRequestFromRelease)(toolName, params, { ...options, adapters: getVersionAdapter });
+}
+function downgradeResponse(toolName, data, options) {
+  return (0, import_translate.convertResponseToRelease)(toolName, data, { ...options, adapters: getVersionAdapter });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  adcpMinorLine,
+  compareAdcpMinorLines,
+  convertRequest,
+  convertResponse,
+  downgradeResponse,
   getVersionAdapter,
+  isNegotiationFailure,
   listVersionAdapterTools,
-  resolveAdapterKey
+  negotiateAdcpRelease,
+  parseAdcpRelease,
+  projectToolPayload,
+  releaseDefinesTool,
+  resolveAdapterKey,
+  translationSteps,
+  upgradeRequest
 });

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

@@ -1,10 +1,28 @@
 import { shouldOmit31Fields } from "../../utils/adcp-version-config.mjs";
+import { isMutatingTask } from "../../utils/idempotency.mjs";
 import { v30Adapters } from "./3.0/index.mjs";
+import { v31Adapters } from "./3.1/index.mjs";
+import {
+  convertRequestFromRelease,
+  convertRequestToRelease,
+  convertResponseFromRelease,
+  convertResponseToRelease
+} from "./translate.mjs";
+import { translationSteps } from "./translate.mjs";
+import {
+  negotiateAdcpRelease,
+  isNegotiationFailure,
+  parseAdcpRelease,
+  adcpMinorLine,
+  compareAdcpMinorLines
+} from "./negotiate.mjs";
+import { projectToolPayload, releaseDefinesTool } from "./schema-projection.mjs";
 const REGISTRY = /* @__PURE__ */ new Map();
 function register(version, adapters) {
   REGISTRY.set(version, new Map(adapters.map((a) => [a.toolName, a])));
 }
 register("3.0", v30Adapters);
+register("3.1", v31Adapters);
 function getVersionAdapter(adapterKey, toolName) {
   return REGISTRY.get(adapterKey)?.get(toolName);
 }
@@ -15,8 +33,38 @@ function resolveAdapterKey(clientVersion, caps) {
 function listVersionAdapterTools(adapterKey) {
   return [...REGISTRY.get(adapterKey)?.keys() ?? []];
 }
+function convertRequest(toolName, params, options) {
+  return convertRequestToRelease(toolName, params, {
+    fromVersion: options.fromVersion,
+    toVersion: options.toVersion,
+    accountIdentity: options.accountIdentity ?? "refuse",
+    mutating: options.mutating ?? isMutatingTask(toolName),
+    adapters: getVersionAdapter
+  });
+}
+function convertResponse(toolName, data, options) {
+  return convertResponseFromRelease(toolName, data, { ...options, adapters: getVersionAdapter });
+}
+function upgradeRequest(toolName, params, options) {
+  return convertRequestFromRelease(toolName, params, { ...options, adapters: getVersionAdapter });
+}
+function downgradeResponse(toolName, data, options) {
+  return convertResponseToRelease(toolName, data, { ...options, adapters: getVersionAdapter });
+}
 export {
+  adcpMinorLine,
+  compareAdcpMinorLines,
+  convertRequest,
+  convertResponse,
+  downgradeResponse,
   getVersionAdapter,
+  isNegotiationFailure,
   listVersionAdapterTools,
-  resolveAdapterKey
+  negotiateAdcpRelease,
+  parseAdcpRelease,
+  projectToolPayload,
+  releaseDefinesTool,
+  resolveAdapterKey,
+  translationSteps,
+  upgradeRequest
 };

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

@@ -0,0 +1,71 @@
+/**
+ * Per-seller AdCP release negotiation.
+ *
+ * The client builds every request in the shape of its own pinned release (the
+ * latest the SDK supports, unless the adopter pins lower). Before a call goes
+ * out, this module picks the release actually spoken on the wire: the highest
+ * release both sides support. Requests are then converted down to that
+ * release and responses converted back up (see `translate.ts`).
+ */
+import type { AdcpCapabilities } from '../../utils/capabilities.mjs';
+export interface ParsedAdcpRelease {
+    major: number;
+    minor: number;
+    patch: number;
+    prerelease?: string;
+    /** Whether the source string carried a patch component (`3.1.4` vs `3.1`). */
+    hasPatch: boolean;
+}
+export declare function parseAdcpRelease(value: string): ParsedAdcpRelease | undefined;
+/** `MAJOR.MINOR` line of a release, e.g. `'3.2'` for `'3.2.5'` or `'3.2.0-beta.6'`. */
+export declare function adcpMinorLine(value: string): string | undefined;
+/** Compare two releases by `MAJOR.MINOR` only. */
+export declare function compareAdcpMinorLines(left: string, right: string): number;
+export type AdcpNegotiationSource = 
+/** The seller lists the client's own minor line in `supported_versions`. */
+'same_release'
+/** The highest older GA line from the seller's `supported_versions`. */
+ | 'supported_versions'
+/** No `supported_versions`; the release the seller served on discovery. */
+ | 'served_version'
+/** A declared AdCP 3 seller with no release metadata predates 3.1. */
+ | 'legacy_v3';
+export interface NegotiatedAdcpRelease {
+    /**
+     * Release to speak on the wire. Equal to the client's own pin when the
+     * seller supports the client's minor line, otherwise the seller's
+     * release-precision `MAJOR.MINOR` (e.g. `'3.1'`).
+     */
+    version: string;
+    source: AdcpNegotiationSource;
+    /** Whether `version` is on an older minor line than the client pin. */
+    downgraded: boolean;
+}
+export interface AdcpNegotiationFailure {
+    version?: undefined;
+    reason: 'no_common_version';
+    /** The seller's advertised releases, for diagnostics. */
+    advertised: string[];
+}
+type NegotiationCapabilities = Pick<AdcpCapabilities, 'supportedVersions' | 'servedVersion' | '_synthetic'> & {
+    version?: AdcpCapabilities['version'];
+    majorVersions?: AdcpCapabilities['majorVersions'];
+    _raw?: Record<string, unknown>;
+};
+/**
+ * Pick the highest AdCP release both the client and the seller support.
+ *
+ * - Returns `undefined` when there is no authoritative evidence to negotiate
+ *   on (no capabilities, or capabilities synthesized after a failed
+ *   discovery call). Callers keep their pre-negotiation behavior.
+ * - Returns an {@link AdcpNegotiationFailure} when the seller advertises
+ *   releases but none of them is on or below the client's line.
+ *
+ * Same-line matches return the client's exact pin so a seller that supports
+ * the client's minor sees the same wire version as before negotiation
+ * existed. Prereleases on older lines are never selected: a prerelease wire
+ * shape matches only itself, and the SDK ships GA bundles for older lines.
+ */
+export declare function negotiateAdcpRelease(clientVersion: string, capabilities: NegotiationCapabilities | undefined): NegotiatedAdcpRelease | AdcpNegotiationFailure | undefined;
+export declare function isNegotiationFailure(value: NegotiatedAdcpRelease | AdcpNegotiationFailure | undefined): value is AdcpNegotiationFailure;
+export {};

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

@@ -0,0 +1,71 @@
+/**
+ * Per-seller AdCP release negotiation.
+ *
+ * The client builds every request in the shape of its own pinned release (the
+ * latest the SDK supports, unless the adopter pins lower). Before a call goes
+ * out, this module picks the release actually spoken on the wire: the highest
+ * release both sides support. Requests are then converted down to that
+ * release and responses converted back up (see `translate.ts`).
+ */
+import type { AdcpCapabilities } from '../../utils/capabilities';
+export interface ParsedAdcpRelease {
+    major: number;
+    minor: number;
+    patch: number;
+    prerelease?: string;
+    /** Whether the source string carried a patch component (`3.1.4` vs `3.1`). */
+    hasPatch: boolean;
+}
+export declare function parseAdcpRelease(value: string): ParsedAdcpRelease | undefined;
+/** `MAJOR.MINOR` line of a release, e.g. `'3.2'` for `'3.2.5'` or `'3.2.0-beta.6'`. */
+export declare function adcpMinorLine(value: string): string | undefined;
+/** Compare two releases by `MAJOR.MINOR` only. */
+export declare function compareAdcpMinorLines(left: string, right: string): number;
+export type AdcpNegotiationSource = 
+/** The seller lists the client's own minor line in `supported_versions`. */
+'same_release'
+/** The highest older GA line from the seller's `supported_versions`. */
+ | 'supported_versions'
+/** No `supported_versions`; the release the seller served on discovery. */
+ | 'served_version'
+/** A declared AdCP 3 seller with no release metadata predates 3.1. */
+ | 'legacy_v3';
+export interface NegotiatedAdcpRelease {
+    /**
+     * Release to speak on the wire. Equal to the client's own pin when the
+     * seller supports the client's minor line, otherwise the seller's
+     * release-precision `MAJOR.MINOR` (e.g. `'3.1'`).
+     */
+    version: string;
+    source: AdcpNegotiationSource;
+    /** Whether `version` is on an older minor line than the client pin. */
+    downgraded: boolean;
+}
+export interface AdcpNegotiationFailure {
+    version?: undefined;
+    reason: 'no_common_version';
+    /** The seller's advertised releases, for diagnostics. */
+    advertised: string[];
+}
+type NegotiationCapabilities = Pick<AdcpCapabilities, 'supportedVersions' | 'servedVersion' | '_synthetic'> & {
+    version?: AdcpCapabilities['version'];
+    majorVersions?: AdcpCapabilities['majorVersions'];
+    _raw?: Record<string, unknown>;
+};
+/**
+ * Pick the highest AdCP release both the client and the seller support.
+ *
+ * - Returns `undefined` when there is no authoritative evidence to negotiate
+ *   on (no capabilities, or capabilities synthesized after a failed
+ *   discovery call). Callers keep their pre-negotiation behavior.
+ * - Returns an {@link AdcpNegotiationFailure} when the seller advertises
+ *   releases but none of them is on or below the client's line.
+ *
+ * Same-line matches return the client's exact pin so a seller that supports
+ * the client's minor sees the same wire version as before negotiation
+ * existed. Prereleases on older lines are never selected: a prerelease wire
+ * shape matches only itself, and the SDK ships GA bundles for older lines.
+ */
+export declare function negotiateAdcpRelease(clientVersion: string, capabilities: NegotiationCapabilities | undefined): NegotiatedAdcpRelease | AdcpNegotiationFailure | undefined;
+export declare function isNegotiationFailure(value: NegotiatedAdcpRelease | AdcpNegotiationFailure | undefined): value is AdcpNegotiationFailure;
+export {};

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

@@ -0,0 +1,101 @@
+"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 negotiate_exports = {};
+__export(negotiate_exports, {
+  adcpMinorLine: () => adcpMinorLine,
+  compareAdcpMinorLines: () => compareAdcpMinorLines,
+  isNegotiationFailure: () => isNegotiationFailure,
+  negotiateAdcpRelease: () => negotiateAdcpRelease,
+  parseAdcpRelease: () => parseAdcpRelease
+});
+module.exports = __toCommonJS(negotiate_exports);
+var import_schema_loader = require('../../validation/schema-loader.js');
+function parseAdcpRelease(value) {
+  const match = /^v?(\d+)\.(\d+)(?:\.(\d+))?(?:-([A-Za-z0-9.-]+))?(?:\+[A-Za-z0-9.-]+)?$/.exec(value.trim());
+  if (!match) return void 0;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3] ?? 0),
+    hasPatch: match[3] !== void 0,
+    ...match[4] !== void 0 && { prerelease: match[4] }
+  };
+}
+function adcpMinorLine(value) {
+  const release = parseAdcpRelease(value);
+  return release ? `${release.major}.${release.minor}` : void 0;
+}
+function compareAdcpMinorLines(left, right) {
+  const a = parseAdcpRelease(left);
+  const b = parseAdcpRelease(right);
+  if (!a || !b) return 0;
+  return a.major - b.major || a.minor - b.minor;
+}
+function negotiateAdcpRelease(clientVersion, capabilities) {
+  if (!capabilities || capabilities._synthetic) return void 0;
+  const client = parseAdcpRelease(clientVersion);
+  if (!client) return void 0;
+  const advertised = (capabilities.supportedVersions ?? []).filter((v) => typeof v === "string");
+  if (advertised.length > 0) {
+    let best;
+    for (const value of advertised) {
+      const release = parseAdcpRelease(value);
+      if (!release || release.major !== client.major) continue;
+      if (release.minor === client.minor) {
+        if (release.prerelease !== client.prerelease) continue;
+        return { version: clientVersion, source: "same_release", downgraded: false };
+      }
+      if (release.minor > client.minor || release.prerelease !== void 0) continue;
+      if (!(0, import_schema_loader.hasSchemaBundle)(`${release.major}.${release.minor}`)) continue;
+      if (!best || release.minor > best.release.minor) best = { release, value };
+    }
+    if (!best) return { reason: "no_common_version", advertised };
+    return {
+      version: `${best.release.major}.${best.release.minor}`,
+      source: "supported_versions",
+      downgraded: true
+    };
+  }
+  const served = capabilities.servedVersion ?? (typeof capabilities._raw?.adcp_version === "string" ? capabilities._raw.adcp_version : void 0);
+  const servedRelease = served !== void 0 ? parseAdcpRelease(served) : void 0;
+  if (servedRelease && servedRelease.major === client.major) {
+    if (servedRelease.minor >= client.minor) {
+      return { version: clientVersion, source: "served_version", downgraded: false };
+    }
+    const servedLine = `${servedRelease.major}.${servedRelease.minor}`;
+    if (servedRelease.prerelease !== void 0 || !(0, import_schema_loader.hasSchemaBundle)(servedLine)) return void 0;
+    return { version: servedLine, source: "served_version", downgraded: true };
+  }
+  if (capabilities.version === "v3" && client.major === 3) {
+    if (client.minor === 0) return { version: clientVersion, source: "legacy_v3", downgraded: false };
+    return { version: "3.0", source: "legacy_v3", downgraded: true };
+  }
+  return void 0;
+}
+function isNegotiationFailure(value) {
+  return value !== void 0 && "reason" in value;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  adcpMinorLine,
+  compareAdcpMinorLines,
+  isNegotiationFailure,
+  negotiateAdcpRelease,
+  parseAdcpRelease
+});

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

@@ -0,0 +1,73 @@
+import { hasSchemaBundle } from "../../validation/schema-loader.mjs";
+function parseAdcpRelease(value) {
+  const match = /^v?(\d+)\.(\d+)(?:\.(\d+))?(?:-([A-Za-z0-9.-]+))?(?:\+[A-Za-z0-9.-]+)?$/.exec(value.trim());
+  if (!match) return void 0;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3] ?? 0),
+    hasPatch: match[3] !== void 0,
+    ...match[4] !== void 0 && { prerelease: match[4] }
+  };
+}
+function adcpMinorLine(value) {
+  const release = parseAdcpRelease(value);
+  return release ? `${release.major}.${release.minor}` : void 0;
+}
+function compareAdcpMinorLines(left, right) {
+  const a = parseAdcpRelease(left);
+  const b = parseAdcpRelease(right);
+  if (!a || !b) return 0;
+  return a.major - b.major || a.minor - b.minor;
+}
+function negotiateAdcpRelease(clientVersion, capabilities) {
+  if (!capabilities || capabilities._synthetic) return void 0;
+  const client = parseAdcpRelease(clientVersion);
+  if (!client) return void 0;
+  const advertised = (capabilities.supportedVersions ?? []).filter((v) => typeof v === "string");
+  if (advertised.length > 0) {
+    let best;
+    for (const value of advertised) {
+      const release = parseAdcpRelease(value);
+      if (!release || release.major !== client.major) continue;
+      if (release.minor === client.minor) {
+        if (release.prerelease !== client.prerelease) continue;
+        return { version: clientVersion, source: "same_release", downgraded: false };
+      }
+      if (release.minor > client.minor || release.prerelease !== void 0) continue;
+      if (!hasSchemaBundle(`${release.major}.${release.minor}`)) continue;
+      if (!best || release.minor > best.release.minor) best = { release, value };
+    }
+    if (!best) return { reason: "no_common_version", advertised };
+    return {
+      version: `${best.release.major}.${best.release.minor}`,
+      source: "supported_versions",
+      downgraded: true
+    };
+  }
+  const served = capabilities.servedVersion ?? (typeof capabilities._raw?.adcp_version === "string" ? capabilities._raw.adcp_version : void 0);
+  const servedRelease = served !== void 0 ? parseAdcpRelease(served) : void 0;
+  if (servedRelease && servedRelease.major === client.major) {
+    if (servedRelease.minor >= client.minor) {
+      return { version: clientVersion, source: "served_version", downgraded: false };
+    }
+    const servedLine = `${servedRelease.major}.${servedRelease.minor}`;
+    if (servedRelease.prerelease !== void 0 || !hasSchemaBundle(servedLine)) return void 0;
+    return { version: servedLine, source: "served_version", downgraded: true };
+  }
+  if (capabilities.version === "v3" && client.major === 3) {
+    if (client.minor === 0) return { version: clientVersion, source: "legacy_v3", downgraded: false };
+    return { version: "3.0", source: "legacy_v3", downgraded: true };
+  }
+  return void 0;
+}
+function isNegotiationFailure(value) {
+  return value !== void 0 && "reason" in value;
+}
+export {
+  adcpMinorLine,
+  compareAdcpMinorLines,
+  isNegotiationFailure,
+  negotiateAdcpRelease,
+  parseAdcpRelease
+};

package/dist/lib/adapters/version/schema-projection.d.mts

@@ -0,0 +1,33 @@
+/**
+ * Schema-driven projection between two AdCP releases.
+ *
+ * Converting a payload down from a newer release to an older one removes what
+ * the older release cannot express: properties the newer schema declares but
+ * the older one does not, enum values the older release does not define, and
+ * union variants whose discriminator the older release does not know.
+ * Everything the projection removes is reported so callers can surface it.
+ *
+ * The projection is a diff of the two schemas, not a whitelist of the older
+ * one. A property neither release declares (an adopter extension at an open
+ * object, say) is left alone, as is anything under an object whose older
+ * schema declares no properties (a free-form map such as `ext`).
+ */
+import { type Direction } from '../../validation/schema-loader.mjs';
+export interface ProjectionDrop {
+    /** JSON path of the removed value, e.g. `packages[0].bidding`. */
+    path: string;
+    /** What kind of value the older release could not express. */
+    kind: 'field' | 'enum_value' | 'variant';
+}
+export interface ProjectionResult<T = unknown> {
+    value: T;
+    dropped: ProjectionDrop[];
+}
+/**
+ * Project a tool payload from the `fromVersion` schema to the `toVersion`
+ * schema. Returns the original reference unchanged (and no drops) when
+ * nothing needs removing or when either release has no schema for the tool.
+ */
+export declare function projectToolPayload<T>(toolName: string, direction: Direction, payload: T, fromVersion: string, toVersion: string): ProjectionResult<T>;
+/** Whether the release's schema bundle defines a request schema for the tool. */
+export declare function releaseDefinesTool(toolName: string, version: string): boolean;

package/dist/lib/adapters/version/schema-projection.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Schema-driven projection between two AdCP releases.
+ *
+ * Converting a payload down from a newer release to an older one removes what
+ * the older release cannot express: properties the newer schema declares but
+ * the older one does not, enum values the older release does not define, and
+ * union variants whose discriminator the older release does not know.
+ * Everything the projection removes is reported so callers can surface it.
+ *
+ * The projection is a diff of the two schemas, not a whitelist of the older
+ * one. A property neither release declares (an adopter extension at an open
+ * object, say) is left alone, as is anything under an object whose older
+ * schema declares no properties (a free-form map such as `ext`).
+ */
+import { type Direction } from '../../validation/schema-loader';
+export interface ProjectionDrop {
+    /** JSON path of the removed value, e.g. `packages[0].bidding`. */
+    path: string;
+    /** What kind of value the older release could not express. */
+    kind: 'field' | 'enum_value' | 'variant';
+}
+export interface ProjectionResult<T = unknown> {
+    value: T;
+    dropped: ProjectionDrop[];
+}
+/**
+ * Project a tool payload from the `fromVersion` schema to the `toVersion`
+ * schema. Returns the original reference unchanged (and no drops) when
+ * nothing needs removing or when either release has no schema for the tool.
+ */
+export declare function projectToolPayload<T>(toolName: string, direction: Direction, payload: T, fromVersion: string, toVersion: string): ProjectionResult<T>;
+/** Whether the release's schema bundle defines a request schema for the tool. */
+export declare function releaseDefinesTool(toolName: string, version: string): boolean;