@adcp/sdk 13.0.0 → 13.0.2

package/ADCP_VERSION

@@ -1 +1 @@
-3.1.15
+3.1.20

package/bin/adcp.js

@@ -1440,13 +1440,13 @@ function loadTestKitFile(testKitPath) {
   try {
     raw = fs.readFileSync(resolved, 'utf8');
   } catch (err) {
-    throw new Error(`failed to read test-kit at ${resolved}: ${err.message}`);
+    throw new Error(`failed to read test-kit at ${resolved} (${err?.code || 'filesystem error'}).`);
   }
   try {
     const { parse } = require('yaml');
     return parse(raw);
-  } catch (err) {
-    throw new Error(`failed to parse ${resolved} as YAML: ${err.message}`);
+  } catch {
+    throw new Error(`failed to parse test-kit at ${resolved} as YAML.`);
   }
 }
 
@@ -1972,14 +1972,18 @@ RUN OPTIONS (full assessment):
                       --test-kit points into a compliance cache, its version is
                       selected automatically; an explicit mismatch is rejected.
   --compliance-dir PATH
-                      Use a specific compliance cache directory
+                      Use a specific compliance cache directory. For --file
+                      storyboards, this explicitly authorizes a cache-relative
+                      prerequisites.test_kit. --compliance-version alone does
+                      not authorize credential loading; pass --test-kit instead.
   --schema-root PATH  Use a specific schema bundle/root for validation.
                       --validator-source is accepted as an alias.
   --hosted-stable-line-alias VERSION
                       Hosted badge mode: allow a stable line (e.g. 3.1)
                       to resolve against a prerelease compliance cache.
   --file PATH         Run an ad-hoc storyboard YAML (spec evolution)
-  --test-kit PATH     Load test-kit YAML. If an ancestor index.json declares
+  --test-kit PATH     Load test-kit YAML for either run or step, overriding any
+                      cache-declared kit. If an ancestor index.json declares
                       adcp_version or published_version, the same compliance
                       line is required for storyboard resolution.
   --timeout SECONDS   Soft budget in seconds: stop starting new storyboards
@@ -2622,6 +2626,27 @@ function enforceStrictFlags(args, removedFound) {
   }
 }
 
