@adcp/sdk 16.2.0 → 16.3.0

package/AGENTS.md

@@ -21,6 +21,8 @@ This document contains essential guidelines for AI coding assistants (Claude, Co
 
 **Migration guides** — [AdCP 2 retirement](docs/migration-drop-adcp-2.md) (AdCP 3-only discovery, removed compatibility APIs, and last supporting SDK pins); [Account change feed](docs/migration-account-change-feed.md) (wake-up parsing, guarded bootstrap/drain, subscriber registration and ownership boundaries); `docs/migration-6.6-to-6.7.md` (fifteen adopter recipes; two breaking changes — `'implicit'` enforces inline-`account_id` refusal and `SalesPlatform` split into `SalesCorePlatform & SalesIngestionPlatform`; plus `definePlatform` helpers, `composeMethod`, `accounts.resolve` security presets, `accounts.upsert/list/syncGovernance(ctx)`, typed errors, `issues[].hint`, `BuyerAgentRegistry`, `createTenantRegistry`, `createOAuthPassthroughResolver`, `createRosterAccountStore`, `createTenantStore` w/ built-in tenant gate, `MEDIA_BUY_TRANSITIONS` lifecycle helpers, `createMediaBuyStore` for `targeting_overlay` echo, `NoAccountCtx` narrow, `refAccountId(ref)`); `docs/migration-5.x-to-6.x.md` (5 → 6 framework shape); `docs/migration-4.x-to-5.x.md` (4 → 5); `docs/migration-buyer-agent-registry.md` (registry deep-dive).
 
+**Pinning a real collection-bearing product in a storyboard?** — Read [`docs/guides/COLLECTION-FIXTURE-FOUNDATION.md`](docs/guides/COLLECTION-FIXTURE-FOUNDATION.md): `collection_selection_satisfies`, same-graph fixture captures, the protected `__adcp_fixture_` namespace, `prepareStoryboardFixtures()`, and `collection_set_equals_context` — plus the limits the foundation does not claim to solve.
+
 **Putting credentials in `ctx_metadata`?** — Don't. Read `docs/guides/CTX-METADATA-SAFETY.md` — wire-strip protects buyer responses but not log lines / error envelopes / heap dumps / adopter strings. Re-derive bearers per request; embed only non-secret upstream IDs.
 
 **Reviewing a safety-critical PR (auth, signing, replay, idempotency, governance, tenancy)?** — Read `docs/development/REVIEW-STACKS.md`. Run Claude expert agents (DX, protocol, code-review, security) in parallel **plus** `npm run review:codex -- --all --base main` for a second-model opinion. Convergence = ship confidence; divergence = the actual review.

package/dist/lib/core/AgentClient.js

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

package/dist/lib/core/AgentClient.mjs

@@ -5,6 +5,8 @@ import {
 import { assertNativeRequestProposalsTask, guardNativeRequestProposalsCompletion } from "./request-proposals-guard.mjs";
 import { buildRefineProposalsRequest } from "../negotiation/buyer.mjs";
 import { assertRefineProposalsResponse } from "../negotiation/verification.mjs";
+import { applicableRefinementServedVersion } from "../negotiation/version.mjs";
+import { toReleasePrecisionVersion } from "../version.mjs";
 function stripRefineProposalsSdkAnnotations(data) {
   const canonical = { ...data };
   delete canonical.success;
@@ -147,6 +149,10 @@ class AgentClient {
   getAdcpVersion() {
     return this.client.getAdcpVersion();
   }
+  /** @internal Original envelope pin, separate from the validation schema pin. */
+  getWireAdcpVersion() {
+    return this.client.getWireAdcpVersion();
+  }
   /**
    * Negotiate one compact-first media-buy facade for this seller.
    *
@@ -480,7 +486,17 @@ class AgentClient {
     this.retainSession(result);
     if (result.success && result.status === "completed") {
       const data = stripRefineProposalsSdkAnnotations(result.data);
-      assertRefineProposalsResponse(request, data);
+      const cachedServedVersion = this.client.getCachedServedAdcpVersion(taskOptions);
+      assertRefineProposalsResponse(request, data, {
+        adcpVersion: this.client.getAdcpVersion(),
+        // Task metadata repeats the response echo. Independently discovered
+        // actual served evidence must constrain that seller-controlled value.
+        servedAdcpVersion: applicableRefinementServedVersion(
+          cachedServedVersion,
+          request.adcp_version,
+          toReleasePrecisionVersion(this.client.getWireAdcpVersion())
+        ) ?? result.metadata.adcpVersion
+      });
       return { ...result, data };
     }
     return result;

package/dist/lib/core/SingleAgentClient.js

@@ -1905,6 +1905,19 @@ class SingleAgentClient {
   getWireAdcpVersion() {
     return this.config.wireAdcpVersion ?? this.resolvedAdcpVersion;
   }
+  /** @internal Read only current, auth-scoped actual discovery evidence; never fetch. */
+  getCachedServedAdcpVersion(options) {
+    this.synchronizeCapabilityEvidenceAuthorizationScope();
+    if (this.usesScopedDiscoveryTransport(options)) return void 0;
+    if (this.primedCapabilitiesExpiresAt !== void 0 && this.primedCapabilitiesExpiresAt <= Date.now())
+      return void 0;
+    if (this.config.discoveryCache && this.cachedCapabilities) {
+      const key = this.sharedDiscoveryKey(options);
+      if (this.sharedEvidenceKey !== key || key !== void 0 && this.sharedEvidenceEpoch !== void 0 && this.sharedEvidenceEpoch !== this.sharedInvalidationEpoch(key))
+        return void 0;
+    }
+    return this.cachedCapabilities?._synthetic === false ? this.cachedCapabilities.servedVersion : void 0;
+  }
   /**
    * Ensure MCP endpoint is discovered (lazy initialization)
    *

package/dist/lib/core/SingleAgentClient.mjs

@@ -2002,6 +2002,19 @@ class SingleAgentClient {
   getWireAdcpVersion() {
     return this.config.wireAdcpVersion ?? this.resolvedAdcpVersion;
   }
+  /** @internal Read only current, auth-scoped actual discovery evidence; never fetch. */
+  getCachedServedAdcpVersion(options) {
+    this.synchronizeCapabilityEvidenceAuthorizationScope();
+    if (this.usesScopedDiscoveryTransport(options)) return void 0;
+    if (this.primedCapabilitiesExpiresAt !== void 0 && this.primedCapabilitiesExpiresAt <= Date.now())
+      return void 0;
+    if (this.config.discoveryCache && this.cachedCapabilities) {
+      const key = this.sharedDiscoveryKey(options);
+      if (this.sharedEvidenceKey !== key || key !== void 0 && this.sharedEvidenceEpoch !== void 0 && this.sharedEvidenceEpoch !== this.sharedInvalidationEpoch(key))
+        return void 0;
+    }
+    return this.cachedCapabilities?._synthetic === false ? this.cachedCapabilities.servedVersion : void 0;
+  }
   /**
    * Ensure MCP endpoint is discovered (lazy initialization)
    *

package/dist/lib/core/TaskExecutor.js

@@ -53,6 +53,8 @@ var import_client_hooks = require('../validation/client-hooks.js');
 var import_schema_validator = require('../validation/schema-validator.js');
 var import_schema_loader = require('../validation/schema-loader.js');
 var import_version = require('../version.js');
+var import_version2 = require('../negotiation/version.js');
+var import_verification = require('../negotiation/verification.js');
 var import_response_unwrapper = require('../utils/response-unwrapper.js');
 var import_error_extraction = require('../utils/error-extraction.js');
 var import_idempotency = require('../utils/idempotency.js');
@@ -823,6 +825,13 @@ class TaskExecutor {
       agent: { id: agent.id, name: agent.name, protocol: agent.protocol },
       serverVersion: effectiveServerVersion,
       serverVersionSynthetic: targetCapabilities?._synthetic ?? serverVersion === void 0,
+      ...taskName === "refine_proposals" && targetCapabilities?._synthetic === false && {
+        refinementServedVersion: (0, import_version2.applicableRefinementServedVersion)(
+          targetCapabilities.servedVersion,
+          params?.adcp_version ?? (0, import_version.toReleasePrecisionVersion)(wireAdcpVersion ?? this.config.adcpVersion ?? import_version.ADCP_VERSION),
+          (0, import_version.toReleasePrecisionVersion)(this.config.wireAdcpVersion ?? this.config.adcpVersion ?? import_version.ADCP_VERSION)
+        )
+      },
       idempotencyKey
     };
     this.activeTasks.set(taskId, taskState);
@@ -1113,7 +1122,8 @@ class TaskExecutor {
         dispatchSettlement?.persistPausedContinuation ?? true,
         effectiveServerVersion,
         deferredClientContext,
-        dispatchSettlement?.requireDeferredSettlementResumeAuthorization === true
+        dispatchSettlement?.requireDeferredSettlementResumeAuthorization === true,
+        taskState.refinementServedVersion
       );
       (0, import_abort.throwIfAborted)(postDispatchOptions.signal);
       if (governanceResult) {
@@ -1256,7 +1266,7 @@ class TaskExecutor {
       debug_logs: debugLogs
     };
   }
-  async handleAsyncResponse(agent, taskId, taskName, params, response, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false, persistPausedContinuation = true, serverVersion = "v3", deferredClientContext, requireDeferredSettlementResumeAuthorization = false) {
+  async handleAsyncResponse(agent, taskId, taskName, params, response, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false, persistPausedContinuation = true, serverVersion = "v3", deferredClientContext, requireDeferredSettlementResumeAuthorization = false, refinementServedVersion) {
     const status = this.responseParser.getStatus(response);
     const serverTaskId = this.responseParser.getTaskId(response);
     const task = this.activeTasks.get(taskId);
@@ -1266,7 +1276,14 @@ class TaskExecutor {
         const completedData = this.extractResponseData(response, debugLogs, taskName, serverVersion);
         if (!deferTerminalTaskStatus) this.updateTaskStatus(taskId, "completed", completedData);
         const operationSuccess = this.isOperationSuccess(completedData, taskName, serverVersion);
-        const validationResult = this.validateResponseSchema(completedData, taskName, debugLogs, serverVersion);
+        const validationResult = this.validateResponseSchema(
+          completedData,
+          taskName,
+          debugLogs,
+          serverVersion,
+          params,
+          refinementServedVersion
+        );
         const finalSuccess = operationSuccess && validationResult.valid;
         const finalError = !finalSuccess ? validationResult.errors.length > 0 ? `Schema validation failed: ${validationResult.errors.join("; ")}` : this.extractOperationError(completedData) : void 0;
         if (finalSuccess) {
@@ -1351,7 +1368,8 @@ class TaskExecutor {
           persistPausedContinuation,
           serverVersion,
           deferredClientContext,
-          requireDeferredSettlementResumeAuthorization
+          requireDeferredSettlementResumeAuthorization,
+          refinementServedVersion
         );
       case import_ProtocolResponseParser.ADCP_STATUS.FAILED:
       case import_ProtocolResponseParser.ADCP_STATUS.REJECTED:
@@ -1387,7 +1405,14 @@ class TaskExecutor {
         const defaultData = this.extractResponseData(response, debugLogs, taskName, serverVersion);
         if (defaultData && (defaultData !== response || response.structuredContent || response.result || response.data)) {
           const defaultSuccess = this.isOperationSuccess(defaultData, taskName, serverVersion);
-          const defaultValidation = this.validateResponseSchema(defaultData, taskName, debugLogs, serverVersion);
+          const defaultValidation = this.validateResponseSchema(
+            defaultData,
+            taskName,
+            debugLogs,
+            serverVersion,
+            params,
+            refinementServedVersion
+          );
           const defaultFinalSuccess = defaultSuccess && defaultValidation.valid;
           const defaultFinalError = !defaultFinalSuccess ? defaultValidation.errors.length > 0 ? `Schema validation failed: ${defaultValidation.errors.join("; ")}` : this.extractOperationError(defaultData) : void 0;
           if (defaultFinalSuccess) {
@@ -2001,7 +2026,7 @@ class TaskExecutor {
    * This is common for HITL (human-in-the-loop) workflows where the agent has already processed
    * the request and is just signaling that async approval may be needed.
    */
-  async handleInputRequired(agent, taskId, taskName, params, response, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false, pauseStatus = "input-required", persistPausedContinuation = true, serverVersion = "v3", deferredClientContext, requireDeferredSettlementResumeAuthorization = false) {
+  async handleInputRequired(agent, taskId, taskName, params, response, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false, pauseStatus = "input-required", persistPausedContinuation = true, serverVersion = "v3", deferredClientContext, requireDeferredSettlementResumeAuthorization = false, refinementServedVersion) {
     const inputRequest = this.responseParser.parseInputRequest(response);
     const serverContextId = this.responseParser.getContextId(response) ?? response.contextId;
     const a2aTaskId = this.responseParser.getA2AContinuationTaskId(response);
@@ -2059,6 +2084,7 @@ class TaskExecutor {
           ...options.wireAdcpVersion !== void 0 && { wireAdcpVersion: options.wireAdcpVersion },
           ...options.versionEnvelope !== void 0 && { versionEnvelope: options.versionEnvelope },
           serverVersionSynthetic: this.activeTasks.get(taskId)?.serverVersionSynthetic,
+          ...refinementServedVersion !== void 0 && { refinementServedVersion },
           agentId: agent.id,
           taskName,
           params: durableDeferredSnapshot(params),
@@ -2123,7 +2149,8 @@ class TaskExecutor {
           persistPausedContinuation,
           serverVersion,
           deferredClientContext,
-          requireDeferredSettlementResumeAuthorization
+          requireDeferredSettlementResumeAuthorization,
+          refinementServedVersion
         );
       };
       const deferred = {
@@ -2201,6 +2228,7 @@ class TaskExecutor {
           ...options.wireAdcpVersion !== void 0 && { wireAdcpVersion: options.wireAdcpVersion },
           ...options.versionEnvelope !== void 0 && { versionEnvelope: options.versionEnvelope },
           serverVersionSynthetic: this.activeTasks.get(taskId)?.serverVersionSynthetic,
+          ...refinementServedVersion !== void 0 && { refinementServedVersion },
           agentId: agent.id,
           taskName,
           params: durableDeferredSnapshot(params),
@@ -2266,7 +2294,8 @@ class TaskExecutor {
           persistPausedContinuation,
           serverVersion,
           deferredClientContext,
-          requireDeferredSettlementResumeAuthorization
+          requireDeferredSettlementResumeAuthorization,
+          refinementServedVersion
         );
       };
       const deferred = {
@@ -2317,7 +2346,8 @@ class TaskExecutor {
       persistPausedContinuation,
       serverVersion,
       deferredClientContext,
-      requireDeferredSettlementResumeAuthorization
+      requireDeferredSettlementResumeAuthorization,
+      refinementServedVersion
     );
   }
   /**
@@ -3317,7 +3347,8 @@ class TaskExecutor {
         false,
         state.serverVersion,
         state.clientContext,
-        state.settlementResumeAuthorizationRequired === true
+        state.settlementResumeAuthorizationRequired === true,
+        state.refinementServedVersion
       );
       resumed = attachDeferredServerVersion(resumed, state);
       const observedResumedServerTaskId = resumed.metadata.serverTaskId;
@@ -3343,6 +3374,9 @@ class TaskExecutor {
           ...resumed.metadata.contextId !== void 0 ? { contextId: resumed.metadata.contextId } : state.contextId !== void 0 ? { contextId: state.contextId } : {},
           a2aTaskId: nextA2ATaskId,
           serverVersion: state.serverVersion,
+          ...state.refinementServedVersion !== void 0 && {
+            refinementServedVersion: state.refinementServedVersion
+          },
           ...state.wireAdcpVersion !== void 0 && { wireAdcpVersion: state.wireAdcpVersion },
           ...state.versionEnvelope !== void 0 && { versionEnvelope: state.versionEnvelope },
           ...state.serverVersionSynthetic !== void 0 && {
@@ -4271,7 +4305,7 @@ class TaskExecutor {
   /**
    * Continue a task after receiving input
    */
-  async continueTaskWithInput(agent, taskId, taskName, params, contextId, a2aTaskId, input, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false, persistPausedContinuation = true, serverVersion = "v3", deferredClientContext, requireDeferredSettlementResumeAuthorization = false) {
+  async continueTaskWithInput(agent, taskId, taskName, params, contextId, a2aTaskId, input, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false, persistPausedContinuation = true, serverVersion = "v3", deferredClientContext, requireDeferredSettlementResumeAuthorization = false, refinementServedVersion) {
     const inputSnapshot = structuredClone(input);
     if (agent.protocol !== "a2a") {
       throw new Error("MCP does not define a standard continuation for a returned input-required task.");
@@ -4337,7 +4371,8 @@ class TaskExecutor {
       persistPausedContinuation,
       serverVersion,
       deferredClientContext,
-      requireDeferredSettlementResumeAuthorization
+      requireDeferredSettlementResumeAuthorization,
+      refinementServedVersion
     );
   }
   /**
@@ -4529,7 +4564,7 @@ class TaskExecutor {
    * valid so the caller can continue. Off mode short-circuits before
    * AJV runs.
    */
-  validateResponseSchema(response, taskName, debugLogs, serverVersion) {
+  validateResponseSchema(response, taskName, debugLogs, serverVersion, requestParams, refinementServedVersion) {
     const mode = this.responseValidationMode;
     const logViolations = this.config.logSchemaViolations !== false;
     try {
@@ -4541,6 +4576,46 @@ class TaskExecutor {
           (validationVersion) => this.validateResponseSchemaAgainst(response, taskName, debugLogs, mode, logViolations, validationVersion)
         );
       }
+      if (taskName === "refine_proposals" && mode !== "off") {
+        const ceiling = requestParams?.adcp_version ?? (0, import_version.toReleasePrecisionVersion)(this.config.wireAdcpVersion ?? pinnedValidationVersion);
+        const issues = [];
+        const selected = (0, import_verification.selectRefinementSchemaVersion)(
+          ceiling,
+          response,
+          {
+            adcpVersion: pinnedValidationVersion,
+            servedAdcpVersion: (0, import_version2.applicableRefinementServedVersion)(refinementServedVersion, ceiling)
+          },
+          issues
+        );
+        if (!selected) {
+          const errors = issues.map((issue) => `${issue.path}: ${issue.message}`);
+          if (logViolations) {
+            debugLogs.push({
+              timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+              type: mode === "strict" ? "error" : "warning",
+              message: `Schema validation ${mode === "strict" ? "failed" : "warning"} for ${taskName}: ${errors.join("; ")}`,
+              errors,
+              issues,
+              schemaVersion: pinnedValidationVersion,
+              mode
+            });
+            if (mode === "warn") {
+              console.warn(
+                `Schema validation failed for ${taskName} against AdCP ${pinnedValidationVersion} (non-blocking):`,
+                errors
+              );
+            } else {
+              console.error(
+                `Schema validation failed for ${taskName} against AdCP ${pinnedValidationVersion}:`,
+                errors
+              );
+            }
+          }
+          return { valid: mode !== "strict", errors: mode === "strict" ? errors : [] };
+        }
+        return this.validateResponseSchemaAgainst(response, taskName, debugLogs, mode, logViolations, selected);
+      }
       return this.validateResponseSchemaAgainst(
         response,
         taskName,

package/dist/lib/core/TaskExecutor.mjs

@@ -28,7 +28,9 @@ import {
 } from "../validation/client-hooks.mjs";
 import { formatIssues } from "../validation/schema-validator.mjs";
 import { withServedValidationVersion } from "../validation/schema-loader.mjs";
-import { ADCP_VERSION } from "../version.mjs";
+import { ADCP_VERSION, toReleasePrecisionVersion } from "../version.mjs";
+import { applicableRefinementServedVersion } from "../negotiation/version.mjs";
+import { selectRefinementSchemaVersion } from "../negotiation/verification.mjs";
 import { unwrapProtocolResponse, isAdcpOperationSuccess } from "../utils/response-unwrapper.mjs";
 import { extractAdcpErrorInfo, extractCorrelationId } from "../utils/error-extraction.mjs";
 import { generateIdempotencyKey, requestUsesIdempotency, redactIdempotencyKeyInArgs } from "../utils/idempotency.mjs";
@@ -801,6 +803,13 @@ class TaskExecutor {
       agent: { id: agent.id, name: agent.name, protocol: agent.protocol },
       serverVersion: effectiveServerVersion,
       serverVersionSynthetic: targetCapabilities?._synthetic ?? serverVersion === void 0,
+      ...taskName === "refine_proposals" && targetCapabilities?._synthetic === false && {
+        refinementServedVersion: applicableRefinementServedVersion(
+          targetCapabilities.servedVersion,
+          params?.adcp_version ?? toReleasePrecisionVersion(wireAdcpVersion ?? this.config.adcpVersion ?? ADCP_VERSION),
+          toReleasePrecisionVersion(this.config.wireAdcpVersion ?? this.config.adcpVersion ?? ADCP_VERSION)
+        )
+      },
       idempotencyKey
     };
     this.activeTasks.set(taskId, taskState);
@@ -1091,7 +1100,8 @@ class TaskExecutor {
         dispatchSettlement?.persistPausedContinuation ?? true,
         effectiveServerVersion,
         deferredClientContext,
-        dispatchSettlement?.requireDeferredSettlementResumeAuthorization === true
+        dispatchSettlement?.requireDeferredSettlementResumeAuthorization === true,
+        taskState.refinementServedVersion
       );
       throwIfAborted(postDispatchOptions.signal);
       if (governanceResult) {
@@ -1234,7 +1244,7 @@ class TaskExecutor {
       debug_logs: debugLogs
     };
   }
-  async handleAsyncResponse(agent, taskId, taskName, params, response, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false, persistPausedContinuation = true, serverVersion = "v3", deferredClientContext, requireDeferredSettlementResumeAuthorization = false) {
+  async handleAsyncResponse(agent, taskId, taskName, params, response, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false, persistPausedContinuation = true, serverVersion = "v3", deferredClientContext, requireDeferredSettlementResumeAuthorization = false, refinementServedVersion) {
     const status = this.responseParser.getStatus(response);
     const serverTaskId = this.responseParser.getTaskId(response);
     const task = this.activeTasks.get(taskId);
@@ -1244,7 +1254,14 @@ class TaskExecutor {
         const completedData = this.extractResponseData(response, debugLogs, taskName, serverVersion);
         if (!deferTerminalTaskStatus) this.updateTaskStatus(taskId, "completed", completedData);
         const operationSuccess = this.isOperationSuccess(completedData, taskName, serverVersion);
-        const validationResult = this.validateResponseSchema(completedData, taskName, debugLogs, serverVersion);
+        const validationResult = this.validateResponseSchema(
+          completedData,
+          taskName,
+          debugLogs,
+          serverVersion,
+          params,
+          refinementServedVersion
+        );
         const finalSuccess = operationSuccess && validationResult.valid;
         const finalError = !finalSuccess ? validationResult.errors.length > 0 ? `Schema validation failed: ${validationResult.errors.join("; ")}` : this.extractOperationError(completedData) : void 0;
         if (finalSuccess) {
@@ -1329,7 +1346,8 @@ class TaskExecutor {
           persistPausedContinuation,
           serverVersion,
           deferredClientContext,
-          requireDeferredSettlementResumeAuthorization
+          requireDeferredSettlementResumeAuthorization,
+          refinementServedVersion
         );
       case ADCP_STATUS.FAILED:
       case ADCP_STATUS.REJECTED:
@@ -1365,7 +1383,14 @@ class TaskExecutor {
         const defaultData = this.extractResponseData(response, debugLogs, taskName, serverVersion);
         if (defaultData && (defaultData !== response || response.structuredContent || response.result || response.data)) {
           const defaultSuccess = this.isOperationSuccess(defaultData, taskName, serverVersion);
-          const defaultValidation = this.validateResponseSchema(defaultData, taskName, debugLogs, serverVersion);
+          const defaultValidation = this.validateResponseSchema(
+            defaultData,
+            taskName,
+            debugLogs,
+            serverVersion,
+            params,
+            refinementServedVersion
+          );
           const defaultFinalSuccess = defaultSuccess && defaultValidation.valid;
           const defaultFinalError = !defaultFinalSuccess ? defaultValidation.errors.length > 0 ? `Schema validation failed: ${defaultValidation.errors.join("; ")}` : this.extractOperationError(defaultData) : void 0;
           if (defaultFinalSuccess) {
@@ -1979,7 +2004,7 @@ class TaskExecutor {
    * This is common for HITL (human-in-the-loop) workflows where the agent has already processed
    * the request and is just signaling that async approval may be needed.
    */
-  async handleInputRequired(agent, taskId, taskName, params, response, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false, pauseStatus = "input-required", persistPausedContinuation = true, serverVersion = "v3", deferredClientContext, requireDeferredSettlementResumeAuthorization = false) {
+  async handleInputRequired(agent, taskId, taskName, params, response, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false, pauseStatus = "input-required", persistPausedContinuation = true, serverVersion = "v3", deferredClientContext, requireDeferredSettlementResumeAuthorization = false, refinementServedVersion) {
     const inputRequest = this.responseParser.parseInputRequest(response);
     const serverContextId = this.responseParser.getContextId(response) ?? response.contextId;
     const a2aTaskId = this.responseParser.getA2AContinuationTaskId(response);
@@ -2037,6 +2062,7 @@ class TaskExecutor {
           ...options.wireAdcpVersion !== void 0 && { wireAdcpVersion: options.wireAdcpVersion },
           ...options.versionEnvelope !== void 0 && { versionEnvelope: options.versionEnvelope },
           serverVersionSynthetic: this.activeTasks.get(taskId)?.serverVersionSynthetic,
+          ...refinementServedVersion !== void 0 && { refinementServedVersion },
           agentId: agent.id,
           taskName,
           params: durableDeferredSnapshot(params),
@@ -2101,7 +2127,8 @@ class TaskExecutor {
           persistPausedContinuation,
           serverVersion,
           deferredClientContext,
-          requireDeferredSettlementResumeAuthorization
+          requireDeferredSettlementResumeAuthorization,
+          refinementServedVersion
         );
       };
       const deferred = {
@@ -2179,6 +2206,7 @@ class TaskExecutor {
           ...options.wireAdcpVersion !== void 0 && { wireAdcpVersion: options.wireAdcpVersion },
           ...options.versionEnvelope !== void 0 && { versionEnvelope: options.versionEnvelope },
           serverVersionSynthetic: this.activeTasks.get(taskId)?.serverVersionSynthetic,
+          ...refinementServedVersion !== void 0 && { refinementServedVersion },
           agentId: agent.id,
           taskName,
           params: durableDeferredSnapshot(params),
@@ -2244,7 +2272,8 @@ class TaskExecutor {
           persistPausedContinuation,
           serverVersion,
           deferredClientContext,
-          requireDeferredSettlementResumeAuthorization
+          requireDeferredSettlementResumeAuthorization,
+          refinementServedVersion
         );
       };
       const deferred = {
@@ -2295,7 +2324,8 @@ class TaskExecutor {
       persistPausedContinuation,
       serverVersion,
       deferredClientContext,
-      requireDeferredSettlementResumeAuthorization
+      requireDeferredSettlementResumeAuthorization,
+      refinementServedVersion
     );
   }
   /**
@@ -3295,7 +3325,8 @@ class TaskExecutor {
         false,
         state.serverVersion,
         state.clientContext,
-        state.settlementResumeAuthorizationRequired === true
+        state.settlementResumeAuthorizationRequired === true,
+        state.refinementServedVersion
       );
       resumed = attachDeferredServerVersion(resumed, state);
       const observedResumedServerTaskId = resumed.metadata.serverTaskId;
@@ -3321,6 +3352,9 @@ class TaskExecutor {
           ...resumed.metadata.contextId !== void 0 ? { contextId: resumed.metadata.contextId } : state.contextId !== void 0 ? { contextId: state.contextId } : {},
           a2aTaskId: nextA2ATaskId,
           serverVersion: state.serverVersion,
+          ...state.refinementServedVersion !== void 0 && {
+            refinementServedVersion: state.refinementServedVersion
+          },
           ...state.wireAdcpVersion !== void 0 && { wireAdcpVersion: state.wireAdcpVersion },
           ...state.versionEnvelope !== void 0 && { versionEnvelope: state.versionEnvelope },
           ...state.serverVersionSynthetic !== void 0 && {
@@ -4249,7 +4283,7 @@ class TaskExecutor {
   /**
    * Continue a task after receiving input
    */
-  async continueTaskWithInput(agent, taskId, taskName, params, contextId, a2aTaskId, input, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false, persistPausedContinuation = true, serverVersion = "v3", deferredClientContext, requireDeferredSettlementResumeAuthorization = false) {
+  async continueTaskWithInput(agent, taskId, taskName, params, contextId, a2aTaskId, input, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false, persistPausedContinuation = true, serverVersion = "v3", deferredClientContext, requireDeferredSettlementResumeAuthorization = false, refinementServedVersion) {
     const inputSnapshot = structuredClone(input);
     if (agent.protocol !== "a2a") {
       throw new Error("MCP does not define a standard continuation for a returned input-required task.");
@@ -4315,7 +4349,8 @@ class TaskExecutor {
       persistPausedContinuation,
       serverVersion,
       deferredClientContext,
-      requireDeferredSettlementResumeAuthorization
+      requireDeferredSettlementResumeAuthorization,
+      refinementServedVersion
     );
   }
   /**
@@ -4507,7 +4542,7 @@ class TaskExecutor {
    * valid so the caller can continue. Off mode short-circuits before
    * AJV runs.
    */
-  validateResponseSchema(response, taskName, debugLogs, serverVersion) {
+  validateResponseSchema(response, taskName, debugLogs, serverVersion, requestParams, refinementServedVersion) {
     const mode = this.responseValidationMode;
     const logViolations = this.config.logSchemaViolations !== false;
     try {
@@ -4519,6 +4554,46 @@ class TaskExecutor {
           (validationVersion) => this.validateResponseSchemaAgainst(response, taskName, debugLogs, mode, logViolations, validationVersion)
         );
       }
+      if (taskName === "refine_proposals" && mode !== "off") {
+        const ceiling = requestParams?.adcp_version ?? toReleasePrecisionVersion(this.config.wireAdcpVersion ?? pinnedValidationVersion);
+        const issues = [];
+        const selected = selectRefinementSchemaVersion(
+          ceiling,
+          response,
+          {
+            adcpVersion: pinnedValidationVersion,
+            servedAdcpVersion: applicableRefinementServedVersion(refinementServedVersion, ceiling)
+          },
+          issues
+        );
+        if (!selected) {
+          const errors = issues.map((issue) => `${issue.path}: ${issue.message}`);
+          if (logViolations) {
+            debugLogs.push({
+              timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+              type: mode === "strict" ? "error" : "warning",
+              message: `Schema validation ${mode === "strict" ? "failed" : "warning"} for ${taskName}: ${errors.join("; ")}`,
+              errors,
+              issues,
+              schemaVersion: pinnedValidationVersion,
+              mode
+            });
+            if (mode === "warn") {
+              console.warn(
+                `Schema validation failed for ${taskName} against AdCP ${pinnedValidationVersion} (non-blocking):`,
+                errors
+              );
+            } else {
+              console.error(
+                `Schema validation failed for ${taskName} against AdCP ${pinnedValidationVersion}:`,
+                errors
+              );
+            }
+          }
+          return { valid: mode !== "strict", errors: mode === "strict" ? errors : [] };
+        }
+        return this.validateResponseSchemaAgainst(response, taskName, debugLogs, mode, logViolations, selected);
+      }
       return this.validateResponseSchemaAgainst(
         response,
         taskName,

package/dist/lib/errors/index.d.mts

@@ -537,3 +537,37 @@ export declare function extractErrorInfo(error: unknown): {
     details?: unknown;
     stack?: string;
 };
+/**
+ * Prepared fixture state was refused by the host authorizer.
+ *
+ * An authorization failure is an ACCESS-CONTROL error, not a grading
+ * outcome, so the refused caller gets this and no `StoryboardResult` —
+ * not a partial one, not a redacted one. It carries the machine refusal
+ * code and nothing else: no fixture identities, no `seller_ids`, no
+ * captures, no binding values, no request/response records, and no
+ * results from steps that ran before the grant was revoked.
+ *
+ * The complete, unredacted record — including the synthesized
+ * `prepared_fixtures_authorization` check, `fixture_resolutions` with
+ * `seller_ids`, and exact request/response records — is handed to the
+ * host's `prepared_fixtures_audit_sink` before this is thrown. Where no
+ * sink is configured the record is simply not produced to anyone.
+ *
+ * Hosted entry points should surface this as a 403-style denial.
+ */
+export declare class PreparedFixturesDeniedError extends ADCPError {
+    /**
+     * Machine refusal code: `authorizer_required` | `untrusted_state` |
+     * `contract_version_mismatch` | `authorizer_denied` |
+     * `binding_mismatch` | `unauthorized_metadata`.
+     */
+    readonly refusalCode: string;
+    readonly code = "PREPARED_FIXTURES_DENIED";
+    constructor(
+    /**
+     * Machine refusal code: `authorizer_required` | `untrusted_state` |
+     * `contract_version_mismatch` | `authorizer_denied` |
+     * `binding_mismatch` | `unauthorized_metadata`.
+     */
+    refusalCode: string);
+}