@adcp/sdk 16.0.0-beta.7 → 16.0.0-beta.9

package/dist/lib/core/SingleAgentClient.mjs

@@ -3,6 +3,9 @@ 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 { normalizeGetProductsResponse } from "../utils/pricing-adapter.mjs";
+import { normalizeMediaBuyResponse } from "../utils/creative-adapter.mjs";
+import { normalizeFormatsResponse } from "../utils/format-renders.mjs";
 import {
   isIdentity33SchemaScope,
   withIdentity33SchemaScope,
@@ -131,7 +134,6 @@ import {
   validateAgentDiscoveryCacheConfig
 } from "./agent-discovery-cache.mjs";
 import {
-  buildSyntheticCapabilities,
   buildSyntheticV3Capabilities,
   augmentCapabilitiesFromTools,
   looksLikeV3Capabilities,
@@ -160,15 +162,17 @@ import { normalizeRequestParams } from "../utils/request-normalizer.mjs";
 import { globalAsyncLocalStorage } from "../utils/global-async-local-storage.mjs";
 import { validateUserAgent } from "../utils/validate-user-agent.mjs";
 import { resolveWebhookUrl, selectWebhookTemplate } from "./webhook-url.mjs";
-import { getV25Adapter } from "../adapters/legacy/v2-5/index.mjs";
 import {
   ProductPropertyPolicyError,
-  validateProductsAgainstPropertyPolicy
+  validateProductsAgainstPropertyPolicy,
+  isSupportedPropertyIdentifierType,
+  normalizeDomainForPropertyPolicy
 } from "../media-buy/property-policy.mjs";
 import { resolvePropertyList } from "../server/targeting-helpers.mjs";
 import {
   CreativeFormatCapabilityError,
   CreativeFormatProjectionError,
+  canUseProductOptionsForCreativeWire,
   projectMediaBuyCreativesForDelivery,
   projectCreativeForDelivery,
   projectSyncCreativesForDelivery,
@@ -188,6 +192,10 @@ import {
 import { toCanonicalOnlyResponse } from "../v2/projection/augment-response.mjs";
 import {
   legacyFormatRefsForDeclaration,
+  isSynthesizedFormatOption,
+  selectedFormatOptions,
+  rememberSellerFormatEvidence,
+  sellerFormatEvidence,
   rememberSellerDeclaredFormatOption,
   sellerDeclaredFormatOption,
   structuredCloneWithLegacyCreativeMetadata
@@ -311,6 +319,56 @@ const RECORDLESS_HMAC_READ_ONLY_TASKS = /* @__PURE__ */ new Set([
 ]);
 const TASK_SCOPED_STATE_LIMIT = 1e4;
 const WEBHOOK_JWKS_RESOLVER_LIMIT = 1024;
+function creativeMatchesProductOption(creative, declaration) {
+  const params = isPlainRecord(declaration.params) ? declaration.params : {};
+  const assets = isPlainRecord(creative.assets) ? creative.assets : {};
+  const slots = Array.isArray(params.slots) ? params.slots : [];
+  if (!slots.every((slot) => {
+    if (!isPlainRecord(slot) || typeof slot.asset_group_id !== "string") return false;
+    const value = assets[slot.asset_group_id];
+    const entries = value === void 0 ? [] : Array.isArray(value) ? value : [value];
+    const minimum = Math.max(typeof slot.min === "number" ? slot.min : 0, slot.required === true ? 1 : 0);
+    if (entries.length < minimum || typeof slot.max === "number" && entries.length > slot.max) return false;
+    return entries.every(
+      (asset) => isPlainRecord(asset) && (typeof slot.asset_type !== "string" || asset.asset_type === slot.asset_type)
+    );
+  }))
+    return false;
+  const formatParams = isPlainRecord(creative.format_parameters) ? creative.format_parameters : {};
+  const kind = String(creative.format_kind);
+  const mediaType = kind.startsWith("image") ? "image" : kind.startsWith("video") ? "video" : kind.startsWith("audio") ? "audio" : kind === "html5" ? "html" : void 0;
+  const assetTypes = mediaType === "video" ? ["video", "vast"] : mediaType === "audio" ? ["audio", "vast", "daast"] : mediaType === "html" ? ["html", "zip"] : mediaType ? [mediaType] : ["image", "video", "audio", "html", "zip", "vast", "daast"];
+  const requiredMediaSlots = slots.filter(
+    (slot) => isPlainRecord(slot) && (slot.required === true || typeof slot.min === "number" && slot.min > 0) && assetTypes.includes(String(slot.asset_type))
+  );
+  const preferredGroups = mediaType ? [`${mediaType}_main`, mediaType, kind, ...assetTypes] : [];
+  const primaryGroup = (requiredMediaSlots.length === 1 ? String(requiredMediaSlots[0].asset_group_id) : void 0) ?? preferredGroups.find((group) => assets[group] !== void 0);
+  const sourceAssets = primaryGroup ? [assets[primaryGroup]] : Object.values(assets);
+  const dimensionalAssets = sourceAssets.flatMap((value) => Array.isArray(value) ? value : [value]).filter(
+    (value) => isPlainRecord(value) && assetTypes.includes(String(value.asset_type))
+  );
+  return (dimensionalAssets.length > 0 ? dimensionalAssets : [{}]).every((asset) => {
+    const actual = { ...asset, ...formatParams };
+    for (const key of ["width", "height"]) {
+      if (typeof params[key] === "number" && actual[key] !== params[key]) return false;
+      const min = params[`min_${key}`];
+      const max = params[`max_${key}`];
+      if (typeof min === "number" && (typeof actual[key] !== "number" || actual[key] < min)) return false;
+      if (typeof max === "number" && (typeof actual[key] !== "number" || actual[key] > max)) return false;
+    }
+    if (Array.isArray(params.sizes) && !params.sizes.some((size) => isPlainRecord(size) && size.width === actual.width && size.height === actual.height))
+      return false;
+    const duration = actual.duration_ms ?? actual.duration_ms_exact;
+    const exact = params.duration_ms_exact ?? params.duration_ms;
+    if (typeof exact === "number" && duration !== exact) return false;
+    if (typeof exact !== "number" && Array.isArray(params.duration_ms_range)) {
+      const [min, max] = params.duration_ms_range;
+      if (typeof duration !== "number" || typeof min === "number" && duration < min || typeof max === "number" && duration > max)
+        return false;
+    }
+    return true;
+  });
+}
 function isDeferredClientFinalizationContext(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
   const context = value;
@@ -757,24 +815,7 @@ function isToolSchemaRecord(value) {
 function isCapabilityEvidence(value) {
   if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
   const candidate = value;
-  return (candidate.version === "v2" || candidate.version === "v3") && Array.isArray(candidate.majorVersions) && candidate.majorVersions.length > 0 && candidate.majorVersions.every((version) => version === 2 || version === 3) && Array.isArray(candidate.protocols) && candidate.protocols.every((protocol) => typeof protocol === "string") && typeof candidate.features === "object" && candidate.features !== null && !Array.isArray(candidate.features) && Array.isArray(candidate.extensions) && candidate.extensions.every((extension) => typeof extension === "string") && typeof candidate._synthetic === "boolean";
-}
-function valueMatchesSchemaType(value, propSchema) {
-  if (!propSchema || typeof propSchema !== "object") return false;
-  const schema = propSchema;
-  if (schema.$ref) return true;
-  const valueType = Array.isArray(value) ? "array" : value === null ? "null" : typeof value === "object" ? "object" : typeof value;
-  for (const key of ["anyOf", "oneOf"]) {
-    const variants = schema[key];
-    if (Array.isArray(variants)) {
-      return variants.some((v) => valueMatchesSchemaType(value, v));
-    }
-  }
-  const declared = schema.type;
-  if (declared === void 0) return false;
-  if (typeof declared === "string") return declared === valueType;
-  if (Array.isArray(declared)) return declared.includes(valueType);
-  return false;
+  return candidate.version === "v3" && Array.isArray(candidate.majorVersions) && candidate.majorVersions.includes(3) && candidate.majorVersions.every((version) => Number.isSafeInteger(version) && version > 0) && Array.isArray(candidate.protocols) && candidate.protocols.every((protocol) => typeof protocol === "string") && typeof candidate.features === "object" && candidate.features !== null && !Array.isArray(candidate.features) && Array.isArray(candidate.extensions) && candidate.extensions.every((extension) => typeof extension === "string") && typeof candidate._synthetic === "boolean";
 }
 function productHasPricingOptions(product) {
   if (!product || typeof product !== "object") return false;
@@ -787,7 +828,9 @@ function productIdForPricingDiagnostics(product) {
   return typeof id === "string" ? id : void 0;
 }
 function propertyListReferenceFromRequest(params) {
-  const value = params.property_list;
+  const filters = params.filters;
+  const nested = filters && typeof filters === "object" && !Array.isArray(filters) && Object.hasOwn(filters, "property_list") && filters.property_list !== void 0;
+  const value = nested ? filters.property_list : params.property_list;
   if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
   const ref = value;
   if (typeof ref.agent_url !== "string" || typeof ref.list_id !== "string") return void 0;
@@ -800,21 +843,37 @@ function propertyListReferenceFromRequest(params) {
 function productPolicyRequestSnapshot(requestParams) {
   const account = canonicalAccountRoutingSnapshot(requestParams.account);
   const propertyList = propertyListReferenceFromRequest(requestParams);
+  const referenceError = propertyListReferenceError(requestParams);
   return Object.freeze({
     ...account ? { account } : {},
-    ...propertyList ? { property_list: Object.freeze(propertyList) } : {}
+    ...propertyList ? { property_list: Object.freeze(propertyList) } : {},
+    ...referenceError ? { property_list_error: referenceError } : {}
   });
 }
+function propertyListReferenceError(params) {
+  if (typeof params.property_list_error === "string") return params.property_list_error;
+  const filters = params.filters;
+  if (params.property_list !== void 0 && !propertyListReferenceFromRequest({ property_list: params.property_list }))
+    return "property_list_invalid_reference";
+  if (!filters || typeof filters !== "object" || Array.isArray(filters) || !Object.hasOwn(filters, "property_list") || filters.property_list === void 0)
+    return void 0;
+  const nested = propertyListReferenceFromRequest(params);
+  if (!nested) return "property_list_invalid_reference";
+  if (params.property_list !== void 0) {
+    const legacy = propertyListReferenceFromRequest({ property_list: params.property_list });
+    if (!legacy || nested.agent_url !== legacy.agent_url || nested.list_id !== legacy.list_id || nested.auth_token !== legacy.auth_token) {
+      return "property_list_conflicting_references";
+    }
+  }
+  return void 0;
+}
 function hasProductPropertyPolicyRules(policy) {
   return Boolean(
     policy.allowedDomains?.length || policy.allowedPropertyIdentifiers?.length || policy.requireAllowedPropertyMatch || policy.excludedDomains?.length || policy.excludedPropertyIds?.length || policy.strict || policy.unknownSelectorBehavior || policy.missingPublisherPropertiesBehavior
   );
 }
-function comparablePropertyIdentifiers(identifiers) {
-  return identifiers.filter((identifier) => identifier.type === "domain" || identifier.type === "subdomain").map((identifier) => ({ type: identifier.type, value: identifier.value }));
-}
 function unsupportedPropertyIdentifiers(identifiers) {
-  return identifiers.filter((identifier) => identifier.type !== "domain" && identifier.type !== "subdomain").map((identifier) => ({ type: identifier.type }));
+  return identifiers.filter((identifier) => !isSupportedPropertyIdentifierType(identifier.type)).map((identifier) => ({ type: identifier.type }));
 }
 function sanitizeDiagnosticUrl(value) {
   try {
@@ -1198,12 +1257,8 @@ class SingleAgentClient {
   // shared invalidation epoch of that key when the evidence was obtained
   sharedEvidenceKey;
   // discoveryCache key the local capability cache was obtained under
-  _v2WarningFired = false;
-  // Gate: emit the v2-sunset warning once per client instance
   _syntheticV3WarningFired = false;
   // Gate: emit the synthetic-v3 warning once per client instance
-  _syntheticV2WarningFired = false;
-  // Gate: emit the synthetic-v2 warning once per client instance
   productPolicyRequestParamsByTask = /* @__PURE__ */ new Map();
   canonicalCreativeTaskAssociations = /* @__PURE__ */ new Map();
   previewCreativeHandlersByTask = /* @__PURE__ */ new Map();
@@ -1411,8 +1466,17 @@ class SingleAgentClient {
   }
   assertDurablePropertyListCredentialSupported(taskType, requestParams) {
     if (!this.config.deferredStorage || taskType !== "get_products") return;
-    const propertyList = propertyListReferenceFromRequest(requestParams);
-    if (!propertyList?.auth_token) return;
+    const filters = requestParams.filters;
+    const references = [
+      requestParams.property_list,
+      filters && typeof filters === "object" ? filters.property_list : void 0
+    ];
+    const hasCredential = references.some((reference) => {
+      if (!reference || typeof reference !== "object") return false;
+      const token = reference.auth_token;
+      return token !== void 0 && token !== null && token !== "";
+    });
+    if (!hasCredential) return;
     const policyConfig = this.config.validation?.productPropertyPolicy;
     if (policyConfig === false || policyConfig?.enforceRequestPropertyList === false) return;
     throw new ConfigurationError(
@@ -1465,7 +1529,7 @@ class SingleAgentClient {
       }
     }
   }
-  rememberCanonicalProductRoutes(products, account, authoritativeProducts) {
+  rememberCanonicalProductRoutes(products, account, authoritativeProducts, evidence) {
     this.invalidateCanonicalProductRoutes(authoritativeProducts ?? products, account);
     const accountScope = this.canonicalAccountScope(account);
     const declaredOptions = authoritativeProducts ? this.sellerDeclaredFormatOptions(authoritativeProducts) : void 0;
@@ -1485,12 +1549,15 @@ class SingleAgentClient {
         const refs = legacyFormatRefsForDeclaration(option);
         const declared = declaredOptions ? declaredOptions.get(product.product_id)?.some((declaredRef) => this.sameCanonicalOptionRef(declaredRef, ref)) : sellerDeclaredFormatOption(option);
         if (declared !== void 0) rememberSellerDeclaredFormatOption(option, declared);
+        if (declared === true && evidence)
+          rememberSellerFormatEvidence(option, { ...evidence, productId: product.product_id });
         this.rememberCanonicalLegacyRoute(this.canonicalLegacyRouteKey(account, product.product_id, ref), {
           kind: "product",
           accountScope,
           productId: product.product_id,
           optionRef: ref,
           refs,
+          ...declared === true && sellerFormatEvidence(option) ? { declaration: structuredCloneWithLegacyCreativeMetadata(option) } : {},
           ...declared === false ? { undeclaredSelector: undeclaredFormatOptionSelector(option) } : {}
         });
       }
@@ -3472,7 +3539,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
   /**
    * Execute task and call appropriate handler on completion
    *
-   * Automatically adapts requests for v2 servers and normalizes responses.
+   * Adapts requests for maintained AdCP 3 releases and normalizes product responses.
    */
   async executeAndHandle(taskType, handlerName, params, inputHandler, options, transformCompletedResponse, legacyFormatConverter, canonicalRequest, projectionCatalogs) {
     const requestParamsSnapshot = structuredClone(params);
@@ -3517,11 +3584,6 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       await this.requireSupportedMajor(taskType, options);
       throwIfAborted(options?.signal);
     }
-    const earlyResult = await this.getEarlyResultForUnsupportedFeatures(taskType, normalizedParams, options);
-    throwIfAborted(options?.signal);
-    if (earlyResult) {
-      return attachMatch(earlyResult);
-    }
     const agent = await this.ensureEndpointDiscovered(options);
     throwIfAborted(options?.signal);
     if (!options?.skipIdempotencyAutoInject && !options?.skipAccountValidation && !options?.skipRequestValidation && !options?.preserveGovernedPayload) {
@@ -3560,11 +3622,8 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       capabilityDiscoveryContext.toolSchemas,
       capabilityDiscoveryContext.capabilities
     );
-    const v25DriftLogs = [...adaptDriftLogs];
-    if (webhookDriftLog) v25DriftLogs.push(webhookDriftLog);
-    if (serverVersion === "v2") {
-      this.executor.validateAdaptedRequestAgainstV2(taskType, adaptedParams, v25DriftLogs);
-    }
+    const adaptationLogs = [...adaptDriftLogs];
+    if (webhookDriftLog) adaptationLogs.push(webhookDriftLog);
     const canonicalInputHandler = this.canonicalCreativeInputHandler(
       taskType,
       inputHandler,
@@ -3611,7 +3670,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     );
     throwIfAborted(effectiveOptions?.signal);
     if (!result.success) await this.invalidateDiscoveryOnCapabilityError(result.adcpError?.code, effectiveOptions);
-    const postAdapterLogs = [...inputSchemaStripLogs, ...v25DriftLogs];
+    const postAdapterLogs = [...inputSchemaStripLogs, ...adaptationLogs];
     if (postAdapterLogs.length > 0) {
       result.debug_logs = [...result.debug_logs ?? [], ...postAdapterLogs];
     }
@@ -3707,7 +3766,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     const rawSubmittedWaitForCompletion = result.submitted?.waitForCompletion;
     const finalizerLegacyFormatConverter = legacyFormatConverter ?? this.resolveLegacyFormatConverter(void 0, context.projectionCatalogs);
     if (result.success && result.data) {
-      result.data = this.normalizeResponseToV3(taskType, result.data);
+      result.data = this.normalizeEstablishedResponse(taskType, result.data);
     }
     result = this.wrapProductPolicySubmittedContinuation(
       result,
@@ -3853,7 +3912,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     };
   }
   projectCanonicalCreativeData(taskType, data, transform, legacyFormatConverter) {
-    let projected = this.normalizeResponseToV3(taskType, data);
+    let projected = this.normalizeEstablishedResponse(taskType, data);
     const record = projected && typeof projected === "object" ? projected : void 0;
     const canProjectRead = taskType === "get_products" ? Array.isArray(record?.products) : taskType === "list_creatives" ? Array.isArray(record?.creatives) : true;
     if (transform && canProjectRead) {
@@ -4223,39 +4282,40 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       message = "Property list not adhered to",
       enforceRequestPropertyList = true,
       propertyListResolveOptions,
+      resolvePublisherProperties,
+      maxPublisherLookups = 100,
+      publisherLookupTimeoutMs = 1e4,
+      publisherLookupBudgetMs = 1e4,
       ...explicitPolicy
     } = policyConfig || {};
     const policy = {
       ...explicitPolicy
     };
     let resolvedRequestPropertyList;
-    if (requestPropertyList && enforceRequestPropertyList) {
+    const referenceError = propertyListReferenceError(requestParams);
+    if ((requestPropertyList || referenceError) && enforceRequestPropertyList) {
       try {
+        if (referenceError) throw new Error(referenceError);
         const resolved = await resolvePropertyList(requestPropertyList, propertyListResolveOptions);
-        const comparableIdentifiers = comparablePropertyIdentifiers(resolved.identifiers);
         const unsupportedIdentifiers = unsupportedPropertyIdentifiers(resolved.identifiers);
-        if (unsupportedIdentifiers.length > 0) {
-          throw new Error("property_list_unsupported_identifier_types");
-        }
-        if (comparableIdentifiers.length > 0 || resolved.identifiers.length === 0) {
-          policy.allowedPropertyIdentifiers = [...policy.allowedPropertyIdentifiers ?? [], ...comparableIdentifiers];
-          policy.requireAllowedPropertyMatch = true;
-        }
+        policy.allowedPropertyIdentifiers = [...policy.allowedPropertyIdentifiers ?? [], ...resolved.identifiers];
+        policy.requireAllowedPropertyMatch = true;
         policy.strict = policy.strict ?? true;
         resolvedRequestPropertyList = {
           listId: resolved.listId,
           agentUrl: resolved.agentUrl,
           identifierCount: resolved.identifiers.length,
+          unsupportedIdentifierTypes: [...new Set(unsupportedIdentifiers.map((identifier) => identifier.type))],
           ...resolved.cacheValidUntil ? { cacheValidUntil: resolved.cacheValidUntil } : {}
         };
       } catch (err) {
         const errorCode = propertyListResolutionErrorCode(err);
-        const diagnosticAgentUrl = sanitizeDiagnosticUrl(requestPropertyList.agent_url);
+        const diagnosticAgentUrl = requestPropertyList ? sanitizeDiagnosticUrl(requestPropertyList.agent_url) : "invalid_url";
         return attachMatch({
           success: false,
           status: "failed",
           data: response,
-          error: `${message}: could not resolve property_list ${requestPropertyList.list_id}`,
+          error: `${message}: could not resolve property_list`,
           metadata: {
             ...result.metadata,
             status: "failed",
@@ -4268,7 +4328,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
               message,
               diagnostics: [],
               request_property_list: {
-                list_id: requestPropertyList.list_id,
+                list_id: requestPropertyList?.list_id ?? "invalid_reference",
                 agent_url: diagnosticAgentUrl,
                 resolution_error: errorCode
               }
@@ -4283,7 +4343,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
               mode,
               ok: false,
               request_property_list: {
-                list_id: requestPropertyList.list_id,
+                list_id: requestPropertyList?.list_id,
                 agent_url: diagnosticAgentUrl,
                 resolution_error: errorCode
               }
@@ -4293,6 +4353,65 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       }
     }
     if (!hasProductPropertyPolicyRules(policy)) return result;
+    if (resolvePublisherProperties && policy.allowedPropertyIdentifiers?.some(
+      (identifier) => identifier.type !== "domain" && identifier.type !== "subdomain"
+    )) {
+      if (!Number.isSafeInteger(maxPublisherLookups) || maxPublisherLookups < 1 || !Number.isSafeInteger(publisherLookupTimeoutMs) || publisherLookupTimeoutMs < 1 || publisherLookupTimeoutMs > 2147483647 || !Number.isSafeInteger(publisherLookupBudgetMs) || publisherLookupBudgetMs < 1 || publisherLookupBudgetMs > 2147483647) {
+        throw new ConfigurationError("Publisher lookup limits must be positive bounded integers");
+      }
+      const { validatePublisherDomain } = await import("../identifiers.mjs");
+      const catalogs = Object.assign(
+        /* @__PURE__ */ Object.create(null),
+        policy.publisherProperties
+      );
+      const domains = new Set(
+        response.products.flatMap(
+          (product) => Array.isArray(product.publisher_properties) ? product.publisher_properties.flatMap(
+            (selector) => selector && typeof selector === "object" && "publisher_domain" in selector ? [selector.publisher_domain] : []
+          ) : []
+        )
+      );
+      const hosts = [
+        ...new Set(
+          [...domains].flatMap(
+            (domain) => typeof domain === "string" ? [normalizeDomainForPropertyPolicy(domain)?.host] : []
+          )
+        )
+      ].filter((host) => typeof host === "string" && !Object.hasOwn(catalogs, host));
+      for (const host of hosts) catalogs[host] = void 0;
+      const lookupStartedAt = performance.now();
+      for (const host of hosts.slice(0, maxPublisherLookups)) {
+        throwIfAborted(taskSignal);
+        const remainingBudgetMs = publisherLookupBudgetMs - (performance.now() - lookupStartedAt);
+        if (remainingBudgetMs <= 0) break;
+        if (!validatePublisherDomain(host).ok || isLikelyPrivateUrl(`https://${host}`)) continue;
+        const controller = new AbortController();
+        const signal = taskSignal ? AbortSignal.any([taskSignal, controller.signal]) : controller.signal;
+        let timeout;
+        let budgetExpired = false;
+        try {
+          catalogs[host] = await Promise.race([
+            resolvePublisherProperties(host, { signal }),
+            new Promise((_, reject) => {
+              timeout = setTimeout(
+                () => {
+                  if (remainingBudgetMs <= publisherLookupTimeoutMs) budgetExpired = true;
+                  controller.abort();
+                  reject(new Error("publisher_catalog_timeout"));
+                },
+                Math.min(publisherLookupTimeoutMs, remainingBudgetMs)
+              );
+            })
+          ]);
+        } catch {
+          catalogs[host] = void 0;
+        } finally {
+          if (timeout) clearTimeout(timeout);
+        }
+        if (budgetExpired) break;
+      }
+      policy.publisherProperties = catalogs;
+    }
     let validation;
     try {
       validation = validateProductsAgainstPropertyPolicy({
@@ -4316,6 +4435,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
           list_id: resolvedRequestPropertyList.listId,
           agent_url: sanitizeDiagnosticUrl(resolvedRequestPropertyList.agentUrl),
           identifier_count: resolvedRequestPropertyList.identifierCount,
+          unsupported_identifier_types: resolvedRequestPropertyList.unsupportedIdentifierTypes,
           ...resolvedRequestPropertyList.cacheValidUntil ? { cache_valid_until: resolvedRequestPropertyList.cacheValidUntil } : {}
         }
       } : {},
@@ -4465,7 +4585,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       waitForCompletion: async (pollInterval, signal) => {
         let completed = await submitted.waitForCompletion(pollInterval, signal);
         if (completed.success && completed.data) {
-          completed.data = this.normalizeResponseToV3(taskType, completed.data);
+          completed.data = this.normalizeEstablishedResponse(taskType, completed.data);
         }
         const terminal = completed.status === "completed" || completed.status === "failed";
         try {
@@ -4496,7 +4616,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       attachMatch({
         success: true,
         status: "completed",
-        data: this.normalizeResponseToV3(taskType, taskInfo.result),
+        data: this.normalizeEstablishedResponse(taskType, taskInfo.result),
         metadata: {
           taskId: taskInfo.taskId,
           taskName: taskInfo.taskType,
@@ -4572,8 +4692,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
   }
   /**
    * Adapt a request for the detected server wire version and the seller's
-   * AdCP protocol version. Applies wire-format adapters (v2.5) when talking
-   * to a v2 server, then applies protocol-version adapters (e.g. stripping
+   * AdCP protocol version. Applies protocol-version adapters (e.g. stripping
    * 3.1-only fields for a 3.0 seller). Returns the adapted params and any
    * drift log entries describing what was changed.
    *
@@ -4581,22 +4700,14 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
    * current call's tool schemas can be supplied without cross-tenant caching.
    */
   adaptRequest(taskType, params, serverVersion, debugLogs, perCallToolSchemas, perCallCapabilities) {
-    const driftLogs = [];
-    let adapted = params;
     if (serverVersion !== "v3") {
-      const pair = getV25Adapter(taskType);
-      if (pair) adapted = pair.adaptRequest(adapted);
+      throw new VersionUnsupportedError(taskType, "version", "v2", this.agent.agent_uri);
     }
+    const driftLogs = [];
+    let adapted = params;
     const toolSchema = (perCallToolSchemas ?? this.cachedToolSchemas)?.get(taskType);
     if (toolSchema && Object.keys(toolSchema).length > 0) {
       const declaredFields = new Set(Object.keys(toolSchema));
-      const adapterAliases = [["brand_manifest", "brand"]];
-      for (const [adapterField, schemaField] of adapterAliases) {
-        if (adapted[adapterField] !== void 0 && !declaredFields.has(adapterField) && declaredFields.has(schemaField) && adapted[schemaField] === void 0 && valueMatchesSchemaType(adapted[adapterField], toolSchema[schemaField])) {
-          adapted[schemaField] = adapted[adapterField];
-          delete adapted[adapterField];
-        }
-      }
       const envelopeFields = ADCP_ENVELOPE_FIELDS;
       const filtered = {};
       const schemaStripped = [];
@@ -4644,67 +4755,19 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     }
     return { params: adapted, driftLogs };
   }
-  /**
-   * Normalize response to v3 format
-   *
-   * Converts v2 responses to v3 structure for consistent API surface.
-   */
-  normalizeResponseToV3(taskType, data) {
-    const pair = getV25Adapter(taskType);
-    if (pair?.normalizeResponse) return pair.normalizeResponse(data);
-    return data;
-  }
-  /**
-   * Check if request uses v3 features that the server doesn't support
-   *
-   * Returns an early empty result if the request requires v3 features
-   * that the server doesn't support. This treats "products matching unsupported
-   * capability" as an empty result set rather than an error.
-   *
-   * @returns TaskResult with empty data if v3 features are unsupported, null to proceed normally
-   */
-  async getEarlyResultForUnsupportedFeatures(taskType, params, options) {
-    if (taskType !== "get_products") {
-      return null;
-    }
-    const capabilities = await this.getCapabilities(options);
-    if (capabilities.version === "v3") {
-      return null;
-    }
-    const usesUnsupportedFeature = (
-      // required_features: content_standards requires contentStandards
-      params.filters?.required_features?.includes("content_standards") && !capabilities.features.contentStandards
-    );
-    if (!usesUnsupportedFeature) {
-      return null;
+  normalizeEstablishedResponse(taskType, data) {
+    if (!data) return data;
+    switch (taskType) {
+      case "get_products":
+        return normalizeGetProductsResponse(data);
+      case "create_media_buy":
+      case "update_media_buy":
+        return normalizeMediaBuyResponse(data);
+      case "list_creative_formats":
+        return normalizeFormatsResponse(data);
+      default:
+        return data;
     }
-    console.warn(
-      `[AdCP] v3-only features not supported by server "${this.agent.id}" (${capabilities.version}). Returning empty results.`
-    );
-    const emptyResponse = {
-      products: [],
-      property_list_applied: false
-    };
-    return {
-      success: true,
-      status: "completed",
-      data: emptyResponse,
-      metadata: {
-        taskId: `early_${Date.now()}`,
-        taskName: taskType,
-        agent: {
-          id: this.agent.id,
-          name: this.agent.name,
-          protocol: this.normalizedAgent.protocol
-        },
-        responseTimeMs: 0,
-        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-        clarificationRounds: 0,
-        status: "completed",
-        serverVersion: capabilities.version,
-        serverVersionSynthetic: capabilities._synthetic
-      }
-    };
   }
   // ====== MEDIA BUY TASKS ======
   /**
@@ -4804,6 +4867,13 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         }
       }
       const conditionalSnapshot = skipCacheRead ? void 0 : cache?.read(cacheScope, cacheParams, true);
+      const productEvidence = this.usesScopedDiscoveryTransport(
+        effectiveOptions
+      ) ? void 0 : {
+        scopeKey: this.getCapabilityEvidenceScope().scopeKey,
+        accountScope: this.canonicalAccountScope(account),
+        expiresAt: Date.now() + resolveAgentDiscoveryTtlMs(this.config.discoveryCache?.ttlMs)
+      };
       const result = await this.executeAndHandle(
         "get_products",
         "onGetProductsStatusChange",
@@ -4816,7 +4886,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
             projectionCatalogs: projectionCatalogs ?? this.config.projectionCatalogs
           });
           const authoritativeProducts = Array.isArray(data.products) ? data.products : response.products;
-          this.rememberCanonicalProductRoutes(response.products, account, authoritativeProducts);
+          this.rememberCanonicalProductRoutes(response.products, account, authoritativeProducts, productEvidence);
           const { _message: _dropLegacyMessage, ...canonical } = response;
           void _dropLegacyMessage;
           return { ...canonical, projection: { diagnostics } };
@@ -4827,7 +4897,9 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       );
       const finishCache = async (completed) => {
         if (!cache) return completed;
-        const cachedResult = cache.write(cacheScope, cacheParams, completed, conditionalSnapshot);
+        const cachedResult = cache.write(cacheScope, cacheParams, completed, conditionalSnapshot, (materialized) => {
+          this.rememberCanonicalProductRoutes(materialized.data?.products ?? [], account, void 0, productEvidence);
+        });
         if (cachedResult.success && cachedResult.status === "completed") {
           if (!skipCacheRead && cacheParams.if_wholesale_feed_version === void 0 && cacheParams.if_pricing_version === void 0 && cachedResult.data.unchanged === true) {
             return this.getProducts(params, inputHandler, {
@@ -5005,7 +5077,12 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     if (hasCreativeFormatData) {
       this.validateBeforeCreativeCapabilityProbe("create_media_buy", params, taskOptions);
     }
-    const wireMode = hasCreativeFormatData ? await this.resolveCreativeFormatWireMode("create_media_buy", taskOptions) : "canonical";
+    const wireMode = hasCreativeFormatData ? await this.resolveCreativeWireMode(
+      "create_media_buy",
+      taskOptions,
+      true,
+      () => this.productOptionsSupportCanonicalWire("create_media_buy", params, [], options)
+    ) : "canonical";
     const wireParams = params;
     const result = await this.executeAndHandle(
       "create_media_buy",
@@ -5093,7 +5170,12 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     if (hasCreativeFormatData) {
       this.validateBeforeCreativeCapabilityProbe("update_media_buy", params, taskOptions);
     }
-    const wireMode = hasCreativeFormatData ? await this.resolveCreativeFormatWireMode("update_media_buy", taskOptions) : "canonical";
+    const wireMode = hasCreativeFormatData ? await this.resolveCreativeWireMode(
+      "update_media_buy",
+      taskOptions,
+      true,
+      () => this.productOptionsSupportCanonicalWire("update_media_buy", params, [], options)
+    ) : "canonical";
     const result = await this.executeAndHandle(
       "update_media_buy",
       "onUpdateMediaBuyStatusChange",
@@ -5182,7 +5264,6 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       projectionCatalogs ?? this.config.projectionCatalogs
     );
     this.validateBeforeCreativeCapabilityProbe("sync_creatives", params, taskOptions);
-    const wireMode = await this.resolveCreativeFormatWireMode("sync_creatives", taskOptions);
     const configuredSelectorContainers = [
       ...creativeFormatProjection?.selectorContainers ?? []
     ];
@@ -5194,10 +5275,17 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     const assignmentPackageContainers = Array.isArray(params.assignments) ? params.assignments.flatMap(
       (assignment) => typeof assignment.package_id === "string" && !configuredPackageIds.has(assignment.package_id) ? [{ package_id: assignment.package_id }] : []
     ) : [];
+    const selectorContainers = [...configuredSelectorContainers, ...assignmentPackageContainers];
+    const wireMode = await this.resolveCreativeWireMode(
+      "sync_creatives",
+      taskOptions,
+      true,
+      () => this.productOptionsSupportCanonicalWire("sync_creatives", params, selectorContainers, options)
+    );
     const wireParams = this.projectUndeclaredFormatOptions(
       projectSyncCreativesForDelivery(
         params,
-        [...configuredSelectorContainers, ...assignmentPackageContainers],
+        selectorContainers,
         wireMode,
         effectiveLegacyFormatConverter,
         effectiveCanonicalFormatLegacyResolver
@@ -5237,16 +5325,17 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
    * sending a mutation. Discovers capabilities and the current tool's input
    * schema, or reuses fresh cached/primed evidence, with this client's wire pin.
    *
-   * `unknown` preserves the conservative legacy projection for older peers
-   * whose capabilities and schema do not establish support. Projection still
-   * requires an unambiguous legacy reference for each creative in that case.
+   * This context-free check returns `unknown` when capabilities and schema do
+   * not establish support. A write to a proven 3.1 seller can still select
+   * canonical delivery from matching seller-advertised product options;
+   * otherwise projection requires an unambiguous legacy reference.
    * Conflicting evidence and unproven support with a 3.2+ buyer pin throw
    * `CreativeFormatCapabilityError`, just as they do during a write.
    */
   async resolveCreativeFormatWireMode(taskType, options) {
     return this.resolveCreativeWireMode(taskType, options, true);
   }
-  async resolveCreativeWireMode(taskType, options, canRediscover) {
+  async resolveCreativeWireMode(taskType, options, canRediscover, matchingProductOptions) {
     const discoveryContext = {};
     const capabilities = await this.getCapabilities({
       ...options,
@@ -5265,13 +5354,16 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         `Seller capability and ${taskType} input schema disagree about canonical creative support`
       );
     }
-    const resolved = declared !== "unknown" ? declared : schema;
+    let resolved = declared !== "unknown" ? declared : schema;
+    if (resolved === "unknown" && canUseProductOptionsForCreativeWire(capabilities, wireRelease) && matchingProductOptions?.()) {
+      resolved = "canonical";
+    }
     const release = /^v?(\d+)\.(\d+)(?:\.|-|$)/.exec(wireRelease.trim());
     const canonicalRequiredByBuyerPin = release !== null && (Number(release[1]) > 3 || Number(release[1]) === 3 && Number(release[2]) >= 2);
     if (resolved === "unknown" && canonicalRequiredByBuyerPin) {
       if (canRediscover && !usesScopedFetch && this.normalizedAgent.protocol === "mcp" && this.capabilitiesFromSharedCache && toolSchemas?.has(taskType) && !toolInputSchemasByProperties.has(toolSchemas)) {
         await this.invalidateDiscoveryCache(options);
-        return this.resolveCreativeWireMode(taskType, options, false);
+        return this.resolveCreativeWireMode(taskType, options, false, matchingProductOptions);
       }
       throw new CreativeFormatCapabilityError(
         `Cannot prove which AdCP release the seller serves for ${taskType}; a 3.2+ client will not guess a legacy creative wire shape`
@@ -5279,6 +5371,112 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     }
     return resolved;
   }
+  /** Product evidence applies to this request only; it must never prime a tool-wide capability. */
+  productOptionsSupportCanonicalWire(taskType, request, selectorContainers = [], options) {
+    if (!isPlainRecord(request) || this.usesScopedDiscoveryTransport(options)) return false;
+    const scopeKey = this.getCapabilityEvidenceScope().scopeKey;
+    const accountScope = this.canonicalAccountScope(request.account);
+    const optionRef = (value) => {
+      if (!isPlainRecord(value) || typeof value.format_option_id !== "string" || !value.format_option_id) {
+        return void 0;
+      }
+      if (typeof value.publisher_domain === "string") {
+        return {
+          scope: "publisher",
+          publisher_domain: value.publisher_domain,
+          format_option_id: value.format_option_id
+        };
+      }
+      if (value.scope !== void 0 && value.scope !== "product") return void 0;
+      return { scope: "product", format_option_id: value.format_option_id };
+    };
+    const accepts = (container, creative, depth = 0) => {
+      if (depth > 32) return false;
+      if (Array.isArray(container.selector_containers)) {
+        return container.selector_containers.length > 0 && container.selector_containers.every((nested) => accepts(nested, creative, depth + 1));
+      }
+      const refs = Array.isArray(container.format_option_refs) ? container.format_option_refs.map(optionRef) : [];
+      if (refs.some((ref) => ref === void 0)) return false;
+      const creativeRef = isPlainRecord(creative) ? optionRef(creative.format_option_ref) : void 0;
+      if (isPlainRecord(creative) && creative.format_option_ref !== void 0 && !creativeRef) return false;
+      const isSellerDeclaration = (value) => {
+        if (!isPlainRecord(value) || sellerDeclaredFormatOption(value) !== true || isSynthesizedFormatOption(value)) {
+          return false;
+        }
+        const evidence2 = sellerFormatEvidence(value);
+        if (!evidence2 || evidence2.scopeKey !== scopeKey || typeof container.product_id === "string" && evidence2.productId !== container.product_id || evidence2.expiresAt <= Date.now() || evidence2.accountScope !== accountScope && evidence2.accountScope !== "none")
+          return false;
+        const ref = optionRef(value);
+        if (ref && formatOptionOriginFromRoutes(
+          options?.canonicalFormatLegacyResolver,
+          ref,
+          typeof container.product_id === "string" ? container.product_id : void 0
+        )?.seller_declared === false)
+          return false;
+        return !ref || typeof container.product_id !== "string" || this.cachedFormatOptionOrigin(request.account, ref, container.product_id)?.seller_declared !== false;
+      };
+      const declarations = [
+        ...(Array.isArray(container.format_options) ? container.format_options : []).filter(isSellerDeclaration),
+        ...selectedFormatOptions(container).filter(isSellerDeclaration)
+      ];
+      if (typeof container.product_id === "string") {
+        for (const ref of [...refs, ...creativeRef ? [creativeRef] : []]) {
+          if (!ref) continue;
+          const route = this.routeForOption(request.account, container.product_id, ref);
+          if (route?.kind === "product" && route.declaration && isSellerDeclaration(route.declaration))
+            declarations.push(route.declaration);
+        }
+      }
+      const available = declarations.filter((declaration) => declaration.experimental !== true);
+      const matchesRef = (declaration, ref) => {
+        const declaredRef = optionRef(declaration);
+        return declaredRef !== void 0 && sameFormatOptionRef(declaredRef, ref);
+      };
+      if (!refs.every((ref) => available.some((declaration) => matchesRef(declaration, ref)))) return false;
+      const selected = available.filter(
+        (declaration) => refs.length === 0 || refs.some((ref) => matchesRef(declaration, ref))
+      );
+      if (creative === void 0) return refs.length > 0 && selected.length > 0;
+      if (!isPlainRecord(creative) || typeof creative.format_kind !== "string" || creative.format_id !== void 0)
+        return false;
+      return selected.some(
+        (declaration) => declaration.format_kind === creative.format_kind && (!creativeRef || matchesRef(declaration, creativeRef)) && creativeMatchesProductOption(creative, declaration)
+      );
+    };
+    if (taskType === "sync_creatives") {
+      if (!Array.isArray(request.creatives) || request.creatives.length === 0) return false;
+      const creatives = request.creatives;
+      const assignments = Array.isArray(request.assignments) ? request.assignments : [];
+      if (!assignments.every(
+        (value) => isPlainRecord(value) && typeof value.package_id === "string" && typeof value.creative_id === "string" && creatives.some((creative) => isPlainRecord(creative) && creative.creative_id === value.creative_id)
+      ))
+        return false;
+      return creatives.every((creative) => {
+        if (!isPlainRecord(creative)) return false;
+        const assigned = new Set(
+          assignments.flatMap(
+            (value) => isPlainRecord(value) && value.creative_id === creative.creative_id && typeof value.package_id === "string" ? [value.package_id] : []
+          )
+        );
+        const relevant = assigned.size === 0 ? selectorContainers : selectorContainers.filter(
+          (container) => typeof container.package_id === "string" && assigned.has(container.package_id)
+        );
+        return relevant.length > 0 && [...assigned].every((id) => relevant.some((container) => container.package_id === id)) && relevant.every((container) => accepts(container, creative));
+      });
+    }
+    const packages = ["packages", "new_packages"].flatMap((key) => Array.isArray(request[key]) ? request[key] : []);
+    let evidence = false;
+    return packages.length > 0 && packages.every((pkg) => {
+      if (!isPlainRecord(pkg)) return false;
+      const creatives = Array.isArray(pkg.creatives) ? pkg.creatives : [];
+      const hasSelectors = Array.isArray(pkg.format_option_refs) && pkg.format_option_refs.length > 0;
+      if (!hasSelectors && creatives.length === 0) {
+        return pkg.format_kind === void 0 && pkg.format_ids === void 0;
+      }
+      evidence = true;
+      return (!hasSelectors || accepts(pkg)) && creatives.every((creative) => accepts(pkg, creative));
+    }) && evidence;
+  }
   /** Validate malformed creative payloads before capability discovery can perform I/O. */
   validateBeforeCreativeCapabilityProbe(taskType, params, options) {
     if (options.skipIdempotencyAutoInject || options.skipAccountValidation || options.skipRequestValidation) return;
@@ -6187,11 +6385,8 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         capabilityDiscoveryContext.toolSchemas,
         capabilityDiscoveryContext.capabilities
       );
-      const v25DriftLogs = [...adaptDriftLogs];
-      if (webhookDriftLog) v25DriftLogs.push(webhookDriftLog);
-      if (serverVersion === "v2") {
-        this.executor.validateAdaptedRequestAgainstV2(taskName, adaptedParams, v25DriftLogs);
-      }
+      const adaptationLogs = [...adaptDriftLogs];
+      if (webhookDriftLog) adaptationLogs.push(webhookDriftLog);
       const deferredClientContext = {
         kind: "single-agent",
         taskType: taskName,
@@ -6221,7 +6416,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         deferredClientContext
       );
       if (!result.success) await this.invalidateDiscoveryOnCapabilityError(result.adcpError?.code, effectiveOptions);
-      const postAdapterLogs = [...inputSchemaStripLogs, ...v25DriftLogs];
+      const postAdapterLogs = [...inputSchemaStripLogs, ...adaptationLogs];
       if (postAdapterLogs.length > 0) {
         result.debug_logs = [...result.debug_logs ?? [], ...postAdapterLogs];
       }
@@ -6411,6 +6606,10 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
   getProtocol() {
     return this.normalizedAgent.protocol;
   }
+  /** Resolved MCP endpoint already used by this client; never performs discovery. */
+  getDiscoveredMcpEndpoint() {
+    return this.discoveredEndpoint;
+  }
   /**
    * Get the canonical base URL for this agent
    *
@@ -6912,7 +7111,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
    * Get agent capabilities, including AdCP version support
    *
    * For v3 servers, calls get_adcp_capabilities tool.
-   * For v2 servers, builds synthetic capabilities from available tools.
+   * Requires AdCP 3 capability discovery; retired AdCP 2 agents are rejected.
    *
    * @returns Promise resolving to normalized capabilities object
    *
@@ -6949,7 +7148,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     }
     if (!usesScopedFetch && this.cachedCapabilities) {
       if (discoveryContext) discoveryContext.toolSchemas = this.cachedToolSchemas;
-      this.maybeWarnV2Sunset(this.cachedCapabilities);
+      this.assertSupportedServer(this.cachedCapabilities);
       return this.cachedCapabilities;
     }
     if (!usesScopedFetch && this.config.discoveryCache) {
@@ -7033,7 +7232,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     this.capabilitiesFromSharedCache = true;
     this.recordSharedEvidence(key);
     if (discoveryContext) discoveryContext.toolSchemas = this.cachedToolSchemas;
-    this.maybeWarnV2Sunset(installed);
+    this.assertSupportedServer(installed);
     return installed;
   }
   async discoverCapabilitiesLive(options, usesScopedFetch, discoveryContext) {
@@ -7083,16 +7282,17 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
           throw createTimeoutError(requestTimeoutMs);
         }
         if (result.success && result.data) {
-          const capabilities2 = augmentCapabilitiesFromTools(parseCapabilitiesResponse(result.data), tools);
+          const capabilities = augmentCapabilitiesFromTools(parseCapabilitiesResponse(result.data), tools);
+          this.assertSupportedServer(capabilities);
           if (!usesScopedFetch && !superseded()) {
-            this.cachedCapabilities = capabilities2;
+            this.cachedCapabilities = capabilities;
             this.capabilitiesFromSharedCache = false;
-            if (!capabilities2._synthetic && this.config.discoveryCache) {
+            if (!capabilities._synthetic && this.config.discoveryCache) {
               this.recordSharedEvidence(this.sharedDiscoveryKey(options));
               const stored = await this.writeSharedDiscovery(
                 options,
                 {
-                  capabilities: structuredClone(capabilities2),
+                  capabilities: structuredClone(capabilities),
                   toolSchemas: Object.fromEntries(discoveredToolSchemas),
                   toolInputSchemas: Object.fromEntries(discoveredInputSchemas)
                 },
@@ -7100,7 +7300,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
                 startedAtEpoch
               );
               if (superseded()) {
-                if (this.cachedCapabilities === capabilities2) {
+                if (this.cachedCapabilities === capabilities) {
                   this.cachedCapabilities = void 0;
                   this.cachedToolSchemas = void 0;
                   this.primedCapabilitiesExpiresAt = void 0;
@@ -7110,31 +7310,26 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
               }
             }
           }
-          this.maybeWarnV2Sunset(capabilities2);
-          return capabilities2;
+          this.assertSupportedServer(capabilities);
+          return capabilities;
         }
         if (!advertisesCapabilitiesTool) {
           throw new Error("unadvertised official A2A capability probe was not supported");
         }
         if (result.data && looksLikeV3Capabilities(result.data)) {
+          const capabilities = augmentCapabilitiesFromTools(parseCapabilitiesResponse(result.data), tools);
+          this.assertSupportedServer(capabilities);
           console.warn(
             `[AdCP] Agent "${this.agent.id}" returned a get_adcp_capabilities response that failed validation, but the response is structurally v3-shaped. Treating as v3 (the agent has a wire-shape bug \u2014 that's the thing to fix).`,
             { hasError: !!result.error, hasData: !!result.data }
           );
-          const parsed = parseCapabilitiesResponse(result.data);
-          const v3Capabilities = {
-            ...parsed,
-            version: "v3",
-            majorVersions: parsed.majorVersions.includes(3) ? parsed.majorVersions : [3]
-          };
-          const capabilities2 = augmentCapabilitiesFromTools(v3Capabilities, tools);
           if (!usesScopedFetch && !superseded()) {
-            this.cachedCapabilities = capabilities2;
+            this.cachedCapabilities = capabilities;
             this.capabilitiesFromSharedCache = false;
             this.recordSharedEvidence(this.sharedDiscoveryKey(options));
           }
-          this.maybeWarnV2Sunset(capabilities2);
-          return capabilities2;
+          this.assertSupportedServer(capabilities);
+          return capabilities;
         }
         console.warn(
           `[AdCP] Agent "${this.agent.id}" advertises get_adcp_capabilities but the call returned non-success and the response is not v3-shaped \u2014 treating as v3 (synthetic) since the agent has the v3-only discovery tool. This client routes to v3 adapters, but calls reading capability details (idempotency TTL, supported_versions, feature flags) will fail until the agent operator fixes the capabilities endpoint.`,
@@ -7145,7 +7340,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
           }
         );
       } catch (error) {
-        if (error instanceof AuthenticationRequiredError || error instanceof ConfigurationError || error instanceof TaskTimeoutError || isAbortOrTimeoutError(error)) {
+        if (error instanceof AuthenticationRequiredError || error instanceof VersionUnsupportedError || error instanceof ConfigurationError || error instanceof TaskTimeoutError || isAbortOrTimeoutError(error)) {
           throw error;
         }
         if (advertisesCapabilitiesTool) {
@@ -7155,26 +7350,17 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         }
       }
       if (advertisesCapabilitiesTool) {
-        const capabilities2 = augmentCapabilitiesFromTools(buildSyntheticV3Capabilities(tools), tools);
+        const capabilities = augmentCapabilitiesFromTools(buildSyntheticV3Capabilities(tools), tools);
         if (!usesScopedFetch && !superseded()) {
-          this.cachedCapabilities = capabilities2;
+          this.cachedCapabilities = capabilities;
           this.capabilitiesFromSharedCache = false;
           this.recordSharedEvidence(this.sharedDiscoveryKey(options));
         }
-        this.maybeWarnV2Sunset(capabilities2);
-        return capabilities2;
+        this.assertSupportedServer(capabilities);
+        return capabilities;
       }
     }
-    console.warn(
-      `[AdCP] Agent "${this.agent.id}" detected as v2 (no get_adcp_capabilities tool). Tools: [${tools.map((t) => t.name).join(", ")}]`
-    );
-    const capabilities = buildSyntheticCapabilities(tools);
-    if (!usesScopedFetch && !superseded()) {
-      this.cachedCapabilities = capabilities;
-      this.capabilitiesFromSharedCache = false;
-      this.recordSharedEvidence(this.sharedDiscoveryKey(options));
-    }
-    return capabilities;
+    throw new VersionUnsupportedError("get_adcp_capabilities", "synthetic", "v2", this.agent.agent_uri);
   }
   /**
    * Return the client-bound scope required by {@link primeCapabilities}.
@@ -7689,28 +7875,11 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     if (!this.config.discoveryCache || !code || !CAPABILITY_STALE_ERROR_CODES.has(code)) return;
     await this.invalidateDiscoveryCache(options);
   }
-  /**
-   * Emit a one-time warning when the agent reports v2 capabilities.
-   *
-   * v2 went unsupported on 2026-04-20 (AdCP 3.0 GA — adcp#2220). We still
-   * execute v2 code paths (no behaviour change), but clients integrating
-   * against an unsupported agent should hear about it loudly.
-   *
-   * Synthetic capabilities (no `get_adcp_capabilities` tool available) don't
-   * trigger the warning — we don't actually know the agent's version, and
-   * shouting at legitimately-unversioned agents would be noise.
-   *
-   * Suppression: `process.env.ADCP_ALLOW_V2 === '1'`.
-   */
-  maybeWarnV2Sunset(capabilities) {
-    if (this._v2WarningFired) return;
-    if (capabilities.version === "v3") return;
-    if (capabilities._synthetic) return;
-    if (process.env.ADCP_ALLOW_V2 === "1") return;
-    this._v2WarningFired = true;
-    console.warn(
-      `[adcp] Warning: agent ${this.agent.agent_uri} reports v2 capabilities. v2 went unsupported on 2026-04-20 (AdCP 3.0 GA). Upgrade the agent to v3 or set ADCP_ALLOW_V2=1 to suppress this warning. See https://github.com/adcontextprotocol/adcp/issues/2220`
-    );
+  /** Reject retired protocol generations before caching or dispatching. */
+  assertSupportedServer(capabilities) {
+    if (capabilities.version !== "v3" || !capabilities.majorVersions.includes(3)) {
+      throw new VersionUnsupportedError("get_adcp_capabilities", "version", capabilities.version, this.agent.agent_uri);
+    }
   }
   /**
    * Warn once per client when `requireSupportedMajor` accepts synthetic v3
@@ -7731,24 +7900,6 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       `[adcp] Warning: agent ${this.agent.agent_uri} advertises get_adcp_capabilities (v3-only) but the call failed. Treating as v3 (synthetic) \u2014 version + idempotency-TTL checks skipped. Calls to getIdempotencyReplayTtlSeconds() will throw until the agent's capabilities endpoint is fixed. Report the wire-shape bug to the agent operator at ${this.agent.agent_uri}.`
     );
   }
-  /**
-   * Warn once per client when `requireSupportedMajor` routes a synthetic-v2
-   * seller through the v2 adapter — the agent did not expose
-   * `get_adcp_capabilities`, so the version was inferred from `tools/list`.
-   * A compliant v3 seller would declare itself; absence of a declaration is
-   * read as v2. Idempotency-TTL guarantees are unknown for these sellers,
-   * so BYOK retry callers should treat them as such.
-   *
-   * One-shot via `_syntheticV2WarningFired` (matches `maybeWarnV2Sunset`
-   * cadence).
-   */
-  maybeWarnSyntheticV2() {
-    if (this._syntheticV2WarningFired) return;
-    this._syntheticV2WarningFired = true;
-    console.warn(
-      `[adcp] Warning: agent ${this.agent.agent_uri} does not expose get_adcp_capabilities. Routing as v2 (synthetic) \u2014 idempotency-TTL guarantee is unknown. Ask the agent operator to declare v3 via get_adcp_capabilities if v3 routing is intended. Branch on client.isSyntheticV2() to tighten retry policies for these sellers.`
-    );
-  }
   /**
    * Detect server AdCP version
    *
@@ -7758,36 +7909,15 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     const capabilities = await this.getCapabilities(options);
     const discoveryContext = options?.[CAPABILITY_DISCOVERY_CONTEXT];
     if (discoveryContext) discoveryContext.capabilities = capabilities;
+    this.assertSupportedServer(capabilities);
     return capabilities.version;
   }
-  /**
-   * Whether the seller's capabilities are synthesized from `tools/list`
-   * with no authoritative `get_adcp_capabilities` response — i.e. the
-   * dispatcher routes through the v2 adapter and idempotency-TTL is
-   * unknown. Use this to gate retry behavior for sellers whose retry
-   * safety can't be derived from declared capabilities (lower attempt
-   * caps, longer backoff, or fall back to natural-key recovery).
-   *
-   * Returns `false` for declared v2 sellers, declared v3 sellers, and
-   * synthetic v3 sellers (which advertise the v3 discovery tool even
-   * when the call itself failed).
-   *
-   * Caveat for synthetic v3: the predicate returns `false`, but TTL is
-   * still unknown for those sellers — `getIdempotencyReplayTtlSeconds()`
-   * throws until the agent's capabilities endpoint is fixed (issue
-   * #1217). Retry-policy consumers that need a complete "TTL unknown"
-   * gate should additionally check `getCapabilities()._synthetic`.
-   */
-  async isSyntheticV2() {
-    const capabilities = await this.getCapabilities();
-    return capabilities._synthetic === true && capabilities.version === "v2";
-  }
   /**
    * Check if server supports a specific AdCP major version
    */
   async supportsVersion(version) {
     const capabilities = await this.getCapabilities();
-    return capabilities.majorVersions.includes(version);
+    return version === 3 && capabilities.majorVersions.includes(3);
   }
   /**
    * Return the seller's declared `adcp.idempotency.replay_ttl_seconds`.
@@ -7798,8 +7928,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
    *
    * Fails closed when the seller is v3 but does not declare the field: the
    * spec makes the declaration REQUIRED, and silently defaulting to 24h
-   * would mislead buyers about retry safety. Callers on v2 servers get
-   * `undefined` instead of a throw — v2 pre-dates the idempotency envelope.
+   * would mislead buyers about retry safety.
    */
   async getIdempotencyReplayTtlSeconds() {
     const capabilities = await this.getCapabilities();
@@ -7808,7 +7937,6 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       assertValidIdempotencyReplayTtlSeconds(capabilities.idempotency.replayTtlSeconds);
       return capabilities.idempotency.replayTtlSeconds;
     }
-    if (capabilities.version !== "v3") return void 0;
     throw new ConfigurationError(
       `Agent "${this.agent.id}" is v3 but does not declare adcp.idempotency.replay_ttl_seconds. The spec requires this for v3 sellers \u2014 treating the agent as non-compliant rather than defaulting to 24h, which would silently mislead retry-sensitive flows.`,
       "adcp.idempotency.replay_ttl_seconds"
@@ -8119,28 +8247,16 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
    *   2. `capabilities.idempotency.replayTtlSeconds` present (spec-required
    *      for real major-3+ sellers)
    *
-   * Sellers whose capabilities are synthesized from `tools/list` (no
-   * authoritative `get_adcp_capabilities` response) are treated as v2: a
-   * compliant v3 seller would declare itself, so absence of a declaration
-   * is taken as evidence of v2. The dispatcher routes the request through
-   * the v2 wire-shape adapter. A one-time warning surfaces the routing
-   * decision so adopters can audit it; retry-safety (idempotency TTL) is
-   * unknown for these sellers and BYOK callers should treat them as such.
-   *
-   * Per-client `allowV2: true` or, when that's undefined,
-   * `ADCP_ALLOW_V2=1` in the environment bypasses the guard entirely.
+   * Synthetic v3 evidence is accepted only when the agent advertises discovery.
+   * Agents without discovery and AdCP 2-only agents are rejected.
    *
    * Throws `VersionUnsupportedError` with the specific reason on failure.
    */
   async requireSupportedMajor(taskType = "request", options) {
-    if (this.isV2Allowed()) return;
     const capabilities = await this.getCapabilities(options);
+    this.assertSupportedServer(capabilities);
     if (capabilities._synthetic) {
-      if (capabilities.version === "v3") {
-        this.maybeWarnSyntheticV3();
-      } else {
-        this.maybeWarnSyntheticV2();
-      }
+      this.maybeWarnSyntheticV3();
       return;
     }
     const supportedVersions = capabilities.supportedVersions;
@@ -8171,10 +8287,6 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
   async requireV3(taskType = "request") {
     return this.requireSupportedMajor(taskType);
   }
-  isV2Allowed() {
-    if (this.config.allowV2 !== void 0) return this.config.allowV2 === true;
-    return process.env.ADCP_ALLOW_V2 === "1";
-  }
   // ====== STATIC HELPER METHODS ======
   /**
    * Query a legacy creative-agent named-format catalog.