@adcp/sdk 16.3.0 → 16.5.0

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

@@ -2,8 +2,10 @@ import { resolveAccount, resolveBrand, validateResponseSchema } from "../client.
 import { getValidator } from "../../validation/schema-loader.mjs";
 import { ADCP_VERSION } from "../../version.mjs";
 import { injectLegacyEnvelopeStatus } from "../../utils/envelope-status-compat.mjs";
+import { readExtractionPath, unwrapProtocolResponse } from "../../utils/response-unwrapper.mjs";
 import { callControllerRaw } from "../test-controller.mjs";
 import { executeStoryboardTask } from "./task-map.mjs";
+import { getCapturesFromError, withRawResponseCapture } from "../../protocols/rawResponseCapture.mjs";
 import {
   buildFixtureResolutionSpecs,
   applyFixtureBindingsToRequest,
@@ -14,6 +16,8 @@ import {
 import { readCollectionWitness } from "./collection-selection.mjs";
 import { resolvePath } from "./path.mjs";
 import { redactSecrets } from "../../utils/redact-secrets.mjs";
+import { redactDiscoveryEvidence as redactDiscoveryResponse } from "../discovery-evidence.mjs";
+import { redactCredentialPatterns } from "../../utils/redact-credential-patterns.mjs";
 const CONTROLLER_SEEDING_PHASE_ID = "__controller_seeding__";
 function buildSeedCalls(fixtures) {
   if (!fixtures) return [];
@@ -463,6 +467,8 @@ async function runDeclaredFixtureResolution(seedClient, discoveryClient, storybo
   let passedCount = 0;
   let failedCount = 0;
   let fixtureUnsatisfied = false;
+  let fixtureUnavailable;
+  const unavailableResolutions = /* @__PURE__ */ new Set();
   for (const call of orderedCalls) {
     const spec = resolutionSpecForCall(call, specByKey);
     if (!spec) {
@@ -491,6 +497,9 @@ async function runDeclaredFixtureResolution(seedClient, discoveryClient, storybo
     const attempts = [];
     let boundIds;
     let chosenStrategy;
+    let attemptedStrategy;
+    let discoveryFailureEvidence;
+    let discoverySchemaFailure;
     let failure;
     const stepStart = Date.now();
     const parentStatus = spec.parentProductHandle ? productStatuses.get(spec.parentProductHandle) : void 0;
@@ -499,7 +508,13 @@ async function runDeclaredFixtureResolution(seedClient, discoveryClient, storybo
       const strategy = spec.strategies[0];
       const detail = parentStatus === "failed" ? `parent product handle "${spec.parentProductHandle}" failed resolution` : `parent product handle "${spec.parentProductHandle}" is unavailable`;
       attempts.push({ strategy, disposition: parentStatus === "failed" ? "failed" : "unavailable", detail });
-      if (parentStatus === "failed") failure = detail;
+      if (parentStatus === "failed") {
+        failure = detail;
+        if (spec.parentProductHandle && unavailableResolutions.has(
+          resolutionSpecKey({ ...spec, entityType: "product", handle: spec.parentProductHandle })
+        ))
+          unavailableResolutions.add(resolutionSpecKey(spec));
+      }
     }
     for (const strategy of parentUnavailable ? [] : spec.strategies) {
       if (strategy === "seed") {
@@ -513,6 +528,7 @@ async function runDeclaredFixtureResolution(seedClient, discoveryClient, storybo
           });
           continue;
         }
+        attemptedStrategy = strategy;
         try {
           const controllerRequest = applyFixtureBindingsToRequest(
             { scenario: call.scenario, params: call.params },
@@ -613,10 +629,22 @@ async function runDeclaredFixtureResolution(seedClient, discoveryClient, storybo
           });
           continue;
         }
+        attemptedStrategy = strategy;
         const discovered = await catalog();
         if (!discovered.ok) {
           failure = discovered.error;
-          attempts.push({ strategy, disposition: "failed", detail: failure, response: discovered.evidence });
+          if (discovered.unavailable) {
+            fixtureUnavailable = discovered.error;
+            unavailableResolutions.add(resolutionSpecKey(spec));
+          }
+          discoveryFailureEvidence = discovered.exchange;
+          discoverySchemaFailure = discovered.schemaFailure;
+          attempts.push({
+            strategy,
+            disposition: discovered.unavailable ? "unavailable" : "failed",
+            detail: failure,
+            response: discovered.evidence
+          });
           break;
         }
         const selected = selectDiscoveredFixture(
@@ -689,6 +717,9 @@ async function runDeclaredFixtureResolution(seedClient, discoveryClient, storybo
       requirements: spec.clauses,
       strategies_attempted: attempts,
       status,
+      ...unavailableResolutions.has(resolutionSpecKey(spec)) && {
+        unavailable_reason: "runner_budget_exhausted"
+      },
       ...chosenStrategy && { strategy: chosenStrategy },
       ...boundIds && { seller_ids: boundIds }
     };
@@ -700,8 +731,20 @@ async function runDeclaredFixtureResolution(seedClient, discoveryClient, storybo
         step_id: call.step_id,
         phase_id: CONTROLLER_SEEDING_PHASE_ID,
         title: call.title,
-        task: chosenStrategy === "discover" ? "get_products" : "comply_test_controller",
-        passed: status !== "failed",
+        // The task that ACTUALLY ran, else the one this handle declared.
+        // Falling back to the controller whenever no strategy RESOLVED
+        // attributed a failed discover-only handle to a seed call that
+        // never happened — and a handle abandoned because its parent
+        // failed makes no call at all, so it is named by the strategy it
+        // declared rather than by a different tool. Such a step carries
+        // no request record, so nothing implies a call was made.
+        task: (chosenStrategy ?? attemptedStrategy ?? spec.strategies[0]) === "discover" ? "get_products" : "comply_test_controller",
+        passed: status !== "failed" || unavailableResolutions.has(resolutionSpecKey(spec)),
+        ...unavailableResolutions.has(resolutionSpecKey(spec)) && {
+          skipped: true,
+          skip_reason: "not_applicable",
+          skip: { reason: "not_applicable", detail: fixtureUnavailable ?? failure }
+        },
         duration_ms: Date.now() - stepStart,
         // An unbuildable capture gets a `check` discriminator like the other
         // two failure classes, so a report renderer keys on `check` for all
@@ -725,15 +768,41 @@ async function runDeclaredFixtureResolution(seedClient, discoveryClient, storybo
             schema_url: null,
             ...captureFailures.get(spec.handle)?.exchange ?? {}
           }
+        ] : discoverySchemaFailure !== void 0 ? [
+          // A page that parsed but failed its response schema is a
+          // `response_schema` failure, not a capture failure. Using
+          // the contract's own kind keeps the schema identity where
+          // consumers already look for it.
+          {
+            check: "response_schema",
+            passed: false,
+            description: "Fixture discovery response must satisfy the get_products response schema",
+            error: discoverySchemaFailure.detail,
+            json_pointer: null,
+            schema_id: discoverySchemaFailure.schema_id,
+            schema_url: discoverySchemaFailure.schema_url,
+            expected: discoverySchemaFailure.schema_id,
+            actual: "schema_validation_failed",
+            ...discoveryFailureEvidence && {
+              request: discoveryFailureEvidence.request,
+              response: discoveryFailureEvidence.response
+            }
+          }
         ] : [],
         context,
-        extraction: { path: "none" },
+        extraction: discoveryFailureEvidence?.extraction ?? { path: "none" },
+        // The REAL exchange the failing strategy made. Absent rather than
+        // invented when the strategy never reached the wire.
+        ...discoveryFailureEvidence && {
+          request: discoveryFailureEvidence.request,
+          ...discoveryFailureEvidence.response && { response_record: discoveryFailureEvidence.response }
+        },
         ...failure && { error: failure }
       });
     }
-    if (status === "failed") failedCount++;
+    if (status === "failed" && !unavailableResolutions.has(resolutionSpecKey(spec))) failedCount++;
     else if (status === "unsatisfied") fixtureUnsatisfied = true;
-    else passedCount++;
+    else if (status === "resolved") passedCount++;
   }
   const allPassed = failedCount === 0;
   const graphComplete = allPassed && !fixtureUnsatisfied && captureFailure === void 0 && records.every((r) => r.status === "resolved");
@@ -765,6 +834,7 @@ async function runDeclaredFixtureResolution(seedClient, discoveryClient, storybo
     passedCount,
     failedCount,
     fixtureUnsatisfied,
+    ...fixtureUnavailable && { fixtureUnavailable },
     bindings,
     resolutionRecords: records,
     ...preparedCaptures && { preparedCaptures }
@@ -926,6 +996,29 @@ async function executeLegacySeedCall(client, storyboard, call, options, context,
     };
   }
 }
+function resolveDiscoverySchemaIdentity(adcpVersion) {
+  const schemaId = `/schemas/${adcpVersion}/media-buy/get-products-response.json`;
+  return { schema_id: schemaId, schema_url: `https://adcontextprotocol.org${schemaId}` };
+}
+function describeDiscoverySchemaFailure(data, options) {
+  try {
+    const version = options.adcpVersion ?? ADCP_VERSION;
+    const validator = getValidator("get_products", "sync", version);
+    let detail;
+    if (validator) {
+      const schemaData = isPlainRecord(data) ? injectLegacyEnvelopeStatus(data, { toolName: "get_products" }) : data;
+      if (validator(schemaData)) return void 0;
+      detail = (validator.errors ?? []).map((error) => `${error.instancePath || "/"} ${error.message ?? error.keyword}`).join("; ");
+    } else {
+      const schema = validateResponseSchema("get_products", data, options.adcpVersion);
+      if (schema.passed) return void 0;
+      detail = schema.error ?? schema.details ?? "schema validation failed";
+    }
+    return { error: detail, schemaFailure: { detail, ...resolveDiscoverySchemaIdentity(version) } };
+  } catch (err) {
+    return { error: `response schema unavailable: ${err instanceof Error ? err.message : String(err)}` };
+  }
+}
 async function discoverProductCatalog(client, options, context) {
   const contextAccount = isPlainRecord(context.account) ? context.account : void 0;
   const baseAccount = contextAccount ?? resolveAccount(options);
@@ -941,89 +1034,212 @@ async function discoverProductCatalog(client, options, context) {
   const seenCursors = /* @__PURE__ */ new Set();
   let cursor;
   let pageCount = 0;
+  let restarts = 0;
+  let feedIdentity;
+  const query = structuredClone({
+    buying_mode: "wholesale",
+    brand,
+    account,
+    ext: { adcp: { creative_wire: "canonical" } }
+  });
+  let lastExchange;
   const exchanges = [];
   const pageOfProduct = /* @__PURE__ */ new Map();
-  do {
+  while (true) {
+    options.signal?.throwIfAborted();
     if (pageCount >= 1e3) {
-      return { ok: false, error: "fixture discovery pagination exceeded the 1,000-page safety limit" };
+      return {
+        ok: false,
+        unavailable: true,
+        evidence: { page_count: pageCount, restart_count: restarts },
+        ...lastExchange && { exchange: lastExchange },
+        error: "fixture discovery pagination exceeded the runner\u2019s 1,000-page safety limit"
+      };
     }
     const request = {
-      buying_mode: "wholesale",
-      brand,
-      account,
-      pagination: { max_results: 100, ...cursor && { cursor } },
-      // Fixture match declarations target the canonical product shape.
-      ext: { adcp: { creative_wire: "canonical" } }
+      ...structuredClone(query),
+      pagination: { max_results: 100, ...cursor && { cursor } }
     };
     let result;
+    let observedResponse;
+    const toolResponse = (captures) => [...captures].reverse().find((capture) => capture.requestAdcpSkill === "get_products");
     const pageStart = Date.now();
+    const requestRecord = {
+      transport: options.protocol === "a2a" ? "a2a" : "mcp",
+      operation: "get_products",
+      payload: redactSecrets(request)
+    };
     try {
-      result = await executeStoryboardTask(client, "get_products", request, { signal: options.signal });
+      if (options.protocol === "a2a") {
+        const captured = await withRawResponseCapture(
+          () => executeStoryboardTask(client, "get_products", request, { signal: options.signal }),
+          { maxBodyBytes: 65536, maxCaptures: 8, maxTotalBodyBytes: 262144 }
+        );
+        result = captured.result;
+        observedResponse = toolResponse(captured.captures);
+      } else {
+        result = await executeStoryboardTask(client, "get_products", request, { signal: options.signal });
+      }
     } catch (err) {
+      const observed = toolResponse(getCapturesFromError(err) ?? []);
       return {
         ok: false,
-        error: `fixture discovery transport failure: ${err instanceof Error ? err.message : String(err)}`
+        error: `fixture discovery transport failure: ${redactCredentialPatterns(err instanceof Error ? err.message : String(err), false)}`,
+        evidence: { page_count: pageCount + 1, request: requestRecord.payload },
+        // Explicitly null: no response was received. Not a placeholder.
+        exchange: {
+          request: requestRecord,
+          response: observed ? {
+            transport: requestRecord.transport,
+            payload: redactDiscoveryResponse(observed.body),
+            status: observed.status,
+            duration_ms: Date.now() - pageStart
+          } : null
+        }
       };
     }
     pageCount++;
+    let wireResponse = result.debug_logs?.slice().reverse().find(
+      (log) => typeof log.message === "string" && (log.message.startsWith("MCP: Tool get_products response received") || log.message.startsWith("A2A: Response received")) && log.response !== void 0
+    )?.response;
+    if (wireResponse === void 0 && observedResponse && !observedResponse.bodyTruncated) {
+      try {
+        wireResponse = JSON.parse(observedResponse.body);
+      } catch {
+      }
+    }
+    if ((!result.success || result.data === void 0) && result._extraction_path === void 0 && observedResponse === void 0 && wireResponse === void 0) {
+      return {
+        ok: false,
+        error: `fixture discovery get_products rejected: ${redactCredentialPatterns(result.error ?? result.adcp_error?.code ?? "unknown error", false)}`,
+        evidence: { page_count: pageCount, request: requestRecord.payload },
+        exchange: { request: requestRecord, response: null }
+      };
+    }
+    const extraction = {
+      path: result._extraction_path ?? "none",
+      ...observedResponse?.bodyTruncated && { note: "Raw HTTP response capture was truncated at its body budget." }
+    };
+    const failedExchange = {
+      request: requestRecord,
+      extraction,
+      response: {
+        transport: requestRecord.transport,
+        payload: redactDiscoveryResponse(wireResponse ?? observedResponse?.body ?? result.data),
+        ...observedResponse && { status: observedResponse.status },
+        duration_ms: Date.now() - pageStart
+      }
+    };
+    lastExchange = failedExchange;
     const retainResponse = exchanges.length < DISCOVERY_RETAINED_RESPONSE_PAGES;
     const pageIndex = exchanges.push({
-      request: { transport: "mcp", operation: "get_products", payload: redactSecrets(request) },
-      response: {
-        transport: "mcp",
-        payload: retainResponse ? redactSecrets(
-          result.data ?? (result.adcp_error ? { adcp_error: result.adcp_error } : void 0) ?? result.error ?? null
-        ) : {
+      request: requestRecord,
+      response: retainResponse ? { ...failedExchange.response, payload: redactSecrets(result.data) } : {
+        transport: requestRecord.transport,
+        payload: {
           response_not_retained: `page ${exchanges.length + 1} is past the runner's ${DISCOVERY_RETAINED_RESPONSE_PAGES}-page discovery-evidence budget; the request for this page is recorded in full`
         },
         duration_ms: Date.now() - pageStart
       }
     }) - 1;
+    let schemaData = result.success ? result.data : void 0;
+    if (!result.success && wireResponse !== void 0 && result._extraction_path !== "error") {
+      try {
+        schemaData = unwrapProtocolResponse(wireResponse, void 0, options.protocol === "a2a" ? "a2a" : "mcp");
+        extraction.path = readExtractionPath(schemaData) ?? extraction.path;
+      } catch {
+        schemaData = void 0;
+      }
+    }
+    const nativeResult = isPlainRecord(wireResponse) && isPlainRecord(wireResponse.result) ? wireResponse.result : void 0;
+    const nativeState = nativeResult && isPlainRecord(nativeResult.status) ? nativeResult.status.state : void 0;
+    const sellerRejected = result._extraction_path === "error" || isPlainRecord(schemaData) && (schemaData.adcp_error !== void 0 || schemaData.status === "failed" || schemaData.status === "rejected") || nativeState === "failed" || nativeState === "rejected" || nativeState === "canceled";
+    const schemaCheck = sellerRejected || schemaData === void 0 ? void 0 : describeDiscoverySchemaFailure(schemaData, options);
     if (!result.success) {
       return {
         ok: false,
-        error: `fixture discovery get_products rejected: ${result.error ?? result.adcp_error?.code ?? "unknown error"}`,
-        evidence: { page_count: pageCount, request }
+        error: `fixture discovery get_products rejected: ${redactCredentialPatterns(result.error ?? result.adcp_error?.code ?? "unknown error", false)}`,
+        evidence: { page_count: pageCount, request: requestRecord.payload },
+        exchange: failedExchange,
+        ...schemaCheck?.schemaFailure && { schemaFailure: schemaCheck.schemaFailure }
       };
     }
-    let schemaFailure;
-    try {
-      const validator = getValidator("get_products", "sync", options.adcpVersion ?? ADCP_VERSION);
-      if (validator) {
-        const responseData = result.data;
-        const schemaData = isPlainRecord(responseData) ? injectLegacyEnvelopeStatus(responseData, { toolName: "get_products" }) : responseData;
-        if (!validator(schemaData)) {
-          schemaFailure = (validator.errors ?? []).map((error) => `${error.instancePath || "/"} ${error.message ?? error.keyword}`).join("; ");
-        }
-      } else {
-        const schema = validateResponseSchema("get_products", result.data, options.adcpVersion);
-        if (!schema.passed) schemaFailure = schema.error ?? schema.details ?? "schema validation failed";
-      }
-    } catch (err) {
-      schemaFailure = `response schema unavailable: ${err instanceof Error ? err.message : String(err)}`;
-    }
-    if (schemaFailure) {
+    if (schemaCheck) {
       return {
         ok: false,
-        error: `fixture discovery returned malformed get_products response: ${schemaFailure}`,
-        evidence: { page_count: pageCount }
+        error: `fixture discovery get_products validation failed: ${schemaCheck.error}`,
+        evidence: { page_count: pageCount },
+        exchange: failedExchange,
+        ...schemaCheck.schemaFailure && { schemaFailure: schemaCheck.schemaFailure }
       };
     }
     if (!isPlainRecord(result.data)) {
-      return { ok: false, error: "fixture discovery returned a non-object get_products response" };
+      return {
+        ...{ ok: false, error: "fixture discovery returned a non-object get_products response" },
+        exchange: failedExchange
+      };
+    }
+    if (result.data.unchanged === true) {
+      return {
+        ok: false,
+        error: "fixture discovery received unchanged without sending a conditional feed token",
+        exchange: failedExchange
+      };
+    }
+    const pagination = isPlainRecord(result.data.pagination) ? result.data.pagination : void 0;
+    if (pagination?.has_more === true && (typeof pagination.cursor !== "string" || pagination.cursor.length === 0)) {
+      return {
+        ok: false,
+        error: "fixture discovery pagination is broken: has_more=true without cursor",
+        exchange: failedExchange
+      };
+    }
+    const identity = JSON.stringify([
+      result.data.cache_scope,
+      result.data.wholesale_feed_version,
+      result.data.pricing_version
+    ]);
+    if (feedIdentity !== void 0 && identity !== feedIdentity) {
+      if (restarts >= 3) {
+        return {
+          ok: false,
+          unavailable: true,
+          error: "fixture discovery could not enumerate a stable feed within the runner\u2019s 3-restart budget",
+          evidence: { page_count: pageCount, restart_count: restarts },
+          exchange: failedExchange
+        };
+      }
+      restarts++;
+      products.length = 0;
+      seenProductIds.clear();
+      cursors.length = 0;
+      seenCursors.clear();
+      exchanges.length = 0;
+      pageOfProduct.clear();
+      cursor = void 0;
+      feedIdentity = void 0;
+      continue;
     }
+    feedIdentity = identity;
     const pageProducts = result.data.products;
     if (pageProducts !== void 0 && !Array.isArray(pageProducts)) {
-      return { ok: false, error: "fixture discovery get_products.products is not an array" };
+      return {
+        ...{ ok: false, error: "fixture discovery get_products.products is not an array" },
+        exchange: failedExchange
+      };
     }
     for (const product of pageProducts ?? []) {
       if (!isPlainRecord(product) || typeof product.product_id !== "string" || product.product_id.length === 0) {
-        return { ok: false, error: "fixture discovery returned a product without a non-empty product_id" };
+        return {
+          ...{ ok: false, error: "fixture discovery returned a product without a non-empty product_id" },
+          exchange: failedExchange
+        };
       }
       if (seenProductIds.has(product.product_id)) {
         return {
           ok: false,
-          error: `fixture discovery returned duplicate product_id "${product.product_id}"; response order cannot resolve duplicate identities`
+          error: `fixture discovery returned duplicate product_id "${product.product_id}"; response order cannot resolve duplicate identities`,
+          exchange: failedExchange
         };
       }
       seenProductIds.add(product.product_id);
@@ -1034,7 +1250,8 @@ async function discoverProductCatalog(client, options, context) {
           if (seenPricingIds.has(option.pricing_option_id)) {
             return {
               ok: false,
-              error: `fixture discovery returned duplicate pricing option identity "${product.product_id}\0${option.pricing_option_id}"`
+              error: `fixture discovery returned duplicate pricing option identity "${product.product_id}\0${option.pricing_option_id}"`,
+              exchange: failedExchange
             };
           }
           seenPricingIds.add(option.pricing_option_id);
@@ -1043,17 +1260,19 @@ async function discoverProductCatalog(client, options, context) {
       pageOfProduct.set(product.product_id, pageIndex);
       products.push(product);
       if (products.length > 1e5) {
-        return { ok: false, error: "fixture discovery exceeded the 100,000-product safety limit" };
+        return {
+          ...{ ok: false, error: "fixture discovery exceeded the 100,000-product safety limit" },
+          exchange: failedExchange
+        };
       }
     }
-    const pagination = isPlainRecord(result.data.pagination) ? result.data.pagination : void 0;
     if (pagination?.has_more === true) {
       const next = pagination.cursor;
-      if (typeof next !== "string" || next.length === 0) {
-        return { ok: false, error: "fixture discovery pagination is broken: has_more=true without cursor" };
-      }
       if (seenCursors.has(next)) {
-        return { ok: false, error: `fixture discovery pagination is broken: repeated cursor "${next}"` };
+        return {
+          ...{ ok: false, error: `fixture discovery pagination is broken: repeated cursor "${next}"` },
+          exchange: failedExchange
+        };
       }
       seenCursors.add(next);
       cursors.push(next);
@@ -1061,12 +1280,18 @@ async function discoverProductCatalog(client, options, context) {
     } else {
       cursor = void 0;
     }
-  } while (cursor);
+    if (!cursor) break;
+  }
   return {
     ok: true,
     catalog: {
       products,
-      evidence: { page_count: pageCount, product_count: products.length, cursors },
+      evidence: {
+        page_count: pageCount,
+        product_count: products.length,
+        cursors,
+        ...restarts > 0 && { restart_count: restarts }
+      },
       exchanges,
       pageOfProduct
     }

package/dist/lib/testing/storyboard/task-map.d.mts

@@ -7,6 +7,7 @@
  * Tasks without a dedicated method fall through to `executeTask()`.
  */
 import type { TaskResult } from '../types.mjs';
+import type { DebugLogEntry } from '../../types/adcp.mjs';
 import type { MediaBuyLifecycleCoordinatorOptions } from '../../media-buy/compatibility.mjs';
 /**
  * Map of AdCP task names to SingleAgentClient method names.
@@ -35,4 +36,6 @@ export declare function defaultStoryboardResponseProjection(taskName: string, co
  * When the agent returns an async status (working/submitted), waits for
  * completion before returning — storyboard steps expect final results.
  */
-export declare function executeStoryboardTask(client: any, taskName: string, params: Record<string, unknown>, opts?: StoryboardTaskExecutionOptions): Promise<TaskResult>;
+export declare function executeStoryboardTask(client: any, taskName: string, params: Record<string, unknown>, opts?: StoryboardTaskExecutionOptions): Promise<TaskResult & {
+    debug_logs?: DebugLogEntry[];
+}>;

package/dist/lib/testing/storyboard/task-map.d.ts

@@ -7,6 +7,7 @@
  * Tasks without a dedicated method fall through to `executeTask()`.
  */
 import type { TaskResult } from '../types';
+import type { DebugLogEntry } from '../../types/adcp';
 import type { MediaBuyLifecycleCoordinatorOptions } from '../../media-buy/compatibility';
 /**
  * Map of AdCP task names to SingleAgentClient method names.
@@ -35,4 +36,6 @@ export declare function defaultStoryboardResponseProjection(taskName: string, co
  * When the agent returns an async status (working/submitted), waits for
  * completion before returning — storyboard steps expect final results.
  */
-export declare function executeStoryboardTask(client: any, taskName: string, params: Record<string, unknown>, opts?: StoryboardTaskExecutionOptions): Promise<TaskResult>;
+export declare function executeStoryboardTask(client: any, taskName: string, params: Record<string, unknown>, opts?: StoryboardTaskExecutionOptions): Promise<TaskResult & {
+    debug_logs?: DebugLogEntry[];
+}>;

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

@@ -1,5 +1,5 @@
 import type { CollectionSelectionSelector, CollectionWitnessKind } from './collection-selection.mjs';
-import type { PreparedFixturesAuthorizer, PreparedFixturesReference, PreparedStoryboardFixtures } from './prepared-fixtures.mjs';
+import type { PreparedFixturesAuthorizer, PreparedFixturesPreparationAuthorizer, PreparedFixturesReference, PreparedStoryboardFixtures } from './prepared-fixtures.mjs';
 import type { CreativeBuildProbeSpec } from './creative-build-probe.mjs';
 /**
  * Types for storyboard-driven testing.
@@ -570,6 +570,8 @@ export interface FixtureResolutionRecord {
         capability_id?: string;
         format_id?: Record<string, unknown>;
     };
+    /** SDK diagnostic: the resolution failed because the runner exhausted its observation budget, not a seller verdict. */
+    unavailable_reason?: 'runner_budget_exhausted';
 }
 /** One storyboard-scoped coverage gap produced by fixture resolution. */
 export interface FixtureResolutionCoverageGap {
@@ -1682,6 +1684,15 @@ export interface TrustedMatchPublisherAuthRunner {
         credentialState: TrustedMatchPublisherCredentialState;
     }): Promise<TrustedMatchPublisherAuthProbeConfiguration>;
 }
+/** Options for explicit fresh preparation; the preparation hook is not a run option. */
+export interface PrepareStoryboardFixturesOptions extends StoryboardRunOptions {
+    /**
+     * Asked exactly once before seller contact by prepareStoryboardFixtures.
+     * The existing prepared_fixtures_authorizer remains reuse-only and is not
+     * consulted here. A preparation grant does not authorize later reuse.
+     */
+    prepared_fixtures_preparation_authorizer?: PreparedFixturesPreparationAuthorizer;
+}
 export interface StoryboardRunOptions extends TestOptions {
     /** Compliance cache root for bundle-scoped fixtures and test vectors. */
     complianceDir?: string;
@@ -2044,6 +2055,8 @@ export interface StoryboardRunOptions extends TestOptions {
     prepared_fixtures?: PreparedStoryboardFixtures | PreparedFixturesReference;
     /**
      * Host authorization resolver, consulted on every prepared-state lookup.
+     * Never consulted by prepareStoryboardFixtures; fresh preparation uses
+     * PrepareStoryboardFixturesOptions.prepared_fixtures_preparation_authorizer.
      *
      * **Required for any reuse.** Omitting it fails closed — for direct
      * in-process state exactly as for an opaque reference, with zero seller
@@ -2496,6 +2509,8 @@ export interface ValidationResult {
     severity_promoted_from_advisory?: boolean;
     /** Dot/bracket JSON path (legacy). See `json_pointer` for the RFC 6901 form. */
     path?: string;
+    /** Authored context key used by a context-based comparison, echoed unchanged. */
+    context_key?: string;
     /** Human-readable failure detail. */
     error?: string;
     /** RFC 6901 pointer to the failing field. Null when the failure is transport-level. */
@@ -2671,12 +2686,26 @@ export interface StoryboardStepResult {
      * structured `adcp_error` envelope; absent for transport-level failures.
      */
     adcp_error?: import('../../core/ConversationTypes.mjs').AdcpErrorInfo;
+    /** Validated MCP OAuth metadata retained when discovery requires authorization. */
+    authorization_required?: import('../../auth/oauth/authorization-required.mjs').AuthorizationRequirements;
     /** Preview of the next step (for LLM consumption) */
     next?: StoryboardStepPreview;
     /** Agent URL that served this step (multi-instance mode). Absent in single-URL mode. */
     agent_url?: string;
     /** 1-based index of the agent instance (multi-instance mode). Absent in single-URL mode. */
     agent_index?: number;
+    /**
+     * Producer fixture-handle records, when this step result stands in for a
+     * whole run.
+     *
+     * `runStoryboardStep` returns one step as the entire result, so a
+     * standalone caller reusing a prepared state has nowhere else to read
+     * the `fixture_resolutions` block a full run carries. Present only when
+     * the prepared state actually holds records.
+     */
+    fixture_resolutions?: FixtureResolutionRecord[];
+    /** Historical producer evidence; excluded from consumer grading and JUnit counts. */
+    fixture_preparation?: StoryboardPhaseResult;
     /** Exact request the runner sent (contract-required on failures). */
     request?: RunnerRequestRecord;
     /** Exact response observed, including transport, status, headers. */
@@ -3151,6 +3180,8 @@ export interface StoryboardResult {
     overall_passed: boolean;
     /** AdCP 3.2 fixture-handle setup/discovery evidence, one row per handle. */
     fixture_resolutions?: FixtureResolutionRecord[];
+    /** Historical producer evidence; excluded from consumer grading and JUnit counts. */
+    fixture_preparation?: StoryboardPhaseResult;
     /** Storyboard-level fixture coverage gaps, emitted once per cause. */
     coverage_gaps?: FixtureResolutionCoverageGap[];
     /**