@adcp/sdk 14.0.0-rc.32 → 14.0.0-rc.34

package/bin/adcp-storyboard-summary.js

@@ -19,6 +19,7 @@ const { writeFileSync } = require('node:fs');
 
 function escapeMarkdownCell(s) {
   return String(s ?? '')
+    .replace(/\\/g, '\\\\')
     .replace(/\|/g, '\\|')
     .replace(/\n/g, ' ');
 }

package/dist/lib/brand/domain.d.mts

@@ -0,0 +1,30 @@
+export type BrandDomainValidationCode = 'invalid_syntax' | 'not_registrable' | 'special_use_not_allowed';
+export declare class BrandDomainValidationError extends Error {
+    readonly code: BrandDomainValidationCode;
+    readonly domain: string;
+    constructor(code: BrandDomainValidationCode, domain: string);
+}
+export interface ValidateBrandDomainOptions {
+    /**
+     * Admit the protocol's narrow development-name set: subdomains of
+     * `.localhost`, `.test`, `.example`, or `.invalid`, plus the reserved
+     * `example.com`, `example.net`, and `example.org` names. Default false.
+     *
+     * This option is deliberately explicit and is never inferred from
+     * `NODE_ENV`. Bare `localhost` remains invalid because BrandRef wire syntax
+     * always requires a dotted domain. `.local` remains forbidden because it
+     * participates in multicast DNS.
+     */
+    allowDevelopmentDomains?: boolean;
+}
+/**
+ * Validate and canonicalize a BrandRef/BrandKey domain.
+ *
+ * The JSON Schema enforces portable dotted wire syntax. This helper adds the
+ * runtime policy needed before brand discovery: a production name must have a
+ * registrable domain in the pinned ICANN+PRIVATE Public Suffix List and must
+ * not be an IANA special-use name.
+ */
+export declare function validateBrandDomain(domain: string, options?: ValidateBrandDomainOptions): string;
+export declare function isDevelopmentBrandDomain(domain: string): boolean;
+export declare function isSpecialUseBrandDomain(domain: string): boolean;

package/dist/lib/brand/domain.d.ts

@@ -0,0 +1,30 @@
+export type BrandDomainValidationCode = 'invalid_syntax' | 'not_registrable' | 'special_use_not_allowed';
+export declare class BrandDomainValidationError extends Error {
+    readonly code: BrandDomainValidationCode;
+    readonly domain: string;
+    constructor(code: BrandDomainValidationCode, domain: string);
+}
+export interface ValidateBrandDomainOptions {
+    /**
+     * Admit the protocol's narrow development-name set: subdomains of
+     * `.localhost`, `.test`, `.example`, or `.invalid`, plus the reserved
+     * `example.com`, `example.net`, and `example.org` names. Default false.
+     *
+     * This option is deliberately explicit and is never inferred from
+     * `NODE_ENV`. Bare `localhost` remains invalid because BrandRef wire syntax
+     * always requires a dotted domain. `.local` remains forbidden because it
+     * participates in multicast DNS.
+     */
+    allowDevelopmentDomains?: boolean;
+}
+/**
+ * Validate and canonicalize a BrandRef/BrandKey domain.
+ *
+ * The JSON Schema enforces portable dotted wire syntax. This helper adds the
+ * runtime policy needed before brand discovery: a production name must have a
+ * registrable domain in the pinned ICANN+PRIVATE Public Suffix List and must
+ * not be an IANA special-use name.
+ */
+export declare function validateBrandDomain(domain: string, options?: ValidateBrandDomainOptions): string;
+export declare function isDevelopmentBrandDomain(domain: string): boolean;
+export declare function isSpecialUseBrandDomain(domain: string): boolean;

package/dist/lib/brand/domain.js

@@ -0,0 +1,109 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var domain_exports = {};
+__export(domain_exports, {
+  BrandDomainValidationError: () => BrandDomainValidationError,
+  isDevelopmentBrandDomain: () => isDevelopmentBrandDomain,
+  isSpecialUseBrandDomain: () => isSpecialUseBrandDomain,
+  validateBrandDomain: () => validateBrandDomain
+});
+module.exports = __toCommonJS(domain_exports);
+var import_tldts = require("tldts");
+var import_canonicalize = require('../signing/agent-resolver/canonicalize.js');
+const DOTTED_WIRE_DOMAIN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/;
+const DEVELOPMENT_SUFFIXES = ["localhost", "test", "example", "invalid"];
+const DEVELOPMENT_EXACT_NAMES = /* @__PURE__ */ new Set(["example.com", "example.net", "example.org"]);
+const SPECIAL_USE_SUFFIXES = [
+  "alt",
+  "6tisch.arpa",
+  "eap.arpa",
+  "eap-noob.arpa",
+  "home.arpa",
+  "in-addr.arpa",
+  "ip6.arpa",
+  "ipv4only.arpa",
+  "resolver.arpa",
+  "service.arpa",
+  "example",
+  "example.com",
+  "example.net",
+  "example.org",
+  "invalid",
+  "local",
+  "localhost",
+  "onion",
+  "test"
+];
+class BrandDomainValidationError extends Error {
+  constructor(code, domain) {
+    const messages = {
+      invalid_syntax: "Brand domain must be a bare, lowercase-compatible dotted hostname",
+      not_registrable: "Brand domain must have a registrable public or private-suffix domain",
+      special_use_not_allowed: "IANA special-use brand domain is not allowed in production"
+    };
+    super(messages[code]);
+    this.code = code;
+    this.domain = domain;
+    this.name = "BrandDomainValidationError";
+  }
+  code;
+  domain;
+}
+function validateBrandDomain(domain, options = {}) {
+  if (typeof domain !== "string" || domain.length === 0 || /[\s/:@?#]/.test(domain)) {
+    throw new BrandDomainValidationError("invalid_syntax", domain);
+  }
+  let canonical;
+  try {
+    canonical = (0, import_canonicalize.canonicalizeHost)(domain);
+  } catch {
+    throw new BrandDomainValidationError("invalid_syntax", domain);
+  }
+  if (!DOTTED_WIRE_DOMAIN.test(canonical)) {
+    throw new BrandDomainValidationError("invalid_syntax", domain);
+  }
+  const developmentName = isDevelopmentBrandDomain(canonical);
+  if (developmentName && options.allowDevelopmentDomains === true) return canonical;
+  const parsed = (0, import_tldts.parse)(canonical, {
+    allowPrivateDomains: true,
+    detectSpecialUse: true,
+    extractHostname: false
+  });
+  if (parsed.isSpecialUse || developmentName || isSpecialUseBrandDomain(canonical)) {
+    throw new BrandDomainValidationError("special_use_not_allowed", domain);
+  }
+  if (parsed.isIp || !parsed.domain || !parsed.isIcann && !parsed.isPrivate) {
+    throw new BrandDomainValidationError("not_registrable", domain);
+  }
+  return canonical;
+}
+function isDevelopmentBrandDomain(domain) {
+  if (DEVELOPMENT_EXACT_NAMES.has(domain)) return true;
+  return DEVELOPMENT_SUFFIXES.some((suffix) => domain.endsWith(`.${suffix}`));
+}
+function isSpecialUseBrandDomain(domain) {
+  return SPECIAL_USE_SUFFIXES.some((suffix) => domain === suffix || domain.endsWith(`.${suffix}`));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BrandDomainValidationError,
+  isDevelopmentBrandDomain,
+  isSpecialUseBrandDomain,
+  validateBrandDomain
+});

