@adcp/sdk 14.0.0-rc.38 → 14.0.0-rc.39

package/dist/lib/testing/storyboard/request-signing/builder.d.mts

@@ -20,15 +20,26 @@ export interface BuildOptions {
      */
     baseUrl?: string;
     /**
-     * Transport-layer framing. `'raw'` (default) sends the vector body to the
-     * retargeted vector URL verbatim — matches the conformance vectors' intent
-     * of testing a per-operation HTTP endpoint. `'mcp'` wraps the vector body
-     * in a JSON-RPC `tools/call` envelope and posts to `baseUrl` as-is (no
-     * path join); operation name comes from the vector URL's last segment.
+     * Transport-layer framing. `'raw'` sends the vector body to the retargeted
+     * vector URL verbatim — matches the conformance vectors' intent of testing
+     * a per-operation HTTP endpoint. `'mcp'` wraps the vector body in a
+     * JSON-RPC `tools/call` envelope and posts to `baseUrl` as-is (no path
+     * join); operation name comes from the vector URL's last segment.
      *
      * MCP mode trades the canonicalization-edge coverage for reach: vectors
      * 005–008 fold into plain POSTs against the MCP endpoint, but the grader
      * works against any MCP agent that wires a verifier at the HTTP layer.
+     *
+     * **Defaults differ by layer, deliberately.** Omitting the field here
+     * builds a raw request: this is the low-level primitive, and a caller
+     * holding a vector and a REST target shouldn't have its body silently
+     * re-framed. Every grader entry point above it (`gradeRequestSigning`,
+     * `gradeOneVector`, the storyboard `request_signing_probe` dispatch)
+     * resolves the default to `'mcp'` instead, because the runner reaches
+     * agents through `tools/call` and raw replay 404s on an MCP mount before
+     * the verifier runs (adcontextprotocol/adcp#6548). REST-binding agents
+     * pass `'raw'` explicitly — `adcp storyboard run --signing-transport raw`
+     * or `adcp grade request-signing --transport raw`.
      */
     transport?: 'raw' | 'mcp';
     /**

package/dist/lib/testing/storyboard/request-signing/builder.d.ts

@@ -20,15 +20,26 @@ export interface BuildOptions {
      */
     baseUrl?: string;
     /**
-     * Transport-layer framing. `'raw'` (default) sends the vector body to the
-     * retargeted vector URL verbatim — matches the conformance vectors' intent
-     * of testing a per-operation HTTP endpoint. `'mcp'` wraps the vector body
-     * in a JSON-RPC `tools/call` envelope and posts to `baseUrl` as-is (no
-     * path join); operation name comes from the vector URL's last segment.
+     * Transport-layer framing. `'raw'` sends the vector body to the retargeted
+     * vector URL verbatim — matches the conformance vectors' intent of testing
+     * a per-operation HTTP endpoint. `'mcp'` wraps the vector body in a
+     * JSON-RPC `tools/call` envelope and posts to `baseUrl` as-is (no path
+     * join); operation name comes from the vector URL's last segment.
      *
      * MCP mode trades the canonicalization-edge coverage for reach: vectors
      * 005–008 fold into plain POSTs against the MCP endpoint, but the grader
      * works against any MCP agent that wires a verifier at the HTTP layer.
+     *
+     * **Defaults differ by layer, deliberately.** Omitting the field here
+     * builds a raw request: this is the low-level primitive, and a caller
+     * holding a vector and a REST target shouldn't have its body silently
+     * re-framed. Every grader entry point above it (`gradeRequestSigning`,
+     * `gradeOneVector`, the storyboard `request_signing_probe` dispatch)
+     * resolves the default to `'mcp'` instead, because the runner reaches
+     * agents through `tools/call` and raw replay 404s on an MCP mount before
+     * the verifier runs (adcontextprotocol/adcp#6548). REST-binding agents
+     * pass `'raw'` explicitly — `adcp storyboard run --signing-transport raw`
+     * or `adcp grade request-signing --transport raw`.
      */
     transport?: 'raw' | 'mcp';
     /**

package/dist/lib/testing/storyboard/request-signing/grader.d.mts

@@ -1,5 +1,5 @@
 import { type LoadVectorsOptions } from './vector-loader.mjs';
-import type { VerifierCapabilityFixture } from './types.mjs';
+import type { NegativeVector, PositiveVector, VerifierCapabilityFixture } from './types.mjs';
 export interface GradeOptions extends LoadVectorsOptions {
     /** Allow http:// and private-IP destinations. Off by default (match fetchProbe). */
     allowPrivateIp?: boolean;
@@ -155,6 +155,15 @@ export interface VectorGradeResult {
     expected_error_code?: string;
     http_status: number;
     diagnostic?: string;
+    /**
+     * The request never completed: `ProbeResult.error` was set (DNS, connect,
+     * TLS, SSRF guard). Structured rather than left to the `probe error:`
+     * prefix on `diagnostic`, because callers have to tell a transport fault
+     * from a verdict — both report `http_status: 0` with text attached, and
+     * the storyboard's coverage classifier would otherwise report an
+     * unreachable agent as "only the SDK self-check ran".
+     */
+    transport_error?: boolean;
     probe_duration_ms: number;
     /**
      * For neg/016 (replayed-nonce) only: total number of (probe1, probe2)
@@ -201,9 +210,43 @@ export interface GradeReport {
  *     copy fires.
  */
 export declare function gradeRequestSigning(agentUrl: string, options?: GradeOptions): Promise<GradeReport>;
+/** A vector excluded on its own terms, independent of the run's transport. */
+export interface SemanticVectorExclusion {
+    skip_reason: 'capability_profile_mismatch' | 'transport_ungradable';
+    diagnostic: string;
+}
+/**
+ * Exclusions that depend on the vector and the agent's declared profile, not
+ * on how this run reaches the agent: a capability-profile mismatch, and the
+ * `TRANSPORT_UNGRADABLE` carve-outs above (which no HTTP binding can grade on
+ * any protocol). Returns `undefined` when the vector is gradable in principle.
+ *
+ * Shared with the storyboard probe so both entry points apply the same rules
+ * in the same order, and so the probe can apply them *before* its own
+ * protocol-transport gate. Gating on protocol first would relabel a vector the
+ * agent's profile never opted into — or one no transport can carry — as this
+ * protocol's missing coverage (adcp-client#2954).
+ */
+export declare function semanticVectorExclusion(vector: PositiveVector | NegativeVector, declaredCapability?: Pick<VerifierCapabilityFixture, 'protocol_methods_required_for'>): SemanticVectorExclusion | undefined;
 /**
  * Grade a single vector. Loads the vectors+keys+contract on every call; for
  * the storyboard-runner dispatch path where the caller runs many vectors in
  * sequence, prefer `gradeRequestSigning` which loads once.
  */
 export declare function gradeOneVector(vectorId: string, kind: 'positive' | 'negative', agentUrl: string, options?: GradeOptions): Promise<VectorGradeResult>;
+/**
+ * The `protocol_methods_required_for` slice of `capabilityMismatch`
+ * (adcp#4326 namespace): negative vectors that grade a JSON-RPC protocol
+ * method (only `028-unsigned-protocol-method-required` today) don't apply to
+ * an agent that never claimed to require a signature on that method, exactly
+ * as `required_for` works for AdCP-tool vectors.
+ *
+ * Split out and exported because it is the one dimension safe to decide from
+ * an agent's *advertised* `request_signing` block. The others describe the
+ * profile a vector was authored against — an operator selects a matching one
+ * with `--covers-content-digest` / `agentCapability`, and reading them off a
+ * live advertisement instead would exclude most of the vector set (a
+ * `covers_content_digest: 'either', required_for: []` advertisement mismatches
+ * 39 of 40 vectors), quietly gutting the storyboard it was meant to sharpen.
+ */
+export declare function protocolMethodCoverageMismatch(vector: PositiveVector | NegativeVector, agentCap: Pick<VerifierCapabilityFixture, 'protocol_methods_required_for'>): string | undefined;

package/dist/lib/testing/storyboard/request-signing/grader.d.ts

@@ -1,5 +1,5 @@
 import { type LoadVectorsOptions } from './vector-loader';
-import type { VerifierCapabilityFixture } from './types';
+import type { NegativeVector, PositiveVector, VerifierCapabilityFixture } from './types';
 export interface GradeOptions extends LoadVectorsOptions {
     /** Allow http:// and private-IP destinations. Off by default (match fetchProbe). */
     allowPrivateIp?: boolean;
@@ -155,6 +155,15 @@ export interface VectorGradeResult {
     expected_error_code?: string;
     http_status: number;
     diagnostic?: string;
+    /**
+     * The request never completed: `ProbeResult.error` was set (DNS, connect,
+     * TLS, SSRF guard). Structured rather than left to the `probe error:`
+     * prefix on `diagnostic`, because callers have to tell a transport fault
+     * from a verdict — both report `http_status: 0` with text attached, and
+     * the storyboard's coverage classifier would otherwise report an
+     * unreachable agent as "only the SDK self-check ran".
+     */
+    transport_error?: boolean;
     probe_duration_ms: number;
     /**
      * For neg/016 (replayed-nonce) only: total number of (probe1, probe2)
@@ -201,9 +210,43 @@ export interface GradeReport {
  *     copy fires.
  */
 export declare function gradeRequestSigning(agentUrl: string, options?: GradeOptions): Promise<GradeReport>;
+/** A vector excluded on its own terms, independent of the run's transport. */
+export interface SemanticVectorExclusion {
+    skip_reason: 'capability_profile_mismatch' | 'transport_ungradable';
+    diagnostic: string;
+}
+/**
+ * Exclusions that depend on the vector and the agent's declared profile, not
+ * on how this run reaches the agent: a capability-profile mismatch, and the
+ * `TRANSPORT_UNGRADABLE` carve-outs above (which no HTTP binding can grade on
+ * any protocol). Returns `undefined` when the vector is gradable in principle.
+ *
+ * Shared with the storyboard probe so both entry points apply the same rules
+ * in the same order, and so the probe can apply them *before* its own
+ * protocol-transport gate. Gating on protocol first would relabel a vector the
+ * agent's profile never opted into — or one no transport can carry — as this
+ * protocol's missing coverage (adcp-client#2954).
+ */
+export declare function semanticVectorExclusion(vector: PositiveVector | NegativeVector, declaredCapability?: Pick<VerifierCapabilityFixture, 'protocol_methods_required_for'>): SemanticVectorExclusion | undefined;
 /**
  * Grade a single vector. Loads the vectors+keys+contract on every call; for
  * the storyboard-runner dispatch path where the caller runs many vectors in
  * sequence, prefer `gradeRequestSigning` which loads once.
  */
 export declare function gradeOneVector(vectorId: string, kind: 'positive' | 'negative', agentUrl: string, options?: GradeOptions): Promise<VectorGradeResult>;
+/**
+ * The `protocol_methods_required_for` slice of `capabilityMismatch`
+ * (adcp#4326 namespace): negative vectors that grade a JSON-RPC protocol
+ * method (only `028-unsigned-protocol-method-required` today) don't apply to
+ * an agent that never claimed to require a signature on that method, exactly
+ * as `required_for` works for AdCP-tool vectors.
+ *
+ * Split out and exported because it is the one dimension safe to decide from
+ * an agent's *advertised* `request_signing` block. The others describe the
+ * profile a vector was authored against — an operator selects a matching one
+ * with `--covers-content-digest` / `agentCapability`, and reading them off a
+ * live advertisement instead would exclude most of the vector set (a
+ * `covers_content_digest: 'either', required_for: []` advertisement mismatches
+ * 39 of 40 vectors), quietly gutting the storyboard it was meant to sharpen.
+ */
+export declare function protocolMethodCoverageMismatch(vector: PositiveVector | NegativeVector, agentCap: Pick<VerifierCapabilityFixture, 'protocol_methods_required_for'>): string | undefined;

package/dist/lib/testing/storyboard/request-signing/grader.js

@@ -19,7 +19,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var grader_exports = {};
 __export(grader_exports, {
   gradeOneVector: () => gradeOneVector,
-  gradeRequestSigning: () => gradeRequestSigning
+  gradeRequestSigning: () => gradeRequestSigning,
+  protocolMethodCoverageMismatch: () => protocolMethodCoverageMismatch,
+  semanticVectorExclusion: () => semanticVectorExclusion
 });
 module.exports = __toCommonJS(grader_exports);
 var import_crypto = require("crypto");
@@ -119,6 +121,15 @@ const TRANSPORT_UNGRADABLE = {
   "026-non-ascii-host": "HTTP transport punycodes U-labels before the request leaves the client; verified at the library level.",
   "profile-3.2/negative/002-multiple-trailing-dots": "HTTP transport cannot route to an intentionally malformed DNS authority; verified at the library level."
 };
+function semanticVectorExclusion(vector, declaredCapability) {
+  if (declaredCapability) {
+    const mismatch = protocolMethodCoverageMismatch(vector, declaredCapability);
+    if (mismatch) return { skip_reason: "capability_profile_mismatch", diagnostic: mismatch };
+  }
+  const transportReason = TRANSPORT_UNGRADABLE[vector.id];
+  if (transportReason) return { skip_reason: "transport_ungradable", diagnostic: transportReason };
+  return void 0;
+}
 function preflightSkip(vector, kind, contract, options) {
   const expected_error_code = kind === "negative" ? vector.expected_error_code : void 0;
   const base = {
@@ -139,12 +150,7 @@ function preflightSkip(vector, kind, contract, options) {
   if (options.agentCapability) {
     const mismatch = capabilityMismatch(vector, options.agentCapability);
     if (mismatch) {
-      return {
-        ...base,
-        skipped: true,
-        skip_reason: "capability_profile_mismatch",
-        diagnostic: mismatch
-      };
+      return { ...base, skipped: true, skip_reason: "capability_profile_mismatch", diagnostic: mismatch };
     }
   }
   if (!options.agentCapability && options.agentContentDigestPolicy) {
@@ -158,9 +164,9 @@ function preflightSkip(vector, kind, contract, options) {
       };
     }
   }
-  const transportReason = TRANSPORT_UNGRADABLE[vector.id];
-  if (transportReason) {
-    return { ...base, skipped: true, skip_reason: "transport_ungradable", diagnostic: transportReason };
+  const semantic = semanticVectorExclusion(vector);
+  if (semantic) {
+    return { ...base, skipped: true, skip_reason: semantic.skip_reason, diagnostic: semantic.diagnostic };
   }
   if (kind === "positive" && (options.transport ?? "mcp") === "mcp" && MCP_FLATTENED_VECTORS.has(vector.id)) {
     return {
@@ -242,6 +248,7 @@ function gradePositive(vector, probe) {
     passed: accepted && !probe.error,
     http_status: probe.status,
     diagnostic: accepted ? void 0 : buildPositiveDiagnostic(vector, probe),
+    ...probe.error !== void 0 && { transport_error: true },
     probe_duration_ms: probe.duration_ms
   };
 }
@@ -321,6 +328,7 @@ function gradeStaticNegative(vector, loaded, probeOpts, buildOpts) {
     expected_error_code: vector.expected_error_code,
     actual_error_code: probe.wwwAuthenticateErrorCode,
     diagnostic: buildNegativeDiagnostic(vector, probe),
+    ...probe.error !== void 0 && { transport_error: true },
     probe_duration_ms: probe.duration_ms
   }));
 }
@@ -329,6 +337,7 @@ async function gradeReplayWindow(vector, loaded, probeOpts, buildOpts, pairCount
   let rejectedCount = 0;
   let lastSecondStatus = 0;
   let lastSecondErrorCode;
+  let sawSecondTransportError = false;
   for (let i = 0; i < pairCount; i++) {
     const nonce = (0, import_crypto.randomBytes)(16).toString("base64url");
     const signed = buildPositiveRequestFromNegative(vector, loaded, { ...buildOpts, nonce });
@@ -343,6 +352,7 @@ async function gradeReplayWindow(vector, loaded, probeOpts, buildOpts, pairCount
         expected_error_code: vector.expected_error_code,
         actual_error_code: first.wwwAuthenticateErrorCode,
         diagnostic: `replay_window contract: first submission MUST be accepted but agent returned ${first.status}` + (first.wwwAuthenticateErrorCode ? ` (error="${first.wwwAuthenticateErrorCode}")` : "") + ". Check runner JWKS registration with the agent.",
+        ...first.error !== void 0 && { transport_error: true },
         probe_duration_ms: totalDurationMs,
         replay_pairs_tried: i + 1,
         replay_pairs_rejected: rejectedCount
@@ -352,6 +362,7 @@ async function gradeReplayWindow(vector, loaded, probeOpts, buildOpts, pairCount
     totalDurationMs += second.duration_ms;
     lastSecondStatus = second.status;
     lastSecondErrorCode = second.wwwAuthenticateErrorCode;
+    if (second.error !== void 0) sawSecondTransportError = true;
     if (negativeAcceptedErrorCode(vector, second)) {
       rejectedCount++;
     }
@@ -364,6 +375,11 @@ async function gradeReplayWindow(vector, loaded, probeOpts, buildOpts, pairCount
       http_status: lastSecondStatus,
       expected_error_code: vector.expected_error_code,
       actual_error_code: lastSecondErrorCode,
+      // Unreachable today — an errored probe cannot satisfy
+      // `negativeAcceptedErrorCode`, so every pair rejecting implies none
+      // faulted — but carried on both terminal paths so the provenance
+      // cannot be lost if that counting changes.
+      ...sawSecondTransportError && { transport_error: true },
       probe_duration_ms: totalDurationMs,
       replay_pairs_tried: pairCount,
       replay_pairs_rejected: pairCount
@@ -377,6 +393,7 @@ async function gradeReplayWindow(vector, loaded, probeOpts, buildOpts, pairCount
     expected_error_code: vector.expected_error_code,
     actual_error_code: lastSecondErrorCode,
     diagnostic: buildReplayWindowFailDiagnostic(vector, rejectedCount, pairCount),
+    ...sawSecondTransportError && { transport_error: true },
     probe_duration_ms: totalDurationMs,
     replay_pairs_tried: pairCount,
     replay_pairs_rejected: rejectedCount
@@ -391,24 +408,30 @@ function buildReplayWindowFailDiagnostic(vector, rejectedCount, pairCount) {
 async function gradeRateAbuse(vector, loaded, contract, probeOpts, buildOpts, options) {
   const cap = options.rateAbuseCap ?? contract.stateful_vector_contract.rate_abuse.grading_target_per_keyid_cap_requests;
   let durationMs = 0;
+  let fillTransportError;
   for (let i = 0; i < cap; i++) {
     const nonce = (0, import_crypto.randomBytes)(16).toString("base64url");
     const signed = (0, import_builder.buildNegativeRequest)(vector, loaded.keys, { nonce, ...buildOpts });
     const probe2 = await (0, import_probe.probeSignedRequest)(signed, probeOpts);
     durationMs += probe2.duration_ms;
+    if (probe2.error !== void 0 && fillTransportError === void 0) {
+      fillTransportError = `cap-fill request ${i + 1} of ${cap} never completed: ${probe2.error}`;
+    }
   }
   const finalNonce = (0, import_crypto.randomBytes)(16).toString("base64url");
   const capPlusOne = (0, import_builder.buildNegativeRequest)(vector, loaded.keys, { nonce: finalNonce, ...buildOpts });
   const probe = await (0, import_probe.probeSignedRequest)(capPlusOne, probeOpts);
   durationMs += probe.duration_ms;
+  const capEstablished = fillTransportError === void 0;
   return {
     vector_id: vector.id,
     kind: "negative",
-    passed: negativeAcceptedErrorCode(vector, probe),
+    passed: capEstablished && negativeAcceptedErrorCode(vector, probe),
     http_status: probe.status,
     expected_error_code: vector.expected_error_code,
     actual_error_code: probe.wwwAuthenticateErrorCode,
-    diagnostic: buildNegativeDiagnostic(vector, probe),
+    diagnostic: capEstablished ? buildNegativeDiagnostic(vector, probe) : `rate_abuse contract: the per-keyid cap was never established \u2014 ${fillTransportError}. The (cap+1) response (status ${probe.status}` + (probe.wwwAuthenticateErrorCode ? `, error="${probe.wwwAuthenticateErrorCode}"` : "") + ") says nothing about the limiter, so this vector is ungraded rather than passing.",
+    ...(probe.error !== void 0 || !capEstablished) && { transport_error: true },
     probe_duration_ms: durationMs
   };
 }
@@ -476,15 +499,14 @@ function capabilityMismatch(vector, agentCap) {
   if (missingRequiredFor.length > 0) {
     return `Vector asserts required_for includes [${missingRequiredFor.join(", ")}] but agent's required_for does not. Either add the operation to the agent's request_signing.required_for, or accept the skip.`;
   }
-  const vectorProtocolMethodsRequiredFor = vectorCap.protocol_methods_required_for ?? [];
-  const agentProtocolMethodsRequiredForSet = new Set(agentCap.protocol_methods_required_for ?? []);
-  const missingProtocolMethodsRequiredFor = vectorProtocolMethodsRequiredFor.filter(
-    (method) => !agentProtocolMethodsRequiredForSet.has(method)
-  );
-  if (missingProtocolMethodsRequiredFor.length > 0) {
-    return `Vector asserts protocol_methods_required_for includes [${missingProtocolMethodsRequiredFor.join(", ")}] but agent's protocol_methods_required_for does not. Either add the method to the agent's request_signing.protocol_methods_required_for, or accept the skip.`;
-  }
-  return void 0;
+  return protocolMethodCoverageMismatch(vector, agentCap);
+}
+function protocolMethodCoverageMismatch(vector, agentCap) {
+  const required = vector.verifier_capability.protocol_methods_required_for ?? [];
+  const declared = new Set(agentCap.protocol_methods_required_for ?? []);
+  const missing = required.filter((method) => !declared.has(method));
+  if (missing.length === 0) return void 0;
+  return `Vector asserts protocol_methods_required_for includes [${missing.join(", ")}] but agent's protocol_methods_required_for does not. Either add the method to the agent's request_signing.protocol_methods_required_for, or accept the skip.`;
 }
 function buildNegativeDiagnostic(vector, probe) {
   if (probe.error) return `probe error: ${probe.error}`;
@@ -500,5 +522,7 @@ function buildNegativeDiagnostic(vector, probe) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   gradeOneVector,
-  gradeRequestSigning
+  gradeRequestSigning,
+  protocolMethodCoverageMismatch,
+  semanticVectorExclusion
 });

package/dist/lib/testing/storyboard/request-signing/grader.mjs

@@ -101,6 +101,15 @@ const TRANSPORT_UNGRADABLE = {
   "026-non-ascii-host": "HTTP transport punycodes U-labels before the request leaves the client; verified at the library level.",
   "profile-3.2/negative/002-multiple-trailing-dots": "HTTP transport cannot route to an intentionally malformed DNS authority; verified at the library level."
 };
+function semanticVectorExclusion(vector, declaredCapability) {
+  if (declaredCapability) {
+    const mismatch = protocolMethodCoverageMismatch(vector, declaredCapability);
+    if (mismatch) return { skip_reason: "capability_profile_mismatch", diagnostic: mismatch };
+  }
+  const transportReason = TRANSPORT_UNGRADABLE[vector.id];
+  if (transportReason) return { skip_reason: "transport_ungradable", diagnostic: transportReason };
+  return void 0;
+}
 function preflightSkip(vector, kind, contract, options) {
   const expected_error_code = kind === "negative" ? vector.expected_error_code : void 0;
   const base = {
@@ -121,12 +130,7 @@ function preflightSkip(vector, kind, contract, options) {
   if (options.agentCapability) {
     const mismatch = capabilityMismatch(vector, options.agentCapability);
     if (mismatch) {
-      return {
-        ...base,
-        skipped: true,
-        skip_reason: "capability_profile_mismatch",
-        diagnostic: mismatch
-      };
+      return { ...base, skipped: true, skip_reason: "capability_profile_mismatch", diagnostic: mismatch };
     }
   }
   if (!options.agentCapability && options.agentContentDigestPolicy) {
@@ -140,9 +144,9 @@ function preflightSkip(vector, kind, contract, options) {
       };
     }
   }
-  const transportReason = TRANSPORT_UNGRADABLE[vector.id];
-  if (transportReason) {
-    return { ...base, skipped: true, skip_reason: "transport_ungradable", diagnostic: transportReason };
+  const semantic = semanticVectorExclusion(vector);
+  if (semantic) {
+    return { ...base, skipped: true, skip_reason: semantic.skip_reason, diagnostic: semantic.diagnostic };
   }
   if (kind === "positive" && (options.transport ?? "mcp") === "mcp" && MCP_FLATTENED_VECTORS.has(vector.id)) {
     return {
@@ -224,6 +228,7 @@ function gradePositive(vector, probe) {
     passed: accepted && !probe.error,
     http_status: probe.status,
     diagnostic: accepted ? void 0 : buildPositiveDiagnostic(vector, probe),
+    ...probe.error !== void 0 && { transport_error: true },
     probe_duration_ms: probe.duration_ms
   };
 }
@@ -303,6 +308,7 @@ function gradeStaticNegative(vector, loaded, probeOpts, buildOpts) {
     expected_error_code: vector.expected_error_code,
     actual_error_code: probe.wwwAuthenticateErrorCode,
     diagnostic: buildNegativeDiagnostic(vector, probe),
+    ...probe.error !== void 0 && { transport_error: true },
     probe_duration_ms: probe.duration_ms
   }));
 }
@@ -311,6 +317,7 @@ async function gradeReplayWindow(vector, loaded, probeOpts, buildOpts, pairCount
   let rejectedCount = 0;
   let lastSecondStatus = 0;
   let lastSecondErrorCode;
+  let sawSecondTransportError = false;
   for (let i = 0; i < pairCount; i++) {
     const nonce = randomBytes(16).toString("base64url");
     const signed = buildPositiveRequestFromNegative(vector, loaded, { ...buildOpts, nonce });
@@ -325,6 +332,7 @@ async function gradeReplayWindow(vector, loaded, probeOpts, buildOpts, pairCount
         expected_error_code: vector.expected_error_code,
         actual_error_code: first.wwwAuthenticateErrorCode,
         diagnostic: `replay_window contract: first submission MUST be accepted but agent returned ${first.status}` + (first.wwwAuthenticateErrorCode ? ` (error="${first.wwwAuthenticateErrorCode}")` : "") + ". Check runner JWKS registration with the agent.",
+        ...first.error !== void 0 && { transport_error: true },
         probe_duration_ms: totalDurationMs,
         replay_pairs_tried: i + 1,
         replay_pairs_rejected: rejectedCount
@@ -334,6 +342,7 @@ async function gradeReplayWindow(vector, loaded, probeOpts, buildOpts, pairCount
     totalDurationMs += second.duration_ms;
     lastSecondStatus = second.status;
     lastSecondErrorCode = second.wwwAuthenticateErrorCode;
+    if (second.error !== void 0) sawSecondTransportError = true;
     if (negativeAcceptedErrorCode(vector, second)) {
       rejectedCount++;
     }
@@ -346,6 +355,11 @@ async function gradeReplayWindow(vector, loaded, probeOpts, buildOpts, pairCount
       http_status: lastSecondStatus,
       expected_error_code: vector.expected_error_code,
       actual_error_code: lastSecondErrorCode,
+      // Unreachable today — an errored probe cannot satisfy
+      // `negativeAcceptedErrorCode`, so every pair rejecting implies none
+      // faulted — but carried on both terminal paths so the provenance
+      // cannot be lost if that counting changes.
+      ...sawSecondTransportError && { transport_error: true },
       probe_duration_ms: totalDurationMs,
       replay_pairs_tried: pairCount,
       replay_pairs_rejected: pairCount
@@ -359,6 +373,7 @@ async function gradeReplayWindow(vector, loaded, probeOpts, buildOpts, pairCount
     expected_error_code: vector.expected_error_code,
     actual_error_code: lastSecondErrorCode,
     diagnostic: buildReplayWindowFailDiagnostic(vector, rejectedCount, pairCount),
+    ...sawSecondTransportError && { transport_error: true },
     probe_duration_ms: totalDurationMs,
     replay_pairs_tried: pairCount,
     replay_pairs_rejected: rejectedCount
@@ -373,24 +388,30 @@ function buildReplayWindowFailDiagnostic(vector, rejectedCount, pairCount) {
 async function gradeRateAbuse(vector, loaded, contract, probeOpts, buildOpts, options) {
   const cap = options.rateAbuseCap ?? contract.stateful_vector_contract.rate_abuse.grading_target_per_keyid_cap_requests;
   let durationMs = 0;
+  let fillTransportError;
   for (let i = 0; i < cap; i++) {
     const nonce = randomBytes(16).toString("base64url");
     const signed = buildNegativeRequest(vector, loaded.keys, { nonce, ...buildOpts });
     const probe2 = await probeSignedRequest(signed, probeOpts);
     durationMs += probe2.duration_ms;
+    if (probe2.error !== void 0 && fillTransportError === void 0) {
+      fillTransportError = `cap-fill request ${i + 1} of ${cap} never completed: ${probe2.error}`;
+    }
   }
   const finalNonce = randomBytes(16).toString("base64url");
   const capPlusOne = buildNegativeRequest(vector, loaded.keys, { nonce: finalNonce, ...buildOpts });
   const probe = await probeSignedRequest(capPlusOne, probeOpts);
   durationMs += probe.duration_ms;
+  const capEstablished = fillTransportError === void 0;
   return {
     vector_id: vector.id,
     kind: "negative",
-    passed: negativeAcceptedErrorCode(vector, probe),
+    passed: capEstablished && negativeAcceptedErrorCode(vector, probe),
     http_status: probe.status,
     expected_error_code: vector.expected_error_code,
     actual_error_code: probe.wwwAuthenticateErrorCode,
-    diagnostic: buildNegativeDiagnostic(vector, probe),
+    diagnostic: capEstablished ? buildNegativeDiagnostic(vector, probe) : `rate_abuse contract: the per-keyid cap was never established \u2014 ${fillTransportError}. The (cap+1) response (status ${probe.status}` + (probe.wwwAuthenticateErrorCode ? `, error="${probe.wwwAuthenticateErrorCode}"` : "") + ") says nothing about the limiter, so this vector is ungraded rather than passing.",
+    ...(probe.error !== void 0 || !capEstablished) && { transport_error: true },
     probe_duration_ms: durationMs
   };
 }
@@ -458,15 +479,14 @@ function capabilityMismatch(vector, agentCap) {
   if (missingRequiredFor.length > 0) {
     return `Vector asserts required_for includes [${missingRequiredFor.join(", ")}] but agent's required_for does not. Either add the operation to the agent's request_signing.required_for, or accept the skip.`;
   }
-  const vectorProtocolMethodsRequiredFor = vectorCap.protocol_methods_required_for ?? [];
-  const agentProtocolMethodsRequiredForSet = new Set(agentCap.protocol_methods_required_for ?? []);
-  const missingProtocolMethodsRequiredFor = vectorProtocolMethodsRequiredFor.filter(
-    (method) => !agentProtocolMethodsRequiredForSet.has(method)
-  );
-  if (missingProtocolMethodsRequiredFor.length > 0) {
-    return `Vector asserts protocol_methods_required_for includes [${missingProtocolMethodsRequiredFor.join(", ")}] but agent's protocol_methods_required_for does not. Either add the method to the agent's request_signing.protocol_methods_required_for, or accept the skip.`;
-  }
-  return void 0;
+  return protocolMethodCoverageMismatch(vector, agentCap);
+}
+function protocolMethodCoverageMismatch(vector, agentCap) {
+  const required = vector.verifier_capability.protocol_methods_required_for ?? [];
+  const declared = new Set(agentCap.protocol_methods_required_for ?? []);
+  const missing = required.filter((method) => !declared.has(method));
+  if (missing.length === 0) return void 0;
+  return `Vector asserts protocol_methods_required_for includes [${missing.join(", ")}] but agent's protocol_methods_required_for does not. Either add the method to the agent's request_signing.protocol_methods_required_for, or accept the skip.`;
 }
 function buildNegativeDiagnostic(vector, probe) {
   if (probe.error) return `probe error: ${probe.error}`;
@@ -481,5 +501,7 @@ function buildNegativeDiagnostic(vector, probe) {
 }
 export {
   gradeOneVector,
-  gradeRequestSigning
+  gradeRequestSigning,
+  protocolMethodCoverageMismatch,
+  semanticVectorExclusion
 };

package/dist/lib/testing/storyboard/request-signing/probe-dispatch.d.mts

@@ -1,22 +1,97 @@
 import type { HttpProbeResult, StoryboardRunOptions } from '../types.mjs';
 /**
- * Resolve the vector transport for a graded agent. Defaults to `'mcp'`: the
- * storyboard runner reaches agents through `tools/call` (MCP, or the
- * AdCP-over-A2A binding) — never through per-task HTTP paths — so replaying
- * the vectors' recorded REST targets (`/adcp/create_media_buy`, raw task
- * body) verbatim guarantees a routing 404 on every MCP-transport agent
- * before its verifier can run (adcontextprotocol/adcp#6548). Operators
- * grading a REST-binding agent opt back in with
- * `request_signing.transport: 'raw'`.
+ * Detail surfaced on each vector step an A2A run cannot frame. Written for
+ * the operator reading a conformance report: it has to say what coverage is
+ * missing and what would restore it.
+ *
+ * Reported as detailed reason `signing_transport_unavailable`, canonical
+ * `not_applicable` with the sub-reason token as `skip.detail` — the output
+ * contract's registered shape. What keeps the gap from reading as a pass is
+ * `signingCoverage` in the runner, not the reason: no vector reached the
+ * agent, so the storyboard cannot pass and the track grades `partial`
+ * instead of letting a sibling storyboard's passes roll it up green.
+ */
+export declare const SIGNING_VECTORS_UNAVAILABLE_DETAIL: string;
+/**
+ * Resolve the vector transport for a graded agent.
+ *
+ * Defaults to `'mcp'`: the storyboard runner reaches MCP agents through
+ * `tools/call` — never through per-task HTTP paths — so replaying the
+ * vectors' recorded REST targets (`/adcp/create_media_buy`, raw task body)
+ * verbatim guarantees a routing 404 on every MCP-transport agent before its
+ * verifier can run (adcontextprotocol/adcp#6548). Operators grading a
+ * REST-binding agent opt back in with `request_signing.transport: 'raw'`.
+ *
+ * Returns `undefined` on an A2A run that didn't pick a transport explicitly:
+ * neither dispatch shape this runner implements is an A2A request, so the
+ * caller skips those vectors as `signing_transport_unavailable` instead of
+ * POSTing an MCP envelope at an A2A
+ * endpoint and grading the resulting 405 as a signature failure
+ * (adcp-client#2954). An explicit `transport` still wins — that's the escape
+ * hatch for an agent whose MCP or REST binding answers on the same URL as its
+ * A2A card.
+ *
+ * There is no `'a2a'` member yet because the path isn't wired here, not
+ * because the official client is incapable: `@a2a-js/sdk` issues the JSON-RPC
+ * methods these vectors target, `tasks/cancel` included. Wiring it means
+ * signing a request the official client issues — applying each vector's RFC
+ * 9421 headers to that client's own request — plus an upstream answer for how
+ * a verifier scopes `required_for` over A2A methods. RFC 9421 conformance
+ * needs byte-level control of the request, which `builder.ts` has for the two
+ * bindings AdCP defines for these fixtures; there is no third binding to
+ * write bytes against, and picking one here would be the SDK inventing it.
+ * The only vectors that still grade are the ones needing no wire exchange at
+ * all — see `gradableWithoutVectorTransport`.
  */
 export declare function resolveVectorTransport(rsOpts: {
     transport?: 'raw' | 'mcp';
-}): 'raw' | 'mcp';
+}, protocol?: 'mcp' | 'a2a'): 'raw' | 'mcp' | undefined;
 /**
  * Dispatch a synthesized request-signing step. The step ID encodes the vector
  * (`positive-<id>` / `negative-<id>`); this helper decodes it, runs the
  * grader's per-vector logic, and maps the `VectorGradeResult` to an
- * `HttpProbeResult`-shaped return so the existing validation pipeline
- * (`http_status`, `http_status_in`) works unchanged.
+ * `HttpProbeResult`-shaped return so the HTTP validation pipeline
+ * (`http_status`, `http_status_in`) works unchanged for probed vectors.
+ *
+ * Vectors the grader decides in-library rather than over HTTP (the
+ * `jwks_override` negatives) carry `http_status: 0` by contract — there is no
+ * wire exchange to report. Their verdict travels on `error`: unset when the
+ * library verifier produced the expected rejection, set to the grader's
+ * diagnostic otherwise. `synthesizeNegativeStep` pairs those vectors with a
+ * `probe_passed` validation that reads exactly that field; asserting an HTTP
+ * status against them would compare a grade to a status code that no
+ * implementation can move (adcp-client#2955).
  */
 export declare function probeRequestSigningVector(stepId: string, agentUrl: string, options: StoryboardRunOptions): Promise<HttpProbeResult>;
+/**
+ * Wire-name grammar for `request_signing.protocol_methods_*`, mirroring the
+ * `items` constraint the capabilities schema ships for each AdCP line:
+ *
+ *   - 3.2+ — slash paths of one or more segments (`tasks/cancel`,
+ *     `tasks/pushNotificationConfig/set`) or A2A 1.0 PascalCase names
+ *     (`CancelTask`), 256 characters max, and never `tools/call`.
+ *   - pre-3.2 — a single lowercase slash pair (`tasks/cancel`), with no
+ *     length cap, because that line's schema declares none.
+ *
+ * Keyed by line rather than taking the union of both, because the union is
+ * unsafe in one direction: honouring a 3.2-only name on a 3.1 run accepts a
+ * declaration that line's schema rejects, and any accepted declaration
+ * omitting the vector's method suppresses that vector.
+ *
+ * Pinned against both shipped schemas by test — a grammar that drifts wider
+ * than the schema re-opens exactly that hole.
+ */
+export declare const PROTOCOL_METHOD_GRAMMARS: {
+    readonly since_3_2: {
+        readonly pattern: RegExp;
+        readonly maxLength: number | undefined;
+        readonly forbidden: readonly string[];
+    };
+    readonly pre_3_2: {
+        readonly pattern: RegExp;
+        readonly maxLength: number | undefined;
+        readonly forbidden: readonly string[];
+    };
+};
+/** Token validator for an AdCP version string, per `PROTOCOL_METHOD_GRAMMARS`. */
+export declare function protocolMethodGrammarFor(version: string): (token: string) => boolean;