@adcp/sdk 14.0.0-rc.52 → 14.0.0-rc.53

package/dist/lib/registry/types.generated.d.mts

@@ -7877,6 +7877,18 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /** @description Agent does not offer public product browsing (no wholesale buying mode, or a buyer account is required) */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        error: string;
+                        message: string;
+                    };
+                };
+            };
             /** @description Rate limit exceeded */
             429: {
                 headers: {

package/dist/lib/registry/types.generated.d.ts

@@ -7877,6 +7877,18 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /** @description Agent does not offer public product browsing (no wholesale buying mode, or a buyer account is required) */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        error: string;
+                        message: string;
+                    };
+                };
+            };
             /** @description Rate limit exceeded */
             429: {
                 headers: {

package/dist/lib/schemas-data/v2.5/_provenance.json

@@ -4,5 +4,5 @@
   "source_sha": "4e553ad955f83b49c7d221ab5c3ff78237ad02e3",
   "source_tarball_sha256": "580656d6466ef9f0d1119985e6726c2efea718dc671e2ad30957fcb2fd54af0f",
   "upstream_adcp_version": "2.5.3",
-  "synced_at": "2026-09-30T06:48:33.322Z"
+  "synced_at": "2026-09-30T09:55:20.074Z"
 }

package/dist/lib/server/auth-signature.d.mts

@@ -69,8 +69,11 @@ export interface VerifySignatureAsAuthenticatorOptions {
     now?: () => number;
     /**
      * Trusted endpoint release pin used to select the 3.0/3.1 or 3.2 signature
-     * profile. When omitted, verification accepts both encodings for SDK 13
-     * compatibility while digest coverage follows `capability`.
+     * profile. Set it on every endpoint that advertises a 3.2 release: a 3.2
+     * pin rejects Base64URL `Signature` / `Content-Digest` values as
+     * `request_signature_header_malformed` whatever `capability` says. When
+     * omitted, verification accepts both encodings for SDK 13 compatibility
+     * while digest coverage follows `capability`.
      */
     adcpVersion?: string;
     /**

package/dist/lib/server/auth-signature.d.ts

@@ -69,8 +69,11 @@ export interface VerifySignatureAsAuthenticatorOptions {
     now?: () => number;
     /**
      * Trusted endpoint release pin used to select the 3.0/3.1 or 3.2 signature
-     * profile. When omitted, verification accepts both encodings for SDK 13
-     * compatibility while digest coverage follows `capability`.
+     * profile. Set it on every endpoint that advertises a 3.2 release: a 3.2
+     * pin rejects Base64URL `Signature` / `Content-Digest` values as
+     * `request_signature_header_malformed` whatever `capability` says. When
+     * omitted, verification accepts both encodings for SDK 13 compatibility
+     * while digest coverage follows `capability`.
      */
     adcpVersion?: string;
     /**

package/dist/lib/signing/content-digest.d.mts

@@ -8,5 +8,13 @@ export declare function computeContentDigest(body: string | Uint8Array, encoding
  * up the `sha-256` member without requiring any particular position.
  */
 export declare function parseContentDigest(header: string): Buffer | null;
+/** Raw text of the `sha-256` byte-sequence token in a Content-Digest header, if present. */
+export declare function contentDigestSha256Token(header: string): string | undefined;
+/**
+ * True when `encoded` is canonical padded standard Base64 (RFC 4648 §4), the
+ * RFC 8941 `sf-binary` form AdCP 3.2 requires: `+`/`/` alphabet, length a
+ * multiple of four, and only the `=` padding the byte length requires.
+ */
+export declare function isPaddedStandardBase64(encoded: string): boolean;
 export declare function contentDigestUsesEncoding(header: string, encoding: SfBinaryEncoding): boolean;
 export declare function contentDigestMatches(header: string, body: string | Uint8Array): boolean;

package/dist/lib/signing/content-digest.d.ts

@@ -8,5 +8,13 @@ export declare function computeContentDigest(body: string | Uint8Array, encoding
  * up the `sha-256` member without requiring any particular position.
  */
 export declare function parseContentDigest(header: string): Buffer | null;
+/** Raw text of the `sha-256` byte-sequence token in a Content-Digest header, if present. */
+export declare function contentDigestSha256Token(header: string): string | undefined;
+/**
+ * True when `encoded` is canonical padded standard Base64 (RFC 4648 §4), the
+ * RFC 8941 `sf-binary` form AdCP 3.2 requires: `+`/`/` alphabet, length a
+ * multiple of four, and only the `=` padding the byte length requires.
+ */
+export declare function isPaddedStandardBase64(encoded: string): boolean;
 export declare function contentDigestUsesEncoding(header: string, encoding: SfBinaryEncoding): boolean;
 export declare function contentDigestMatches(header: string, body: string | Uint8Array): boolean;

package/dist/lib/signing/content-digest.js

@@ -20,7 +20,9 @@ var content_digest_exports = {};
 __export(content_digest_exports, {
   computeContentDigest: () => computeContentDigest,
   contentDigestMatches: () => contentDigestMatches,
+  contentDigestSha256Token: () => contentDigestSha256Token,
   contentDigestUsesEncoding: () => contentDigestUsesEncoding,
+  isPaddedStandardBase64: () => isPaddedStandardBase64,
   parseContentDigest: () => parseContentDigest,
   requestSigningEncodingForVersion: () => requestSigningEncodingForVersion
 });
@@ -47,12 +49,17 @@ function parseContentDigest(header) {
   const m = header.match(SHA256_MEMBER_RE);
   return m && m[1] ? Buffer.from(m[1], "base64") : null;
 }
+function contentDigestSha256Token(header) {
+  return header.match(/(?:^|[,\s])sha-256=:([^:]+):/)?.[1];
+}
+function isPaddedStandardBase64(encoded) {
+  return encoded.length > 0 && encoded.length % 4 === 0 && /^[A-Za-z0-9+/]+={0,2}$/.test(encoded);
+}
 function contentDigestUsesEncoding(header, encoding) {
-  const match = header.match(/(?:^|[,\s])sha-256=:([^:]+):/);
-  if (!match?.[1]) return false;
-  const encoded = match[1];
+  const encoded = contentDigestSha256Token(header);
+  if (!encoded) return false;
   if (encoding === "legacy-base64url") return /^[A-Za-z0-9_-]+$/.test(encoded);
-  return encoded.length % 4 === 0 && /^[A-Za-z0-9+/]+={1,2}$/.test(encoded);
+  return isPaddedStandardBase64(encoded);
 }
 function contentDigestMatches(header, body) {
   const expected = parseContentDigest(header);
@@ -70,7 +77,9 @@ function toBuffer(body) {
 0 && (module.exports = {
   computeContentDigest,
   contentDigestMatches,
+  contentDigestSha256Token,
   contentDigestUsesEncoding,
+  isPaddedStandardBase64,
   parseContentDigest,
   requestSigningEncodingForVersion
 });

package/dist/lib/signing/content-digest.mjs

@@ -20,12 +20,17 @@ function parseContentDigest(header) {
   const m = header.match(SHA256_MEMBER_RE);
   return m && m[1] ? Buffer.from(m[1], "base64") : null;
 }
+function contentDigestSha256Token(header) {
+  return header.match(/(?:^|[,\s])sha-256=:([^:]+):/)?.[1];
+}
+function isPaddedStandardBase64(encoded) {
+  return encoded.length > 0 && encoded.length % 4 === 0 && /^[A-Za-z0-9+/]+={0,2}$/.test(encoded);
+}
 function contentDigestUsesEncoding(header, encoding) {
-  const match = header.match(/(?:^|[,\s])sha-256=:([^:]+):/);
-  if (!match?.[1]) return false;
-  const encoded = match[1];
+  const encoded = contentDigestSha256Token(header);
+  if (!encoded) return false;
   if (encoding === "legacy-base64url") return /^[A-Za-z0-9_-]+$/.test(encoded);
-  return encoded.length % 4 === 0 && /^[A-Za-z0-9+/]+={1,2}$/.test(encoded);
+  return isPaddedStandardBase64(encoded);
 }
 function contentDigestMatches(header, body) {
   const expected = parseContentDigest(header);
@@ -42,7 +47,9 @@ function toBuffer(body) {
 export {
   computeContentDigest,
   contentDigestMatches,
+  contentDigestSha256Token,
   contentDigestUsesEncoding,
+  isPaddedStandardBase64,
   parseContentDigest,
   requestSigningEncodingForVersion
 };

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

@@ -1,4 +1,4 @@
-import type { SfBinaryEncoding } from './content-digest.mjs';
+import { type SfBinaryEncoding } from './content-digest.mjs';
 export interface ParsedSignatureInput {
     label: string;
     components: string[];

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

@@ -1,4 +1,4 @@
-import type { SfBinaryEncoding } from './content-digest';
+import { type SfBinaryEncoding } from './content-digest';
 export interface ParsedSignatureInput {
     label: string;
     components: string[];

package/dist/lib/signing/parser.js

@@ -25,6 +25,7 @@ __export(parser_exports, {
 module.exports = __toCommonJS(parser_exports);
 var import_structured_headers = require("structured-headers");
 var import_errors = require('./errors.js');
+var import_content_digest = require('./content-digest.js');
 const STRING_PARAMS = /* @__PURE__ */ new Set(["nonce", "keyid", "alg", "tag"]);
 const INTEGER_PARAMS = /* @__PURE__ */ new Set(["created", "expires"]);
 function malformed(message) {
@@ -79,7 +80,7 @@ function parseSignature(headerValue, expectedLabel, encoding = "legacy-base64url
   const rawBytes = headerValue.match(new RegExp(`(?:^|,\\s*)${escapedLabel}\\s*=\\s*:([^:]+):`))?.[1];
   if (!rawBytes) malformed(`Signature header does not contain a byte sequence for label "${expectedLabel}"`);
   if (encoding === "rfc8941-base64") {
-    if (rawBytes.length % 4 !== 0 || !/^[A-Za-z0-9+/]+={1,2}$/.test(rawBytes)) {
+    if (!(0, import_content_digest.isPaddedStandardBase64)(rawBytes)) {
       malformed("Signature value must use padded standard Base64 for AdCP 3.2+");
     }
   } else if (!/^[A-Za-z0-9_-]+$/.test(rawBytes)) {
@@ -87,7 +88,7 @@ function parseSignature(headerValue, expectedLabel, encoding = "legacy-base64url
   }
   let dict;
   try {
-    dict = (0, import_structured_headers.parseDictionary)(normalizeByteSequenceBase64(headerValue));
+    dict = (0, import_structured_headers.parseDictionary)(encoding === "rfc8941-base64" ? headerValue : normalizeByteSequenceBase64(headerValue));
   } catch (e) {
     if (e instanceof import_structured_headers.ParseError) {
       if (/base64/i.test(e.message)) malformed("Signature value contains non-base64 characters");

package/dist/lib/signing/parser.mjs

@@ -1,5 +1,6 @@
 import { ParseError, parseDictionary, serializeInnerList } from "structured-headers";
 import { RequestSignatureError } from "./errors.mjs";
+import { isPaddedStandardBase64 } from "./content-digest.mjs";
 const STRING_PARAMS = /* @__PURE__ */ new Set(["nonce", "keyid", "alg", "tag"]);
 const INTEGER_PARAMS = /* @__PURE__ */ new Set(["created", "expires"]);
 function malformed(message) {
@@ -54,7 +55,7 @@ function parseSignature(headerValue, expectedLabel, encoding = "legacy-base64url
   const rawBytes = headerValue.match(new RegExp(`(?:^|,\\s*)${escapedLabel}\\s*=\\s*:([^:]+):`))?.[1];
   if (!rawBytes) malformed(`Signature header does not contain a byte sequence for label "${expectedLabel}"`);
   if (encoding === "rfc8941-base64") {
-    if (rawBytes.length % 4 !== 0 || !/^[A-Za-z0-9+/]+={1,2}$/.test(rawBytes)) {
+    if (!isPaddedStandardBase64(rawBytes)) {
       malformed("Signature value must use padded standard Base64 for AdCP 3.2+");
     }
   } else if (!/^[A-Za-z0-9_-]+$/.test(rawBytes)) {
@@ -62,7 +63,7 @@ function parseSignature(headerValue, expectedLabel, encoding = "legacy-base64url
   }
   let dict;
   try {
-    dict = parseDictionary(normalizeByteSequenceBase64(headerValue));
+    dict = parseDictionary(encoding === "rfc8941-base64" ? headerValue : normalizeByteSequenceBase64(headerValue));
   } catch (e) {
     if (e instanceof ParseError) {
       if (/base64/i.test(e.message)) malformed("Signature value contains non-base64 characters");

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

@@ -19,8 +19,12 @@ export interface VerifyRequestOptions {
     operation?: string;
     /**
      * Trusted endpoint release pin; never inferred from request payload data.
-     * When omitted, the verifier accepts both the legacy 3.0/3.1 Base64URL
-     * representation and the 3.2+ RFC 8941 Base64 representation. Digest
+     * A 3.2+ pin parses `Signature` and `Content-Digest` strictly as RFC 8941
+     * padded standard Base64 and rejects Base64URL as
+     * `request_signature_header_malformed`, regardless of
+     * `capability.covers_content_digest`. When omitted, the verifier accepts
+     * both the legacy 3.0/3.1 Base64URL representation and the 3.2+ RFC 8941
+     * Base64 representation, so it cannot grade as a 3.2 verifier. Digest
      * coverage still follows `capability.covers_content_digest`.
      */
     adcpVersion?: string;

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

@@ -19,8 +19,12 @@ export interface VerifyRequestOptions {
     operation?: string;
     /**
      * Trusted endpoint release pin; never inferred from request payload data.
-     * When omitted, the verifier accepts both the legacy 3.0/3.1 Base64URL
-     * representation and the 3.2+ RFC 8941 Base64 representation. Digest
+     * A 3.2+ pin parses `Signature` and `Content-Digest` strictly as RFC 8941
+     * padded standard Base64 and rejects Base64URL as
+     * `request_signature_header_malformed`, regardless of
+     * `capability.covers_content_digest`. When omitted, the verifier accepts
+     * both the legacy 3.0/3.1 Base64URL representation and the 3.2+ RFC 8941
+     * Base64 representation, so it cannot grade as a 3.2 verifier. Digest
      * coverage still follows `capability.covers_content_digest`.
      */
     adcpVersion?: string;

package/dist/lib/signing/verifier.js

@@ -92,7 +92,7 @@ async function verifyRequestSignature(request, options) {
       parsedEncoding = candidate;
       break;
     } catch (error) {
-      parseError ??= error;
+      if (parseError === void 0 || candidate === (pinnedBinaryEncoding ?? "rfc8941-base64")) parseError = error;
     }
   }
   if (!parsedSig) throw parseError;
@@ -192,9 +192,16 @@ async function verifyRequestSignature(request, options) {
   }
   if (parsedInput.components.includes("content-digest")) {
     const digestHeader = (0, import_canonicalize.getHeaderValue)(request.headers, "Content-Digest");
-    const encodingMatches = !!digestHeader && contentDigestEncodingCandidates(pinnedBinaryEncoding, options.capability.covers_content_digest).some(
+    const encodingMatches = !!digestHeader && contentDigestEncodingCandidates(pinnedBinaryEncoding).some(
       (candidate) => (0, import_content_digest.contentDigestUsesEncoding)(digestHeader, candidate)
     );
+    if (digestHeader && !encodingMatches && pinnedBinaryEncoding === "rfc8941-base64" && (0, import_content_digest.contentDigestSha256Token)(digestHeader) !== void 0) {
+      throw new import_errors.RequestSignatureError(
+        "request_signature_header_malformed",
+        11,
+        "Content-Digest sha-256 value must use padded standard Base64 for AdCP 3.2+"
+      );
+    }
     if (!digestHeader || !encodingMatches || !(0, import_content_digest.contentDigestMatches)(digestHeader, request.body ?? "")) {
       throw new import_errors.RequestSignatureError(
         "request_signature_digest_mismatch",
@@ -236,17 +243,14 @@ async function verifyRequestSignature(request, options) {
   return { status: "verified", keyid: jwk.kid, agent_url, verified_at: now };
 }
 function signatureEncodingCandidates(pinned, digestPolicy) {
-  if (!pinned) return ["rfc8941-base64", "legacy-base64url"];
-  if (digestPolicy !== "either") return [pinned];
-  return [pinned, alternateBinaryEncoding(pinned)];
+  if (!pinned) return ["legacy-base64url", "rfc8941-base64"];
+  if (pinned === "rfc8941-base64" || digestPolicy !== "either") return [pinned];
+  return ["legacy-base64url", "rfc8941-base64"];
 }
-function contentDigestEncodingCandidates(pinned, digestPolicy) {
-  if (pinned === "rfc8941-base64" && digestPolicy !== "either") return [pinned];
+function contentDigestEncodingCandidates(pinned) {
+  if (pinned === "rfc8941-base64") return [pinned];
   return ["rfc8941-base64", "legacy-base64url"];
 }
-function alternateBinaryEncoding(encoding) {
-  return encoding === "rfc8941-base64" ? "legacy-base64url" : "rfc8941-base64";
-}
 function jsonRpcProtocolMethods(body) {
   if (!body) return [];
   if (exceedsUnsignedBodyInspectionCap(body)) return [];

package/dist/lib/signing/verifier.mjs

@@ -7,6 +7,7 @@ import {
 } from "./canonicalize.mjs";
 import {
   contentDigestMatches,
+  contentDigestSha256Token,
   contentDigestUsesEncoding,
   requestSigningEncodingForVersion
 } from "./content-digest.mjs";
@@ -84,7 +85,7 @@ async function verifyRequestSignature(request, options) {
       parsedEncoding = candidate;
       break;
     } catch (error) {
-      parseError ??= error;
+      if (parseError === void 0 || candidate === (pinnedBinaryEncoding ?? "rfc8941-base64")) parseError = error;
     }
   }
   if (!parsedSig) throw parseError;
@@ -184,9 +185,16 @@ async function verifyRequestSignature(request, options) {
   }
   if (parsedInput.components.includes("content-digest")) {
     const digestHeader = getHeaderValue(request.headers, "Content-Digest");
-    const encodingMatches = !!digestHeader && contentDigestEncodingCandidates(pinnedBinaryEncoding, options.capability.covers_content_digest).some(
+    const encodingMatches = !!digestHeader && contentDigestEncodingCandidates(pinnedBinaryEncoding).some(
       (candidate) => contentDigestUsesEncoding(digestHeader, candidate)
     );
+    if (digestHeader && !encodingMatches && pinnedBinaryEncoding === "rfc8941-base64" && contentDigestSha256Token(digestHeader) !== void 0) {
+      throw new RequestSignatureError(
+        "request_signature_header_malformed",
+        11,
+        "Content-Digest sha-256 value must use padded standard Base64 for AdCP 3.2+"
+      );
+    }
     if (!digestHeader || !encodingMatches || !contentDigestMatches(digestHeader, request.body ?? "")) {
       throw new RequestSignatureError(
         "request_signature_digest_mismatch",
@@ -228,17 +236,14 @@ async function verifyRequestSignature(request, options) {
   return { status: "verified", keyid: jwk.kid, agent_url, verified_at: now };
 }
 function signatureEncodingCandidates(pinned, digestPolicy) {
-  if (!pinned) return ["rfc8941-base64", "legacy-base64url"];
-  if (digestPolicy !== "either") return [pinned];
-  return [pinned, alternateBinaryEncoding(pinned)];
+  if (!pinned) return ["legacy-base64url", "rfc8941-base64"];
+  if (pinned === "rfc8941-base64" || digestPolicy !== "either") return [pinned];
+  return ["legacy-base64url", "rfc8941-base64"];
 }
-function contentDigestEncodingCandidates(pinned, digestPolicy) {
-  if (pinned === "rfc8941-base64" && digestPolicy !== "either") return [pinned];
+function contentDigestEncodingCandidates(pinned) {
+  if (pinned === "rfc8941-base64") return [pinned];
   return ["rfc8941-base64", "legacy-base64url"];
 }
-function alternateBinaryEncoding(encoding) {
-  return encoding === "rfc8941-base64" ? "legacy-base64url" : "rfc8941-base64";
-}
 function jsonRpcProtocolMethods(body) {
   if (!body) return [];
   if (exceedsUnsignedBodyInspectionCap(body)) return [];

package/dist/lib/testing/compliance/comply.d.mts

@@ -9,7 +9,7 @@
  */
 import type { TestOptions, TestResult, AgentProfile } from '../types.mjs';
 import type { NotApplicableStoryboard, ResolvedBundle } from '../storyboard/compliance.mjs';
-import type { Storyboard, StoryboardResult, StoryboardRunOptions } from '../storyboard/types.mjs';
+import type { AgentEntry, Storyboard, StoryboardContext, StoryboardResult, StoryboardRunOptions } from '../storyboard/types.mjs';
 import type { ComplianceBundleResult, ComplianceTrack, ComplianceFailure, ComplianceResult, ComplianceSummary, AdvisoryObservation, OverallStatus } from './types.mjs';
 import type { VersionEnvelopeMode } from '../../protocols/index.mjs';
 /**
@@ -98,7 +98,113 @@ export interface ComplyOptions extends TestOptions {
     testKitPath?: string;
     /** Scoped hosted stable-line alias for prerelease-backed compliance caches. */
     hostedStableLineAlias?: string;
+    /**
+     * Per-storyboard routing hook. `comply()` grades one agent, so storyboards
+     * that need a second agent (`requires: [multi_agent]`, e.g. the
+     * governance-aware seller scenarios) otherwise skip with
+     * `requirement_unmet`. The hook lets a caller that can supply the other
+     * agents route those storyboards while every other storyboard keeps the
+     * ordinary single-URL run.
+     *
+     * Called once per selected storyboard, after capability discovery,
+     * `required_tools` partitioning and the `timeout_ms` budget check, and
+     * before the storyboard runs. Storyboards whose root capability predicate
+     * (`requires_capability` / `requires_all_capabilities`) the agent under
+     * test does not satisfy are not passed to the hook: they keep their
+     * `not_applicable` verdict. Not consulted in the degraded auth-rejected
+     * path, which runs only storyboards with no `required_tools`. An error the
+     * hook throws propagates out of `comply()`.
+     *
+     * `context.profile` is the agent under test's own `get_adcp_capabilities`
+     * answer: untrusted, agent-controlled input. Do not derive agent URLs or
+     * credentials from it.
+     *
+     * Return:
+     * - `undefined`: run the storyboard as usual against `agentUrl`.
+     * - a {@link ComplyStoryboardRoute}: run it as
+     *   `runStoryboard('', storyboard, { ...runOptions, agents, default_agent, context })`
+     *   and grade the result against the agent under test only (below). The
+     *   result lands in `tracks`, `summary`, `failures`, `storyboards_executed`
+     *   and `bundle_results` like any other run.
+     * - a {@link ComplyStoryboardSkip}: do not run it. `comply()` records the
+     *   same whole-storyboard `requirement_unmet` row the runner emits for an
+     *   unmet `requires:` gate, with `skip.detail` set to the reason (control
+     *   and bidi characters stripped, max 1000 chars) and `skip.requirement:
+     *   'multi_agent'` when the storyboard declares it. Like an unrouted
+     *   `multi_agent` storyboard it is listed in `storyboards_executed` and caps
+     *   its bundle at `partial`.
+     *
+     * Grading of routed results. The agent under test is only credited or
+     * blamed for what it served:
+     * - A failed step served by another routed agent, including that agent's
+     *   discovery failure (routed runs use `discovery_resilient`), becomes a
+     *   `prerequisite_failed` skip: a coverage gap (`partial`), never `failing`.
+     * - If no step served by the agent under test passed, a synthetic
+     *   `agent_under_test_coverage` gap row keeps the bundle from `passing`.
+     * - `failures[].fix_command` for a routed storyboard is a single-URL
+     *   command; re-running it reproduces only the unrouted skip.
+     *
+     * Credential and network isolation, enforced by `comply()`. Caller
+     * configuration errors throw, failing the run:
+     * - `agents[default_agent].url` must be the agent under test (`agentUrl`).
+     * - Every entry that sets `auth` must set a real credential object (a known
+     *   `type` with its secret fields); `null`, `''`, `{}` and the like throw.
+     *   Only an agent-under-test entry may omit `auth`; it then gets the
+     *   run-level `auth` pinned onto it (or the test-kit default if there is
+     *   none). Run-level `auth` is dropped from the routed options, so the
+     *   runner's `entry.auth ?? options.auth` fallback cannot hand it to
+     *   another agent.
+     * - Routing is refused while run-level `headers` are set, because the runner
+     *   sends them to every routed agent.
+     * - A replacement `route.storyboard` must keep the same `id` and grading
+     *   shape (phases, steps, tasks, agent pins, validations, expectations and
+     *   gates); only request payloads and context may change.
+     * - Run-level `transport` (including `trustedFetchFn` / SSRF guards) is
+     *   shared by every routed agent. The hook cannot override it; only `url`,
+     *   `auth` and `transport` (wire protocol) are read from each entry.
+     *
+     * Storyboard content that would forward test-kit credentials is refused as
+     * a skip rather than a throw: `$test_kit.auth` references in storyboard
+     * context, or a step not pinned to an agent-under-test key (unpinned steps
+     * route by protocol) that uses a `from_test_kit` auth directive or a
+     * `$test_kit.auth` reference.
+     *
+     * Known limit: version negotiation (`adcpVersion`, `wireAdcpVersion`,
+     * `versionEnvelope`) is done once against the agent under test and shared
+     * by every routed agent.
+     *
+     * Do not mutate `storyboard`; return a patched copy in `route.storyboard`.
+     */
+    routeStoryboard?: (storyboard: Storyboard, context: ComplyRouteStoryboardContext) => ComplyStoryboardRouting | Promise<ComplyStoryboardRouting>;
+}
+/** Second argument to {@link ComplyOptions.routeStoryboard}. */
+export interface ComplyRouteStoryboardContext {
+    /** The agent under test, as passed to `comply()`. */
+    agent_url: string;
+    /** Capability profile `comply()` discovered for the agent under test. */
+    profile: AgentProfile;
+}
+/** Route one storyboard across several agents. See {@link ComplyOptions.routeStoryboard}. */
+export interface ComplyStoryboardRoute {
+    /** Agents map for `runStoryboard`. `agents[default_agent].url` must be the agent under test. */
+    agents: Record<string, AgentEntry>;
+    /** Key of the agent under test in `agents`. */
+    default_agent: string;
+    /** Initial-context overrides, merged over any run-level context. */
+    context?: StoryboardContext;
+    /**
+     * Storyboard to run in place of the selected one (e.g. a patched copy).
+     * Must keep the same `id` so the result is attributed to the same bundle.
+     */
+    storyboard?: Storyboard;
+}
+/** Record a storyboard as not runnable. See {@link ComplyOptions.routeStoryboard}. */
+export interface ComplyStoryboardSkip {
+    /** Human-readable reason, reported as `skip.detail`. */
+    skip: string;
 }
+/** Return type of {@link ComplyOptions.routeStoryboard}. */
+export type ComplyStoryboardRouting = ComplyStoryboardRoute | ComplyStoryboardSkip | undefined;
 /**
  * Run compliance assessment against an agent.
  *

package/dist/lib/testing/compliance/comply.d.ts

@@ -9,7 +9,7 @@
  */
 import type { TestOptions, TestResult, AgentProfile } from '../types';
 import type { NotApplicableStoryboard, ResolvedBundle } from '../storyboard/compliance';
-import type { Storyboard, StoryboardResult, StoryboardRunOptions } from '../storyboard/types';
+import type { AgentEntry, Storyboard, StoryboardContext, StoryboardResult, StoryboardRunOptions } from '../storyboard/types';
 import type { ComplianceBundleResult, ComplianceTrack, ComplianceFailure, ComplianceResult, ComplianceSummary, AdvisoryObservation, OverallStatus } from './types';
 import type { VersionEnvelopeMode } from '../../protocols';
 /**
@@ -98,7 +98,113 @@ export interface ComplyOptions extends TestOptions {
     testKitPath?: string;
     /** Scoped hosted stable-line alias for prerelease-backed compliance caches. */
     hostedStableLineAlias?: string;
+    /**
+     * Per-storyboard routing hook. `comply()` grades one agent, so storyboards
+     * that need a second agent (`requires: [multi_agent]`, e.g. the
+     * governance-aware seller scenarios) otherwise skip with
+     * `requirement_unmet`. The hook lets a caller that can supply the other
+     * agents route those storyboards while every other storyboard keeps the
+     * ordinary single-URL run.
+     *
+     * Called once per selected storyboard, after capability discovery,
+     * `required_tools` partitioning and the `timeout_ms` budget check, and
+     * before the storyboard runs. Storyboards whose root capability predicate
+     * (`requires_capability` / `requires_all_capabilities`) the agent under
+     * test does not satisfy are not passed to the hook: they keep their
+     * `not_applicable` verdict. Not consulted in the degraded auth-rejected
+     * path, which runs only storyboards with no `required_tools`. An error the
+     * hook throws propagates out of `comply()`.
+     *
+     * `context.profile` is the agent under test's own `get_adcp_capabilities`
+     * answer: untrusted, agent-controlled input. Do not derive agent URLs or
+     * credentials from it.
+     *
+     * Return:
+     * - `undefined`: run the storyboard as usual against `agentUrl`.
+     * - a {@link ComplyStoryboardRoute}: run it as
+     *   `runStoryboard('', storyboard, { ...runOptions, agents, default_agent, context })`
+     *   and grade the result against the agent under test only (below). The
+     *   result lands in `tracks`, `summary`, `failures`, `storyboards_executed`
+     *   and `bundle_results` like any other run.
+     * - a {@link ComplyStoryboardSkip}: do not run it. `comply()` records the
+     *   same whole-storyboard `requirement_unmet` row the runner emits for an
+     *   unmet `requires:` gate, with `skip.detail` set to the reason (control
+     *   and bidi characters stripped, max 1000 chars) and `skip.requirement:
+     *   'multi_agent'` when the storyboard declares it. Like an unrouted
+     *   `multi_agent` storyboard it is listed in `storyboards_executed` and caps
+     *   its bundle at `partial`.
+     *
+     * Grading of routed results. The agent under test is only credited or
+     * blamed for what it served:
+     * - A failed step served by another routed agent, including that agent's
+     *   discovery failure (routed runs use `discovery_resilient`), becomes a
+     *   `prerequisite_failed` skip: a coverage gap (`partial`), never `failing`.
+     * - If no step served by the agent under test passed, a synthetic
+     *   `agent_under_test_coverage` gap row keeps the bundle from `passing`.
+     * - `failures[].fix_command` for a routed storyboard is a single-URL
+     *   command; re-running it reproduces only the unrouted skip.
+     *
+     * Credential and network isolation, enforced by `comply()`. Caller
+     * configuration errors throw, failing the run:
+     * - `agents[default_agent].url` must be the agent under test (`agentUrl`).
+     * - Every entry that sets `auth` must set a real credential object (a known
+     *   `type` with its secret fields); `null`, `''`, `{}` and the like throw.
+     *   Only an agent-under-test entry may omit `auth`; it then gets the
+     *   run-level `auth` pinned onto it (or the test-kit default if there is
+     *   none). Run-level `auth` is dropped from the routed options, so the
+     *   runner's `entry.auth ?? options.auth` fallback cannot hand it to
+     *   another agent.
+     * - Routing is refused while run-level `headers` are set, because the runner
+     *   sends them to every routed agent.
+     * - A replacement `route.storyboard` must keep the same `id` and grading
+     *   shape (phases, steps, tasks, agent pins, validations, expectations and
+     *   gates); only request payloads and context may change.
+     * - Run-level `transport` (including `trustedFetchFn` / SSRF guards) is
+     *   shared by every routed agent. The hook cannot override it; only `url`,
+     *   `auth` and `transport` (wire protocol) are read from each entry.
+     *
+     * Storyboard content that would forward test-kit credentials is refused as
+     * a skip rather than a throw: `$test_kit.auth` references in storyboard
+     * context, or a step not pinned to an agent-under-test key (unpinned steps
+     * route by protocol) that uses a `from_test_kit` auth directive or a
+     * `$test_kit.auth` reference.
+     *
+     * Known limit: version negotiation (`adcpVersion`, `wireAdcpVersion`,
+     * `versionEnvelope`) is done once against the agent under test and shared
+     * by every routed agent.
+     *
+     * Do not mutate `storyboard`; return a patched copy in `route.storyboard`.
+     */
+    routeStoryboard?: (storyboard: Storyboard, context: ComplyRouteStoryboardContext) => ComplyStoryboardRouting | Promise<ComplyStoryboardRouting>;
+}
+/** Second argument to {@link ComplyOptions.routeStoryboard}. */
+export interface ComplyRouteStoryboardContext {
+    /** The agent under test, as passed to `comply()`. */
+    agent_url: string;
+    /** Capability profile `comply()` discovered for the agent under test. */
+    profile: AgentProfile;
+}
+/** Route one storyboard across several agents. See {@link ComplyOptions.routeStoryboard}. */
+export interface ComplyStoryboardRoute {
+    /** Agents map for `runStoryboard`. `agents[default_agent].url` must be the agent under test. */
+    agents: Record<string, AgentEntry>;
+    /** Key of the agent under test in `agents`. */
+    default_agent: string;
+    /** Initial-context overrides, merged over any run-level context. */
+    context?: StoryboardContext;
+    /**
+     * Storyboard to run in place of the selected one (e.g. a patched copy).
+     * Must keep the same `id` so the result is attributed to the same bundle.
+     */
+    storyboard?: Storyboard;
+}
+/** Record a storyboard as not runnable. See {@link ComplyOptions.routeStoryboard}. */
+export interface ComplyStoryboardSkip {
+    /** Human-readable reason, reported as `skip.detail`. */
+    skip: string;
 }
+/** Return type of {@link ComplyOptions.routeStoryboard}. */
+export type ComplyStoryboardRouting = ComplyStoryboardRoute | ComplyStoryboardSkip | undefined;
 /**
  * Run compliance assessment against an agent.
  *