@adcp/sdk 16.2.0 → 16.4.0

package/dist/lib/negotiation/verification.d.ts

@@ -38,13 +38,22 @@ export declare function verifyProposalCommercialTerms(proposal: unknown, expecte
 export declare function assertProposalCommercialTerms(proposal: unknown, expectedCommercialTerms: unknown, options?: VerifyProposalCommercialTermsOptions): void;
 /** Strict RFC 3339 date-time accepted by the AdCP `format: date-time` contract. */
 export declare function isStrictDateTime(value: unknown): value is string;
-export declare function verifyRefineProposalsResponse(request: Pick<RefineProposalsRequest, 'refinements'>, response: unknown, options?: {
+export declare function verifyRefineProposalsResponse(request: Pick<RefineProposalsRequest, 'refinements'> & Partial<Pick<RefineProposalsRequest, 'adcp_version'>>, response: unknown, options?: {
     now?: Date;
+    adcpVersion?: string;
+    servedAdcpVersion?: string;
 }): ProposalVerificationResult;
-export declare function assertRefineProposalsResponse(request: Pick<RefineProposalsRequest, 'refinements'>, response: unknown, options?: {
+export declare function assertRefineProposalsResponse(request: Pick<RefineProposalsRequest, 'refinements'> & Partial<Pick<RefineProposalsRequest, 'adcp_version'>>, response: unknown, options?: {
     now?: Date;
+    adcpVersion?: string;
+    servedAdcpVersion?: string;
 }): asserts response is RefineProposalsCompletedResponse;
-/** Validate the finalized 3.2 completed or compact-submitted wire shape, without source semantics. */
-export declare function validateRefineProposalsResponseShape(response: unknown): ProposalVerificationResult;
-/** Assert the finalized 3.2 completed or compact-submitted wire shape, without requiring a source request. */
-export declare function assertRefineProposalsResponseShape(response: unknown): asserts response is RefineProposalsResponse;
+/** Validate a completed or compact-submitted wire shape using the selected bundle.
+ * Pass adcpVersion when validating a negotiated contract other than the SDK pin. */
+export declare function validateRefineProposalsResponseShape(response: unknown, options?: {
+    adcpVersion?: string;
+}): ProposalVerificationResult;
+/** Assert a selected completed or compact-submitted wire shape without source semantics. */
+export declare function assertRefineProposalsResponseShape(response: unknown, options?: {
+    adcpVersion?: string;
+}): asserts response is RefineProposalsResponse;

package/dist/lib/negotiation/verification.js

@@ -25,6 +25,7 @@ __export(verification_exports, {
   assertRefineProposalsResponseShape: () => assertRefineProposalsResponseShape,
   isStrictDateTime: () => isStrictDateTime,
   proposalTermsDigest: () => proposalTermsDigest,
+  selectRefinementSchemaVersion: () => selectRefinementSchemaVersion,
   validateRefineProposalsResponseShape: () => validateRefineProposalsResponseShape,
   verifyProposalCommercialTerms: () => verifyProposalCommercialTerms,
   verifyProposalTermsDigest: () => verifyProposalTermsDigest,
@@ -36,9 +37,10 @@ var import_json_depth = require('../utils/json-depth.js');
 var import_jcs = require('../utils/jcs.js');
 var import_schema_loader = require('../validation/schema-loader.js');
 var import_version = require('../version.js');
+var import_errors = require('../errors/index.js');
+var import_version2 = require('./version.js');
 var import_commercial_terms_schema = require('./commercial-terms-schema.js');
 var import_commercial_terms_keywords = require('./commercial-terms-keywords.js');
-const ADCP_32_RELEASE = /^3\.2(?:-[A-Za-z0-9]+(?:[.-][A-Za-z0-9]+)*)?$/;
 const MAX_COMMERCIAL_TERMS_BYTES = 256 * 1024;
 const MAX_COMMERCIAL_TERMS_NODES = 5e4;
 const MAX_COMMERCIAL_TERMS_MISMATCHES = 100;
@@ -296,7 +298,8 @@ function isStrictDateTime(value) {
 }
 function verifyRefineProposalsResponse(request, response, options = {}) {
   const issues = [];
-  if (!validateResponseShape(response, issues)) return { ok: false, issues };
+  const adcpVersion = selectRefinementSchemaVersion(request.adcp_version, response, options, issues);
+  if (adcpVersion === void 0 || !validateResponseShape(response, issues, adcpVersion)) return { ok: false, issues };
   if (response.status === "submitted") {
     push(issues, "shape", "status", "semantic proposal verification requires a completed response");
     return { ok: false, issues };
@@ -338,30 +341,126 @@ function assertRefineProposalsResponse(request, response, options = {}) {
   const result = verifyRefineProposalsResponse(request, response, options);
   if (!result.ok) throw new ProposalResponseVerificationError(result.issues);
 }
-function validateRefineProposalsResponseShape(response) {
+function validateRefineProposalsResponseShape(response, options = {}) {
   const issues = [];
-  validateResponseShape(response, issues);
+  validateResponseShape(
+    response,
+    issues,
+    options.adcpVersion ?? import_version.ADCP_VERSION,
+    options.adcpVersion && (0, import_version.toReleasePrecisionVersion)(options.adcpVersion)
+  );
   return { ok: issues.length === 0, issues };
 }
-function assertRefineProposalsResponseShape(response) {
-  const result = validateRefineProposalsResponseShape(response);
+function assertRefineProposalsResponseShape(response, options = {}) {
+  const result = validateRefineProposalsResponseShape(response, options);
   if (!result.ok) throw new ProposalResponseVerificationError(result.issues);
 }
-function validateResponseShape(value, issues) {
+function selectRefinementSchemaVersion(requested, response, options, issues) {
+  const configured = options.adcpVersion ?? import_version.ADCP_VERSION;
+  const configuredWire = (0, import_version.toReleasePrecisionVersion)(configured);
+  if (!(0, import_version2.isProposalRefinementVersion)(configuredWire)) {
+    shape(issues, "adcp_version", `selected schema ${(0, import_version2.describeRefinementVersion)(configured)} must be AdCP 3.2 or 3.3`);
+    return void 0;
+  }
+  const ceiling = requested ?? configuredWire;
+  if (!(0, import_version2.isProposalRefinementVersion)(ceiling)) {
+    shape(
+      issues,
+      "adcp_version",
+      `request ceiling must be release-precision AdCP 3.2 or 3.3; received ${(0, import_version2.describeRefinementVersion)(ceiling)}`
+    );
+    return void 0;
+  }
+  const echo = isRecord(response) ? response.adcp_version : void 0;
+  if (echo !== void 0 && !(0, import_version2.isProposalRefinementVersion)(echo)) {
+    shape(
+      issues,
+      "adcp_version",
+      `response must echo release-precision AdCP 3.2 or 3.3 at or below request ceiling ${ceiling}; received ${(0, import_version2.describeRefinementVersion)(echo)}`
+    );
+    return void 0;
+  }
+  const metadata = options.servedAdcpVersion === void 0 ? void 0 : (0, import_version.toReleasePrecisionVersion)(options.servedAdcpVersion);
+  if (metadata !== void 0 && !(0, import_version2.isProposalRefinementVersion)(metadata)) {
+    shape(
+      issues,
+      "adcp_version",
+      `served version metadata must identify AdCP 3.2 or 3.3; received ${(0, import_version2.describeRefinementVersion)(options.servedAdcpVersion)}`
+    );
+    return void 0;
+  }
+  if (metadata !== void 0 && echo !== void 0 && metadata !== echo) {
+    shape(issues, "adcp_version", `response echo ${echo} conflicts with served version metadata ${metadata}`);
+    return void 0;
+  }
+  const served = echo ?? metadata;
+  if (served === void 0) return configured;
+  if ((0, import_version2.compareProposalRefinementVersions)(served, ceiling) > 0) {
+    shape(
+      issues,
+      "adcp_version",
+      `response served AdCP ${served} above request ceiling ${ceiling} (configured schema ${configured})`
+    );
+    return void 0;
+  }
+  const sameMinor = served.split("-")[0] === configuredWire.split("-")[0];
+  const wireOnlyOverride = ceiling !== configuredWire && ceiling.split("-")[0] === configuredWire.split("-")[0];
+  if (served === configuredWire || wireOnlyOverride && served === ceiling && sameMinor) return configured;
+  if ((0, import_version2.compareProposalRefinementVersions)(served, configuredWire) > 0) {
+    shape(
+      issues,
+      "adcp_version",
+      `response served AdCP ${served}, newer than configured schema ${configured}; set adcpVersion to the served contract and register its matching schema bundle`
+    );
+    return void 0;
+  }
+  return metadata === served && options.servedAdcpVersion ? options.servedAdcpVersion : served;
+}
+function validateResponseShape(value, issues, adcpVersion, expectedVersion) {
   if (!isRecord(value)) {
     push(issues, "shape", "response", "response must be an object");
     return false;
   }
   let valid = allowedKeys(value, RESPONSE_KEYS, "response", issues);
-  if (value.adcp_version !== void 0 && (typeof value.adcp_version !== "string" || !ADCP_32_RELEASE.test(value.adcp_version))) {
+  if (value.adcp_version !== void 0 && !(0, import_version2.isProposalRefinementVersion)(value.adcp_version)) {
     valid = shape(
       issues,
       "adcp_version",
-      `refine_proposals response adcp_version must be on the 3.2 release line; received ${describeReceived(
+      `refine_proposals response adcp_version must be release-precision AdCP 3.2 or 3.3; received ${(0, import_version2.describeRefinementVersion)(
         value.adcp_version
       )}`
     );
   }
+  const selectedWireVersion = (0, import_version.toReleasePrecisionVersion)(adcpVersion);
+  if (!(0, import_version2.isProposalRefinementVersion)(selectedWireVersion)) {
+    return shape(
+      issues,
+      "adcp_version",
+      `selected schema version ${(0, import_version2.describeRefinementVersion)(adcpVersion)} must be AdCP 3.2 or 3.3`
+    );
+  }
+  if ((0, import_version2.isProposalRefinementVersion)(value.adcp_version) && (expectedVersion ? value.adcp_version !== expectedVersion : value.adcp_version.split("-")[0] !== selectedWireVersion.split("-")[0])) {
+    return shape(
+      issues,
+      "adcp_version",
+      `response adcp_version ${(0, import_version2.describeRefinementVersion)(value.adcp_version)} must match selected served schema ${adcpVersion}`
+    );
+  }
+  try {
+    const selected = (0, import_schema_loader.getSchemaDocumentByRef)("core/canonical-proposal.json", adcpVersion);
+    if (!selected) {
+      return shape(issues, "adcp_version", unavailableRefinementSchema(adcpVersion));
+    }
+    if ((0, import_version.toReleasePrecisionVersion)(selected.resolvedVersion) !== selectedWireVersion) {
+      return shape(
+        issues,
+        "adcp_version",
+        `selected proposal schema for AdCP ${adcpVersion} resolved to ${(0, import_version2.describeRefinementVersion)(selected.resolvedVersion)}; install or register the actual matching schema bundle`
+      );
+    }
+  } catch (error) {
+    return shape(issues, "adcp_version", unavailableRefinementSchema(adcpVersion, error));
+  }
   if (value.message !== void 0 && (typeof value.message !== "string" || value.message.length > 2e3)) {
     valid = shape(issues, "message", "message must be a string of at most 2000 characters");
   }
@@ -393,7 +492,7 @@ function validateResponseShape(value, issues) {
     valid = shape(issues, "results", "results must be a non-empty array");
   } else {
     value.results.forEach((result, index) => {
-      if (!validateResultShape(result, `results[${index}]`, issues)) valid = false;
+      if (!validateResultShape(result, `results[${index}]`, issues, adcpVersion)) valid = false;
     });
   }
   if (!Array.isArray(value.products)) {
@@ -420,7 +519,7 @@ function validateAdvisoryErrors(value, issues) {
   });
   return valid;
 }
-function validateResultShape(value, path, issues) {
+function validateResultShape(value, path, issues, adcpVersion) {
   if (!isRecord(value)) return shape(issues, path, "result must be an object");
   let valid = allowedKeys(value, RESULT_KEYS, path, issues);
   if (!nonempty(value.source_proposal_id))
@@ -437,14 +536,14 @@ function validateResultShape(value, path, issues) {
   };
   if (outcome === "revised") {
     forbidden(["proposal", "reason_code", "reason", "unsatisfied_constraints", "unsatisfied_product_changes"]);
-    if (!validateProposalArray(value.proposals, `${path}.proposals`, issues)) valid = false;
+    if (!validateProposalArray(value.proposals, `${path}.proposals`, issues, adcpVersion)) valid = false;
   } else if (outcome === "partial") {
     forbidden(["proposal"]);
-    if (!validateProposalArray(value.proposals, `${path}.proposals`, issues)) valid = false;
+    if (!validateProposalArray(value.proposals, `${path}.proposals`, issues, adcpVersion)) valid = false;
     if (!validateReason(value, path, issues)) valid = false;
   } else if (outcome === "finalized") {
     forbidden(["proposals", "reason_code", "reason", "unsatisfied_constraints", "unsatisfied_product_changes"]);
-    if (!validateCanonicalProposalShape(value.proposal, `${path}.proposal`, issues)) valid = false;
+    if (!validateCanonicalProposalShape(value.proposal, `${path}.proposal`, issues, adcpVersion)) valid = false;
   } else {
     forbidden(["proposal", "proposals"]);
     if (!validateReason(value, path, issues)) valid = false;
@@ -486,24 +585,39 @@ function validateReason(value, path, issues) {
   if (!nonempty(value.reason)) valid = shape(issues, `${path}.reason`, "reason must be a non-empty string");
   return valid;
 }
-function validateProposalArray(value, path, issues) {
+function validateProposalArray(value, path, issues, adcpVersion) {
   if (!Array.isArray(value) || value.length === 0) return shape(issues, path, "proposals must be a non-empty array");
   let valid = true;
   value.forEach((proposal, index) => {
-    if (!validateCanonicalProposalShape(proposal, `${path}[${index}]`, issues)) valid = false;
+    if (!validateCanonicalProposalShape(proposal, `${path}[${index}]`, issues, adcpVersion)) valid = false;
   });
   return valid;
 }
-function validateCanonicalProposalShape(value, path, issues) {
-  const validateCanonicalProposal = (0, import_schema_loader.getSchemaValidatorByRef)("core/canonical-proposal.json");
-  if (!validateCanonicalProposal) return shape(issues, path, "canonical-proposal schema is unavailable");
+function unavailableRefinementSchema(adcpVersion, error) {
+  const cause = error instanceof import_errors.ConfigurationError ? error.message.includes("Schema validation requires unambiguous schema identities") ? " (ConfigurationError: schema validation requires unambiguous schema identities)" : " (ConfigurationError)" : error === void 0 ? "" : error instanceof Error && /^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(error.name) ? ` (${error.name})` : " (schema loading error)";
+  return `selected proposal schema for AdCP ${adcpVersion} is unavailable${cause}; install its schema bundle or register a matching external schema root with @adcp/sdk/testing`;
+}
+function getRefinementSchemaValidator(schemaRef, adcpVersion) {
+  try {
+    const validator = (0, import_schema_loader.getSchemaValidatorByRef)(schemaRef, adcpVersion);
+    return { validator, error: validator ? void 0 : unavailableRefinementSchema(adcpVersion) };
+  } catch (error) {
+    return { validator: void 0, error: unavailableRefinementSchema(adcpVersion, error) };
+  }
+}
+function validateCanonicalProposalShape(value, path, issues, adcpVersion) {
+  const { validator: validateCanonicalProposal, error: schemaError } = getRefinementSchemaValidator(
+    "core/canonical-proposal.json",
+    adcpVersion
+  );
+  if (!validateCanonicalProposal) return shape(issues, path, schemaError);
   if (!validateCanonicalProposal(value)) {
     const error = validateCanonicalProposal.errors?.[0];
     const errorPath = error?.instancePath ? `${path}${error.instancePath.replaceAll("/", ".")}` : path;
     return shape(
       issues,
       errorPath,
-      `proposal must satisfy the AdCP 3.2 schema${error?.message ? `: ${error.message}` : ""}`
+      `proposal must satisfy the selected AdCP ${adcpVersion} schema${error?.message ? `: ${error.message}` : ""}`
     );
   }
   const proposal = value;
@@ -547,10 +661,11 @@ function validateCanonicalProposalShape(value, path, issues) {
   if (proposal.proposal_status === "committed" && !isStrictDateTime(proposal.expires_at)) {
     valid = shape(issues, `${path}.expires_at`, "committed proposals require expires_at");
   }
-  if (!validateCommercialTerms(proposal.commercial_terms, `${path}.commercial_terms`, issues)) valid = false;
+  if (!validateCommercialTerms(proposal.commercial_terms, `${path}.commercial_terms`, issues, adcpVersion))
+    valid = false;
   return valid;
 }
-function validateCommercialTerms(value, path, issues) {
+function validateCommercialTerms(value, path, issues, adcpVersion) {
   if (!isRecord(value)) return shape(issues, path, "commercial_terms must be an object");
   let valid = true;
   if (!isRecord(value.brand)) valid = shape(issues, `${path}.brand`, "brand must be an object");
@@ -604,7 +719,7 @@ function validateCommercialTerms(value, path, issues) {
     valid = shape(issues, `${path}.reporting_commitments`, "reporting_commitments must be a non-empty array");
   if (value.cancellation_terms !== void 0 && !validateCancellationTerms(value.cancellation_terms, `${path}.cancellation_terms`, issues))
     valid = false;
-  if (value.change_terms !== void 0 && !validateChangeTerms(value.change_terms, `${path}.change_terms`, issues, purchaseCurrency))
+  if (value.change_terms !== void 0 && !validateChangeTerms(value.change_terms, `${path}.change_terms`, issues, adcpVersion, purchaseCurrency))
     valid = false;
   return valid;
 }
@@ -620,10 +735,13 @@ const CHANGE_TERM_ACTIONS_BY_CONSTRAINT = {
   package_count: /* @__PURE__ */ new Set(["add_packages", "remove_packages"]),
   effective_timing: /* @__PURE__ */ new Set(["pause", "resume", "cancel"])
 };
-function validateChangeTerms(value, path, issues, purchaseCurrency) {
+function validateChangeTerms(value, path, issues, adcpVersion, purchaseCurrency) {
   if (!Array.isArray(value) || value.length === 0) return shape(issues, path, "change_terms must be a non-empty array");
-  const validateChangeTerm = (0, import_schema_loader.getSchemaValidatorByRef)("media-buy/change-term.json");
-  if (!validateChangeTerm) return shape(issues, path, "change-term schema is unavailable");
+  const { validator: validateChangeTerm, error: schemaError } = getRefinementSchemaValidator(
+    "media-buy/change-term.json",
+    adcpVersion
+  );
+  if (!validateChangeTerm) return shape(issues, path, schemaError);
   let valid = true;
   const actions = /* @__PURE__ */ new Set();
   value.forEach((term, index) => {
@@ -634,7 +752,7 @@ function validateChangeTerms(value, path, issues, purchaseCurrency) {
       valid = shape(
         issues,
         errorPath,
-        `change term must satisfy the AdCP 3.2 schema${error?.message ? `: ${error.message}` : ""}`
+        `change term must satisfy the selected AdCP ${adcpVersion} schema${error?.message ? `: ${error.message}` : ""}`
       );
       return;
     }
@@ -1341,6 +1459,7 @@ function push(issues, code, path, message) {
   assertRefineProposalsResponseShape,
   isStrictDateTime,
   proposalTermsDigest,
+  selectRefinementSchemaVersion,
   validateRefineProposalsResponseShape,
   verifyProposalCommercialTerms,
   verifyProposalTermsDigest,

package/dist/lib/negotiation/verification.mjs

@@ -2,10 +2,11 @@ import { createHash } from "node:crypto";
 import { MAX_JSON_DEPTH } from "../utils/json-depth.mjs";
 import { canonicalize } from "../utils/jcs.mjs";
 import { getSchemaDocumentByRef, getSchemaValidatorByRef } from "../validation/schema-loader.mjs";
-import { ADCP_VERSION } from "../version.mjs";
+import { ADCP_VERSION, toReleasePrecisionVersion } from "../version.mjs";
+import { ConfigurationError } from "../errors/index.mjs";
+import { compareProposalRefinementVersions, describeRefinementVersion, isProposalRefinementVersion } from "./version.mjs";
 import { commercialTermsSchemaSupportError } from "./commercial-terms-schema.mjs";
 import { COMMERCIAL_TERMS_KEYWORDS } from "./commercial-terms-keywords.mjs";
-const ADCP_32_RELEASE = /^3\.2(?:-[A-Za-z0-9]+(?:[.-][A-Za-z0-9]+)*)?$/;
 const MAX_COMMERCIAL_TERMS_BYTES = 256 * 1024;
 const MAX_COMMERCIAL_TERMS_NODES = 5e4;
 const MAX_COMMERCIAL_TERMS_MISMATCHES = 100;
@@ -263,7 +264,8 @@ function isStrictDateTime(value) {
 }
 function verifyRefineProposalsResponse(request, response, options = {}) {
   const issues = [];
-  if (!validateResponseShape(response, issues)) return { ok: false, issues };
+  const adcpVersion = selectRefinementSchemaVersion(request.adcp_version, response, options, issues);
+  if (adcpVersion === void 0 || !validateResponseShape(response, issues, adcpVersion)) return { ok: false, issues };
   if (response.status === "submitted") {
     push(issues, "shape", "status", "semantic proposal verification requires a completed response");
     return { ok: false, issues };
@@ -305,30 +307,126 @@ function assertRefineProposalsResponse(request, response, options = {}) {
   const result = verifyRefineProposalsResponse(request, response, options);
   if (!result.ok) throw new ProposalResponseVerificationError(result.issues);
 }
-function validateRefineProposalsResponseShape(response) {
+function validateRefineProposalsResponseShape(response, options = {}) {
   const issues = [];
-  validateResponseShape(response, issues);
+  validateResponseShape(
+    response,
+    issues,
+    options.adcpVersion ?? ADCP_VERSION,
+    options.adcpVersion && toReleasePrecisionVersion(options.adcpVersion)
+  );
   return { ok: issues.length === 0, issues };
 }
-function assertRefineProposalsResponseShape(response) {
-  const result = validateRefineProposalsResponseShape(response);
+function assertRefineProposalsResponseShape(response, options = {}) {
+  const result = validateRefineProposalsResponseShape(response, options);
   if (!result.ok) throw new ProposalResponseVerificationError(result.issues);
 }
-function validateResponseShape(value, issues) {
+function selectRefinementSchemaVersion(requested, response, options, issues) {
+  const configured = options.adcpVersion ?? ADCP_VERSION;
+  const configuredWire = toReleasePrecisionVersion(configured);
+  if (!isProposalRefinementVersion(configuredWire)) {
+    shape(issues, "adcp_version", `selected schema ${describeRefinementVersion(configured)} must be AdCP 3.2 or 3.3`);
+    return void 0;
+  }
+  const ceiling = requested ?? configuredWire;
+  if (!isProposalRefinementVersion(ceiling)) {
+    shape(
+      issues,
+      "adcp_version",
+      `request ceiling must be release-precision AdCP 3.2 or 3.3; received ${describeRefinementVersion(ceiling)}`
+    );
+    return void 0;
+  }
+  const echo = isRecord(response) ? response.adcp_version : void 0;
+  if (echo !== void 0 && !isProposalRefinementVersion(echo)) {
+    shape(
+      issues,
+      "adcp_version",
+      `response must echo release-precision AdCP 3.2 or 3.3 at or below request ceiling ${ceiling}; received ${describeRefinementVersion(echo)}`
+    );
+    return void 0;
+  }
+  const metadata = options.servedAdcpVersion === void 0 ? void 0 : toReleasePrecisionVersion(options.servedAdcpVersion);
+  if (metadata !== void 0 && !isProposalRefinementVersion(metadata)) {
+    shape(
+      issues,
+      "adcp_version",
+      `served version metadata must identify AdCP 3.2 or 3.3; received ${describeRefinementVersion(options.servedAdcpVersion)}`
+    );
+    return void 0;
+  }
+  if (metadata !== void 0 && echo !== void 0 && metadata !== echo) {
+    shape(issues, "adcp_version", `response echo ${echo} conflicts with served version metadata ${metadata}`);
+    return void 0;
+  }
+  const served = echo ?? metadata;
+  if (served === void 0) return configured;
+  if (compareProposalRefinementVersions(served, ceiling) > 0) {
+    shape(
+      issues,
+      "adcp_version",
+      `response served AdCP ${served} above request ceiling ${ceiling} (configured schema ${configured})`
+    );
+    return void 0;
+  }
+  const sameMinor = served.split("-")[0] === configuredWire.split("-")[0];
+  const wireOnlyOverride = ceiling !== configuredWire && ceiling.split("-")[0] === configuredWire.split("-")[0];
+  if (served === configuredWire || wireOnlyOverride && served === ceiling && sameMinor) return configured;
+  if (compareProposalRefinementVersions(served, configuredWire) > 0) {
+    shape(
+      issues,
+      "adcp_version",
+      `response served AdCP ${served}, newer than configured schema ${configured}; set adcpVersion to the served contract and register its matching schema bundle`
+    );
+    return void 0;
+  }
+  return metadata === served && options.servedAdcpVersion ? options.servedAdcpVersion : served;
+}
+function validateResponseShape(value, issues, adcpVersion, expectedVersion) {
   if (!isRecord(value)) {
     push(issues, "shape", "response", "response must be an object");
     return false;
   }
   let valid = allowedKeys(value, RESPONSE_KEYS, "response", issues);
-  if (value.adcp_version !== void 0 && (typeof value.adcp_version !== "string" || !ADCP_32_RELEASE.test(value.adcp_version))) {
+  if (value.adcp_version !== void 0 && !isProposalRefinementVersion(value.adcp_version)) {
     valid = shape(
       issues,
       "adcp_version",
-      `refine_proposals response adcp_version must be on the 3.2 release line; received ${describeReceived(
+      `refine_proposals response adcp_version must be release-precision AdCP 3.2 or 3.3; received ${describeRefinementVersion(
         value.adcp_version
       )}`
     );
   }
+  const selectedWireVersion = toReleasePrecisionVersion(adcpVersion);
+  if (!isProposalRefinementVersion(selectedWireVersion)) {
+    return shape(
+      issues,
+      "adcp_version",
+      `selected schema version ${describeRefinementVersion(adcpVersion)} must be AdCP 3.2 or 3.3`
+    );
+  }
+  if (isProposalRefinementVersion(value.adcp_version) && (expectedVersion ? value.adcp_version !== expectedVersion : value.adcp_version.split("-")[0] !== selectedWireVersion.split("-")[0])) {
+    return shape(
+      issues,
+      "adcp_version",
+      `response adcp_version ${describeRefinementVersion(value.adcp_version)} must match selected served schema ${adcpVersion}`
+    );
+  }
+  try {
+    const selected = getSchemaDocumentByRef("core/canonical-proposal.json", adcpVersion);
+    if (!selected) {
+      return shape(issues, "adcp_version", unavailableRefinementSchema(adcpVersion));
+    }
+    if (toReleasePrecisionVersion(selected.resolvedVersion) !== selectedWireVersion) {
+      return shape(
+        issues,
+        "adcp_version",
+        `selected proposal schema for AdCP ${adcpVersion} resolved to ${describeRefinementVersion(selected.resolvedVersion)}; install or register the actual matching schema bundle`
+      );
+    }
+  } catch (error) {
+    return shape(issues, "adcp_version", unavailableRefinementSchema(adcpVersion, error));
+  }
   if (value.message !== void 0 && (typeof value.message !== "string" || value.message.length > 2e3)) {
     valid = shape(issues, "message", "message must be a string of at most 2000 characters");
   }
@@ -360,7 +458,7 @@ function validateResponseShape(value, issues) {
     valid = shape(issues, "results", "results must be a non-empty array");
   } else {
     value.results.forEach((result, index) => {
-      if (!validateResultShape(result, `results[${index}]`, issues)) valid = false;
+      if (!validateResultShape(result, `results[${index}]`, issues, adcpVersion)) valid = false;
     });
   }
   if (!Array.isArray(value.products)) {
@@ -387,7 +485,7 @@ function validateAdvisoryErrors(value, issues) {
   });
   return valid;
 }
-function validateResultShape(value, path, issues) {
+function validateResultShape(value, path, issues, adcpVersion) {
   if (!isRecord(value)) return shape(issues, path, "result must be an object");
   let valid = allowedKeys(value, RESULT_KEYS, path, issues);
   if (!nonempty(value.source_proposal_id))
@@ -404,14 +502,14 @@ function validateResultShape(value, path, issues) {
   };
   if (outcome === "revised") {
     forbidden(["proposal", "reason_code", "reason", "unsatisfied_constraints", "unsatisfied_product_changes"]);
-    if (!validateProposalArray(value.proposals, `${path}.proposals`, issues)) valid = false;
+    if (!validateProposalArray(value.proposals, `${path}.proposals`, issues, adcpVersion)) valid = false;
   } else if (outcome === "partial") {
     forbidden(["proposal"]);
-    if (!validateProposalArray(value.proposals, `${path}.proposals`, issues)) valid = false;
+    if (!validateProposalArray(value.proposals, `${path}.proposals`, issues, adcpVersion)) valid = false;
     if (!validateReason(value, path, issues)) valid = false;
   } else if (outcome === "finalized") {
     forbidden(["proposals", "reason_code", "reason", "unsatisfied_constraints", "unsatisfied_product_changes"]);
-    if (!validateCanonicalProposalShape(value.proposal, `${path}.proposal`, issues)) valid = false;
+    if (!validateCanonicalProposalShape(value.proposal, `${path}.proposal`, issues, adcpVersion)) valid = false;
   } else {
     forbidden(["proposal", "proposals"]);
     if (!validateReason(value, path, issues)) valid = false;
@@ -453,24 +551,39 @@ function validateReason(value, path, issues) {
   if (!nonempty(value.reason)) valid = shape(issues, `${path}.reason`, "reason must be a non-empty string");
   return valid;
 }
-function validateProposalArray(value, path, issues) {
+function validateProposalArray(value, path, issues, adcpVersion) {
   if (!Array.isArray(value) || value.length === 0) return shape(issues, path, "proposals must be a non-empty array");
   let valid = true;
   value.forEach((proposal, index) => {
-    if (!validateCanonicalProposalShape(proposal, `${path}[${index}]`, issues)) valid = false;
+    if (!validateCanonicalProposalShape(proposal, `${path}[${index}]`, issues, adcpVersion)) valid = false;
   });
   return valid;
 }
-function validateCanonicalProposalShape(value, path, issues) {
-  const validateCanonicalProposal = getSchemaValidatorByRef("core/canonical-proposal.json");
-  if (!validateCanonicalProposal) return shape(issues, path, "canonical-proposal schema is unavailable");
+function unavailableRefinementSchema(adcpVersion, error) {
+  const cause = error instanceof ConfigurationError ? error.message.includes("Schema validation requires unambiguous schema identities") ? " (ConfigurationError: schema validation requires unambiguous schema identities)" : " (ConfigurationError)" : error === void 0 ? "" : error instanceof Error && /^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(error.name) ? ` (${error.name})` : " (schema loading error)";
+  return `selected proposal schema for AdCP ${adcpVersion} is unavailable${cause}; install its schema bundle or register a matching external schema root with @adcp/sdk/testing`;
+}
+function getRefinementSchemaValidator(schemaRef, adcpVersion) {
+  try {
+    const validator = getSchemaValidatorByRef(schemaRef, adcpVersion);
+    return { validator, error: validator ? void 0 : unavailableRefinementSchema(adcpVersion) };
+  } catch (error) {
+    return { validator: void 0, error: unavailableRefinementSchema(adcpVersion, error) };
+  }
+}
+function validateCanonicalProposalShape(value, path, issues, adcpVersion) {
+  const { validator: validateCanonicalProposal, error: schemaError } = getRefinementSchemaValidator(
+    "core/canonical-proposal.json",
+    adcpVersion
+  );
+  if (!validateCanonicalProposal) return shape(issues, path, schemaError);
   if (!validateCanonicalProposal(value)) {
     const error = validateCanonicalProposal.errors?.[0];
     const errorPath = error?.instancePath ? `${path}${error.instancePath.replaceAll("/", ".")}` : path;
     return shape(
       issues,
       errorPath,
-      `proposal must satisfy the AdCP 3.2 schema${error?.message ? `: ${error.message}` : ""}`
+      `proposal must satisfy the selected AdCP ${adcpVersion} schema${error?.message ? `: ${error.message}` : ""}`
     );
   }
   const proposal = value;
@@ -514,10 +627,11 @@ function validateCanonicalProposalShape(value, path, issues) {
   if (proposal.proposal_status === "committed" && !isStrictDateTime(proposal.expires_at)) {
     valid = shape(issues, `${path}.expires_at`, "committed proposals require expires_at");
   }
-  if (!validateCommercialTerms(proposal.commercial_terms, `${path}.commercial_terms`, issues)) valid = false;
+  if (!validateCommercialTerms(proposal.commercial_terms, `${path}.commercial_terms`, issues, adcpVersion))
+    valid = false;
   return valid;
 }
-function validateCommercialTerms(value, path, issues) {
+function validateCommercialTerms(value, path, issues, adcpVersion) {
   if (!isRecord(value)) return shape(issues, path, "commercial_terms must be an object");
   let valid = true;
   if (!isRecord(value.brand)) valid = shape(issues, `${path}.brand`, "brand must be an object");
@@ -571,7 +685,7 @@ function validateCommercialTerms(value, path, issues) {
     valid = shape(issues, `${path}.reporting_commitments`, "reporting_commitments must be a non-empty array");
   if (value.cancellation_terms !== void 0 && !validateCancellationTerms(value.cancellation_terms, `${path}.cancellation_terms`, issues))
     valid = false;
-  if (value.change_terms !== void 0 && !validateChangeTerms(value.change_terms, `${path}.change_terms`, issues, purchaseCurrency))
+  if (value.change_terms !== void 0 && !validateChangeTerms(value.change_terms, `${path}.change_terms`, issues, adcpVersion, purchaseCurrency))
     valid = false;
   return valid;
 }
@@ -587,10 +701,13 @@ const CHANGE_TERM_ACTIONS_BY_CONSTRAINT = {
   package_count: /* @__PURE__ */ new Set(["add_packages", "remove_packages"]),
   effective_timing: /* @__PURE__ */ new Set(["pause", "resume", "cancel"])
 };
-function validateChangeTerms(value, path, issues, purchaseCurrency) {
+function validateChangeTerms(value, path, issues, adcpVersion, purchaseCurrency) {
   if (!Array.isArray(value) || value.length === 0) return shape(issues, path, "change_terms must be a non-empty array");
-  const validateChangeTerm = getSchemaValidatorByRef("media-buy/change-term.json");
-  if (!validateChangeTerm) return shape(issues, path, "change-term schema is unavailable");
+  const { validator: validateChangeTerm, error: schemaError } = getRefinementSchemaValidator(
+    "media-buy/change-term.json",
+    adcpVersion
+  );
+  if (!validateChangeTerm) return shape(issues, path, schemaError);
   let valid = true;
   const actions = /* @__PURE__ */ new Set();
   value.forEach((term, index) => {
@@ -601,7 +718,7 @@ function validateChangeTerms(value, path, issues, purchaseCurrency) {
       valid = shape(
         issues,
         errorPath,
-        `change term must satisfy the AdCP 3.2 schema${error?.message ? `: ${error.message}` : ""}`
+        `change term must satisfy the selected AdCP ${adcpVersion} schema${error?.message ? `: ${error.message}` : ""}`
       );
       return;
     }
@@ -1307,6 +1424,7 @@ export {
   assertRefineProposalsResponseShape,
   isStrictDateTime,
   proposalTermsDigest,
+  selectRefinementSchemaVersion,
   validateRefineProposalsResponseShape,
   verifyProposalCommercialTerms,
   verifyProposalTermsDigest,

package/dist/lib/negotiation/version.d.mts

@@ -0,0 +1,6 @@
+import type { ProposalRefinementVersion } from './types.mjs';
+/** Supported wire releases. Keep this guard and the public type in sync. */
+export declare function isProposalRefinementVersion(value: unknown): value is ProposalRefinementVersion;
+/** Inputs have already passed the release-precision guard above. */
+export declare function compareProposalRefinementVersions(left: ProposalRefinementVersion, right: ProposalRefinementVersion): number;
+export declare function describeRefinementVersion(value: unknown): string;

package/dist/lib/negotiation/version.d.ts

@@ -0,0 +1,6 @@
+import type { ProposalRefinementVersion } from './types';
+/** Supported wire releases. Keep this guard and the public type in sync. */
+export declare function isProposalRefinementVersion(value: unknown): value is ProposalRefinementVersion;
+/** Inputs have already passed the release-precision guard above. */
+export declare function compareProposalRefinementVersions(left: ProposalRefinementVersion, right: ProposalRefinementVersion): number;
+export declare function describeRefinementVersion(value: unknown): string;