+async function resolveFileComplianceRunOptions(args, opts) {
+  let adcpVersion = opts.complianceVersion;
+  let complianceDir = opts.complianceDir;
+  let schemaRoot = opts.schemaRoot;
+  if (opts.complianceDir || opts.complianceVersion || opts.schemaRoot) {
+    const { loadComplianceIndex, getExternalSchemaRootForCompliance } =
+      await import('../dist/lib/testing/storyboard/index.js');
+    const resolveOptions = parseComplianceSelection(args).resolveOptions;
+    const index = loadComplianceIndex(resolveOptions);
+    if (opts.complianceVersion && index.adcp_version !== opts.complianceVersion) {
+      throw new Error(
+        `--compliance-version ${opts.complianceVersion} selected a compliance cache that declares ` +
+          `AdCP ${index.adcp_version}. Check --compliance-dir or ADCP_COMPLIANCE_DIR and select a matching cache.`
+      );
+    }
+    adcpVersion = adcpVersion || index.adcp_version;
+    schemaRoot = schemaRoot || getExternalSchemaRootForCompliance(resolveOptions, index.adcp_version);
+  }
+  return { adcpVersion, complianceDir, schemaRoot };
+}
+
 async function handleStoryboardRun(args) {
   let opts = parseAgentOptions(args);
   let {
@@ -2726,8 +2751,7 @@ async function handleStoryboardRun(args) {
     return;
   }
 
-  const { loadStoryboardFile, runStoryboard, loadComplianceIndex, getExternalSchemaRootForCompliance } =
-    await import('../dist/lib/testing/storyboard/index.js');
+  const { loadStoryboardFile, runStoryboard } = await import('../dist/lib/testing/storyboard/index.js');
   let storyboard;
   try {
     storyboard = loadStoryboardFile(filePath);
@@ -2735,18 +2759,12 @@ async function handleStoryboardRun(args) {
     console.error(`Failed to load storyboard from ${filePath}: ${err.message}`);
     process.exit(2);
   }
-  let fileComplianceVersion = opts.complianceVersion;
-  let fileSchemaRoot = opts.schemaRoot;
-  if (opts.complianceDir || opts.complianceVersion || opts.schemaRoot) {
-    try {
-      const resolveOptions = parseComplianceSelection(args).resolveOptions;
-      const index = loadComplianceIndex(resolveOptions);
-      fileComplianceVersion = fileComplianceVersion || index.adcp_version;
-      fileSchemaRoot = fileSchemaRoot || getExternalSchemaRootForCompliance(resolveOptions, index.adcp_version);
-    } catch (err) {
-      console.error(`ERROR: ${err.message}`);
-      process.exit(2);
-    }
+  let fileComplianceOptions;
+  try {
+    fileComplianceOptions = await resolveFileComplianceRunOptions(args, opts);
+  } catch (err) {
+    console.error(`ERROR: ${err.message}`);
+    process.exit(2);
   }
 
   const {
@@ -2820,8 +2838,6 @@ async function handleStoryboardRun(args) {
     ? await resolveWebhookReceiverOptions(args, { jsonOutput })
     : webhookReceiverBase;
 
-  const loadedTestKit = opts.loadedTestKit ?? null;
-
   const options = {
     protocol,
     ...buildResolvedAuthOption({
@@ -2832,12 +2848,13 @@ async function handleStoryboardRun(args) {
       resolvedOauthClientCredentials,
     }),
     ...(webhookReceiverOpts ?? {}),
-    ...(fileComplianceVersion && { adcpVersion: fileComplianceVersion }),
-    ...(fileSchemaRoot && { schemaRoot: fileSchemaRoot }),
+    ...(fileComplianceOptions.complianceDir && { complianceDir: fileComplianceOptions.complianceDir }),
+    ...(fileComplianceOptions.adcpVersion && { adcpVersion: fileComplianceOptions.adcpVersion }),
+    ...(fileComplianceOptions.schemaRoot && { schemaRoot: fileComplianceOptions.schemaRoot }),
     ...(opts.noSandbox && { sandbox: false, disable_sandbox: true }),
     ...(opts.assertsSeededState && { assertsSeededState: true }),
     ...(mergedRunHeaders && { headers: mergedRunHeaders }),
-    ...(loadedTestKit && { test_kit: loadedTestKit }),
+    ...(opts.loadedTestKit !== undefined && { test_kit: opts.loadedTestKit }),
   };
 
   const restoreLogs = jsonOutput ? captureStdoutLogs() : null;
@@ -3670,14 +3687,18 @@ async function handleLocalAgentStoryboardRun(modulePath, args, opts) {
       createAgent,
       storyboards: storyboardsSpec,
       compliance: resolveOptions,
-      ...(opts.complianceVersion || opts.schemaRoot || opts.noSandbox || opts.assertsSeededState || opts.loadedTestKit
+      ...(opts.complianceVersion ||
+      opts.schemaRoot ||
+      opts.noSandbox ||
+      opts.assertsSeededState ||
+      opts.loadedTestKit !== undefined
         ? {
             runStoryboardOptions: {
               ...(opts.complianceVersion && !opts.complianceDir && { adcpVersion: opts.complianceVersion }),
               ...(opts.schemaRoot && { schemaRoot: opts.schemaRoot }),
               ...(opts.noSandbox && { sandbox: false, disable_sandbox: true }),
               ...(opts.assertsSeededState && { assertsSeededState: true }),
-              ...(opts.loadedTestKit && { test_kit: opts.loadedTestKit }),
+              ...(opts.loadedTestKit !== undefined && { test_kit: opts.loadedTestKit }),
             },
           }
         : {}),
@@ -3962,6 +3983,21 @@ async function handleMultiInstanceStoryboardRun(args, opts, urls) {
     }
   }
 
+  let runAdcpVersion = opts.complianceVersion && !opts.complianceDir ? opts.complianceVersion : undefined;
+  let runComplianceDir = opts.complianceDir;
+  let runSchemaRoot = opts.schemaRoot;
+  if (filePath) {
+    try {
+      const selected = await resolveFileComplianceRunOptions(args, opts);
+      runAdcpVersion = selected.adcpVersion;
+      runComplianceDir = selected.complianceDir;
+      runSchemaRoot = selected.schemaRoot;
+    } catch (err) {
+      console.error(`ERROR: ${err.message}`);
+      process.exit(2);
+    }
+  }
+
   // Auto-detect protocol from the first URL. Multi-instance deployments
   // share a codebase across replicas, so one probe is representative.
   let protocol = protocolFlag;
@@ -4090,11 +4126,12 @@ async function handleMultiInstanceStoryboardRun(args, opts, urls) {
     ...(opts.allowHttp && { allow_http: true }),
     multi_instance_strategy: strategy,
     ...(webhookReceiverOpts ?? {}),
-    ...(opts.complianceVersion && !opts.complianceDir && { adcpVersion: opts.complianceVersion }),
-    ...(opts.schemaRoot && { schemaRoot: opts.schemaRoot }),
+    ...(runComplianceDir && { complianceDir: runComplianceDir }),
+    ...(runAdcpVersion && { adcpVersion: runAdcpVersion }),
+    ...(runSchemaRoot && { schemaRoot: runSchemaRoot }),
     ...(opts.noSandbox && { sandbox: false, disable_sandbox: true }),
     ...(opts.assertsSeededState && { assertsSeededState: true }),
-    ...(opts.loadedTestKit && { test_kit: opts.loadedTestKit }),
+    ...(opts.loadedTestKit !== undefined && { test_kit: opts.loadedTestKit }),
   };
 
   const restoreLogs = jsonOutput ? captureStdoutLogs() : null;
@@ -4269,6 +4306,21 @@ async function handleAgentsRoutedStoryboardRun(args, opts, routing) {
     }
   }
 
+  let runAdcpVersion = opts.complianceVersion && !opts.complianceDir ? opts.complianceVersion : undefined;
+  let runComplianceDir = opts.complianceDir;
+  let runSchemaRoot = opts.schemaRoot;
+  if (filePath) {
+    try {
+      const selected = await resolveFileComplianceRunOptions(args, opts);
+      runAdcpVersion = selected.adcpVersion;
+      runComplianceDir = selected.complianceDir;
+      runSchemaRoot = selected.schemaRoot;
+    } catch (err) {
+      console.error(`ERROR: ${err.message}`);
+      process.exit(2);
+    }
+  }
+
   // Detect protocol from the first agent. Multi-agent topologies typically
   // share the same transport (the prod test-agent uses MCP across all 6
   // tenants), so one probe is representative. Per-agent transport overrides
@@ -4354,11 +4406,12 @@ async function handleAgentsRoutedStoryboardRun(args, opts, routing) {
     agents: routing.agents,
     ...(routing.default_agent ? { default_agent: routing.default_agent } : {}),
     ...(webhookReceiverOpts ?? {}),
-    ...(opts.complianceVersion && !opts.complianceDir && { adcpVersion: opts.complianceVersion }),
-    ...(opts.schemaRoot && { schemaRoot: opts.schemaRoot }),
+    ...(runComplianceDir && { complianceDir: runComplianceDir }),
+    ...(runAdcpVersion && { adcpVersion: runAdcpVersion }),
+    ...(runSchemaRoot && { schemaRoot: runSchemaRoot }),
     ...(opts.noSandbox && { sandbox: false, disable_sandbox: true }),
     ...(opts.assertsSeededState && { assertsSeededState: true }),
-    ...(opts.loadedTestKit && { test_kit: opts.loadedTestKit }),
+    ...(opts.loadedTestKit !== undefined && { test_kit: opts.loadedTestKit }),
   };
 
   const restoreLogs = jsonOutput ? captureStdoutLogs() : null;
@@ -4550,8 +4603,6 @@ async function runFullAssessment(agentArg, rawArgs, parsedOpts) {
 
   await loadInvariantModules(rawArgs);
 
-  const loadedTestKit = opts.loadedTestKit ?? null;
-
   const testOptions = {
     protocol,
     brief: opts.brief,
@@ -4565,7 +4616,8 @@ async function runFullAssessment(agentArg, rawArgs, parsedOpts) {
     ...(opts.noSandbox && { sandbox: false, disable_sandbox: true }),
     ...(opts.assertsSeededState && { assertsSeededState: true }),
     ...(mergedAssessmentHeaders && { headers: mergedAssessmentHeaders }),
-    ...(loadedTestKit && { test_kit: loadedTestKit }),
+    ...(opts.loadedTestKit !== undefined && { test_kit: opts.loadedTestKit }),
+    ...(opts.testKitPath && { testKitPath: path.resolve(opts.testKitPath) }),
     ...(opts.complianceVersion && { version: opts.complianceVersion }),
     ...(opts.complianceDir && { complianceDir: opts.complianceDir }),
     ...(opts.schemaRoot && { schemaRoot: opts.schemaRoot }),
@@ -4709,12 +4761,22 @@ async function runFullAssessment(agentArg, rawArgs, parsedOpts) {
 
 async function handleStoryboardStepCmd(args) {
   const { getComplianceStoryboardById, runStoryboardStep } = await import('../dist/lib/testing/storyboard/index.js');
-  const { authToken, authScheme, protocolFlag, jsonOutput, positionalArgs, complianceVersion, schemaRoot } =
-    parseAgentOptions(args);
-  const { resolveOptions } = parseComplianceSelection(args);
+  let opts = parseAgentOptions(args);
+  let { authToken, authScheme, protocolFlag, jsonOutput, positionalArgs, complianceVersion, schemaRoot } = opts;
 
   enforceStrictFlags(args, warnRemovedFlags(args));
 
+  try {
+    const prepared = prepareTestKitComplianceSelection(args, opts);
+    args = prepared.args;
+    opts = prepared.opts;
+  } catch (err) {
+    exitTestKitSelectionError(err, jsonOutput);
+  }
+
+  ({ authToken, authScheme, protocolFlag, jsonOutput, positionalArgs, complianceVersion, schemaRoot } = opts);
+  const { resolveOptions } = parseComplianceSelection(args);
+
   const agentArg = positionalArgs[0];
   const storyboardId = positionalArgs[1];
   const stepId = positionalArgs[2];
@@ -4765,7 +4827,9 @@ async function handleStoryboardStepCmd(args) {
     ...(contributions && { contributions }),
     request,
     ...(complianceVersion && { adcpVersion: complianceVersion }),
+    ...(opts.complianceDir && { complianceDir: opts.complianceDir }),
     ...(schemaRoot && { schemaRoot }),
+    ...(opts.loadedTestKit !== undefined && { test_kit: opts.loadedTestKit }),
     ...buildResolvedAuthOption({
       resolvedAuth,
       resolvedAuthScheme,

package/compliance/cache/{3.1.15 → 3.1.20}/domains/media-buy/index.yaml

@@ -1,5 +1,5 @@
 id: media_buy_seller
-version: "1.0.0"
+version: "1.0.1"
 title: "Media buy seller agent"
 category: media_buy_seller
 summary: "Seller agent that receives briefs, returns products, accepts media buys, and reports delivery."
@@ -587,6 +587,9 @@ phases:
 
   - id: creative_sync
     title: "Creative sync"
+    requires_capability:
+      path: creative.has_creative_library
+      equals: true
     narrative: |
       With the media buy confirmed, the buyer syncs creative assets to your platform.
       Each package in the buy has creative format requirements — the buyer discovered
@@ -745,6 +748,7 @@ phases:
 
   - id: delivery_monitoring
     title: "Delivery and reporting"
+    depends_on: [create_buy]
     narrative: |
       The campaign is live. The buyer monitors delivery through two tasks:
       get_media_buys for status and get_media_buy_delivery for performance metrics.

package/compliance/cache/{3.1.15.previous/protocols → 3.1.20/domains}/media-buy/scenarios/creative_fate_after_cancellation.yaml

@@ -1,5 +1,5 @@
 id: media_buy_seller/creative_fate_after_cancellation
-version: "1.0.0"
+version: "1.0.1"
 title: "Creative lifecycle is decoupled from media buy lifecycle"
 category: media_buy_seller
 summary: "Validates that canceling a media buy releases package-creative assignments but leaves the underlying creatives in the library with their review state intact, and that buyers can reuse released creatives on a new buy."
@@ -12,6 +12,10 @@ required_tools:
   - sync_creatives
   - list_creatives
 
+requires_capability:
+  path: creative.has_creative_library
+  equals: true
+
 narrative: |
   Per the creative library model (docs/creative/creative-libraries#creative-state-and-assignment-state-are-separate)
   and the Media Buy State Transitions rule, canceling or rejecting a media buy

package/compliance/cache/{3.1.15/protocols → 3.1.20/domains}/media-buy/scenarios/dependency_impairment.yaml

@@ -1,5 +1,5 @@
 id: media_buy_seller/dependency_impairment
-version: "2.0.0"
+version: "2.0.1"
 title: "Dependency impairment end-to-end — resource transition propagates to media buy health"
 category: media_buy_seller
 summary: "Forces a creative from approved → rejected on a non-terminal media buy, verifies the buy reflects health: impaired with a matching impairments[] entry, and recovers via assignment swap to a different creative (canonical recovery vector — re-approval of the same creative_id is uncommon in production)."
@@ -13,19 +13,13 @@ required_tools:
   - update_media_buy
   - comply_test_controller
 
-# Capability gate: this scenario grades the snapshot-coherence surface, so it
-# runs only for sellers that declare media_buy.propagation_surfaces including
-# "snapshot". Webhook-only or out_of_band sellers grade not_applicable instead
-# of false-failing on a contract that does not apply to them — the opt-out the
-# propagation_surfaces schema already documents (get-adcp-capabilities-response.json)
-# but that was never wired into this scenario. Requires the `contains:` matcher
-# (@adcp/sdk >= 7.70). Sellers that OMIT propagation_surfaces inherit the
-# ["snapshot"] default and are graded here only on @adcp/sdk >= 9.2.0, which
-# materializes capability-gate schema defaults; earlier runners skip them as
-# not_applicable (adcp-client#2278).
+# The 3.1 runner supports one storyboard-level capability predicate. Gate the
+# whole creative workflow on the library declaration, then repeat the snapshot
+# predicate on every phase so webhook-only and out_of_band sellers remain out
+# of scope as well.
 requires_capability:
-  path: media_buy.propagation_surfaces
-  contains: "snapshot"
+  path: creative.has_creative_library
+  equals: true
 
 narrative: |
   Per the dependency-impairment surface ([adcp#2855](https://github.com/adcontextprotocol/adcp/issues/2855)
@@ -118,6 +112,9 @@ prerequisites:
 
 phases:
   - id: setup
+    requires_capability: &snapshot_gate
+      path: media_buy.propagation_surfaces
+      contains: "snapshot"
     title: "Create an active buy with a creative assignment"
     narrative: |
       Discover a product, create a media buy, sync one creative into the library
@@ -339,6 +336,7 @@ phases:
             description: "Controller acknowledged the directive"
 
   - id: baseline_healthy
+    requires_capability: *snapshot_gate
     title: "Baseline: buy reads as healthy, no impairments"
     narrative: |
       With the creative at approved and assigned, the buy MUST report
@@ -383,6 +381,7 @@ phases:
             description: "impairments[] is empty (or absent) in the baseline — no resources are offline yet"
 
   - id: transition_offline
+    requires_capability: *snapshot_gate
     title: "Force the creative to rejected"
     narrative: |
       The seller transitions the creative from approved → rejected via
@@ -422,6 +421,7 @@ phases:
             description: "Controller acknowledged the rejection directive"
 
   - id: verify_impaired
+    requires_capability: *snapshot_gate
     title: "Buy reads as impaired with a matching impairments[] entry"
     narrative: |
       After the rejection, the buy MUST report `health: impaired` and
@@ -520,6 +520,7 @@ phases:
             description: "At least one impairment entry matches the rejected creative, affected package, and rejected transition (forward rule)"
 
   - id: swap_recovery
+    requires_capability: *snapshot_gate
     title: "Recover via assignment swap — different creative replaces the rejected one"
     narrative: |
       Sync a second creative (B) into the library as approved, then use

package/compliance/cache/{3.1.15/protocols → 3.1.20/domains}/media-buy/scenarios/dependency_impairment_cardinality.yaml

@@ -1,5 +1,5 @@
 id: media_buy_seller/dependency_impairment_cardinality
-version: "1.0.0"
+version: "1.0.1"
 title: "Dependency impairment cardinality — impairments[] tracks each offline resource independently"
 category: media_buy_seller
 summary: "Two creatives on two packages of the same buy. Rejects them sequentially and verifies impairments[] grows 0 → 1 → 2; recovers them sequentially via swap-assignment and verifies impairments[] shrinks 2 → 1 → 0. Pressure-tests the inverse rule under cardinality — a seller emitting any impairment entry rather than the right one fails."
@@ -13,19 +13,13 @@ required_tools:
   - update_media_buy
   - comply_test_controller
 
-# Capability gate: this scenario grades the snapshot-coherence surface, so it
-# runs only for sellers that declare media_buy.propagation_surfaces including
-# "snapshot". Webhook-only or out_of_band sellers grade not_applicable instead
-# of false-failing on a contract that does not apply to them — the opt-out the
-# propagation_surfaces schema already documents (get-adcp-capabilities-response.json)
-# but that was never wired into this scenario. Requires the `contains:` matcher
-# (@adcp/sdk >= 7.70). Sellers that OMIT propagation_surfaces inherit the
-# ["snapshot"] default and are graded here only on @adcp/sdk >= 9.2.0, which
-# materializes capability-gate schema defaults; earlier runners skip them as
-# not_applicable (adcp-client#2278).
+# The 3.1 runner supports one storyboard-level capability predicate. Gate the
+# whole creative workflow on the library declaration, then repeat the snapshot
+# predicate on every phase so webhook-only and out_of_band sellers remain out
+# of scope as well.
 requires_capability:
-  path: media_buy.propagation_surfaces
-  contains: "snapshot"
+  path: creative.has_creative_library
+  equals: true
 
 narrative: |
   The base dependency_impairment scenario tests forward + inverse + health-iff
@@ -98,6 +92,9 @@ prerequisites:
 
 phases:
   - id: setup
+    requires_capability: &snapshot_gate
+      path: media_buy.propagation_surfaces
+      contains: "snapshot"
     title: "Create a buy with two packages, two creatives, two assignments"
     narrative: |
       Discover a product, create a buy with two packages (same product is
@@ -396,6 +393,7 @@ phases:
             description: "impairments[] is empty (cardinality zero baseline)"
 
   - id: reject_first_cardinality_one
+    requires_capability: *snapshot_gate
     title: "Reject creative A — impairments[] cardinality 1, scoped to package_a"
     narrative: |
       Force creative A to rejected. The buy MUST report exactly ONE
@@ -525,6 +523,7 @@ phases:
           # an `array_length` check kind — tracked in a follow-up.
 
   - id: reject_second_cardinality_two
+    requires_capability: *snapshot_gate
     title: "Reject creative B — impairments[] grows to cardinality 2"
     narrative: |
       Force creative B to rejected. The buy MUST report exactly TWO
@@ -643,6 +642,7 @@ phases:
           # a creative that isn't offline, failing the invariant.
 
   - id: recover_first_via_swap
+    requires_capability: *snapshot_gate
     title: "Swap package_a's binding to a fresh creative C — cardinality back to 1"
     narrative: |
       Sync creative C (approved), then update_media_buy to swap
@@ -800,6 +800,7 @@ phases:
             description: "impairments[1] MUST NOT exist — the swap recovered A's dependency; only B remains rejected. Cardinality decrement check."
 
   - id: recover_second_via_swap
+    requires_capability: *snapshot_gate
     title: "Swap package_b's binding to a fresh creative D — cardinality back to 0"
     narrative: |
       Sync creative D (approved), swap package_b's binding from B → D, read