@adcp/sdk 16.0.0-beta.6 → 16.0.0-beta.8

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

@@ -22,6 +22,7 @@
  * so failures can point at a specific spec clause. Numbers are 1-based to
  * match the security doc.
  */
+import { type SfBinaryEncoding } from './content-digest.mjs';
 import type { JwksResolver } from './jwks.mjs';
 import { type PublisherSigningKeyPin } from './publisher-pins.mjs';
 import { type ReplayStore } from './replay.mjs';
@@ -43,6 +44,16 @@ export interface WebhookRequestLike {
 export declare const WEBHOOK_MANDATORY_COMPONENTS: ReadonlyArray<string>;
 export interface VerifyWebhookOptions {
     jwks: JwksResolver;
+    /**
+     * Trusted receiver configuration for the Signature byte sequence.
+     * Defaults to `legacy-base64url`, as the AdCP webhook-v1 profile requires
+     * throughout 3.x. Set `rfc8941-base64` only for an explicitly configured
+     * peer emitting standard padded Base64 (for example, a generic RFC 9421
+     * request signer with the webhook tag). There is no encoding fallback.
+     * URL canonicalization remains AdCP 3.2 in either mode; Signature encoding
+     * does not identify a webhook's AdCP version.
+     */
+    signatureEncoding?: SfBinaryEncoding;
     /** Applicable publishers from the verifier's own media-buy record. */
     publisherPins?: readonly PublisherSigningKeyPin[];
     /** Log the underlying request_signature_* discovery cause locally. */

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

@@ -22,6 +22,7 @@
  * so failures can point at a specific spec clause. Numbers are 1-based to
  * match the security doc.
  */
+import { type SfBinaryEncoding } from './content-digest';
 import type { JwksResolver } from './jwks';
 import { type PublisherSigningKeyPin } from './publisher-pins';
 import { type ReplayStore } from './replay';
@@ -43,6 +44,16 @@ export interface WebhookRequestLike {
 export declare const WEBHOOK_MANDATORY_COMPONENTS: ReadonlyArray<string>;
 export interface VerifyWebhookOptions {
     jwks: JwksResolver;
+    /**
+     * Trusted receiver configuration for the Signature byte sequence.
+     * Defaults to `legacy-base64url`, as the AdCP webhook-v1 profile requires
+     * throughout 3.x. Set `rfc8941-base64` only for an explicitly configured
+     * peer emitting standard padded Base64 (for example, a generic RFC 9421
+     * request signer with the webhook tag). There is no encoding fallback.
+     * URL canonicalization remains AdCP 3.2 in either mode; Signature encoding
+     * does not identify a webhook's AdCP version.
+     */
+    signatureEncoding?: SfBinaryEncoding;
     /** Applicable publishers from the verifier's own media-buy record. */
     publisherPins?: readonly PublisherSigningKeyPin[];
     /** Log the underlying request_signature_* discovery cause locally. */

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

@@ -50,6 +50,7 @@ const WEBHOOK_MANDATORY_COMPONENTS = [
   "content-digest"
 ];
 async function verifyWebhookSignature(request, options) {
+  const signatureEncoding = resolveSignatureEncoding(options.signatureEncoding);
   const currentTime = options.now ?? (() => Date.now() / 1e3);
   const now = currentTime();
   const requiredTag = options.requiredTag ?? WEBHOOK_SIGNING_TAG;
@@ -66,12 +67,12 @@ async function verifyWebhookSignature(request, options) {
   let parsedSig;
   try {
     parsedInput = (0, import_parser.parseSignatureInput)(sigInputHeader);
-    parsedSig = (0, import_parser.parseSignature)(sigHeader, parsedInput.label);
+    parsedSig = (0, import_parser.parseSignature)(sigHeader, parsedInput.label, signatureEncoding);
   } catch (err) {
     throw new import_errors.WebhookSignatureError(
       "webhook_signature_header_malformed",
       1,
-      err instanceof Error ? err.message : String(err)
+      `${err instanceof Error ? err.message : String(err)} (webhook signatureEncoding="${signatureEncoding}").`
     );
   }
   requireParams(parsedInput);
@@ -239,6 +240,12 @@ async function verifyWebhookSignature(request, options) {
     verified_at: Math.floor(now)
   };
 }
+function resolveSignatureEncoding(encoding = "legacy-base64url") {
+  if (encoding !== "legacy-base64url" && encoding !== "rfc8941-base64") {
+    throw new TypeError('signatureEncoding must be "legacy-base64url" or "rfc8941-base64".');
+  }
+  return encoding;
+}
 function assertDelegatedOperatorAuthorizationActive(validUntil, now) {
   if (validUntil !== void 0 && (!Number.isFinite(validUntil) || now >= validUntil)) {
     throw new import_errors.WebhookSignatureError(
@@ -345,9 +352,10 @@ function isWebhookLoopbackHost(hostname) {
   return LOOPBACK_IPV4.test(normalized);
 }
 function createWebhookVerifier(options) {
+  const signatureEncoding = resolveSignatureEncoding(options.signatureEncoding);
   const replayStore = options.replayStore ?? new import_replay.InMemoryReplayStore();
   const revocationStore = options.revocationStore ?? new import_revocation.InMemoryRevocationStore();
-  return (request) => verifyWebhookSignature(request, { ...options, replayStore, revocationStore });
+  return (request) => verifyWebhookSignature(request, { ...options, signatureEncoding, replayStore, revocationStore });
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

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

@@ -23,6 +23,7 @@ const WEBHOOK_MANDATORY_COMPONENTS = [
   "content-digest"
 ];
 async function verifyWebhookSignature(request, options) {
+  const signatureEncoding = resolveSignatureEncoding(options.signatureEncoding);
   const currentTime = options.now ?? (() => Date.now() / 1e3);
   const now = currentTime();
   const requiredTag = options.requiredTag ?? WEBHOOK_SIGNING_TAG;
@@ -39,12 +40,12 @@ async function verifyWebhookSignature(request, options) {
   let parsedSig;
   try {
     parsedInput = parseSignatureInput(sigInputHeader);
-    parsedSig = parseSignature(sigHeader, parsedInput.label);
+    parsedSig = parseSignature(sigHeader, parsedInput.label, signatureEncoding);
   } catch (err) {
     throw new WebhookSignatureError(
       "webhook_signature_header_malformed",
       1,
-      err instanceof Error ? err.message : String(err)
+      `${err instanceof Error ? err.message : String(err)} (webhook signatureEncoding="${signatureEncoding}").`
     );
   }
   requireParams(parsedInput);
@@ -212,6 +213,12 @@ async function verifyWebhookSignature(request, options) {
     verified_at: Math.floor(now)
   };
 }
+function resolveSignatureEncoding(encoding = "legacy-base64url") {
+  if (encoding !== "legacy-base64url" && encoding !== "rfc8941-base64") {
+    throw new TypeError('signatureEncoding must be "legacy-base64url" or "rfc8941-base64".');
+  }
+  return encoding;
+}
 function assertDelegatedOperatorAuthorizationActive(validUntil, now) {
   if (validUntil !== void 0 && (!Number.isFinite(validUntil) || now >= validUntil)) {
     throw new WebhookSignatureError(
@@ -318,9 +325,10 @@ function isWebhookLoopbackHost(hostname) {
   return LOOPBACK_IPV4.test(normalized);
 }
 function createWebhookVerifier(options) {
+  const signatureEncoding = resolveSignatureEncoding(options.signatureEncoding);
   const replayStore = options.replayStore ?? new InMemoryReplayStore();
   const revocationStore = options.revocationStore ?? new InMemoryRevocationStore();
-  return (request) => verifyWebhookSignature(request, { ...options, replayStore, revocationStore });
+  return (request) => verifyWebhookSignature(request, { ...options, signatureEncoding, replayStore, revocationStore });
 }
 export {
   WEBHOOK_MANDATORY_COMPONENTS,

package/dist/lib/supply-path/verify.js

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var verify_exports = {};
 __export(verify_exports, {
@@ -25,7 +35,6 @@ module.exports = __toCommonJS(verify_exports);
 var import_abort = require('../protocols/abort.js');
 var import_publisher_property_selector = require('../discovery/publisher-property-selector.js');
 var import_validation = require('./validation.js');
-var import_registry = require('../registry/index.js');
 var import_fetch_evidence = require('./fetch-evidence.js');
 var import_evaluate = require('./evaluate.js');
 var import_validation2 = require('./validation.js');
@@ -34,7 +43,8 @@ const MAX_PROPERTY_SELECTOR_EXPANSIONS = 4096;
 async function verifySupplyPath(request, options = { source: "authoritative" }) {
   const normalized = (0, import_validation2.validateSupplyPathRequest)(request);
   if (options.source === "registry") {
-    const result = await (options.registry ?? new import_registry.RegistryClient()).verifySupplyPath(normalized);
+    const registry = options.registry ?? new (await import("../registry/index.js")).RegistryClient();
+    const result = await registry.verifySupplyPath(normalized);
     (0, import_validation2.assertRegistrySupplyPathResult)(result, normalized);
     return result;
   }

package/dist/lib/supply-path/verify.mjs

@@ -4,7 +4,6 @@ import {
   expandPublisherPropertySelector
 } from "../discovery/publisher-property-selector.mjs";
 import { domain, records, strings } from "./validation.mjs";
-import { RegistryClient } from "../registry/index.mjs";
 import { SupplyPathEvidenceSession } from "./fetch-evidence.mjs";
 import {
   isUnqualifiedPropertySelector,
@@ -20,7 +19,8 @@ const MAX_PROPERTY_SELECTOR_EXPANSIONS = 4096;
 async function verifySupplyPath(request, options = { source: "authoritative" }) {
   const normalized = validateSupplyPathRequest(request);
   if (options.source === "registry") {
-    const result = await (options.registry ?? new RegistryClient()).verifySupplyPath(normalized);
+    const registry = options.registry ?? new (await import("../registry/index.mjs")).RegistryClient();
+    const result = await registry.verifySupplyPath(normalized);
     assertRegistrySupplyPathResult(result, normalized);
     return result;
   }

package/dist/lib/testing/client.js

@@ -530,12 +530,10 @@ async function discoverAgentProfile(client, signal, schemaAdcpVersion) {
         step.error = versionUnsupported;
       } else if (caps?.data) {
         profile.raw_capabilities = caps.data;
-        const validation = (0, import_client_hooks.validateIncomingResponse)(
-          "get_adcp_capabilities",
+        const validation = (0, import_schema_loader.withServedValidationVersion)(
           caps.data,
-          "strict",
-          void 0,
-          (0, import_schema_loader.resolveServedValidationVersion)(caps.data, schemaAdcpVersion ?? client.getAdcpVersion())
+          schemaAdcpVersion ?? client.getAdcpVersion(),
+          (validationVersion) => (0, import_client_hooks.validateIncomingResponse)("get_adcp_capabilities", caps.data, "strict", void 0, validationVersion)
         );
         if (!validation.valid) {
           profile.capabilities_schema_issues = validation.issues.map((issue) => ({

package/dist/lib/testing/client.mjs

@@ -12,7 +12,7 @@ import { normalizeTransportOptions } from "../protocols/index.mjs";
 import { createHmac, hkdfSync, randomBytes } from "node:crypto";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { validateIncomingResponse } from "../validation/client-hooks.mjs";
-import { resolveServedValidationVersion } from "../validation/schema-loader.mjs";
+import { withServedValidationVersion } from "../validation/schema-loader.mjs";
 import { extractVersionUnsupportedDetails } from "../utils/error-extraction.mjs";
 import { buildAgentSigningContext } from "../signing/client.mjs";
 import { bindAgentStorage } from "../auth/oauth/storage-registry.mjs";
@@ -487,12 +487,10 @@ async function discoverAgentProfile(client, signal, schemaAdcpVersion) {
         step.error = versionUnsupported;
       } else if (caps?.data) {
         profile.raw_capabilities = caps.data;
-        const validation = validateIncomingResponse(
-          "get_adcp_capabilities",
+        const validation = withServedValidationVersion(
           caps.data,
-          "strict",
-          void 0,
-          resolveServedValidationVersion(caps.data, schemaAdcpVersion ?? client.getAdcpVersion())
+          schemaAdcpVersion ?? client.getAdcpVersion(),
+          (validationVersion) => validateIncomingResponse("get_adcp_capabilities", caps.data, "strict", void 0, validationVersion)
         );
         if (!validation.valid) {
           profile.capabilities_schema_issues = validation.issues.map((issue) => ({

package/dist/lib/testing/compliance/comply.js

@@ -1358,7 +1358,12 @@ async function complyImpl(agentUrl, options) {
   }
   (0, import_test_kit.validateTestKit)(testOptions.test_kit);
   const signal = externalSignal;
-  return await (0, import_schema_loader.withExternalSchemaRoot)(complianceIndex.adcp_version, scopedSchemaRoot, async () => {
+  return await (0, import_schema_loader.withExternalSchemaRoot)(
+    complianceIndex.adcp_version,
+    scopedSchemaRoot,
+    () => (0, import_schema_loader.withServedReleaseSchemaRoots)(testOptions.servedReleaseSchemaRoots, () => complyInSchemaScope())
+  );
+  async function complyInSchemaScope() {
     let effectiveOptions = (0, import_runner.applyAdcpVersionRunOptions)(complianceIndex.adcp_version, {
       ...testOptions,
       // `comply()` has always defaulted an unset transport to MCP when it built
@@ -1667,7 +1672,7 @@ async function complyImpl(agentUrl, options) {
       total_duration_ms: Date.now() - start,
       notices: noticesDedup
     };
-  });
+  }
 }
 function hasComplyTimeoutBudgetExpired(start, timeout_ms, now = Date.now()) {
   return timeout_ms !== void 0 && now - start >= timeout_ms;

package/dist/lib/testing/compliance/comply.mjs

@@ -35,7 +35,7 @@ import { closeScopedConnections, withMCPConnectionScope } from "../../protocols/
 import { detectController, hasTestController } from "../test-controller.mjs";
 import { randomBytes } from "crypto";
 import { isPre31AdcpVersion } from "../../utils/adcp-version-config.mjs";
-import { withExternalSchemaRoot } from "../../validation/schema-loader.mjs";
+import { withExternalSchemaRoot, withServedReleaseSchemaRoots } from "../../validation/schema-loader.mjs";
 import { redactOAuthUrlForOutput, redactOAuthUrlsInText } from "../storyboard/oauth-metadata-graph/index.mjs";
 import { LIBRARY_VERSION } from "../../version.mjs";
 import { validationFailsStep } from "../storyboard/validations.mjs";
@@ -1348,7 +1348,12 @@ async function complyImpl(agentUrl, options) {
   }
   validateTestKit(testOptions.test_kit);
   const signal = externalSignal;
-  return await withExternalSchemaRoot(complianceIndex.adcp_version, scopedSchemaRoot, async () => {
+  return await withExternalSchemaRoot(
+    complianceIndex.adcp_version,
+    scopedSchemaRoot,
+    () => withServedReleaseSchemaRoots(testOptions.servedReleaseSchemaRoots, () => complyInSchemaScope())
+  );
+  async function complyInSchemaScope() {
     let effectiveOptions = applyAdcpVersionRunOptions(complianceIndex.adcp_version, {
       ...testOptions,
       // `comply()` has always defaulted an unset transport to MCP when it built
@@ -1657,7 +1662,7 @@ async function complyImpl(agentUrl, options) {
       total_duration_ms: Date.now() - start,
       notices: noticesDedup
     };
-  });
+  }
 }
 function hasComplyTimeoutBudgetExpired(start, timeout_ms, now = Date.now()) {
   return timeout_ms !== void 0 && now - start >= timeout_ms;

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

@@ -16,5 +16,5 @@ export { isSandboxRequest, mergeSeededProductsIntoResponse, filterValidSeededPro
 export type { TestControllerBridge, TestControllerBridgeContext, BridgeFromSessionStoreOptions, SeededCreative, SeededMediaBuy, SeededAccountFinancials, } from '../server/test-controller-bridge.mjs';
 export { runAgainstLocalAgent } from './local-agent-runner.mjs';
 export type { LocalAgentRunResult, PerStoryboardOverride, RunAgainstLocalAgentOptions } from './local-agent-runner.mjs';
-export { registerExternalSchemaRoot, unregisterExternalSchemaRoot, withExternalSchemaRoot } from '../validation/index.mjs';
+export { registerExternalSchemaRoot, unregisterExternalSchemaRoot, withExternalSchemaRoot, withServedReleaseSchemaRoots, } from '../validation/index.mjs';
 export { runStoryboard, runStoryboardStep, applyAdcpVersionRunOptions, applyStoryboardVersionOptions, getFirstStepPreview, parseStoryboard, loadStoryboardFile, normalizeValidationOnlyTasks, VALIDATION_ONLY_TASK, applyFixtureBindingsToRequest, buildFixtureResolutionSpecs, FixtureBindingRegistry, matchesFixtureRequirements, normalizeFixtureMatchExpression, validateFixtureResolutionDeclarations, getComplianceCacheDir, loadComplianceIndex, listBundles, loadBundleStoryboards, listAllComplianceStoryboards, getComplianceStoryboardById, findBundleById, resolveBundleOrStoryboard, resolveStoryboardsForCapabilities, isComplianceVersionSupported, CapabilityResolutionError, TASK_TO_METHOD, executeStoryboardTask, expandCreativeAssetDirectives, findUnresolvedCreativeAssetDirectives, extractContext, injectContext, runValidations, resolvePath, RateLimitTripObserver, RATE_LIMIT_TRIP_CONTRACT, RATE_LIMIT_TRIP_DEFAULT_REPLAY_MAX_WAIT_SECONDS, RATE_LIMIT_TRIP_MAX_ATTEMPTS_MAX, RATE_LIMIT_TRIP_MAX_ATTEMPTS_MIN, validateRateLimitTripSpec, getSandboxEntities, getSandboxBrands, getSandboxBrand, isSandboxDomain, clearSandboxCache, registerAssertion, getAssertion, listAssertions, listDefaultAssertions, clearAssertionRegistry, resolveAssertions, type AssertionSpec, type AssertionContext, type AssertionResult, type RegisterAssertionOptions, type Storyboard, type StoryboardFixtureResolution, type FixtureResolutionStrategy, type FixtureMatchOperator, type FixtureMatchClause, type FixtureResolutionDeclaration, type ProductFixtureResolutionDeclaration, type PricingOptionFixtureResolutionDeclaration, type FixtureResolutionStatus, type FixtureResolutionRecord, type FixtureResolutionAttempt, type FixtureResolutionEvidence, type FixtureResolutionCoverageGap, type StoryboardInvariants, type StoryboardInvariantsObject, type StepInvariantsObject, type StoryboardPhase, type StoryboardStep, type RateLimitTripSpec, type StoryboardValidation, type RateLimitTripClient, type RateLimitTripFailureCode, type RateLimitTripObservation, type RateLimitTripObserverOptions, type RateLimitTripResponseSnapshot, type RateLimitTripStructuredResult, type RateLimitTripTaskOptions, type StoryboardContext, type StoryboardRunOptions, type TrustedMatchContextProviderEndpoint, type TrustedMatchContextRegistrationContext, type TrustedMatchContextRouterRunnerOptions, type TrustedMatchPublisherAuthOperation, type TrustedMatchPublisherCredentialState, type TrustedMatchPublisherAuthTls, type TrustedMatchPublisherAuthProbeConfiguration, type TrustedMatchPublisherAuthRunner, type ValidationResult, type StoryboardStepPreview, type StoryboardStepResult, type StoryboardStepHint, type StoryboardStepHintBase, type ContextValueRejectedHint, type ShapeDriftHint, type MissingRequiredFieldHint, type FormatMismatchHint, type MonotonicViolationHint, type ContextProvenanceEntry, type StoryboardPhaseResult, type StoryboardResult, type RunnerNotice, type NoticeCode, type NoticeSeverity, type AgentCapabilities, type BundleKind, type BundleRef, type CapabilityResolutionCode, type ComplianceIndex, type ComplianceIndexProtocol, type ComplianceIndexSpecialism, type ResolveOptions, type ResolvedBundle, type ResolvedStoryboards, type SandboxBrand, type SandboxAgent, type SandboxEntities, type BrandJson, type AdagentsJson, gradeOAuthMetadataGraph, gradeOAuthMetadataGraphVector, loadOAuthMetadataGraphVectors, normalizeOAuthResourceForComparison, redactOAuthUrlForOutput, type GradeOAuthMetadataGraphOptions, type OAuthMetadataGraphErrorCode, type OAuthMetadataGraphFinding, type OAuthMetadataGraphGrade, type OAuthMetadataGraphObservation, type OAuthMetadataGraphVector, type OAuthMetadataGraphVectorCorpus, BrandJsonSchema, AdagentsJsonSchema, MCP_SESSION_PROBE_TASK, } from './storyboard/index.mjs';

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

@@ -16,5 +16,5 @@ export { isSandboxRequest, mergeSeededProductsIntoResponse, filterValidSeededPro
 export type { TestControllerBridge, TestControllerBridgeContext, BridgeFromSessionStoreOptions, SeededCreative, SeededMediaBuy, SeededAccountFinancials, } from '../server/test-controller-bridge';
 export { runAgainstLocalAgent } from './local-agent-runner';
 export type { LocalAgentRunResult, PerStoryboardOverride, RunAgainstLocalAgentOptions } from './local-agent-runner';
-export { registerExternalSchemaRoot, unregisterExternalSchemaRoot, withExternalSchemaRoot } from '../validation';
+export { registerExternalSchemaRoot, unregisterExternalSchemaRoot, withExternalSchemaRoot, withServedReleaseSchemaRoots, } from '../validation';
 export { runStoryboard, runStoryboardStep, applyAdcpVersionRunOptions, applyStoryboardVersionOptions, getFirstStepPreview, parseStoryboard, loadStoryboardFile, normalizeValidationOnlyTasks, VALIDATION_ONLY_TASK, applyFixtureBindingsToRequest, buildFixtureResolutionSpecs, FixtureBindingRegistry, matchesFixtureRequirements, normalizeFixtureMatchExpression, validateFixtureResolutionDeclarations, getComplianceCacheDir, loadComplianceIndex, listBundles, loadBundleStoryboards, listAllComplianceStoryboards, getComplianceStoryboardById, findBundleById, resolveBundleOrStoryboard, resolveStoryboardsForCapabilities, isComplianceVersionSupported, CapabilityResolutionError, TASK_TO_METHOD, executeStoryboardTask, expandCreativeAssetDirectives, findUnresolvedCreativeAssetDirectives, extractContext, injectContext, runValidations, resolvePath, RateLimitTripObserver, RATE_LIMIT_TRIP_CONTRACT, RATE_LIMIT_TRIP_DEFAULT_REPLAY_MAX_WAIT_SECONDS, RATE_LIMIT_TRIP_MAX_ATTEMPTS_MAX, RATE_LIMIT_TRIP_MAX_ATTEMPTS_MIN, validateRateLimitTripSpec, getSandboxEntities, getSandboxBrands, getSandboxBrand, isSandboxDomain, clearSandboxCache, registerAssertion, getAssertion, listAssertions, listDefaultAssertions, clearAssertionRegistry, resolveAssertions, type AssertionSpec, type AssertionContext, type AssertionResult, type RegisterAssertionOptions, type Storyboard, type StoryboardFixtureResolution, type FixtureResolutionStrategy, type FixtureMatchOperator, type FixtureMatchClause, type FixtureResolutionDeclaration, type ProductFixtureResolutionDeclaration, type PricingOptionFixtureResolutionDeclaration, type FixtureResolutionStatus, type FixtureResolutionRecord, type FixtureResolutionAttempt, type FixtureResolutionEvidence, type FixtureResolutionCoverageGap, type StoryboardInvariants, type StoryboardInvariantsObject, type StepInvariantsObject, type StoryboardPhase, type StoryboardStep, type RateLimitTripSpec, type StoryboardValidation, type RateLimitTripClient, type RateLimitTripFailureCode, type RateLimitTripObservation, type RateLimitTripObserverOptions, type RateLimitTripResponseSnapshot, type RateLimitTripStructuredResult, type RateLimitTripTaskOptions, type StoryboardContext, type StoryboardRunOptions, type TrustedMatchContextProviderEndpoint, type TrustedMatchContextRegistrationContext, type TrustedMatchContextRouterRunnerOptions, type TrustedMatchPublisherAuthOperation, type TrustedMatchPublisherCredentialState, type TrustedMatchPublisherAuthTls, type TrustedMatchPublisherAuthProbeConfiguration, type TrustedMatchPublisherAuthRunner, type ValidationResult, type StoryboardStepPreview, type StoryboardStepResult, type StoryboardStepHint, type StoryboardStepHintBase, type ContextValueRejectedHint, type ShapeDriftHint, type MissingRequiredFieldHint, type FormatMismatchHint, type MonotonicViolationHint, type ContextProvenanceEntry, type StoryboardPhaseResult, type StoryboardResult, type RunnerNotice, type NoticeCode, type NoticeSeverity, type AgentCapabilities, type BundleKind, type BundleRef, type CapabilityResolutionCode, type ComplianceIndex, type ComplianceIndexProtocol, type ComplianceIndexSpecialism, type ResolveOptions, type ResolvedBundle, type ResolvedStoryboards, type SandboxBrand, type SandboxAgent, type SandboxEntities, type BrandJson, type AdagentsJson, gradeOAuthMetadataGraph, gradeOAuthMetadataGraphVector, loadOAuthMetadataGraphVectors, normalizeOAuthResourceForComparison, redactOAuthUrlForOutput, type GradeOAuthMetadataGraphOptions, type OAuthMetadataGraphErrorCode, type OAuthMetadataGraphFinding, type OAuthMetadataGraphGrade, type OAuthMetadataGraphObservation, type OAuthMetadataGraphVector, type OAuthMetadataGraphVectorCorpus, BrandJsonSchema, AdagentsJsonSchema, MCP_SESSION_PROBE_TASK, } from './storyboard';

package/dist/lib/testing/index.js

@@ -192,7 +192,8 @@ __export(testing_exports, {
   unregisterExternalSchemaRoot: () => import_validation.unregisterExternalSchemaRoot,
   validateFixtureResolutionDeclarations: () => import_storyboard.validateFixtureResolutionDeclarations,
   validateRateLimitTripSpec: () => import_storyboard.validateRateLimitTripSpec,
-  withExternalSchemaRoot: () => import_validation.withExternalSchemaRoot
+  withExternalSchemaRoot: () => import_validation.withExternalSchemaRoot,
+  withServedReleaseSchemaRoots: () => import_validation.withServedReleaseSchemaRoots
 });
 module.exports = __toCommonJS(testing_exports);
 var import_pending_web_flow_store = require('./pending-web-flow-store.js');
@@ -384,5 +385,6 @@ var import_storyboard = require('./storyboard/index.js');
   unregisterExternalSchemaRoot,
   validateFixtureResolutionDeclarations,
   validateRateLimitTripSpec,
-  withExternalSchemaRoot
+  withExternalSchemaRoot,
+  withServedReleaseSchemaRoots
 });

package/dist/lib/testing/index.mjs

@@ -122,7 +122,12 @@ import {
   bridgeFromSessionStore
 } from "../server/test-controller-bridge.mjs";
 import { runAgainstLocalAgent } from "./local-agent-runner.mjs";
-import { registerExternalSchemaRoot, unregisterExternalSchemaRoot, withExternalSchemaRoot } from "../validation/index.mjs";
+import {
+  registerExternalSchemaRoot,
+  unregisterExternalSchemaRoot,
+  withExternalSchemaRoot,
+  withServedReleaseSchemaRoots
+} from "../validation/index.mjs";
 import {
   runStoryboard,
   runStoryboardStep,
@@ -359,5 +364,6 @@ export {
   unregisterExternalSchemaRoot,
   validateFixtureResolutionDeclarations,
   validateRateLimitTripSpec,
-  withExternalSchemaRoot
+  withExternalSchemaRoot,
+  withServedReleaseSchemaRoots
 };

package/dist/lib/testing/storyboard/runner.js

@@ -783,14 +783,14 @@ async function runStoryboard(agentUrlOrUrls, storyboard, options = {}) {
         };
       }
       const schemaRoot = getRunSchemaRoot(options);
+      const runBody = () => (0, import_schema_loader.withServedReleaseSchemaRoots)(
+        options.servedReleaseSchemaRoots,
+        () => runStoryboardBody(agentUrlOrUrls, storyboard, options)
+      );
       if (schemaRoot) {
-        return await (0, import_schema_loader.withExternalSchemaRoot)(
-          schemaRoot.adcpVersion,
-          schemaRoot.schemaRoot,
-          () => runStoryboardBody(agentUrlOrUrls, storyboard, options)
-        );
+        return await (0, import_schema_loader.withExternalSchemaRoot)(schemaRoot.adcpVersion, schemaRoot.schemaRoot, runBody);
       }
-      return await runStoryboardBody(agentUrlOrUrls, storyboard, options);
+      return await runBody();
     },
     { isolate: !(0, import_client.hasTestClientScope)() }
   );
@@ -3117,14 +3117,14 @@ async function runStoryboardStep(agentUrl, storyboard, stepId, options = {}) {
       options = (0, import_test_kit.resolveDeclaredTestKit)(storyboard, options);
       options = (0, import_native_a2a_compliance.applyNativeA2AComplianceTransportOptions)(options);
       const schemaRoot = getRunSchemaRoot(options);
+      const runBody = () => (0, import_schema_loader.withServedReleaseSchemaRoots)(
+        options.servedReleaseSchemaRoots,
+        () => runStoryboardStepBody(agentUrl, storyboard, stepId, options)
+      );
       if (schemaRoot) {
-        return await (0, import_schema_loader.withExternalSchemaRoot)(
-          schemaRoot.adcpVersion,
-          schemaRoot.schemaRoot,
-          () => runStoryboardStepBody(agentUrl, storyboard, stepId, options)
-        );
+        return await (0, import_schema_loader.withExternalSchemaRoot)(schemaRoot.adcpVersion, schemaRoot.schemaRoot, runBody);
       }
-      return await runStoryboardStepBody(agentUrl, storyboard, stepId, options);
+      return await runBody();
     },
     { isolate: !(0, import_client.hasTestClientScope)() }
   );

package/dist/lib/testing/storyboard/runner.mjs

@@ -61,7 +61,8 @@ import {
   getSchemaValidatorByRef,
   resolveBundleKey,
   schemaAllowsTopLevelField,
-  withExternalSchemaRoot
+  withExternalSchemaRoot,
+  withServedReleaseSchemaRoots
 } from "../../validation/schema-loader.mjs";
 import { ADCP_VERSION, parseAdcpMajorVersion } from "../../version.mjs";
 import {
@@ -806,14 +807,14 @@ async function runStoryboard(agentUrlOrUrls, storyboard, options = {}) {
         };
       }
       const schemaRoot = getRunSchemaRoot(options);
+      const runBody = () => withServedReleaseSchemaRoots(
+        options.servedReleaseSchemaRoots,
+        () => runStoryboardBody(agentUrlOrUrls, storyboard, options)
+      );
       if (schemaRoot) {
-        return await withExternalSchemaRoot(
-          schemaRoot.adcpVersion,
-          schemaRoot.schemaRoot,
-          () => runStoryboardBody(agentUrlOrUrls, storyboard, options)
-        );
+        return await withExternalSchemaRoot(schemaRoot.adcpVersion, schemaRoot.schemaRoot, runBody);
       }
-      return await runStoryboardBody(agentUrlOrUrls, storyboard, options);
+      return await runBody();
     },
     { isolate: !hasTestClientScope() }
   );
@@ -3140,14 +3141,14 @@ async function runStoryboardStep(agentUrl, storyboard, stepId, options = {}) {
       options = resolveDeclaredTestKit(storyboard, options);
       options = applyNativeA2AComplianceTransportOptions(options);
       const schemaRoot = getRunSchemaRoot(options);
+      const runBody = () => withServedReleaseSchemaRoots(
+        options.servedReleaseSchemaRoots,
+        () => runStoryboardStepBody(agentUrl, storyboard, stepId, options)
+      );
       if (schemaRoot) {
-        return await withExternalSchemaRoot(
-          schemaRoot.adcpVersion,
-          schemaRoot.schemaRoot,
-          () => runStoryboardStepBody(agentUrl, storyboard, stepId, options)
-        );
+        return await withExternalSchemaRoot(schemaRoot.adcpVersion, schemaRoot.schemaRoot, runBody);
       }
-      return await runStoryboardStepBody(agentUrl, storyboard, stepId, options);
+      return await runBody();
     },
     { isolate: !hasTestClientScope() }
   );

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

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

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

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

package/dist/lib/testing/storyboard/validations.js

@@ -259,6 +259,21 @@ function mapZodIssueToSchemaKeyword(issue) {
   }
 }
 function validateResponseSchema(validation, ctx, taskResult) {
+  const pinnedVersion = ctx.adcpVersion;
+  if (ctx.taskName === "get_adcp_capabilities" && pinnedVersion !== void 0) {
+    return (0, import_schema_loader.withServedValidationVersion)(
+      taskResult.data,
+      pinnedVersion,
+      (validationVersion) => validateResponseSchemaForVersion(
+        validation,
+        validationVersion === pinnedVersion ? ctx : { ...ctx, adcpVersion: validationVersion, responseAdcpVersion: validationVersion },
+        taskResult
+      )
+    );
+  }
+  return validateResponseSchemaForVersion(validation, ctx, taskResult);
+}
+function validateResponseSchemaForVersion(validation, ctx, taskResult) {
   const taskName = ctx.taskName;
   const schemaIdentityVersion = ctx.adcpVersion ?? ctx.responseAdcpVersion ?? import_version.ADCP_VERSION;
   const { schema_id, schema_url } = resolveSchemaIdentity(ctx.responseSchemaRef, schemaIdentityVersion);
@@ -356,7 +371,14 @@ function validateResponseSchema(validation, ctx, taskResult) {
 }
 function isExternalResponseSchemaAuthoritative(ctx) {
   const validationVersion = responseSchemaValidationVersion(ctx.adcpVersion, ctx.responseAdcpVersion);
-  return validationVersion !== void 0 && (0, import_schema_loader.isExternalSchemaRootActive)(validationVersion);
+  if (validationVersion !== void 0 && (0, import_schema_loader.isExternalSchemaRootActive)(validationVersion)) return true;
+  const pinnedVersion = ctx.adcpVersion;
+  if (ctx.taskName !== "get_adcp_capabilities" || pinnedVersion === void 0 || !ctx.taskResult) return false;
+  return (0, import_schema_loader.withServedValidationVersion)(
+    ctx.taskResult.data,
+    pinnedVersion,
+    (version) => version !== pinnedVersion && (0, import_schema_loader.isExternalSchemaRootActive)(version)
+  );
 }
 function responseSchemaValidationVersion(adcpVersion, responseAdcpVersion) {
   if (adcpVersion && (0, import_schema_loader.isExternalSchemaRootActive)(adcpVersion)) return adcpVersion;

package/dist/lib/testing/storyboard/validations.mjs

@@ -2,7 +2,11 @@ import { prepareResponseForSchemaValidation, TOOL_RESPONSE_SCHEMAS } from "../..
 import { injectLegacyEnvelopeStatus } from "../../utils/envelope-status-compat.mjs";
 import { TRANSPORT_SUFFIX_REGEX } from "../../utils/a2a-discovery.mjs";
 import { validateResponse } from "../../validation/schema-validator.mjs";
-import { hasSchemaBundle, isExternalSchemaRootActive } from "../../validation/schema-loader.mjs";
+import {
+  hasSchemaBundle,
+  isExternalSchemaRootActive,
+  withServedValidationVersion
+} from "../../validation/schema-loader.mjs";
 import { ADCP_VERSION, LIBRARY_VERSION } from "../../version.mjs";
 import { isPre31AdcpVersion } from "../../utils/adcp-version-config.mjs";
 import { gte as semverGte, valid as validSemver } from "semver";
@@ -234,6 +238,21 @@ function mapZodIssueToSchemaKeyword(issue) {
   }
 }
 function validateResponseSchema(validation, ctx, taskResult) {
+  const pinnedVersion = ctx.adcpVersion;
+  if (ctx.taskName === "get_adcp_capabilities" && pinnedVersion !== void 0) {
+    return withServedValidationVersion(
+      taskResult.data,
+      pinnedVersion,
+      (validationVersion) => validateResponseSchemaForVersion(
+        validation,
+        validationVersion === pinnedVersion ? ctx : { ...ctx, adcpVersion: validationVersion, responseAdcpVersion: validationVersion },
+        taskResult
+      )
+    );
+  }
+  return validateResponseSchemaForVersion(validation, ctx, taskResult);
+}
+function validateResponseSchemaForVersion(validation, ctx, taskResult) {
   const taskName = ctx.taskName;
   const schemaIdentityVersion = ctx.adcpVersion ?? ctx.responseAdcpVersion ?? ADCP_VERSION;
   const { schema_id, schema_url } = resolveSchemaIdentity(ctx.responseSchemaRef, schemaIdentityVersion);
@@ -331,7 +350,14 @@ function validateResponseSchema(validation, ctx, taskResult) {
 }
 function isExternalResponseSchemaAuthoritative(ctx) {
   const validationVersion = responseSchemaValidationVersion(ctx.adcpVersion, ctx.responseAdcpVersion);
-  return validationVersion !== void 0 && isExternalSchemaRootActive(validationVersion);
+  if (validationVersion !== void 0 && isExternalSchemaRootActive(validationVersion)) return true;
+  const pinnedVersion = ctx.adcpVersion;
+  if (ctx.taskName !== "get_adcp_capabilities" || pinnedVersion === void 0 || !ctx.taskResult) return false;
+  return withServedValidationVersion(
+    ctx.taskResult.data,
+    pinnedVersion,
+    (version) => version !== pinnedVersion && isExternalSchemaRootActive(version)
+  );
 }
 function responseSchemaValidationVersion(adcpVersion, responseAdcpVersion) {
   if (adcpVersion && isExternalSchemaRootActive(adcpVersion)) return adcpVersion;

package/dist/lib/testing/types.d.mts

@@ -58,6 +58,45 @@ export interface TestOptions {
      * authoritative over the SDK's generated Zod snapshot for the run.
      */
     schemaRoot?: string;
+    /**
+     * Schema roots for releases the agent may echo in its
+     * `get_adcp_capabilities` response, keyed by AdCP version (`'3.2'`,
+     * `'3.2.5'`, `'3.3.0-beta.1'`). Values are schema-data roots in the same
+     * shape as `schemaRoot`.
+     *
+     * A 3.0 pin sends only `adcp_major_version`, so an agent may serve and echo
+     * a newer release in the same major (versioning spec, "Server echoes").
+     * The SDK validates that capabilities response against the echoed release
+     * when the echo is the pin's major, is listed in the response's
+     * `adcp.supported_versions`, and has a schema root: an entry here, an
+     * external root registered for it, or the SDK's bundled schemas. That
+     * applies to discovery's capability notices, `getAdcpCapabilities()` and
+     * storyboard `response_schema` checks on `get_adcp_capabilities`, including
+     * when `schemaRoot` is set for the pin. Otherwise validation stays on the
+     * pin.
+     *
+     * Entries are used for that capabilities validation only. Every other
+     * task's response, storyboard selection and grading stay on the pin. Each
+     * root is checked against its key once per process; a malformed map throws
+     * before the run starts. Honored by `comply()`, `runStoryboard()` and
+     * `runStoryboardStep()`; other callers can use `withServedReleaseSchemaRoots`.
+     * The echo is compared with the run's pin, so storyboard checks apply it
+     * only when the run has one (`adcpVersion`, or the storyboard or compliance
+     * bundle's `adcp_version`); `comply()` always does.
+     *
+     * @example
+     * ```ts
+     * await comply(agentUrl, {
+     *   complianceDir: hosted30.complianceDir,
+     *   schemaRoot: hosted30.schemaRoot,
+     *   servedReleaseSchemaRoots: {
+     *     '3.1.29': hosted31.schemaRoot,
+     *     '3.2.5': hosted32.schemaRoot,
+     *   },
+     * });
+     * ```
+     */
+    servedReleaseSchemaRoots?: Readonly<Record<string, string>>;
     /**
      * Whether strict AJV response-schema failures contribute to storyboard
      * grading. Defaults to `true`, matching the hosted compliance grader.