@adcp/sdk 14.1.0 → 14.2.0

package/dist/lib/signing/agent-resolver/resolve-agent.js

@@ -22,9 +22,12 @@ __export(resolve_agent_exports, {
 });
 module.exports = __toCommonJS(resolve_agent_exports);
 var import_tldts = require("tldts");
+var import_node_net = require("node:net");
 var import_protocols = require('../../protocols/index.js');
 var import_domain = require('../../brand/domain.js');
 var import_capabilities_types = require('./capabilities-types.js');
+var import_net = require('../../net/index.js');
+var import_agent_transport_fetch = require('../../net/agent-transport-fetch.js');
 var import_operator_authorization = require('./operator-authorization.js');
 var import_legacy_brand = require('./legacy-brand.js');
 var import_consistency = require('./consistency.js');
@@ -42,7 +45,7 @@ async function resolveAgent(agentUrl, options = {}) {
   const caps = options.bodyCaps ?? {};
   const brandJsonCap = caps.brandJsonBytes ?? import_fetch_helpers.MAX_BRAND_JSON_BYTES;
   const jwksCap = caps.jwksBytes ?? import_fetch_helpers.MAX_JWKS_BYTES;
-  const fetchCapabilities = options.fetchCapabilities ?? defaultFetchCapabilities(agentUrl, options.protocol ?? "mcp");
+  const fetchCapabilities = options.fetchCapabilities ?? defaultFetchCapabilities(agentUrl, options.protocol ?? "mcp", allowPrivateIp, timeoutMs);
   let capabilitiesPayload;
   let capabilitiesFetchedAt;
   try {
@@ -59,7 +62,7 @@ async function resolveAgent(agentUrl, options = {}) {
   } catch (err) {
     const detail = {
       agent_url: agentUrl,
-      dns_error: err instanceof import_fetch_helpers.SafeFetchError ? err.transport : "fetch_failed",
+      ...(0, import_fetch_helpers.classifyDiscoveryFailure)(err),
       last_attempt_at: now()
     };
     pushTrace(trace, { step: 1, name: "fetch_capabilities", ok: false, url: agentUrl, detail });
@@ -368,10 +371,49 @@ function checkAllowPrivateIp(requested) {
     "resolveAgent: allowPrivateIp=true refused outside {NODE_ENV=test, NODE_ENV=development}. Set NODE_ENV appropriately for dev/test, or set ADCP_RESOLVER_ALLOW_PRIVATE_IP=1 as an explicit ops acknowledgment if you genuinely need private-IP discovery in this process."
   );
 }
-function defaultFetchCapabilities(agentUrl, protocol) {
+function defaultFetchCapabilities(agentUrl, protocol, allowPrivateIp, timeoutMs) {
   return async () => {
-    const client = protocol === "a2a" ? (0, import_protocols.createA2AClient)(agentUrl) : (0, import_protocols.createMCPClient)(agentUrl);
-    return client.callTool("get_adcp_capabilities", {});
+    const url = new URL(agentUrl);
+    const hostname = url.hostname.replace(/^\[|\]$/g, "");
+    if (!allowPrivateIp && url.protocol !== "https:" || (0, import_node_net.isIP)(hostname) && ((0, import_net.isAlwaysBlocked)(hostname) || !allowPrivateIp && (0, import_net.isPrivateIp)(hostname)))
+      throw new import_agent_transport_fetch.AgentTransportPolicyError("Signing discovery URL refused by address or HTTPS policy.");
+    let failure;
+    const upstream = (0, import_agent_transport_fetch.createAgentTransportFetch)(agentUrl, {
+      allowPrivateIp,
+      allowPrivateInitialOrigin: false,
+      requireHttps: true
+    });
+    let postSucceeded = false;
+    const trustedFetchFn = async (input, init) => {
+      const method = init?.method ?? (input instanceof Request ? input.method : "GET");
+      try {
+        const response = await upstream(input, init);
+        const isGet = method.toUpperCase() === "GET";
+        const observed = response.status >= 400 ? { dns_error: "fetch_failed", http_status: response.status } : void 0;
+        if (protocol === "mcp" && method.toUpperCase() === "POST" && response.ok) postSucceeded = true;
+        if (!(protocol === "mcp" && isGet && (postSucceeded || response.status === 405)) && !(isGet && observed && failure && !(0, import_fetch_helpers.isPermanentDiscoveryFailure)(failure) && (0, import_fetch_helpers.isPermanentDiscoveryFailure)(observed)))
+          failure = observed;
+        return response;
+      } catch (error) {
+        if (!(protocol === "mcp" && method.toUpperCase() === "GET" && postSucceeded))
+          failure = (0, import_fetch_helpers.classifyDiscoveryFailure)(error);
+        throw error;
+      }
+    };
+    const transport = { trustedFetchFn, requestTimeoutMs: timeoutMs };
+    const client = protocol === "a2a" ? (0, import_protocols.createA2AClient)(agentUrl, void 0, void 0, void 0, void 0, transport) : (0, import_protocols.createMCPClient)(agentUrl, void 0, void 0, void 0, void 0, transport);
+    try {
+      return await client.callTool("get_adcp_capabilities", {});
+    } catch (error) {
+      if (failure)
+        throw new import_fetch_helpers.SafeFetchError(
+          "capabilities",
+          failure.dns_error,
+          "Capabilities fetch failed",
+          failure.http_status
+        );
+      throw error;
+    }
   };
 }
 function findAuthorizedOperator(brandJson, agentEtld1, _now, _options) {

package/dist/lib/signing/agent-resolver/resolve-agent.mjs

@@ -1,7 +1,10 @@
 import { parse as parseTld } from "tldts";
+import { isIP } from "node:net";
 import { createA2AClient, createMCPClient } from "../../protocols/index.mjs";
 import { isDevelopmentBrandDomain } from "../../brand/domain.mjs";
 import { readBrandJsonUrl, readIdentityPosture } from "./capabilities-types.mjs";
+import { isAlwaysBlocked, isPrivateIp } from "../../net/index.mjs";
+import { AgentTransportPolicyError, createAgentTransportFetch } from "../../net/agent-transport-fetch.mjs";
 import { checkDelegatedOperatorAuthorization } from "./operator-authorization.mjs";
 import { fetchLegacyBrandJson } from "./legacy-brand.mjs";
 import {
@@ -11,7 +14,14 @@ import {
 } from "./consistency.mjs";
 import { AgentResolverError } from "./errors.mjs";
 import { eTldPlusOne, sameEtldPlusOne } from "./etld.mjs";
-import { MAX_BRAND_JSON_BYTES, MAX_JWKS_BYTES, safeFetchJson, SafeFetchError } from "./fetch-helpers.mjs";
+import {
+  MAX_BRAND_JSON_BYTES,
+  MAX_JWKS_BYTES,
+  safeFetchJson,
+  SafeFetchError,
+  classifyDiscoveryFailure,
+  isPermanentDiscoveryFailure
+} from "./fetch-helpers.mjs";
 import { unwrapProtocolResponse } from "../protocol-response.mjs";
 import { selectAgentByUrl, agentJwksUri, AgentSelectorError, canonicalAgentUrl } from "./select-agent.mjs";
 const DEFAULT_TIMEOUT_MS = 1e4;
@@ -23,7 +33,7 @@ async function resolveAgent(agentUrl, options = {}) {
   const caps = options.bodyCaps ?? {};
   const brandJsonCap = caps.brandJsonBytes ?? MAX_BRAND_JSON_BYTES;
   const jwksCap = caps.jwksBytes ?? MAX_JWKS_BYTES;
-  const fetchCapabilities = options.fetchCapabilities ?? defaultFetchCapabilities(agentUrl, options.protocol ?? "mcp");
+  const fetchCapabilities = options.fetchCapabilities ?? defaultFetchCapabilities(agentUrl, options.protocol ?? "mcp", allowPrivateIp, timeoutMs);
   let capabilitiesPayload;
   let capabilitiesFetchedAt;
   try {
@@ -40,7 +50,7 @@ async function resolveAgent(agentUrl, options = {}) {
   } catch (err) {
     const detail = {
       agent_url: agentUrl,
-      dns_error: err instanceof SafeFetchError ? err.transport : "fetch_failed",
+      ...classifyDiscoveryFailure(err),
       last_attempt_at: now()
     };
     pushTrace(trace, { step: 1, name: "fetch_capabilities", ok: false, url: agentUrl, detail });
@@ -349,10 +359,49 @@ function checkAllowPrivateIp(requested) {
     "resolveAgent: allowPrivateIp=true refused outside {NODE_ENV=test, NODE_ENV=development}. Set NODE_ENV appropriately for dev/test, or set ADCP_RESOLVER_ALLOW_PRIVATE_IP=1 as an explicit ops acknowledgment if you genuinely need private-IP discovery in this process."
   );
 }
-function defaultFetchCapabilities(agentUrl, protocol) {
+function defaultFetchCapabilities(agentUrl, protocol, allowPrivateIp, timeoutMs) {
   return async () => {
-    const client = protocol === "a2a" ? createA2AClient(agentUrl) : createMCPClient(agentUrl);
-    return client.callTool("get_adcp_capabilities", {});
+    const url = new URL(agentUrl);
+    const hostname = url.hostname.replace(/^\[|\]$/g, "");
+    if (!allowPrivateIp && url.protocol !== "https:" || isIP(hostname) && (isAlwaysBlocked(hostname) || !allowPrivateIp && isPrivateIp(hostname)))
+      throw new AgentTransportPolicyError("Signing discovery URL refused by address or HTTPS policy.");
+    let failure;
+    const upstream = createAgentTransportFetch(agentUrl, {
+      allowPrivateIp,
+      allowPrivateInitialOrigin: false,
+      requireHttps: true
+    });
+    let postSucceeded = false;
+    const trustedFetchFn = async (input, init) => {
+      const method = init?.method ?? (input instanceof Request ? input.method : "GET");
+      try {
+        const response = await upstream(input, init);
+        const isGet = method.toUpperCase() === "GET";
+        const observed = response.status >= 400 ? { dns_error: "fetch_failed", http_status: response.status } : void 0;
+        if (protocol === "mcp" && method.toUpperCase() === "POST" && response.ok) postSucceeded = true;
+        if (!(protocol === "mcp" && isGet && (postSucceeded || response.status === 405)) && !(isGet && observed && failure && !isPermanentDiscoveryFailure(failure) && isPermanentDiscoveryFailure(observed)))
+          failure = observed;
+        return response;
+      } catch (error) {
+        if (!(protocol === "mcp" && method.toUpperCase() === "GET" && postSucceeded))
+          failure = classifyDiscoveryFailure(error);
+        throw error;
+      }
+    };
+    const transport = { trustedFetchFn, requestTimeoutMs: timeoutMs };
+    const client = protocol === "a2a" ? createA2AClient(agentUrl, void 0, void 0, void 0, void 0, transport) : createMCPClient(agentUrl, void 0, void 0, void 0, void 0, transport);
+    try {
+      return await client.callTool("get_adcp_capabilities", {});
+    } catch (error) {
+      if (failure)
+        throw new SafeFetchError(
+          "capabilities",
+          failure.dns_error,
+          "Capabilities fetch failed",
+          failure.http_status
+        );
+      throw error;
+    }
   };
 }
 function findAuthorizedOperator(brandJson, agentEtld1, _now, _options) {

package/dist/lib/signing/brand-jwks.d.mts

@@ -14,6 +14,7 @@ export type BrandJsonResolverErrorCode = 'invalid_url' | 'invalid_house' | 'redi
  */
 export declare class BrandJsonResolverError extends Error {
     readonly code: BrandJsonResolverErrorCode;
+    readonly recovery: 'terminal' | 'transient';
     readonly cause?: unknown;
     /** HTTP status for `fetch_failed` responses, when a response was received. */
     readonly httpStatus?: number;
@@ -79,6 +80,7 @@ export declare class BrandJsonJwksResolver implements JwksResolver {
     private resolver?;
     private onboarding?;
     private lastOnboardingAttempt;
+    private lastOnboardingError?;
     constructor(brandJsonUrl: string, options: BrandJsonJwksResolverOptions);
     private createResolver;
     private confirmedResolver;

package/dist/lib/signing/brand-jwks.d.ts

@@ -14,6 +14,7 @@ export type BrandJsonResolverErrorCode = 'invalid_url' | 'invalid_house' | 'redi
  */
 export declare class BrandJsonResolverError extends Error {
     readonly code: BrandJsonResolverErrorCode;
+    readonly recovery: 'terminal' | 'transient';
     readonly cause?: unknown;
     /** HTTP status for `fetch_failed` responses, when a response was received. */
     readonly httpStatus?: number;
@@ -79,6 +80,7 @@ export declare class BrandJsonJwksResolver implements JwksResolver {
     private resolver?;
     private onboarding?;
     private lastOnboardingAttempt;
+    private lastOnboardingError?;
     constructor(brandJsonUrl: string, options: BrandJsonJwksResolverOptions);
     private createResolver;
     private confirmedResolver;

package/dist/lib/signing/brand-jwks.js

@@ -23,12 +23,14 @@ __export(brand_jwks_exports, {
   fetchBrandJson: () => fetchBrandJson
 });
 module.exports = __toCommonJS(brand_jwks_exports);
+var import_fetch_helpers = require('./agent-resolver/fetch-helpers.js');
 var import_net = require('../net/index.js');
 var import_resolved_agent_jwks = require('./agent-resolver/resolved-agent-jwks.js');
 var import_strict_json = require('./agent-resolver/strict-json.js');
 var import_select_agent = require('./agent-resolver/select-agent.js');
 class BrandJsonResolverError extends Error {
   code;
+  recovery;
   cause;
   /** HTTP status for `fetch_failed` responses, when a response was received. */
   httpStatus;
@@ -38,6 +40,7 @@ class BrandJsonResolverError extends Error {
     this.code = code;
     this.httpStatus = details.httpStatus;
     this.cause = details.cause;
+    this.recovery = code !== "fetch_failed" || (0, import_fetch_helpers.isPermanentDiscoveryFailure)((0, import_fetch_helpers.classifyDiscoveryFailure)(this)) ? "terminal" : "transient";
   }
 }
 const DEFAULT_MIN_COOLDOWN_SECONDS = 30;
@@ -63,6 +66,7 @@ class BrandJsonJwksResolver {
   resolver;
   onboarding;
   lastOnboardingAttempt = Number.NEGATIVE_INFINITY;
+  lastOnboardingError;
   createResolver(agentUrl, operatorUrl) {
     const options = this.options;
     return new import_resolved_agent_jwks.ResolvedAgentJwksResolver(agentUrl, options.protocol ?? "mcp", {
@@ -86,7 +90,7 @@ class BrandJsonJwksResolver {
     if (this.onboarding) return this.onboarding;
     const now = this.options.now?.() ?? Date.now() / 1e3;
     if (now - this.lastOnboardingAttempt < 30)
-      throw new BrandJsonResolverError("fetch_failed", "Operator onboarding discovery is in its retry cooldown.");
+      throw this.lastOnboardingError ?? new BrandJsonResolverError("fetch_failed", "Operator onboarding discovery is in its retry cooldown.");
     this.lastOnboardingAttempt = now;
     this.onboarding = (async () => {
       const record = await fetchBrandJson({
@@ -99,8 +103,12 @@ class BrandJsonJwksResolver {
       const resolver = this.createResolver(agentUrl, record.finalUrl);
       await resolver.forceRefresh();
       this.resolver = resolver;
+      this.lastOnboardingError = void 0;
       return resolver;
-    })().finally(() => {
+    })().catch((error) => {
+      this.lastOnboardingError = error;
+      throw error;
+    }).finally(() => {
       this.onboarding = void 0;
     });
     return this.onboarding;

package/dist/lib/signing/brand-jwks.mjs

@@ -1,9 +1,11 @@
+import { classifyDiscoveryFailure, isPermanentDiscoveryFailure } from "./agent-resolver/fetch-helpers.mjs";
 import { ssrfSafeFetch } from "../net/index.mjs";
 import { ResolvedAgentJwksResolver } from "./agent-resolver/resolved-agent-jwks.mjs";
 import { parseStrictJson } from "./agent-resolver/strict-json.mjs";
 import { canonicalAgentUrl } from "./agent-resolver/select-agent.mjs";
 class BrandJsonResolverError extends Error {
   code;
+  recovery;
   cause;
   /** HTTP status for `fetch_failed` responses, when a response was received. */
   httpStatus;
@@ -13,6 +15,7 @@ class BrandJsonResolverError extends Error {
     this.code = code;
     this.httpStatus = details.httpStatus;
     this.cause = details.cause;
+    this.recovery = code !== "fetch_failed" || isPermanentDiscoveryFailure(classifyDiscoveryFailure(this)) ? "terminal" : "transient";
   }
 }
 const DEFAULT_MIN_COOLDOWN_SECONDS = 30;
@@ -38,6 +41,7 @@ class BrandJsonJwksResolver {
   resolver;
   onboarding;
   lastOnboardingAttempt = Number.NEGATIVE_INFINITY;
+  lastOnboardingError;
   createResolver(agentUrl, operatorUrl) {
     const options = this.options;
     return new ResolvedAgentJwksResolver(agentUrl, options.protocol ?? "mcp", {
@@ -61,7 +65,7 @@ class BrandJsonJwksResolver {
     if (this.onboarding) return this.onboarding;
     const now = this.options.now?.() ?? Date.now() / 1e3;
     if (now - this.lastOnboardingAttempt < 30)
-      throw new BrandJsonResolverError("fetch_failed", "Operator onboarding discovery is in its retry cooldown.");
+      throw this.lastOnboardingError ?? new BrandJsonResolverError("fetch_failed", "Operator onboarding discovery is in its retry cooldown.");
     this.lastOnboardingAttempt = now;
     this.onboarding = (async () => {
       const record = await fetchBrandJson({
@@ -74,8 +78,12 @@ class BrandJsonJwksResolver {
       const resolver = this.createResolver(agentUrl, record.finalUrl);
       await resolver.forceRefresh();
       this.resolver = resolver;
+      this.lastOnboardingError = void 0;
       return resolver;
-    })().finally(() => {
+    })().catch((error) => {
+      this.lastOnboardingError = error;
+      throw error;
+    }).finally(() => {
       this.onboarding = void 0;
     });
     return this.onboarding;

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

@@ -1,12 +1,14 @@
 import { ADCPError } from '../errors/index.mjs';
 import type { RequestSigningErrorCode } from '../types/core.generated.mjs';
-export { RequestSigningErrorCodeMetadata } from '../types/enums.generated.mjs';
+import { RequestSigningErrorCodeMetadata } from '../types/enums.generated.mjs';
+export { RequestSigningErrorCodeMetadata };
 /** Canonical rc.6 request-signing transport vocabulary. */
 export type RequestSignatureErrorCode = RequestSigningErrorCode;
 export declare class RequestSignatureError extends ADCPError {
     readonly code: RequestSignatureErrorCode;
     readonly failedStep: number;
-    constructor(code: RequestSignatureErrorCode, failedStep: number, message: string, details?: unknown);
+    readonly recovery: 'transient' | 'correctable' | 'terminal';
+    constructor(code: RequestSignatureErrorCode, failedStep: number, message: string, details?: unknown, recovery?: 'transient' | 'correctable' | 'terminal');
 }
 /**
  * Error codes surfaced by the RFC 9421 webhook-signing verifier. Maps onto

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

@@ -1,12 +1,14 @@
 import { ADCPError } from '../errors';
 import type { RequestSigningErrorCode } from '../types/core.generated';
-export { RequestSigningErrorCodeMetadata } from '../types/enums.generated';
+import { RequestSigningErrorCodeMetadata } from '../types/enums.generated';
+export { RequestSigningErrorCodeMetadata };
 /** Canonical rc.6 request-signing transport vocabulary. */
 export type RequestSignatureErrorCode = RequestSigningErrorCode;
 export declare class RequestSignatureError extends ADCPError {
     readonly code: RequestSignatureErrorCode;
     readonly failedStep: number;
-    constructor(code: RequestSignatureErrorCode, failedStep: number, message: string, details?: unknown);
+    readonly recovery: 'transient' | 'correctable' | 'terminal';
+    constructor(code: RequestSignatureErrorCode, failedStep: number, message: string, details?: unknown, recovery?: 'transient' | 'correctable' | 'terminal');
 }
 /**
  * Error codes surfaced by the RFC 9421 webhook-signing verifier. Maps onto

package/dist/lib/signing/errors.js

@@ -30,10 +30,12 @@ var import_enums = require('../types/enums.generated.js');
 class RequestSignatureError extends import_errors.ADCPError {
   code;
   failedStep;
-  constructor(code, failedStep, message, details) {
+  recovery;
+  constructor(code, failedStep, message, details, recovery) {
     super(message, details);
     this.code = code;
     this.failedStep = failedStep;
+    this.recovery = recovery ?? import_enums.RequestSigningErrorCodeMetadata[code].recovery;
   }
 }
 class WebhookSignatureError extends import_errors.ADCPError {

package/dist/lib/signing/errors.mjs

@@ -3,10 +3,12 @@ import { RequestSigningErrorCodeMetadata } from "../types/enums.generated.mjs";
 class RequestSignatureError extends ADCPError {
   code;
   failedStep;
-  constructor(code, failedStep, message, details) {
+  recovery;
+  constructor(code, failedStep, message, details, recovery) {
     super(message, details);
     this.code = code;
     this.failedStep = failedStep;
+    this.recovery = recovery ?? RequestSigningErrorCodeMetadata[code].recovery;
   }
 }
 class WebhookSignatureError extends ADCPError {

package/dist/lib/signing/verifier.js

@@ -141,7 +141,7 @@ async function verifyRequestSignature(request, options) {
     }
   } catch (err) {
     if (err instanceof import_errors2.AgentResolverError) {
-      throw new import_errors.RequestSignatureError(err.code, 7, err.message, err.detail);
+      throw new import_errors.RequestSignatureError(err.code, 7, err.message, err.detail, err.recovery);
     }
     throw err;
   }

package/dist/lib/signing/verifier.mjs

@@ -134,7 +134,7 @@ async function verifyRequestSignature(request, options) {
     }
   } catch (err) {
     if (err instanceof AgentResolverError) {
-      throw new RequestSignatureError(err.code, 7, err.message, err.detail);
+      throw new RequestSignatureError(err.code, 7, err.message, err.detail, err.recovery);
     }
     throw err;
   }

package/dist/lib/signing/webhook-verifier.js

@@ -37,8 +37,8 @@ var import_replay = require('./replay.js');
 var import_revocation = require('./revocation.js');
 var import_types = require('./types.js');
 function keyDiscoveryRetryable(error) {
-  if (error instanceof import_errors2.AgentResolverError) return import_errors.RequestSigningErrorCodeMetadata[error.code].recovery === "transient";
-  if (error instanceof import_brand_jwks.BrandJsonResolverError) return error.code === "fetch_failed";
+  if (error instanceof import_errors2.AgentResolverError) return error.recovery === "transient";
+  if (error instanceof import_brand_jwks.BrandJsonResolverError) return error.recovery === "transient";
   return true;
 }
 const WEBHOOK_SIGNING_TAG = "adcp/webhook-signing/v1";

package/dist/lib/signing/webhook-verifier.mjs

@@ -1,6 +1,6 @@
 import { buildSignatureBase, canonicalTargetUri, getHeaderValue } from "./canonicalize.mjs";
 import { contentDigestMatches } from "./content-digest.mjs";
-import { RequestSignatureError, WebhookSignatureError, RequestSigningErrorCodeMetadata } from "./errors.mjs";
+import { RequestSignatureError, WebhookSignatureError } from "./errors.mjs";
 import { AgentResolverError } from "./agent-resolver/errors.mjs";
 import { BrandJsonResolverError } from "./brand-jwks.mjs";
 import { parseSignature, parseSignatureInput } from "./parser.mjs";
@@ -10,8 +10,8 @@ import { InMemoryReplayStore } from "./replay.mjs";
 import { InMemoryRevocationStore } from "./revocation.mjs";
 import { ALLOWED_ALGS, CLOCK_SKEW_TOLERANCE_SECONDS, MAX_SIGNATURE_WINDOW_SECONDS } from "./types.mjs";
 function keyDiscoveryRetryable(error) {
-  if (error instanceof AgentResolverError) return RequestSigningErrorCodeMetadata[error.code].recovery === "transient";
-  if (error instanceof BrandJsonResolverError) return error.code === "fetch_failed";
+  if (error instanceof AgentResolverError) return error.recovery === "transient";
+  if (error instanceof BrandJsonResolverError) return error.recovery === "transient";
   return true;
 }
 const WEBHOOK_SIGNING_TAG = "adcp/webhook-signing/v1";

package/dist/lib/testing/storyboard/validations.d.mts

@@ -197,7 +197,7 @@ export interface UpstreamTrafficQueryResult {
  */
 export declare function runValidations(validations: StoryboardValidation[], context: ValidationContext): ValidationResult[];
 /** Capability semver emitted in run summaries and used for advisory expiry. */
-export declare const RUNNER_CAPABILITY_VERSION = "14.1.0";
+export declare const RUNNER_CAPABILITY_VERSION = "14.2.0";
 /** True when a failed validation contributes to the owning step's grade. */
 export declare function validationFailsStep(result: ValidationResult): boolean;
 /**

package/dist/lib/testing/storyboard/validations.d.ts

@@ -197,7 +197,7 @@ export interface UpstreamTrafficQueryResult {
  */
 export declare function runValidations(validations: StoryboardValidation[], context: ValidationContext): ValidationResult[];
 /** Capability semver emitted in run summaries and used for advisory expiry. */
-export declare const RUNNER_CAPABILITY_VERSION = "14.1.0";
+export declare const RUNNER_CAPABILITY_VERSION = "14.2.0";
 /** True when a failed validation contributes to the owning step's grade. */
 export declare function validationFailsStep(result: ValidationResult): boolean;
 /**

package/dist/lib/types/accept-proposal.d.ts

@@ -145,6 +145,11 @@ export type ActivationKey = {
  */
 export type AdvertiserIndustry = 'automotive' | 'automotive.electric_vehicles' | 'automotive.parts_accessories' | 'automotive.luxury' | 'beauty_cosmetics' | 'beauty_cosmetics.skincare' | 'beauty_cosmetics.fragrance' | 'beauty_cosmetics.haircare' | 'cannabis' | 'cpg' | 'cpg.personal_care' | 'cpg.household' | 'dating' | 'education' | 'education.higher_education' | 'education.online_learning' | 'education.k12' | 'energy_utilities' | 'energy_utilities.renewable' | 'fashion_apparel' | 'fashion_apparel.luxury' | 'fashion_apparel.sportswear' | 'finance' | 'finance.banking' | 'finance.insurance' | 'finance.investment' | 'finance.cryptocurrency' | 'food_beverage' | 'food_beverage.alcohol' | 'food_beverage.restaurants' | 'food_beverage.packaged_goods' | 'gambling_betting' | 'gambling_betting.sports_betting' | 'gambling_betting.casino' | 'gaming' | 'gaming.mobile' | 'gaming.console_pc' | 'gaming.esports' | 'government_nonprofit' | 'government_nonprofit.political' | 'government_nonprofit.charity' | 'healthcare' | 'healthcare.pharmaceutical' | 'healthcare.medical_devices' | 'healthcare.wellness' | 'home_garden' | 'home_garden.furniture' | 'home_garden.home_improvement' | 'media_entertainment' | 'media_entertainment.podcasts' | 'media_entertainment.music' | 'media_entertainment.film_tv' | 'media_entertainment.publishing' | 'media_entertainment.live_events' | 'pets' | 'professional_services' | 'professional_services.legal' | 'professional_services.consulting' | 'real_estate' | 'real_estate.residential' | 'real_estate.commercial' | 'recruitment_hr' | 'retail' | 'retail.ecommerce' | 'retail.department_stores' | 'sports_fitness' | 'sports_fitness.equipment' | 'sports_fitness.teams_leagues' | 'technology' | 'technology.software' | 'technology.hardware' | 'technology.ai_ml' | 'telecom' | 'telecom.mobile_carriers' | 'telecom.internet_providers' | 'transportation_logistics' | 'travel_hospitality' | 'travel_hospitality.airlines' | 'travel_hospitality.hotels' | 'travel_hospitality.cruise' | 'travel_hospitality.tourism';
 
+/**
+ * User-level bases that may resolve age for demographic targeting execution. Population estimates are deliberately absent because aggregate composition cannot establish an individual impression's age.
+ */
+export type AgeDeterminationBasis = 'verified' | 'declared' | 'inferred';
+
 /**
  * Methods for verifying user age for compliance. Does not include 'inferred' as it is not accepted for regulatory compliance.
  */
@@ -1083,7 +1088,20 @@ export type DemographicSystem = 'nielsen' | 'nielsen_audio' | 'barb' | 'agf' | '
  * Canonical demographic audience targeting intent with optional constraints on how age may be determined. This is distinct from age_restriction: demographics selects an audience, while age_restriction expresses a legal eligibility or verification floor. Fresh create/update targeting MUST compile exactly or be rejected. During get_products, a seller may offer a different configured predicate only through sparse targeting_resolution modifications on a distinguishable product_id; selecting that product accepts the alternative. Sellers never silently broaden, narrow, default, drop, or substitute the basis.
  */
 export interface DemographicTargetingIntent {
-    age: DemographicAgeRange & {};
+    age: DemographicAgeRange & {
+        /**
+         * User-level age determination bases the buyer permits for this predicate. Sellers MUST use only these bases or reject the request; they MUST NOT silently fall back to another basis. When omitted, the buyer imposes no determination-basis constraint beyond product capability and any age_restriction. population_estimate is structurally unavailable because aggregate evidence cannot identify an eligible user.
+         *
+         * @minItems 1
+         */
+        accepted_bases?: [AgeDeterminationBasis, ...AgeDeterminationBasis[]];
+        /**
+         * Verification methods acceptable when verified is an accepted basis. This field narrows verified demographic execution; age_restriction.accepted_methods independently governs legal eligibility and the two sets are intersected when both are present.
+         *
+         * @minItems 1
+         */
+        accepted_verification_methods?: [AgeVerificationMethod, ...AgeVerificationMethod[]];
+    };
 }
 
 /**

package/dist/lib/types/buy-products.d.ts

@@ -145,6 +145,11 @@ export type ActivationKey = {
  */
 export type AdvertiserIndustry = 'automotive' | 'automotive.electric_vehicles' | 'automotive.parts_accessories' | 'automotive.luxury' | 'beauty_cosmetics' | 'beauty_cosmetics.skincare' | 'beauty_cosmetics.fragrance' | 'beauty_cosmetics.haircare' | 'cannabis' | 'cpg' | 'cpg.personal_care' | 'cpg.household' | 'dating' | 'education' | 'education.higher_education' | 'education.online_learning' | 'education.k12' | 'energy_utilities' | 'energy_utilities.renewable' | 'fashion_apparel' | 'fashion_apparel.luxury' | 'fashion_apparel.sportswear' | 'finance' | 'finance.banking' | 'finance.insurance' | 'finance.investment' | 'finance.cryptocurrency' | 'food_beverage' | 'food_beverage.alcohol' | 'food_beverage.restaurants' | 'food_beverage.packaged_goods' | 'gambling_betting' | 'gambling_betting.sports_betting' | 'gambling_betting.casino' | 'gaming' | 'gaming.mobile' | 'gaming.console_pc' | 'gaming.esports' | 'government_nonprofit' | 'government_nonprofit.political' | 'government_nonprofit.charity' | 'healthcare' | 'healthcare.pharmaceutical' | 'healthcare.medical_devices' | 'healthcare.wellness' | 'home_garden' | 'home_garden.furniture' | 'home_garden.home_improvement' | 'media_entertainment' | 'media_entertainment.podcasts' | 'media_entertainment.music' | 'media_entertainment.film_tv' | 'media_entertainment.publishing' | 'media_entertainment.live_events' | 'pets' | 'professional_services' | 'professional_services.legal' | 'professional_services.consulting' | 'real_estate' | 'real_estate.residential' | 'real_estate.commercial' | 'recruitment_hr' | 'retail' | 'retail.ecommerce' | 'retail.department_stores' | 'sports_fitness' | 'sports_fitness.equipment' | 'sports_fitness.teams_leagues' | 'technology' | 'technology.software' | 'technology.hardware' | 'technology.ai_ml' | 'telecom' | 'telecom.mobile_carriers' | 'telecom.internet_providers' | 'transportation_logistics' | 'travel_hospitality' | 'travel_hospitality.airlines' | 'travel_hospitality.hotels' | 'travel_hospitality.cruise' | 'travel_hospitality.tourism';
 
+/**
+ * User-level bases that may resolve age for demographic targeting execution. Population estimates are deliberately absent because aggregate composition cannot establish an individual impression's age.
+ */
+export type AgeDeterminationBasis = 'verified' | 'declared' | 'inferred';
+
 /**
  * Age restriction for compliance. Use for legal requirements (alcohol, gambling), not audience targeting.
  */
@@ -1152,7 +1157,20 @@ export type DemographicSystem = 'nielsen' | 'nielsen_audio' | 'barb' | 'agf' | '
  * Canonical demographic audience targeting intent with optional constraints on how age may be determined. This is distinct from age_restriction: demographics selects an audience, while age_restriction expresses a legal eligibility or verification floor. Fresh create/update targeting MUST compile exactly or be rejected. During get_products, a seller may offer a different configured predicate only through sparse targeting_resolution modifications on a distinguishable product_id; selecting that product accepts the alternative. Sellers never silently broaden, narrow, default, drop, or substitute the basis.
  */
 export interface DemographicTargetingIntent {
-    age: DemographicAgeRange & {};
+    age: DemographicAgeRange & {
+        /**
+         * User-level age determination bases the buyer permits for this predicate. Sellers MUST use only these bases or reject the request; they MUST NOT silently fall back to another basis. When omitted, the buyer imposes no determination-basis constraint beyond product capability and any age_restriction. population_estimate is structurally unavailable because aggregate evidence cannot identify an eligible user.
+         *
+         * @minItems 1
+         */
+        accepted_bases?: [AgeDeterminationBasis, ...AgeDeterminationBasis[]];
+        /**
+         * Verification methods acceptable when verified is an accepted basis. This field narrows verified demographic execution; age_restriction.accepted_methods independently governs legal eligibility and the two sets are intersected when both are present.
+         *
+         * @minItems 1
+         */
+        accepted_verification_methods?: [AgeVerificationMethod, ...AgeVerificationMethod[]];
+    };
 }
 
 /**

package/dist/lib/types/check-governance.d.ts

@@ -445,6 +445,11 @@ export type ActivationKey = {
  */
 export type AdvertiserIndustry = 'automotive' | 'automotive.electric_vehicles' | 'automotive.parts_accessories' | 'automotive.luxury' | 'beauty_cosmetics' | 'beauty_cosmetics.skincare' | 'beauty_cosmetics.fragrance' | 'beauty_cosmetics.haircare' | 'cannabis' | 'cpg' | 'cpg.personal_care' | 'cpg.household' | 'dating' | 'education' | 'education.higher_education' | 'education.online_learning' | 'education.k12' | 'energy_utilities' | 'energy_utilities.renewable' | 'fashion_apparel' | 'fashion_apparel.luxury' | 'fashion_apparel.sportswear' | 'finance' | 'finance.banking' | 'finance.insurance' | 'finance.investment' | 'finance.cryptocurrency' | 'food_beverage' | 'food_beverage.alcohol' | 'food_beverage.restaurants' | 'food_beverage.packaged_goods' | 'gambling_betting' | 'gambling_betting.sports_betting' | 'gambling_betting.casino' | 'gaming' | 'gaming.mobile' | 'gaming.console_pc' | 'gaming.esports' | 'government_nonprofit' | 'government_nonprofit.political' | 'government_nonprofit.charity' | 'healthcare' | 'healthcare.pharmaceutical' | 'healthcare.medical_devices' | 'healthcare.wellness' | 'home_garden' | 'home_garden.furniture' | 'home_garden.home_improvement' | 'media_entertainment' | 'media_entertainment.podcasts' | 'media_entertainment.music' | 'media_entertainment.film_tv' | 'media_entertainment.publishing' | 'media_entertainment.live_events' | 'pets' | 'professional_services' | 'professional_services.legal' | 'professional_services.consulting' | 'real_estate' | 'real_estate.residential' | 'real_estate.commercial' | 'recruitment_hr' | 'retail' | 'retail.ecommerce' | 'retail.department_stores' | 'sports_fitness' | 'sports_fitness.equipment' | 'sports_fitness.teams_leagues' | 'technology' | 'technology.software' | 'technology.hardware' | 'technology.ai_ml' | 'telecom' | 'telecom.mobile_carriers' | 'telecom.internet_providers' | 'transportation_logistics' | 'travel_hospitality' | 'travel_hospitality.airlines' | 'travel_hospitality.hotels' | 'travel_hospitality.cruise' | 'travel_hospitality.tourism';
 
+/**
+ * User-level bases that may resolve age for demographic targeting execution. Population estimates are deliberately absent because aggregate composition cannot establish an individual impression's age.
+ */
+export type AgeDeterminationBasis = 'verified' | 'declared' | 'inferred';
+
 /**
  * Methods for verifying user age for compliance. Does not include 'inferred' as it is not accepted for regulatory compliance.
  */
@@ -1585,7 +1590,20 @@ export type DemographicSystem = 'nielsen' | 'nielsen_audio' | 'barb' | 'agf' | '
  * Canonical demographic audience targeting intent with optional constraints on how age may be determined. This is distinct from age_restriction: demographics selects an audience, while age_restriction expresses a legal eligibility or verification floor. Fresh create/update targeting MUST compile exactly or be rejected. During get_products, a seller may offer a different configured predicate only through sparse targeting_resolution modifications on a distinguishable product_id; selecting that product accepts the alternative. Sellers never silently broaden, narrow, default, drop, or substitute the basis.
  */
 export interface DemographicTargetingIntent {
-    age: DemographicAgeRange & {};
+    age: DemographicAgeRange & {
+        /**
+         * User-level age determination bases the buyer permits for this predicate. Sellers MUST use only these bases or reject the request; they MUST NOT silently fall back to another basis. When omitted, the buyer imposes no determination-basis constraint beyond product capability and any age_restriction. population_estimate is structurally unavailable because aggregate evidence cannot identify an eligible user.
+         *
+         * @minItems 1
+         */
+        accepted_bases?: [AgeDeterminationBasis, ...AgeDeterminationBasis[]];
+        /**
+         * Verification methods acceptable when verified is an accepted basis. This field narrows verified demographic execution; age_restriction.accepted_methods independently governs legal eligibility and the two sets are intersected when both are present.
+         *
+         * @minItems 1
+         */
+        accepted_verification_methods?: [AgeVerificationMethod, ...AgeVerificationMethod[]];
+    };
 }
 
 /**

package/dist/lib/types/comply-test-controller.d.ts

@@ -486,6 +486,11 @@ export interface AdInventoryConfiguration {
     supported_formats?: string[];
 }
 
+/**
+ * User-level bases that may resolve age for demographic targeting execution. Population estimates are deliberately absent because aggregate composition cannot establish an individual impression's age.
+ */
+export type AgeDeterminationBasis = 'verified' | 'declared' | 'inferred';
+
 /**
  * Methods for verifying user age for compliance. Does not include 'inferred' as it is not accepted for regulatory compliance.
  */
@@ -5526,7 +5531,20 @@ export interface DemographicTargetingCapability {
  * Canonical demographic audience targeting intent with optional constraints on how age may be determined. This is distinct from age_restriction: demographics selects an audience, while age_restriction expresses a legal eligibility or verification floor. Fresh create/update targeting MUST compile exactly or be rejected. During get_products, a seller may offer a different configured predicate only through sparse targeting_resolution modifications on a distinguishable product_id; selecting that product accepts the alternative. Sellers never silently broaden, narrow, default, drop, or substitute the basis.
  */
 export interface DemographicTargetingIntent {
-    age: DemographicAgeRange & {};
+    age: DemographicAgeRange & {
+        /**
+         * User-level age determination bases the buyer permits for this predicate. Sellers MUST use only these bases or reject the request; they MUST NOT silently fall back to another basis. When omitted, the buyer imposes no determination-basis constraint beyond product capability and any age_restriction. population_estimate is structurally unavailable because aggregate evidence cannot identify an eligible user.
+         *
+         * @minItems 1
+         */
+        accepted_bases?: [AgeDeterminationBasis, ...AgeDeterminationBasis[]];
+        /**
+         * Verification methods acceptable when verified is an accepted basis. This field narrows verified demographic execution; age_restriction.accepted_methods independently governs legal eligibility and the two sets are intersected when both are present.
+         *
+         * @minItems 1
+         */
+        accepted_verification_methods?: [AgeVerificationMethod, ...AgeVerificationMethod[]];
+    };
 }
 
 /**