package/dist/lib/brand/domain.mjs

@@ -0,0 +1,82 @@
+import { parse as parseTld } from "tldts";
+import { canonicalizeHost } from "../signing/agent-resolver/canonicalize.mjs";
+const DOTTED_WIRE_DOMAIN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/;
+const DEVELOPMENT_SUFFIXES = ["localhost", "test", "example", "invalid"];
+const DEVELOPMENT_EXACT_NAMES = /* @__PURE__ */ new Set(["example.com", "example.net", "example.org"]);
+const SPECIAL_USE_SUFFIXES = [
+  "alt",
+  "6tisch.arpa",
+  "eap.arpa",
+  "eap-noob.arpa",
+  "home.arpa",
+  "in-addr.arpa",
+  "ip6.arpa",
+  "ipv4only.arpa",
+  "resolver.arpa",
+  "service.arpa",
+  "example",
+  "example.com",
+  "example.net",
+  "example.org",
+  "invalid",
+  "local",
+  "localhost",
+  "onion",
+  "test"
+];
+class BrandDomainValidationError extends Error {
+  constructor(code, domain) {
+    const messages = {
+      invalid_syntax: "Brand domain must be a bare, lowercase-compatible dotted hostname",
+      not_registrable: "Brand domain must have a registrable public or private-suffix domain",
+      special_use_not_allowed: "IANA special-use brand domain is not allowed in production"
+    };
+    super(messages[code]);
+    this.code = code;
+    this.domain = domain;
+    this.name = "BrandDomainValidationError";
+  }
+  code;
+  domain;
+}
+function validateBrandDomain(domain, options = {}) {
+  if (typeof domain !== "string" || domain.length === 0 || /[\s/:@?#]/.test(domain)) {
+    throw new BrandDomainValidationError("invalid_syntax", domain);
+  }
+  let canonical;
+  try {
+    canonical = canonicalizeHost(domain);
+  } catch {
+    throw new BrandDomainValidationError("invalid_syntax", domain);
+  }
+  if (!DOTTED_WIRE_DOMAIN.test(canonical)) {
+    throw new BrandDomainValidationError("invalid_syntax", domain);
+  }
+  const developmentName = isDevelopmentBrandDomain(canonical);
+  if (developmentName && options.allowDevelopmentDomains === true) return canonical;
+  const parsed = parseTld(canonical, {
+    allowPrivateDomains: true,
+    detectSpecialUse: true,
+    extractHostname: false
+  });
+  if (parsed.isSpecialUse || developmentName || isSpecialUseBrandDomain(canonical)) {
+    throw new BrandDomainValidationError("special_use_not_allowed", domain);
+  }
+  if (parsed.isIp || !parsed.domain || !parsed.isIcann && !parsed.isPrivate) {
+    throw new BrandDomainValidationError("not_registrable", domain);
+  }
+  return canonical;
+}
+function isDevelopmentBrandDomain(domain) {
+  if (DEVELOPMENT_EXACT_NAMES.has(domain)) return true;
+  return DEVELOPMENT_SUFFIXES.some((suffix) => domain.endsWith(`.${suffix}`));
+}
+function isSpecialUseBrandDomain(domain) {
+  return SPECIAL_USE_SUFFIXES.some((suffix) => domain === suffix || domain.endsWith(`.${suffix}`));
+}
+export {
+  BrandDomainValidationError,
+  isDevelopmentBrandDomain,
+  isSpecialUseBrandDomain,
+  validateBrandDomain
+};

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

@@ -1,5 +1,7 @@
 import type { RegistryClient, SaveBrandResponse } from '../registry/index.mjs';
 import type { GetBrandIdentitySuccess } from '../types/core.generated.mjs';
+export { BrandDomainValidationError, isDevelopmentBrandDomain, validateBrandDomain } from './domain.mjs';
+export type { BrandDomainValidationCode, ValidateBrandDomainOptions } from './domain.mjs';
 export type BrandJsonRecord = Record<string, unknown>;
 type ProtocolBrandLogo = NonNullable<GetBrandIdentitySuccess['logos']>[number];
 export type BrandWebsiteAliasRelationship = 'owned';
@@ -148,4 +150,3 @@ export declare function checkLogoSlotCoverage(brandJsonOrBrand: BrandJsonRecord,
 export declare function updateBrandJsonFromMappings(options: UpdateBrandJsonFromMappingsOptions): Promise<UpdateBrandJsonFromMappingsResult>;
 export declare function extractBrandWebsiteAliases(brandJsonOrBrand: BrandJsonRecord, options?: ExtractBrandWebsiteAliasesOptions): BrandWebsiteAlias[];
 export declare function extractBrandWebsiteAliasDomains(brandJsonOrBrand: BrandJsonRecord, options?: ExtractBrandWebsiteAliasesOptions): string[];
-export {};

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

@@ -1,5 +1,7 @@
 import type { RegistryClient, SaveBrandResponse } from '../registry';
 import type { GetBrandIdentitySuccess } from '../types/core.generated';
+export { BrandDomainValidationError, isDevelopmentBrandDomain, validateBrandDomain } from './domain';
+export type { BrandDomainValidationCode, ValidateBrandDomainOptions } from './domain';
 export type BrandJsonRecord = Record<string, unknown>;
 type ProtocolBrandLogo = NonNullable<GetBrandIdentitySuccess['logos']>[number];
 export type BrandWebsiteAliasRelationship = 'owned';
@@ -148,4 +150,3 @@ export declare function checkLogoSlotCoverage(brandJsonOrBrand: BrandJsonRecord,
 export declare function updateBrandJsonFromMappings(options: UpdateBrandJsonFromMappingsOptions): Promise<UpdateBrandJsonFromMappingsResult>;
 export declare function extractBrandWebsiteAliases(brandJsonOrBrand: BrandJsonRecord, options?: ExtractBrandWebsiteAliasesOptions): BrandWebsiteAlias[];
 export declare function extractBrandWebsiteAliasDomains(brandJsonOrBrand: BrandJsonRecord, options?: ExtractBrandWebsiteAliasesOptions): string[];
-export {};

package/dist/lib/brand/index.js

@@ -18,16 +18,20 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var brand_exports = {};
 __export(brand_exports, {
+  BrandDomainValidationError: () => import_domain.BrandDomainValidationError,
   COMMON_LOGO_SLOTS: () => COMMON_LOGO_SLOTS,
   applyBrandAssetMappings: () => applyBrandAssetMappings,
   checkLogoSlotCoverage: () => checkLogoSlotCoverage,
   extractBrandWebsiteAliasDomains: () => extractBrandWebsiteAliasDomains,
   extractBrandWebsiteAliases: () => extractBrandWebsiteAliases,
+  isDevelopmentBrandDomain: () => import_domain.isDevelopmentBrandDomain,
   selectLogoForSlot: () => selectLogoForSlot,
   updateBrandJsonFromMappings: () => updateBrandJsonFromMappings,
-  validateBrandAssetMappings: () => validateBrandAssetMappings
+  validateBrandAssetMappings: () => validateBrandAssetMappings,
+  validateBrandDomain: () => import_domain.validateBrandDomain
 });
 module.exports = __toCommonJS(brand_exports);
+var import_domain = require('./domain.js');
 const COMMON_LOGO_SLOTS = [
   "logo_card_light",
   "logo_card_dark",
@@ -464,12 +468,15 @@ function readLocalizedName(value) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BrandDomainValidationError,
   COMMON_LOGO_SLOTS,
   applyBrandAssetMappings,
   checkLogoSlotCoverage,
   extractBrandWebsiteAliasDomains,
   extractBrandWebsiteAliases,
+  isDevelopmentBrandDomain,
   selectLogoForSlot,
   updateBrandJsonFromMappings,
-  validateBrandAssetMappings
+  validateBrandAssetMappings,
+  validateBrandDomain
 });

package/dist/lib/brand/index.mjs

@@ -1,3 +1,4 @@
+import { BrandDomainValidationError, isDevelopmentBrandDomain, validateBrandDomain } from "./domain.mjs";
 const COMMON_LOGO_SLOTS = [
   "logo_card_light",
   "logo_card_dark",
@@ -433,12 +434,15 @@ function readLocalizedName(value) {
   return void 0;
 }
 export {
+  BrandDomainValidationError,
   COMMON_LOGO_SLOTS,
   applyBrandAssetMappings,
   checkLogoSlotCoverage,
   extractBrandWebsiteAliasDomains,
   extractBrandWebsiteAliases,
+  isDevelopmentBrandDomain,
   selectLogoForSlot,
   updateBrandJsonFromMappings,
-  validateBrandAssetMappings
+  validateBrandAssetMappings,
+  validateBrandDomain
 };

package/dist/lib/conformance/oracle.js

@@ -56,17 +56,33 @@ const STACK_TRACE_REGEXES = [
   /\.go:\d+ \+0x[0-9a-f]+/,
   // PHP: `#7 /var/www/foo.php(42): Bar->baz()` — numbered frame with file:line
   /#\d+ [^\s]+\.php\(\d+\):/,
-  // JVM: `\n\tat com.foo.Bar.method(Bar.java:42)` — fully-qualified
-  // method with source:line. Anchored to whitespace/newline so an
-  // echoed Javadoc reference in prose (`"at com.foo.Bar(Bar.java:42)"`)
-  // doesn't trigger the detector — real stack frames sit on their own
-  // indented line.
-  /(?:\\n\s*|^\s+|\n\s+)at [\w$.]+\.[\w$]+\([\w$]+\.(?:java|kt|kts|scala|groovy):\d+\)/,
   // .NET: `at Foo.Bar.Baz() in /path/to/X.cs:line 42` — method invocation
   // followed by ` in ` and a file:line marker. The method-name charset
   // includes parens/brackets for generic and overloaded signatures.
   /at [\w.<>`,()[\]]+ in [^:\s]+\.(?:cs|vb|fs):line \d+/
 ];
+const JVM_STACK_FRAME = /^at [\w$.]+\.[\w$]+\([\w$]+\.(?:java|kt|kts|scala|groovy):\d+\)\s*/;
+function isJsonFramingSuffix(value) {
+  if (!value.startsWith('"')) return false;
+  for (let index = 1; index < value.length; index++) {
+    const char = value[index];
+    if (char !== "}" && char !== "]" && char !== "," && char !== " " && char !== "	") return false;
+  }
+  return true;
+}
+function hasJvmStackFrame(haystack) {
+  const lines = haystack.replaceAll("\\n", "\n").split("\n");
+  for (const [index, line] of lines.entries()) {
+    const candidate = line.trimStart();
+    if (index > 0 || candidate !== line) {
+      const match = JVM_STACK_FRAME.exec(candidate);
+      if (match && (match[0].length === candidate.length || isJsonFramingSuffix(candidate.slice(match[0].length)))) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
 const FS_PATH_SIGNATURES = [/\/Users\/[^ "']+/, /\/home\/[^ "']+/, /[A-Z]:\\\\Users\\\\/];
 let cachedAjv = null;
 function getAjv() {
@@ -160,6 +176,10 @@ function checkNoStackLeak(result, failures) {
       return;
     }
   }
+  if (hasJvmStackFrame(haystack)) {
+    failures.push(`stack trace leak (matched ${JVM_STACK_FRAME.source})`);
+    return;
+  }
   for (const rx of STACK_TRACE_REGEXES) {
     if (rx.test(haystack)) {
       failures.push(`stack trace leak (matched ${rx.source})`);

package/dist/lib/conformance/oracle.mjs

@@ -22,17 +22,33 @@ const STACK_TRACE_REGEXES = [
   /\.go:\d+ \+0x[0-9a-f]+/,
   // PHP: `#7 /var/www/foo.php(42): Bar->baz()` — numbered frame with file:line
   /#\d+ [^\s]+\.php\(\d+\):/,
-  // JVM: `\n\tat com.foo.Bar.method(Bar.java:42)` — fully-qualified
-  // method with source:line. Anchored to whitespace/newline so an
-  // echoed Javadoc reference in prose (`"at com.foo.Bar(Bar.java:42)"`)
-  // doesn't trigger the detector — real stack frames sit on their own
-  // indented line.
-  /(?:\\n\s*|^\s+|\n\s+)at [\w$.]+\.[\w$]+\([\w$]+\.(?:java|kt|kts|scala|groovy):\d+\)/,
   // .NET: `at Foo.Bar.Baz() in /path/to/X.cs:line 42` — method invocation
   // followed by ` in ` and a file:line marker. The method-name charset
   // includes parens/brackets for generic and overloaded signatures.
   /at [\w.<>`,()[\]]+ in [^:\s]+\.(?:cs|vb|fs):line \d+/
 ];
+const JVM_STACK_FRAME = /^at [\w$.]+\.[\w$]+\([\w$]+\.(?:java|kt|kts|scala|groovy):\d+\)\s*/;
+function isJsonFramingSuffix(value) {
+  if (!value.startsWith('"')) return false;
+  for (let index = 1; index < value.length; index++) {
+    const char = value[index];
+    if (char !== "}" && char !== "]" && char !== "," && char !== " " && char !== "	") return false;
+  }
+  return true;
+}
+function hasJvmStackFrame(haystack) {
+  const lines = haystack.replaceAll("\\n", "\n").split("\n");
+  for (const [index, line] of lines.entries()) {
+    const candidate = line.trimStart();
+    if (index > 0 || candidate !== line) {
+      const match = JVM_STACK_FRAME.exec(candidate);
+      if (match && (match[0].length === candidate.length || isJsonFramingSuffix(candidate.slice(match[0].length)))) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
 const FS_PATH_SIGNATURES = [/\/Users\/[^ "']+/, /\/home\/[^ "']+/, /[A-Z]:\\\\Users\\\\/];
 let cachedAjv = null;
 function getAjv() {
@@ -126,6 +142,10 @@ function checkNoStackLeak(result, failures) {
       return;
     }
   }
+  if (hasJvmStackFrame(haystack)) {
+    failures.push(`stack trace leak (matched ${JVM_STACK_FRAME.source})`);
+    return;
+  }
   for (const rx of STACK_TRACE_REGEXES) {
     if (rx.test(haystack)) {
       failures.push(`stack trace leak (matched ${rx.source})`);

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

@@ -345,6 +345,20 @@ export interface AdcpErrorInfo {
      * the field, `'enum'` → pick a valid value, `'type'` → fix the value type.
      */
     issues?: AdcpValidationIssue[];
+    /**
+     * Buyer-actionable classification of the failure. Present when the enclosing
+     * `code`/`message` is too coarse or carries producer-internal context that
+     * must not cross the buyer trust boundary. `code` reuses the standard error
+     * vocabulary; `message` is buyer-safe by spec — no vendor identifiers,
+     * ad-server type names, internal object names, internal IDs, or stack traces
+     * — so it may be rendered directly to a buyer UI. When present, the
+     * enclosing `recovery` classifies the buyer-actionable reason. See
+     * `core/error.json`'s `buyer_reason` field for the normative contract.
+     */
+    buyer_reason?: {
+        code: string;
+        message: string;
+    };
     /** True when the SDK inferred this error from unstructured text (L1 compliance) */
     synthetic?: boolean;
 }

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

@@ -345,6 +345,20 @@ export interface AdcpErrorInfo {
      * the field, `'enum'` → pick a valid value, `'type'` → fix the value type.
      */
     issues?: AdcpValidationIssue[];
+    /**
+     * Buyer-actionable classification of the failure. Present when the enclosing
+     * `code`/`message` is too coarse or carries producer-internal context that
+     * must not cross the buyer trust boundary. `code` reuses the standard error
+     * vocabulary; `message` is buyer-safe by spec — no vendor identifiers,
+     * ad-server type names, internal object names, internal IDs, or stack traces
+     * — so it may be rendered directly to a buyer UI. When present, the
+     * enclosing `recovery` classifies the buyer-actionable reason. See
+     * `core/error.json`'s `buyer_reason` field for the normative contract.
+     */
+    buyer_reason?: {
+        code: string;
+        message: string;
+    };
     /** True when the SDK inferred this error from unstructured text (L1 compliance) */
     synthetic?: boolean;
 }

package/dist/lib/core/SingleAgentClient.js

@@ -5488,6 +5488,8 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       ...options?.signal && { signal: options.signal },
       ...clientRequestTimeoutMs !== void 0 && { timeout: clientRequestTimeoutMs }
     };
+    const discoveryAdcpVersion = this.getWireAdcpVersion();
+    const mcpListParams = (0, import_version.parseAdcpMajorVersion)(discoveryAdcpVersion) >= 3 ? { _meta: { adcp_version: (0, import_version.toReleasePrecisionVersion)(discoveryAdcpVersion) } } : void 0;
     const ensureReadAuthToken = async () => {
       if (!this.normalizedAgent.oauth_client_credentials) return this.normalizedAgent.auth_token;
       const { ensureClientCredentialsTokens, getAgentStorage } = await import("../auth/oauth/index.js");
@@ -5504,7 +5506,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         const mcpClient2 = this.normalizedAgent._inProcessMcpClient;
         const toolsList = await withResponseSizeLimit(
           maxResponseBytes,
-          () => mcpClient2.listTools(void 0, mcpRequestOptions)
+          () => mcpClient2.listTools(mcpListParams, mcpRequestOptions)
         );
         const tools = toolsList.tools.map((tool) => ({
           name: tool.name,
@@ -5557,6 +5559,9 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         maxResponseBytes,
         () => tryListModernMCPTools(agent.agent_uri, readAuthToken, this.normalizedAgent.headers, {
           authProvider,
+          ...mcpListParams?._meta.adcp_version !== void 0 && {
+            adcpVersion: mcpListParams._meta.adcp_version
+          },
           signal: options?.signal,
           requestTimeoutMs: transport?.requestTimeoutMs,
           fetchFn: transport?.trustedFetchFn,
@@ -5582,7 +5587,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       try {
         const toolsList = await withResponseSizeLimit(
           maxResponseBytes,
-          () => mcpClient.listTools(void 0, mcpRequestOptions)
+          () => mcpClient.listTools(mcpListParams, mcpRequestOptions)
         );
         const tools = toolsList.tools.map((tool) => ({
           name: tool.name,

package/dist/lib/core/SingleAgentClient.mjs

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import * as schemas from "../types/schemas.generated.mjs";
 import { ADCP_ENVELOPE_FIELDS } from "../types/adcp.mjs";
-import { parseAdcpMajorVersion } from "../version.mjs";
+import { parseAdcpMajorVersion, toReleasePrecisionVersion } from "../version.mjs";
 import {
   isAdcpVersionSupported,
   isAdcpVersionAtLeast,
@@ -5542,6 +5542,8 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       ...options?.signal && { signal: options.signal },
       ...clientRequestTimeoutMs !== void 0 && { timeout: clientRequestTimeoutMs }
     };
+    const discoveryAdcpVersion = this.getWireAdcpVersion();
+    const mcpListParams = parseAdcpMajorVersion(discoveryAdcpVersion) >= 3 ? { _meta: { adcp_version: toReleasePrecisionVersion(discoveryAdcpVersion) } } : void 0;
     const ensureReadAuthToken = async () => {
       if (!this.normalizedAgent.oauth_client_credentials) return this.normalizedAgent.auth_token;
       const { ensureClientCredentialsTokens, getAgentStorage } = await import("../auth/oauth/index.mjs");
@@ -5558,7 +5560,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         const mcpClient2 = this.normalizedAgent._inProcessMcpClient;
         const toolsList = await withResponseSizeLimit(
           maxResponseBytes,
-          () => mcpClient2.listTools(void 0, mcpRequestOptions)
+          () => mcpClient2.listTools(mcpListParams, mcpRequestOptions)
         );
         const tools = toolsList.tools.map((tool) => ({
           name: tool.name,
@@ -5611,6 +5613,9 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         maxResponseBytes,
         () => tryListModernMCPTools(agent.agent_uri, readAuthToken, this.normalizedAgent.headers, {
           authProvider,
+          ...mcpListParams?._meta.adcp_version !== void 0 && {
+            adcpVersion: mcpListParams._meta.adcp_version
+          },
           signal: options?.signal,
           requestTimeoutMs: transport?.requestTimeoutMs,
           fetchFn: transport?.trustedFetchFn,
@@ -5636,7 +5641,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       try {
         const toolsList = await withResponseSizeLimit(
           maxResponseBytes,
-          () => mcpClient.listTools(void 0, mcpRequestOptions)
+          () => mcpClient.listTools(mcpListParams, mcpRequestOptions)
         );
         const tools = toolsList.tools.map((tool) => ({
           name: tool.name,

package/dist/lib/core/TaskExecutor.js

@@ -1673,6 +1673,9 @@ class TaskExecutor {
   }
   externalTaskObservationKey(observation) {
     return (0, import_crypto.createHmac)("sha256", EXTERNAL_TASK_OBSERVATION_HMAC_KEY).update(
+      // This keyed digest deduplicates canonical task observations; it does
+      // not store or verify passwords. Agent responses are over-tainted.
+      // codeql[js/insufficient-password-hash]
       (0, import_jcs.canonicalize)({
         status: observation.status,
         serverTaskId: observation.serverTaskId ?? null,

package/dist/lib/core/TaskExecutor.mjs

@@ -1647,6 +1647,9 @@ class TaskExecutor {
   }
   externalTaskObservationKey(observation) {
     return createHmac("sha256", EXTERNAL_TASK_OBSERVATION_HMAC_KEY).update(
+      // This keyed digest deduplicates canonical task observations; it does
+      // not store or verify passwords. Agent responses are over-tainted.
+      // codeql[js/insufficient-password-hash]
       canonicalize({
         status: observation.status,
         serverTaskId: observation.serverTaskId ?? null,

package/dist/lib/index.d.mts

@@ -2,8 +2,8 @@ export { RegistryClient, RegistryRequestError, isRegistryRequestError, RegistryS
 export type { RegistrySyncConfig, RegistrySyncState, RegistrySyncTransport, RegistrySyncEvents, AgentFilter, RegistrySyncProperty, CursorStore, PropertyRegistryConfig, FeedStreamQuery, FeedStreamMessage, FeedHeartbeat, FeedStreamErrorData, OpenFeedStreamOptions, FeedFreshness, } from './registry/index.mjs';
 export { openFeedStream, parseSseStream, sanitizeStreamText, DEFAULT_MAX_SSE_FRAME_BYTES, FeedStreamError, FeedStreamUnsupportedError, FeedStreamCursorExpiredError, FeedStreamHttpError, FeedStreamParseError, } from './registry/index.mjs';
 export type { ResolvedBrand, LookupBrandOptions, ResolvedProperty as ResolvedRegistryProperty, PropertyInfo, RegistryClientConfig, SaveBrandRequest, SaveBrandResponse, BrandLogoReviewStatus, ApprovedBrandLogoAsset, PendingBrandLogoAsset, ReviewedBrandLogoAsset, BrandLogoAsset, ListBrandLogosOptions, ListBrandLogosResponse, SaveBrandLogoInput, SaveBrandLogoResponse, UploadBrandLogoInput, UploadBrandLogoResponse, SavePropertyIdentity, RegistryPropertyIdentity, SavePropertyRequest, SavePropertyResponse, ResolveIdentifiersRequest, ResolveIdentifiersResponse, FileCatalogDisputeRequest, FileCatalogDisputeResponse, GetCatalogDisputeResponse, BrandRegistryItem, PropertyRegistryItem, ValidationResult as RegistryValidationResult, FederatedAgentWithDetails, FederatedPublisher, DomainLookupResult, ListBrandsOptions, ListBrandsResponse, GetBrandJsonResponse, ListOptions, ListAgentsOptions, ListAgentsResponse, ListPublishersResponse, ValidateAdagentsRequest, ValidateAdagentsResponse, CreateAdagentsRequest, CreateAdagentsResponse, AdagentsAuthorizedAgent, AdagentsCatalogFormat, AdagentsPlacementDefinition, AdagentsPlacementFormatReference, AdagentsPlacementFormatOption, AdagentsPlacementTag, CreatedAdagentsJson, CommunityMirrorAdagentsConfig, CreateCommunityMirrorAdagentsConfig, CommunityMirrorAdagentsCatalog, PublishCommunityMirrorAdagentsResponse, CommunityMirrorAdagentsSummary, ListCommunityMirrorAdagentsResponse, GetCommunityMirrorAdagentsResponse, PublishCommunityMirrorAdagentsRequest, PublishCommunityMirrorAdagentsError, DeleteCommunityMirrorAdagentsResponse, PublisherPropertySelector, CompanySearchResult, FindCompanyResult, ManagerRevalidationRequest, ManagerRevalidationResponse, ListPoliciesQuery, ListPoliciesResponse, ResolvePolicyQuery, ResolvePolicyResponse, ResolvePoliciesBulkRequest, ResolvePoliciesBulkResponse, GetPolicyHistoryQuery, GetPolicyHistoryResponse, SavePolicyRequest, SavePolicyResponse, GetBrandHistoryQuery, GetBrandHistoryResponse, GetPropertyHistoryQuery, GetPropertyHistoryResponse, RegistryFeedEvent, AgentEventPayload, PropertyEventPayload, CollectionEventPayload, AuthorizationEventPayload, PublisherEventPayload, BrandEventPayload, CatalogBrowseResponse, CatalogBrowseEntry, CatalogSyncResponse, CatalogSyncEntry, AgentCompliance, AgentComplianceDetail, StoryboardStatus, OperatorLookupResult, PublisherLookupResult, ComplianceChangedPayload, GetAgentStoryboardStatusResponse, GetAgentStoryboardStatusBulkResponse, } from './registry/index.mjs';
-export { COMMON_LOGO_SLOTS, applyBrandAssetMappings, checkLogoSlotCoverage, extractBrandWebsiteAliasDomains, extractBrandWebsiteAliases, selectLogoForSlot, updateBrandJsonFromMappings, validateBrandAssetMappings, } from './brand/index.mjs';
-export type { AppliedBrandAssetMapping, ApplyBrandAssetMappingsOptions, ApplyBrandAssetMappingsResult, BrandAssetCandidate, BrandAssetCropBox, BrandAssetExtractionMethod, BrandAssetMapping, BrandAssetMappingIssue, BrandAssetMappingTarget, BrandAssetMappingValidationResult, BrandAssetReviewStatus, BrandWebsiteAlias, BrandWebsiteAliasRelationship, BrandWebsiteAliasSource, BrandJsonRecord, BrandLogoBackground, BrandLogoOrientation, BrandLogoProposal, BrandLogoVariant, ExtractBrandWebsiteAliasesOptions, LogoSelectionOptions, LogoSlotCoverage, LogoSlotCoverageOptions, ResolveBrandAssetUrl, SkippedBrandAssetMapping, UpdateBrandJsonFromMappingsOptions, UpdateBrandJsonFromMappingsResult, } from './brand/index.mjs';
+export { COMMON_LOGO_SLOTS, BrandDomainValidationError, applyBrandAssetMappings, checkLogoSlotCoverage, extractBrandWebsiteAliasDomains, extractBrandWebsiteAliases, isDevelopmentBrandDomain, selectLogoForSlot, updateBrandJsonFromMappings, validateBrandAssetMappings, validateBrandDomain, } from './brand/index.mjs';
+export type { AppliedBrandAssetMapping, ApplyBrandAssetMappingsOptions, ApplyBrandAssetMappingsResult, BrandAssetCandidate, BrandAssetCropBox, BrandAssetExtractionMethod, BrandAssetMapping, BrandAssetMappingIssue, BrandAssetMappingTarget, BrandAssetMappingValidationResult, BrandAssetReviewStatus, BrandWebsiteAlias, BrandWebsiteAliasRelationship, BrandWebsiteAliasSource, BrandJsonRecord, BrandDomainValidationCode, BrandLogoBackground, BrandLogoOrientation, BrandLogoProposal, BrandLogoVariant, ExtractBrandWebsiteAliasesOptions, LogoSelectionOptions, LogoSlotCoverage, LogoSlotCoverageOptions, ResolveBrandAssetUrl, SkippedBrandAssetMapping, UpdateBrandJsonFromMappingsOptions, UpdateBrandJsonFromMappingsResult, ValidateBrandDomainOptions, } from './brand/index.mjs';
 export { PropertyIndex, getPropertyIndex, resetPropertyIndex, type PropertyMatch, type AgentAuthorization, } from './discovery/property-index.mjs';
 export { PropertyCrawler, type AgentInfo, type CrawlResult, type PropertyCrawlerConfig, } from './discovery/property-crawler.mjs';
 export { NetworkConsistencyChecker, type NetworkConsistencyCheckerConfig, type NetworkCheckReport, type CheckSummary, type CheckProgress, type OrphanedPointer, type StalePointer, type MissingPointer, type SchemaError, type AgentHealthResult, type DomainDetail, type DomainStatus, } from './discovery/network-consistency-checker.mjs';
@@ -163,7 +163,7 @@ export type { Error as TaskErrorDetail } from './types/core.generated.mjs';
 export { STANDARD_ERROR_CODES, isStandardErrorCode, getErrorRecovery } from './types/error-codes.mjs';
 export type { StandardErrorCode, ErrorRecovery } from './types/error-codes.mjs';
 export { adcpError, legacyCapabilitiesResponse, legacyProductsResponse, legacyMediaBuyResponse, legacyDeliveryResponse, legacyListAccountsResponse, legacyListCreativeFormatsResponse, legacyUpdateMediaBuyResponse, legacyGetMediaBuysResponse, legacyPerformanceFeedbackResponse, legacyBuildCreativeResponse, legacyBuildCreativeMultiResponse, legacyPreviewCreativeResponse, legacyCreativeDeliveryResponse, legacyListCreativesResponse, legacyListPropertyListsResponse, legacyListCollectionListsResponse, legacyListContentStandardsResponse, legacyGetPlanAuditLogsResponse, legacySyncCreativesResponse, legacyGetSignalsResponse, legacyActivateSignalResponse, legacyCancelMediaBuyResponse, legacyAcquireRightsResponse, legacyAcquireRightsAcquired, legacyAcquireRightsPendingApproval, legacyAcquireRightsRejected, legacySyncAccountsResponse, legacySyncGovernanceResponse, legacyReportUsageResponse, validActionsForStatus, MEDIA_BUY_TRANSITIONS, CREATIVE_ASSET_TRANSITIONS, isLegalMediaBuyTransition, isLegalCreativeTransition, assertMediaBuyTransition, assertCreativeTransition, getAccountMode, isSandboxOrMockAccount, assertSandboxAccount, taskToolResponse, registerAdcpTaskTool, createTaskCapableServer, InMemoryTaskStore, isTerminal, serve, taskScopeFromPrincipal, UnknownHostError, hostname, resolveHost, verifyIntrospection, registerTestController, handleTestControllerRequest, TestControllerError, toMcpResponse, TOOL_INPUT_SHAPE, CONTROLLER_SCENARIOS, DISCOVERY_ARM_SCENARIOS, SEED_SCENARIOS, SESSION_ENTRY_CAP, enforceMapCap, createSeedFixtureCache, PostgresTaskStore, cleanupExpiredTasks, getMcpTasksMigration, MCP_TASKS_MIGRATION, ADCP_PRE_TRANSPORT, checkGovernance, governanceDeniedError, DEFAULT_REPORTING_CAPABILITIES, InMemoryStateStore, PostgresStateStore, getAdcpStateMigration, ADCP_STATE_MIGRATION, StateError, PatchConflictError, SESSION_KEY_FIELD, createSessionedStore, scopedStore, patchWithRetry, isPutIfMatchConflict, requireSessionKey, structuredSerialize, structuredDeserialize, createIdempotencyStore, memoryBackend, pgBackend, getIdempotencyMigration, IDEMPOTENCY_MIGRATION, cleanupExpiredIdempotency, redisBackend, createLazyBackend, hashPayload, IdempotencyClaimOwnershipError, getServeRequestContext, ADCP_SERVE_REQUEST_CONTEXT, createA2AAdapter, A2AInvocationError, MCP_APP_RESOURCE_MIME_TYPE, ADCP_MIRRORED_STRUCTURED_CONTENT_META_KEY, } from './server/index.mjs';
-export type { AdcpErrorOptions, AdcpErrorResponse, McpToolResponse, ValidAction, CancelMediaBuyInput, AdcpTaskToolConfig, TaskStore, TaskMessageQueue, CreateTaskOptions, ToolTaskHandler, CreateTaskRequestHandlerExtra, TaskRequestHandlerExtra, CreateTaskResult, GetTaskResult, Task, ServeContext, ServeOptions, PgQueryable, PostgresTaskStoreOptions, TestControllerStore, TestControllerStoreFactory, TestControllerStoreOrFactory, ControllerScenario, SeedScenario, SeedFixtureCache, SessionContext, OnInstructionsError, MaybePromise, LegacyAdcpServerConfig, LegacyAdcpToolMap, AdcpServerToolName, AdcpCapabilitiesConfig, LegacyAdcpCustomToolConfig, McpAppUiMeta, McpAppMeta, AdcpMcpResourceDefinition, McpAppResourceCsp, McpAppResourcePermissions, McpAppResourceUiMeta, McpAppResourceMeta, McpAppResourceReadContext, AdcpLogger, LegacyHandlerContext, LegacyMediaBuyHandlers, LegacySignalsHandlers, LegacyCreativeHandlers, LegacyGovernanceHandlers, LegacyAccountHandlers, LegacyEventTrackingHandlers, LegacySponsoredIntelligenceHandlers, SignedRequestsConfig, AdcpPreTransport, AdcpServer, AdcpServerTransport, AdcpTestRequest, AdcpTestToolsCallRequest, AdcpTestResponse, AdcpInvokeOptions, StructuredContentFallbackTransport, StructuredContentTextFallback, StructuredContentTextFallbackContext, CheckGovernanceOptions, GovernanceCallResult, GovernanceApproved, GovernanceDenied, GovernanceConditions, AdcpStateStore, ListOptions as StateListOptions, ListResult as StateListResult, PostgresStateStoreOptions, InMemoryStateStoreOptions, VersionedDocument, PutIfMatchResult, PatchWithRetryOptions, StateErrorCode, SessionKeyContext, IdempotencyStore, IdempotencyStoreConfig, IdempotencyBackend, IdempotencyCacheEntry, IdempotencyCheckResult, MemoryBackendOptions, PgBackendOptions, RedisBackendOptions, RedisBackendClient, RedisLikeClient, LazyBackendFactory, LazyBackendOptions, A2AAdapter, A2AAdapterOptions, A2AAgentCardOverrides, A2AAgentCapabilitiesOverride, A2AAgentSkillOverride, A2AMountOptions, ExpressAppLike, LegacyHttpSecurityScheme, LegacySecurityScheme, AccountMode, RequireCacheScopeWhenProducts, ServerPayload, GetProductsPayload, CreateMediaBuyPayload, UpdateMediaBuyPayload, GetMediaBuysPayload, GetMediaBuyDeliveryPayload, ListCreativesPayload, GetCreativeDeliveryPayload, CanonicalPreviewCreativePayload, PreviewCreativePayload, LegacyGetProductsPayload, LegacyCreateMediaBuyPayload, LegacyUpdateMediaBuyPayload, LegacyGetMediaBuysPayload, LegacyGetMediaBuyDeliveryPayload, LegacyListCreativesPayload, LegacyGetCreativeDeliveryPayload, LegacyListCreativeFormatsPayload, LegacyListCreativeFormatsResponsePayload, LegacyListCreativeFormatsServerPayload, LegacyBuildCreativePayload, LegacyBuildCreativeMultiPayload, LegacyBuildCreativeVariantPayload, LegacyPreviewCreativePayload, SyncCreativesPayload, SyncCreativesSuccessPayload, SyncCreativesErrorPayload, } from './server/index.mjs';
+export type { AdcpErrorOptions, AdcpErrorResponse, McpToolResponse, ValidAction, CancelMediaBuyInput, AdcpTaskToolConfig, TaskStore, TaskMessageQueue, CreateTaskOptions, ToolTaskHandler, CreateTaskRequestHandlerExtra, TaskRequestHandlerExtra, CreateTaskResult, GetTaskResult, Task, ServeContext, ServeOptions, PgQueryable, PostgresTaskStoreOptions, TestControllerStore, TestControllerStoreFactory, TestControllerStoreOrFactory, ControllerScenario, SeedScenario, SeedFixtureCache, SessionContext, OnInstructionsError, MaybePromise, LegacyAdcpServerConfig, LegacyAdcpToolMap, AdcpServerToolName, AdcpCapabilitiesConfig, LegacyAdcpCustomToolConfig, LegacyAdcpCustomToolHandler, LegacyAdcpCustomToolHandlerExtra, McpAppUiMeta, McpAppMeta, AdcpMcpResourceDefinition, McpAppResourceCsp, McpAppResourcePermissions, McpAppResourceUiMeta, McpAppResourceMeta, McpAppResourceReadContext, AdcpLogger, LegacyHandlerContext, LegacyMediaBuyHandlers, LegacySignalsHandlers, LegacyCreativeHandlers, LegacyGovernanceHandlers, LegacyAccountHandlers, LegacyEventTrackingHandlers, LegacySponsoredIntelligenceHandlers, SignedRequestsConfig, AdcpPreTransport, AdcpServer, AdcpServerTransport, AdcpTestRequest, AdcpTestToolsCallRequest, AdcpTestResponse, AdcpInvokeOptions, StructuredContentFallbackTransport, StructuredContentTextFallback, StructuredContentTextFallbackContext, CheckGovernanceOptions, GovernanceCallResult, GovernanceApproved, GovernanceDenied, GovernanceConditions, AdcpStateStore, ListOptions as StateListOptions, ListResult as StateListResult, PostgresStateStoreOptions, InMemoryStateStoreOptions, VersionedDocument, PutIfMatchResult, PatchWithRetryOptions, StateErrorCode, SessionKeyContext, IdempotencyStore, IdempotencyStoreConfig, IdempotencyBackend, IdempotencyCacheEntry, IdempotencyCheckResult, MemoryBackendOptions, PgBackendOptions, RedisBackendOptions, RedisBackendClient, RedisLikeClient, LazyBackendFactory, LazyBackendOptions, A2AAdapter, A2AAdapterOptions, A2AAgentCardOverrides, A2AAgentCapabilitiesOverride, A2AAgentSkillOverride, A2AMountOptions, ExpressAppLike, LegacyHttpSecurityScheme, LegacySecurityScheme, AccountMode, RequireCacheScopeWhenProducts, ServerPayload, GetProductsPayload, CreateMediaBuyPayload, UpdateMediaBuyPayload, GetMediaBuysPayload, GetMediaBuyDeliveryPayload, ListCreativesPayload, GetCreativeDeliveryPayload, CanonicalPreviewCreativePayload, PreviewCreativePayload, LegacyGetProductsPayload, LegacyCreateMediaBuyPayload, LegacyUpdateMediaBuyPayload, LegacyGetMediaBuysPayload, LegacyGetMediaBuyDeliveryPayload, LegacyListCreativesPayload, LegacyGetCreativeDeliveryPayload, LegacyListCreativeFormatsPayload, LegacyListCreativeFormatsResponsePayload, LegacyListCreativeFormatsServerPayload, LegacyBuildCreativePayload, LegacyBuildCreativeMultiPayload, LegacyBuildCreativeVariantPayload, LegacyPreviewCreativePayload, SyncCreativesPayload, SyncCreativesSuccessPayload, SyncCreativesErrorPayload, } from './server/index.mjs';
 export { isRetryable, getRetryDelay } from './utils/retry.mjs';
 export { decideRetry, BuyerRetryPolicy } from './utils/buyer-retry-policy.mjs';
 export type { RetryDecision, RetryContext, RetryDecisionOverride } from './utils/buyer-retry-policy.mjs';