@adcp/sdk 16.0.0-beta.8 → 16.0.0

package/dist/lib/core/TaskExecutor.d.mts

@@ -227,20 +227,6 @@ export declare class TaskExecutor {
      * Throws in strict, logs to `debugLogs` in warn, no-ops in off.
      */
     validateRequest(taskName: string, params: unknown, debugLogs?: any[]): void;
-    /**
-     * After `adaptRequestForServerVersion` has rewritten a v3 request into v2
-     * wire format, validate the adapted shape against the cached v2.5 schema
-     * bundle. Always warn-only — adapter bugs shouldn't break user requests,
-     * and the v3 pre-send pass already vouched for the user-facing input.
-     * This pass exists to surface drift between what the adapter emits and
-     * what a v2.5 server expects on the wire (primarily as CI signal via the
-     * adapter-conformance test suite).
-     *
-     * Skips silently for tasks without a v2.5 schema or when the v2.5 bundle
-     * isn't cached. Caller is responsible for gating on `serverVersion === 'v2'`
-     * so v3-targeted traffic doesn't pay the validation cost.
-     */
-    validateAdaptedRequestAgainstV2(taskName: string, adaptedParams: unknown, debugLogs?: any[]): void;
     /**
      * Generate webhook URL for protocol-level webhook support
      */
@@ -430,8 +416,7 @@ export declare class TaskExecutor {
     /**
      * Normalize response data for schema validation
      *
-     * Converts v2-style responses to v3 format before validation.
-     * This ensures validation passes for both v2 and v3 server responses.
+     * Normalizes established AdCP 3 product fields before validation.
      */
     private normalizeResponseForValidation;
     /**

package/dist/lib/core/TaskExecutor.d.ts

@@ -227,20 +227,6 @@ export declare class TaskExecutor {
      * Throws in strict, logs to `debugLogs` in warn, no-ops in off.
      */
     validateRequest(taskName: string, params: unknown, debugLogs?: any[]): void;
-    /**
-     * After `adaptRequestForServerVersion` has rewritten a v3 request into v2
-     * wire format, validate the adapted shape against the cached v2.5 schema
-     * bundle. Always warn-only — adapter bugs shouldn't break user requests,
-     * and the v3 pre-send pass already vouched for the user-facing input.
-     * This pass exists to surface drift between what the adapter emits and
-     * what a v2.5 server expects on the wire (primarily as CI signal via the
-     * adapter-conformance test suite).
-     *
-     * Skips silently for tasks without a v2.5 schema or when the v2.5 bundle
-     * isn't cached. Caller is responsible for gating on `serverVersion === 'v2'`
-     * so v3-targeted traffic doesn't pay the validation cost.
-     */
-    validateAdaptedRequestAgainstV2(taskName: string, adaptedParams: unknown, debugLogs?: any[]): void;
     /**
      * Generate webhook URL for protocol-level webhook support
      */
@@ -430,8 +416,7 @@ export declare class TaskExecutor {
     /**
      * Normalize response data for schema validation
      *
-     * Converts v2-style responses to v3 format before validation.
-     * This ensures validation passes for both v2 and v3 server responses.
+     * Normalizes established AdCP 3 product fields before validation.
      */
     private normalizeResponseForValidation;
     /**

package/dist/lib/core/TaskExecutor.js

@@ -27,7 +27,7 @@ __export(TaskExecutor_exports, {
   InputRequiredError: () => InputRequiredError,
   MaxClarificationError: () => MaxClarificationError,
   TaskExecutor: () => TaskExecutor,
-  TaskTimeoutError: () => import_errors2.TaskTimeoutError,
+  TaskTimeoutError: () => import_errors3.TaskTimeoutError,
   acknowledgeDeferredSettlement: () => acknowledgeDeferredSettlement,
   checkpointDeferredPendingSettlement: () => checkpointDeferredPendingSettlement,
   hasCompletionHandlerAlreadyPublished: () => hasCompletionHandlerAlreadyPublished,
@@ -38,6 +38,7 @@ __export(TaskExecutor_exports, {
   transferDeferredSettlementAcknowledgement: () => transferDeferredSettlementAcknowledgement
 });
 module.exports = __toCommonJS(TaskExecutor_exports);
+var import_errors = require('../errors/index.js');
 var import_webhook_registration = require('./webhook-registration.js');
 var import_adcp_version_config = require('../utils/adcp-version-config.js');
 var import_schema_errors = require('../validation/schema-errors.js');
@@ -47,7 +48,7 @@ var import_mcp_tasks = require('../protocols/mcp-tasks.js');
 var import_prepared_call_context = require('../protocols/prepared-call-context.js');
 var import_auth = require('../auth/index.js');
 var import_signedRequestRejection = require('../protocols/signedRequestRejection.js');
-var import_errors = require('../errors/index.js');
+var import_errors2 = require('../errors/index.js');
 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');
@@ -70,7 +71,7 @@ var import_governance = require('../governance/index.js');
 var import_match = require('./match.js');
 var import_webhook_url = require('./webhook-url.js');
 var import_task_deadline = require('./task-deadline.js');
-var import_errors2 = require('../errors/index.js');
+var import_errors3 = require('../errors/index.js');
 function validateIdentity33Payload(...args) {
   return require('../identity-3.3/validation.js').validateIdentity33Payload(...args);
 }
@@ -196,12 +197,12 @@ function webhookRegistrationFromPreparedCall(_agent, preparedCall) {
   const candidate = preparedCall.args.push_notification_config && typeof preparedCall.args.push_notification_config === "object" && !Array.isArray(preparedCall.args.push_notification_config) ? preparedCall.args.push_notification_config : _agent.protocol === "a2a" ? preparedCall.pushNotificationConfig : void 0;
   if (!candidate) return void 0;
   if (typeof candidate.url !== "string") {
-    throw new import_errors.ConfigurationError("push_notification_config.url must be a string.", "push_notification_config.url");
+    throw new import_errors2.ConfigurationError("push_notification_config.url must be a string.", "push_notification_config.url");
   }
   const profile = candidate.signing_profile;
   if (!Object.prototype.hasOwnProperty.call(candidate, "authentication")) {
     if (profile !== void 0 && !["adcp/webhook-signing/v1", "web-bot-auth"].includes(profile))
-      throw new import_errors.ConfigurationError("Unsupported webhook signing profile", "signing_profile");
+      throw new import_errors2.ConfigurationError("Unsupported webhook signing profile", "signing_profile");
     return {
       callbackUrl: candidate.url,
       mode: "rfc9421",
@@ -210,7 +211,7 @@ function webhookRegistrationFromPreparedCall(_agent, preparedCall) {
   }
   const authentication = candidate.authentication;
   if (!authentication || typeof authentication !== "object" || Array.isArray(authentication)) {
-    throw new import_errors.ConfigurationError(
+    throw new import_errors2.ConfigurationError(
       "push_notification_config.authentication selects legacy verification and must be a supported object.",
       "push_notification_config.authentication"
     );
@@ -218,7 +219,7 @@ function webhookRegistrationFromPreparedCall(_agent, preparedCall) {
   const schemes = authentication.schemes;
   const credentials = authentication.credentials;
   if (!Array.isArray(schemes) || schemes.length !== 1 || schemes[0] !== "HMAC-SHA256" || typeof credentials !== "string" || credentials.length === 0) {
-    throw new import_errors.ConfigurationError(
+    throw new import_errors2.ConfigurationError(
       "This receiver supports legacy HMAC-SHA256 or RFC 9421 push notifications; Bearer and mixed schemes are not supported.",
       "push_notification_config.authentication.schemes"
     );
@@ -271,13 +272,13 @@ function assertGovernedPayloadHasNoCallbackCredentials(taskName, payload, option
   if (!scanResult) return;
   if (scanResult.kind === "limit") {
     const limitDescription = scanResult.limit === "nodes" ? `${GOVERNED_CREDENTIAL_SCAN_MAX_NODES.toLocaleString("en-US")} nested objects` : `${GOVERNED_CREDENTIAL_SCAN_MAX_DEPTH} object levels`;
-    throw new import_errors.ConfigurationError(
+    throw new import_errors2.ConfigurationError(
       `The SDK could not safely inspect the governed ${taskName} payload for callback credentials because it exceeds the ${limitDescription} safety limit. Simplify the payload or move deeply nested extension data out of the governed request before retrying.`,
       "governance.payload"
     );
   }
   const remedy = scanResult.callbackField === "push_notification_config" ? options.sdkInjectedPushConfig ? "Retry with task options `{ disableWebhook: true }` and poll for completion, or use A2A task-status notifications." : "Remove the credential-bearing push notification config and poll for completion, or use A2A task-status notifications." : `Remove the credential-bearing ${scanResult.callbackField} from this governed request and use a non-webhook delivery path.`;
-  throw new import_errors.ConfigurationError(
+  throw new import_errors2.ConfigurationError(
     `Governed ${taskName} cannot forward ${scanResult.path} to the governance agent. The SDK will not disclose receiver authentication credentials, and redacting modern AdCP 3.2 payloads would invalidate seller authorization. ${remedy}`,
     scanResult.path
   );
@@ -354,9 +355,6 @@ function parseTimestamp(value) {
 function resolveIdempotencyKey(taskName, params, serverVersion) {
   const callerSupplied = params && typeof params === "object" && typeof params.idempotency_key === "string" ? params.idempotency_key : void 0;
   if (callerSupplied) return callerSupplied;
-  if (serverVersion === "v2") {
-    return params && typeof params === "object" && typeof params.buyer_ref === "string" ? params.buyer_ref : void 0;
-  }
   if ((0, import_idempotency.requestUsesIdempotency)(taskName, params)) return (0, import_idempotency.generateIdempotencyKey)();
   return void 0;
 }
@@ -424,7 +422,7 @@ function directContinuationRecoveryKeyMatches(expectedDigest, recoveryKey) {
 }
 function assertDirectContinuationOwnerScope(ownerScope) {
   if (typeof ownerScope !== "string" || ownerScope.trim().length === 0 || /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(ownerScope) || Buffer.byteLength(ownerScope, "utf8") > MAX_DIRECT_CONTINUATION_OWNER_SCOPE_BYTES) {
-    throw new import_errors.ConfigurationError(
+    throw new import_errors2.ConfigurationError(
       "durableContinuationRecovery.ownerScope must be a non-empty authenticated owner/account scope of at most 1024 UTF-8 bytes."
     );
   }
@@ -558,23 +556,23 @@ class TaskExecutor {
   constructor(config = {}) {
     this.config = config;
     if (config.externalTaskSettlementRetentionMs !== void 0 && (!Number.isSafeInteger(config.externalTaskSettlementRetentionMs) || config.externalTaskSettlementRetentionMs < 1)) {
-      throw new import_errors.ConfigurationError("externalTaskSettlementRetentionMs must be a positive safe integer.");
+      throw new import_errors2.ConfigurationError("externalTaskSettlementRetentionMs must be a positive safe integer.");
     }
     if (config.deferredTaskTtlSeconds !== void 0 && (!Number.isSafeInteger(config.deferredTaskTtlSeconds) || config.deferredTaskTtlSeconds < 1)) {
-      throw new import_errors.ConfigurationError("deferredTaskTtlSeconds must be a positive safe integer.");
+      throw new import_errors2.ConfigurationError("deferredTaskTtlSeconds must be a positive safe integer.");
     }
     if (config.deferredStorage && typeof config.deferredStorage.putIfAbsent !== "function") {
-      throw new import_errors.ConfigurationError(
+      throw new import_errors2.ConfigurationError(
         "Deferred storage must implement atomic putIfAbsent() creation so replicas cannot overwrite a continuation. Use MemoryStorage for single-process tests or implement the DeferredTaskStorage atomic contract."
       );
     }
     if (config.deferredStorage && typeof config.deferredStorage.replaceIfVersion !== "function") {
-      throw new import_errors.ConfigurationError(
+      throw new import_errors2.ConfigurationError(
         "Deferred storage must implement atomic replaceIfVersion() fencing so only one replica can dispatch a resume. Use MemoryStorage for single-process tests or implement the DeferredTaskStorage atomic contract."
       );
     }
     if (config.deferredStorage && typeof config.deferredStorage.takeIfVersion !== "function") {
-      throw new import_errors.ConfigurationError(
+      throw new import_errors2.ConfigurationError(
         "Deferred storage must implement atomic takeIfVersion() cleanup so stale owners cannot delete newer state. Use MemoryStorage for single-process tests or implement the DeferredTaskStorage atomic contract."
       );
     }
@@ -695,22 +693,6 @@ class TaskExecutor {
     }
     (0, import_client_hooks.validateOutgoingRequest)(taskName, params, this.requestValidationMode, debugLogs, this.config.adcpVersion);
   }
-  /**
-   * After `adaptRequestForServerVersion` has rewritten a v3 request into v2
-   * wire format, validate the adapted shape against the cached v2.5 schema
-   * bundle. Always warn-only — adapter bugs shouldn't break user requests,
-   * and the v3 pre-send pass already vouched for the user-facing input.
-   * This pass exists to surface drift between what the adapter emits and
-   * what a v2.5 server expects on the wire (primarily as CI signal via the
-   * adapter-conformance test suite).
-   *
-   * Skips silently for tasks without a v2.5 schema or when the v2.5 bundle
-   * isn't cached. Caller is responsible for gating on `serverVersion === 'v2'`
-   * so v3-targeted traffic doesn't pay the validation cost.
-   */
-  validateAdaptedRequestAgainstV2(taskName, adaptedParams, debugLogs) {
-    (0, import_client_hooks.validateOutgoingRequest)(taskName, adaptedParams, "warn", debugLogs, "v2.5");
-  }
   /**
    * Generate webhook URL for protocol-level webhook support
    */
@@ -762,7 +744,7 @@ class TaskExecutor {
   buildErrorInstance(taskId, adcpError) {
     if (!adcpError) return void 0;
     const key = this.activeTasks.get(taskId)?.idempotencyKey;
-    return (0, import_errors.adcpErrorToTypedError)(adcpError, key);
+    return (0, import_errors2.adcpErrorToTypedError)(adcpError, key);
   }
   generateWebhookUrl(taskName, operationId, options) {
     return (0, import_webhook_url.resolveWebhookUrl)(this.config.webhookUrlTemplate, this.config.agentId, taskName, operationId, options);
@@ -792,19 +774,20 @@ class TaskExecutor {
     );
   }
   async executeTaskWithinDeadline(agent, taskName, params, inputHandler, options = {}, serverVersion, targetCapabilities, beforeProtocolDispatch, deferredClientContext) {
+    if (serverVersion === "v2") throw new import_errors.VersionUnsupportedError(taskName, "version", "v2", agent.agent_uri);
     const effectiveServerVersion = serverVersion ?? "v3";
     this.lastKnownServerVersion = effectiveServerVersion;
     params = structuredClone(params);
     if (options.durableContinuationRecovery !== void 0) {
       assertDirectContinuationOwnerScope(options.durableContinuationRecovery.ownerScope);
       if (agent.protocol !== "a2a") {
-        throw new import_errors.ConfigurationError("durableContinuationRecovery is supported only for resumable A2A mutations.");
+        throw new import_errors2.ConfigurationError("durableContinuationRecovery is supported only for resumable A2A mutations.");
       }
       if (!(0, import_idempotency.requestUsesIdempotency)(taskName, params)) {
-        throw new import_errors.ConfigurationError("durableContinuationRecovery is supported only for mutating AdCP requests.");
+        throw new import_errors2.ConfigurationError("durableContinuationRecovery is supported only for mutating AdCP requests.");
       }
       if (!this.config.deferredStorage) {
-        throw new import_errors.ConfigurationError("durableContinuationRecovery requires deferredStorage.");
+        throw new import_errors2.ConfigurationError("durableContinuationRecovery requires deferredStorage.");
       }
       this.requireDeferredSettlementOperationRouting(this.config.deferredStorage, true);
     }
@@ -815,7 +798,7 @@ class TaskExecutor {
     const versionEnvelope = options.versionEnvelope ?? this.config.versionEnvelope;
     const idempotencyKey = options.skipIdempotencyAutoInject || options.preserveGovernedPayload ? void 0 : resolveIdempotencyKey(taskName, params, serverVersion);
     if (idempotencyKey) (0, import_task_deadline.attachTaskDeadlineIdempotencyKey)(options, idempotencyKey);
-    if (serverVersion !== "v2" && idempotencyKey && params && typeof params === "object" && !params.idempotency_key) {
+    if (idempotencyKey && params && typeof params === "object" && !params.idempotency_key) {
       params = { ...params, idempotency_key: idempotencyKey };
     }
     const taskState = {
@@ -2270,7 +2253,7 @@ class TaskExecutor {
           }
         });
       } catch (err) {
-        if ((0, import_errors.is401Error)(err)) throw err;
+        if ((0, import_errors2.is401Error)(err)) throw err;
       }
     }
     const response = await import_protocols.ProtocolClient.callTool(
@@ -2581,7 +2564,7 @@ class TaskExecutor {
   }
   requireDeferredSettlementOperationRouting(storage, direct = false) {
     if (typeof storage.putForSettlementOperationIfAbsent !== "function" || typeof storage.getBySettlementOperationId !== "function" || typeof storage.replaceForSettlementOperationIfVersion !== "function") {
-      throw new import_errors.ConfigurationError(
+      throw new import_errors2.ConfigurationError(
         direct ? "durableContinuationRecovery requires atomic DeferredTaskStorage operation routing. Use MemoryStorage or implement putForSettlementOperationIfAbsent(), getBySettlementOperationId(), and replaceForSettlementOperationIfVersion()." : "Committed deferred settlement requires atomic operation routing so paused mutations remain discoverable across crashes. Use MemoryStorage or implement the DeferredTaskStorage operation-route contract."
       );
     }
@@ -2643,7 +2626,7 @@ class TaskExecutor {
   /** Recover an opt-in direct continuation through its secret operation capability. */
   async recoverDirectPauseContinuation(request, publishTerminalTaskStatus = true) {
     const storage = this.config.deferredStorage;
-    if (!storage) throw new import_errors.ConfigurationError("Direct continuation recovery requires deferredStorage.");
+    if (!storage) throw new import_errors2.ConfigurationError("Direct continuation recovery requires deferredStorage.");
     this.requireDeferredSettlementOperationRouting(storage, true);
     const operationId = typeof request?.operationId === "string" ? request.operationId : "";
     const recoveryKey = typeof request?.recoveryKey === "string" ? request.recoveryKey : "";
@@ -2873,6 +2856,9 @@ class TaskExecutor {
     if (!state) {
       throw new Error("Deferred task not found.");
     }
+    if (state.serverVersion === "v2") {
+      throw new import_errors.VersionUnsupportedError(state.taskName, "version", "v2");
+    }
     if (state.expiresAt <= Date.now()) {
       throw new Error("Deferred task expired.");
     }
@@ -4428,10 +4414,9 @@ class TaskExecutor {
   /**
    * Normalize response data for schema validation
    *
-   * Converts v2-style responses to v3 format before validation.
-   * This ensures validation passes for both v2 and v3 server responses.
+   * Normalizes established AdCP 3 product fields before validation.
    */
-  normalizeResponseForValidation(response, taskName, legacyWire = false) {
+  normalizeResponseForValidation(response, taskName) {
     if (!response) return response;
     const stripped = {};
     if (typeof response === "object" && !Array.isArray(response)) {
@@ -4439,9 +4424,8 @@ class TaskExecutor {
         if (!k.startsWith("_")) stripped[k] = v;
       }
     } else {
-      return taskName === "get_products" && !legacyWire ? (0, import_pricing_adapter.normalizeGetProductsResponse)(response) : response;
+      return taskName === "get_products" ? (0, import_pricing_adapter.normalizeGetProductsResponse)(response) : response;
     }
-    if (legacyWire) return stripped;
     switch (taskName) {
       case "get_products":
         return (0, import_pricing_adapter.normalizeGetProductsResponse)(stripped);
@@ -4459,8 +4443,8 @@ class TaskExecutor {
     const mode = this.responseValidationMode;
     const logViolations = this.config.logSchemaViolations !== false;
     try {
-      const pinnedValidationVersion = (serverVersion ?? this.lastKnownServerVersion) === "v2" ? "v2.5" : this.responseAdcpVersionForValidation() ?? this.config.adcpVersion ?? import_version.ADCP_VERSION;
-      if (taskName === "get_adcp_capabilities" && pinnedValidationVersion !== "v2.5") {
+      const pinnedValidationVersion = this.responseAdcpVersionForValidation() ?? this.config.adcpVersion ?? import_version.ADCP_VERSION;
+      if (taskName === "get_adcp_capabilities") {
         return (0, import_schema_loader.withServedValidationVersion)(
           response,
           pinnedValidationVersion,
@@ -4485,7 +4469,7 @@ class TaskExecutor {
     }
   }
   validateResponseSchemaAgainst(response, taskName, debugLogs, mode, logViolations, validationVersion) {
-    const normalizedResponse = this.normalizeResponseForValidation(response, taskName, validationVersion === "v2.5");
+    const normalizedResponse = this.normalizeResponseForValidation(response, taskName);
     const outcome = (this.config.experimentalIdentity33?.() || this.config.identity33SchemaExperiment && normalizedResponse && typeof normalizedResponse === "object" && (0, import_adcp_version_config.isAdcpVersionAtLeast)(normalizedResponse.adcp_version, "3.3")) && mode !== "off" ? validateIdentity33Payload(taskName, "response", normalizedResponse, validationVersion) : (0, import_client_hooks.validateIncomingResponse)(taskName, normalizedResponse, mode, void 0, validationVersion);
     if (outcome.valid) return { valid: true, errors: [] };
     const errorStrings = outcome.issues.map((i) => `${i.pointer}: ${i.message}`);
@@ -4522,7 +4506,6 @@ class TaskExecutor {
     return void 0;
   }
   effectiveResponseAdcpVersion(serverVersion) {
-    if ((serverVersion ?? this.lastKnownServerVersion) === "v2") return "v2.5";
     return this.responseAdcpVersionForValidation() ?? this.config.adcpVersion ?? import_version.ADCP_VERSION;
   }
   /**

package/dist/lib/core/TaskExecutor.mjs

@@ -3,6 +3,7 @@ import { dirname as __adcpDirname } from "node:path";
 import { createRequire as __adcpCreateRequire } from "node:module";
 const __dirname = __adcpDirname(__adcpFileURLToPath(import.meta.url));
 const require2 = __adcpCreateRequire(import.meta.url);
+import { VersionUnsupportedError } from "../errors/index.mjs";
 import { deliveryWebhookRegistrationId } from "./webhook-registration.mjs";
 import { isAdcpVersionAtLeast } from "../utils/adcp-version-config.mjs";
 function validateIdentity33Payload(...args) {
@@ -332,9 +333,6 @@ function parseTimestamp(value) {
 function resolveIdempotencyKey(taskName, params, serverVersion) {
   const callerSupplied = params && typeof params === "object" && typeof params.idempotency_key === "string" ? params.idempotency_key : void 0;
   if (callerSupplied) return callerSupplied;
-  if (serverVersion === "v2") {
-    return params && typeof params === "object" && typeof params.buyer_ref === "string" ? params.buyer_ref : void 0;
-  }
   if (requestUsesIdempotency(taskName, params)) return generateIdempotencyKey();
   return void 0;
 }
@@ -673,22 +671,6 @@ class TaskExecutor {
     }
     validateOutgoingRequest(taskName, params, this.requestValidationMode, debugLogs, this.config.adcpVersion);
   }
-  /**
-   * After `adaptRequestForServerVersion` has rewritten a v3 request into v2
-   * wire format, validate the adapted shape against the cached v2.5 schema
-   * bundle. Always warn-only — adapter bugs shouldn't break user requests,
-   * and the v3 pre-send pass already vouched for the user-facing input.
-   * This pass exists to surface drift between what the adapter emits and
-   * what a v2.5 server expects on the wire (primarily as CI signal via the
-   * adapter-conformance test suite).
-   *
-   * Skips silently for tasks without a v2.5 schema or when the v2.5 bundle
-   * isn't cached. Caller is responsible for gating on `serverVersion === 'v2'`
-   * so v3-targeted traffic doesn't pay the validation cost.
-   */
-  validateAdaptedRequestAgainstV2(taskName, adaptedParams, debugLogs) {
-    validateOutgoingRequest(taskName, adaptedParams, "warn", debugLogs, "v2.5");
-  }
   /**
    * Generate webhook URL for protocol-level webhook support
    */
@@ -770,6 +752,7 @@ class TaskExecutor {
     );
   }
   async executeTaskWithinDeadline(agent, taskName, params, inputHandler, options = {}, serverVersion, targetCapabilities, beforeProtocolDispatch, deferredClientContext) {
+    if (serverVersion === "v2") throw new VersionUnsupportedError(taskName, "version", "v2", agent.agent_uri);
     const effectiveServerVersion = serverVersion ?? "v3";
     this.lastKnownServerVersion = effectiveServerVersion;
     params = structuredClone(params);
@@ -793,7 +776,7 @@ class TaskExecutor {
     const versionEnvelope = options.versionEnvelope ?? this.config.versionEnvelope;
     const idempotencyKey = options.skipIdempotencyAutoInject || options.preserveGovernedPayload ? void 0 : resolveIdempotencyKey(taskName, params, serverVersion);
     if (idempotencyKey) attachTaskDeadlineIdempotencyKey(options, idempotencyKey);
-    if (serverVersion !== "v2" && idempotencyKey && params && typeof params === "object" && !params.idempotency_key) {
+    if (idempotencyKey && params && typeof params === "object" && !params.idempotency_key) {
       params = { ...params, idempotency_key: idempotencyKey };
     }
     const taskState = {
@@ -2851,6 +2834,9 @@ class TaskExecutor {
     if (!state) {
       throw new Error("Deferred task not found.");
     }
+    if (state.serverVersion === "v2") {
+      throw new VersionUnsupportedError(state.taskName, "version", "v2");
+    }
     if (state.expiresAt <= Date.now()) {
       throw new Error("Deferred task expired.");
     }
@@ -4406,10 +4392,9 @@ class TaskExecutor {
   /**
    * Normalize response data for schema validation
    *
-   * Converts v2-style responses to v3 format before validation.
-   * This ensures validation passes for both v2 and v3 server responses.
+   * Normalizes established AdCP 3 product fields before validation.
    */
-  normalizeResponseForValidation(response, taskName, legacyWire = false) {
+  normalizeResponseForValidation(response, taskName) {
     if (!response) return response;
     const stripped = {};
     if (typeof response === "object" && !Array.isArray(response)) {
@@ -4417,9 +4402,8 @@ class TaskExecutor {
         if (!k.startsWith("_")) stripped[k] = v;
       }
     } else {
-      return taskName === "get_products" && !legacyWire ? normalizeGetProductsResponse(response) : response;
+      return taskName === "get_products" ? normalizeGetProductsResponse(response) : response;
     }
-    if (legacyWire) return stripped;
     switch (taskName) {
       case "get_products":
         return normalizeGetProductsResponse(stripped);
@@ -4437,8 +4421,8 @@ class TaskExecutor {
     const mode = this.responseValidationMode;
     const logViolations = this.config.logSchemaViolations !== false;
     try {
-      const pinnedValidationVersion = (serverVersion ?? this.lastKnownServerVersion) === "v2" ? "v2.5" : this.responseAdcpVersionForValidation() ?? this.config.adcpVersion ?? ADCP_VERSION;
-      if (taskName === "get_adcp_capabilities" && pinnedValidationVersion !== "v2.5") {
+      const pinnedValidationVersion = this.responseAdcpVersionForValidation() ?? this.config.adcpVersion ?? ADCP_VERSION;
+      if (taskName === "get_adcp_capabilities") {
         return withServedValidationVersion(
           response,
           pinnedValidationVersion,
@@ -4463,7 +4447,7 @@ class TaskExecutor {
     }
   }
   validateResponseSchemaAgainst(response, taskName, debugLogs, mode, logViolations, validationVersion) {
-    const normalizedResponse = this.normalizeResponseForValidation(response, taskName, validationVersion === "v2.5");
+    const normalizedResponse = this.normalizeResponseForValidation(response, taskName);
     const outcome = (this.config.experimentalIdentity33?.() || this.config.identity33SchemaExperiment && normalizedResponse && typeof normalizedResponse === "object" && isAdcpVersionAtLeast(normalizedResponse.adcp_version, "3.3")) && mode !== "off" ? validateIdentity33Payload(taskName, "response", normalizedResponse, validationVersion) : validateIncomingResponse(taskName, normalizedResponse, mode, void 0, validationVersion);
     if (outcome.valid) return { valid: true, errors: [] };
     const errorStrings = outcome.issues.map((i) => `${i.pointer}: ${i.message}`);
@@ -4500,7 +4484,6 @@ class TaskExecutor {
     return void 0;
   }
   effectiveResponseAdcpVersion(serverVersion) {
-    if ((serverVersion ?? this.lastKnownServerVersion) === "v2") return "v2.5";
     return this.responseAdcpVersionForValidation() ?? this.config.adcpVersion ?? ADCP_VERSION;
   }
   /**

package/dist/lib/core/product-cache.d.mts

@@ -12,7 +12,9 @@ export declare class ProductCache {
     private key;
     read<T>(scope: string, params: Record<string, unknown>, allowExpired?: boolean): TaskResult<T> | undefined;
     conditionalParams(scope: string, params: Record<string, unknown>): Record<string, unknown>;
-    write<T>(scope: string, params: Record<string, unknown>, result: TaskResult<T>, conditionalSnapshot?: TaskResult<T>): TaskResult<T>;
+    write<T>(scope: string, params: Record<string, unknown>, result: TaskResult<T>, conditionalSnapshot?: TaskResult<T>, 
+    /** @internal Refresh private discovery evidence before a confirmed snapshot is cloned into storage. */
+    onRevalidated?: (materialized: TaskResult<T>) => void): TaskResult<T>;
     clear(): void;
 }
 export declare function createProductCache(options?: ProductCacheOptions): ProductCache;

package/dist/lib/core/product-cache.d.ts

@@ -12,7 +12,9 @@ export declare class ProductCache {
     private key;
     read<T>(scope: string, params: Record<string, unknown>, allowExpired?: boolean): TaskResult<T> | undefined;
     conditionalParams(scope: string, params: Record<string, unknown>): Record<string, unknown>;
-    write<T>(scope: string, params: Record<string, unknown>, result: TaskResult<T>, conditionalSnapshot?: TaskResult<T>): TaskResult<T>;
+    write<T>(scope: string, params: Record<string, unknown>, result: TaskResult<T>, conditionalSnapshot?: TaskResult<T>, 
+    /** @internal Refresh private discovery evidence before a confirmed snapshot is cloned into storage. */
+    onRevalidated?: (materialized: TaskResult<T>) => void): TaskResult<T>;
     clear(): void;
 }
 export declare function createProductCache(options?: ProductCacheOptions): ProductCache;

package/dist/lib/core/product-cache.js

@@ -86,7 +86,7 @@ class ProductCache {
       ...typeof data.pricing_version === "string" && { if_pricing_version: data.pricing_version }
     };
   }
-  write(scope, params, result, conditionalSnapshot) {
+  write(scope, params, result, conditionalSnapshot, onRevalidated) {
     const key = this.key(scope, params);
     if (!key) return result;
     if (!result.success || result.status !== "completed" || !result.data || typeof result.data !== "object")
@@ -109,6 +109,7 @@ class ProductCache {
         return result;
       if (params.if_wholesale_feed_version !== void 0 || params.if_pricing_version !== void 0) return result;
       completed = { ...result, data: (0, import_legacy_metadata.structuredCloneWithLegacyCreativeMetadata)(oldData) };
+      onRevalidated?.(completed);
     } else if (!Array.isArray(data.products)) return result;
     if (!this.entries.has(key) && this.entries.size >= (this.options.maxEntries ?? 1e3))
       this.entries.delete(this.entries.keys().next().value);

package/dist/lib/core/product-cache.mjs

@@ -62,7 +62,7 @@ class ProductCache {
       ...typeof data.pricing_version === "string" && { if_pricing_version: data.pricing_version }
     };
   }
-  write(scope, params, result, conditionalSnapshot) {
+  write(scope, params, result, conditionalSnapshot, onRevalidated) {
     const key = this.key(scope, params);
     if (!key) return result;
     if (!result.success || result.status !== "completed" || !result.data || typeof result.data !== "object")
@@ -85,6 +85,7 @@ class ProductCache {
         return result;
       if (params.if_wholesale_feed_version !== void 0 || params.if_pricing_version !== void 0) return result;
       completed = { ...result, data: structuredCloneWithLegacyCreativeMetadata(oldData) };
+      onRevalidated?.(completed);
     } else if (!Array.isArray(data.products)) return result;
     if (!this.entries.has(key) && this.entries.size >= (this.options.maxEntries ?? 1e3))
       this.entries.delete(this.entries.keys().next().value);

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

@@ -471,15 +471,9 @@ export type ActionNotAllowedRecovery = {
  * - `version`: seller's `major_versions` does not include 3
  * - `idempotency`: seller reports v3 but omits the required
  *   `adcp.idempotency.replay_ttl_seconds` declaration
- * - `synthetic`: @deprecated — kept in the union for downstream
- *   consumers that pattern-match on the union literal, but the SDK no
- *   longer emits it. Sellers whose capabilities are synthesized from
- *   `tools/list` are routed through the v2 adapter with a one-time
- *   warning; gate retry behavior on `SingleAgentClient.isSyntheticV2()`.
+ * - `synthetic`: agent lacks the required AdCP 3 discovery tool.
  */
-export type VersionUnsupportedReason = 'version' | 'idempotency'
-/** @deprecated SDK no longer emits this reason. See union JSDoc. */
- | 'synthetic';
+export type VersionUnsupportedReason = 'version' | 'idempotency' | 'synthetic';
 /**
  * Error thrown when a mutating call would dispatch to a seller whose
  * capabilities cannot be corroborated as v3. Provides an explicit

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

@@ -471,15 +471,9 @@ export type ActionNotAllowedRecovery = {
  * - `version`: seller's `major_versions` does not include 3
  * - `idempotency`: seller reports v3 but omits the required
  *   `adcp.idempotency.replay_ttl_seconds` declaration
- * - `synthetic`: @deprecated — kept in the union for downstream
- *   consumers that pattern-match on the union literal, but the SDK no
- *   longer emits it. Sellers whose capabilities are synthesized from
- *   `tools/list` are routed through the v2 adapter with a one-time
- *   warning; gate retry behavior on `SingleAgentClient.isSyntheticV2()`.
+ * - `synthetic`: agent lacks the required AdCP 3 discovery tool.
  */
-export type VersionUnsupportedReason = 'version' | 'idempotency'
-/** @deprecated SDK no longer emits this reason. See union JSDoc. */
- | 'synthetic';
+export type VersionUnsupportedReason = 'version' | 'idempotency' | 'synthetic';
 /**
  * Error thrown when a mutating call would dispatch to a seller whose
  * capabilities cannot be corroborated as v3. Provides an explicit

package/dist/lib/errors/index.js

@@ -535,7 +535,7 @@ function buildModeMismatchRecovery(details) {
 class VersionUnsupportedError extends ADCPError {
   constructor(taskType, reason, actualVersion, agentUrl) {
     super(
-      `Refusing to dispatch mutating task '${taskType}': ` + VersionUnsupportedError.explain(reason, actualVersion) + ` Pass allowV2: true or requireV3ForMutations: false to override.`
+      (taskType === "get_adcp_capabilities" ? "Cannot discover supported AdCP capabilities: " : `Refusing to dispatch task '${taskType}': `) + VersionUnsupportedError.explain(reason, actualVersion)
     );
     this.taskType = taskType;
     this.reason = reason;
@@ -550,11 +550,11 @@ class VersionUnsupportedError extends ADCPError {
   static explain(reason, actualVersion) {
     switch (reason) {
       case "version":
-        return `seller advertises major version '${actualVersion}' but v3 is required.`;
+        return actualVersion === "v2" ? "AdCP 2 reached end of life on 2026-08-01. Upgrade the agent to AdCP 3. Migration and older SDK pins: https://github.com/adcontextprotocol/adcp-client/blob/main/docs/migration-drop-adcp-2.md" : `seller does not support the configured AdCP 3 release.`;
       case "idempotency":
-        return `seller reports v3 but omits adcp.idempotency.replay_ttl_seconds (required by spec).`;
+        return "seller reports v3 but omits adcp.idempotency.replay_ttl_seconds (required by spec). Upgrade the agent to publish its replay guarantee. If your application does not require this guarantee, configure requireV3ForMutations: false.";
       case "synthetic":
-        return `capabilities were synthesized from a tool list, v3 claim is unverifiable.`;
+        return "The agent does not advertise get_adcp_capabilities. AdCP 3 capability discovery is required; AdCP 2 compatibility has been removed.";
     }
   }
 }

package/dist/lib/errors/index.mjs

@@ -475,7 +475,7 @@ function buildModeMismatchRecovery(details) {
 class VersionUnsupportedError extends ADCPError {
   constructor(taskType, reason, actualVersion, agentUrl) {
     super(
-      `Refusing to dispatch mutating task '${taskType}': ` + VersionUnsupportedError.explain(reason, actualVersion) + ` Pass allowV2: true or requireV3ForMutations: false to override.`
+      (taskType === "get_adcp_capabilities" ? "Cannot discover supported AdCP capabilities: " : `Refusing to dispatch task '${taskType}': `) + VersionUnsupportedError.explain(reason, actualVersion)
     );
     this.taskType = taskType;
     this.reason = reason;
@@ -490,11 +490,11 @@ class VersionUnsupportedError extends ADCPError {
   static explain(reason, actualVersion) {
     switch (reason) {
       case "version":
-        return `seller advertises major version '${actualVersion}' but v3 is required.`;
+        return actualVersion === "v2" ? "AdCP 2 reached end of life on 2026-08-01. Upgrade the agent to AdCP 3. Migration and older SDK pins: https://github.com/adcontextprotocol/adcp-client/blob/main/docs/migration-drop-adcp-2.md" : `seller does not support the configured AdCP 3 release.`;
       case "idempotency":
-        return `seller reports v3 but omits adcp.idempotency.replay_ttl_seconds (required by spec).`;
+        return "seller reports v3 but omits adcp.idempotency.replay_ttl_seconds (required by spec). Upgrade the agent to publish its replay guarantee. If your application does not require this guarantee, configure requireV3ForMutations: false.";
       case "synthetic":
-        return `capabilities were synthesized from a tool list, v3 claim is unverifiable.`;
+        return "The agent does not advertise get_adcp_capabilities. AdCP 3 capability discovery is required; AdCP 2 compatibility has been removed.";
     }
   }
 }