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

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

@@ -132,7 +132,8 @@ import { REQUEST_SIGNING_PROBE_TASK } from "./request-signing/synthesize.mjs";
 import { createWebhookReceiver } from "./webhook-receiver.mjs";
 import { WEBHOOK_ASSERTION_TASKS, armWebhookAssertions, executeWebhookAssertionStep } from "./webhook-assertions.mjs";
 import {
-  runControllerSeeding
+  runControllerSeeding,
+  collectWholesaleProductPages
 } from "./seeding.mjs";
 import { callControllerRaw } from "../test-controller.mjs";
 import { applyFixtureBindingsToRequest } from "./fixture-resolution.mjs";
@@ -1187,6 +1188,7 @@ function buildPhaseCapabilitySkippedSteps(storyboard, phase, detail, context) {
 }
 const REQUIREMENT_TO_SKIP_REASON = {
   controller: "missing_test_controller",
+  collect_product_pages_runner: "requirement_unmet",
   seeded_state: "requirement_unmet",
   real_wire: "requirement_unmet",
   webhook_receiver: "requirement_unmet",
@@ -1320,6 +1322,8 @@ async function checkRequires(requires, storyboard, options, profile, precomputed
       continue;
     }
     switch (requirement) {
+      case "collect_product_pages_runner":
+        break;
       case "controller": {
         if (!options.agentTools) continue;
         if (!options.agentTools.includes("comply_test_controller")) {
@@ -3553,6 +3557,11 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
       }
       assignment ??= dispatch.nextFor(step);
       const stepExecutionState = buildExecutionState(assignment.agentUrl, assignment.profile);
+      stepExecutionState.onCollectedProductPage = async (page, pageIndex) => {
+        const observed = await applyStepAssertions(step, page, assertions, assertionContexts, pageIndex);
+        assertionResults.push(...observed);
+        if (observed.some((assertion) => !assertion.passed)) assertionsFailed = true;
+      };
       if (routingContext) {
         let probes = routedPriorProbes.get(assignment.instanceIndex);
         if (!probes) {
@@ -3670,45 +3679,10 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
       }
       stepResults.push(result2);
       priorStepResults.set(step.id, result2);
-      const schemaInvalidResponse = result2.validations.some(
-        (v) => v.check === "response_schema" && validationFailsStep(v)
-      );
-      const rateLimitTripNotApplicable = result2.skipped === true && result2.skip_reason === "rate_limit_not_triggered";
-      for (const spec of assertions) {
-        if (!spec.onStep) continue;
-        if (stepDisablesAssertion(step.invariants, spec.id)) continue;
-        if (schemaInvalidResponse) {
-          result2.validations.push({
-            check: "assertion",
-            passed: true,
-            description: `${spec.id}: skipped \u2014 response failed schema validation (adcp-client#1709)`
-          });
-          continue;
-        }
-        const raw = await spec.onStep(assertionContexts.get(spec.id), {
-          ...result2,
-          context: withoutProtectedCaptures(result2.context ?? {})
-        });
-        for (const r of raw) {
-          const full = { ...r, assertion_id: spec.id, scope: "step", step_id: step.id };
-          assertionResults.push(full);
-          if (!rateLimitTripNotApplicable) {
-            result2.validations.push({
-              check: "assertion",
-              passed: r.passed,
-              description: `${spec.id}: ${r.description}`,
-              ...r.error !== void 0 && { error: r.error }
-            });
-          }
-          if (r.hint) {
-            const existing = result2.hints ?? [];
-            result2.hints = [...existing, r.hint];
-          }
-          if (!r.passed) {
-            if (!rateLimitTripNotApplicable) result2.passed = false;
-            assertionsFailed = true;
-          }
-        }
+      if (!result2.product_page_collection) {
+        const observedAssertions = await applyStepAssertions(step, result2, assertions, assertionContexts);
+        assertionResults.push(...observedAssertions);
+        if (observedAssertions.some((assertion) => !assertion.passed)) assertionsFailed = true;
       }
       if (step.task === "protected_resource_metadata") {
         if (result2.skipped && result2.skip_reason === "oauth_not_advertised") {
@@ -4890,6 +4864,18 @@ async function runStoryboardStepBody(agentUrl, storyboard, stepId, options) {
         }
       }
     }
+    if (found.step.collect_product_pages) {
+      const pageAssertions = resolveAssertions(storyboard.invariants);
+      const pageContexts = /* @__PURE__ */ new Map();
+      for (const spec of pageAssertions) {
+        const assertionContext = { storyboard, agentUrl, options, state: {} };
+        pageContexts.set(spec.id, assertionContext);
+        if (spec.onStart) await spec.onStart(assertionContext);
+      }
+      runState.onCollectedProductPage = async (page, pageIndex) => {
+        await applyStepAssertions(found.step, page, pageAssertions, pageContexts, pageIndex);
+      };
+    }
     const result = prerequisiteFailure ?? await executeStep(client, found.step, storyboard.id, found.phaseId, context, allSteps, options, runState);
     if (!result.skipped && result.passed && found.step.contributes_to) {
       if (evalContributesIf(found.step.contributes_if, /* @__PURE__ */ new Map())) {
@@ -4908,6 +4894,82 @@ async function runStoryboardStepBody(agentUrl, storyboard, stepId, options) {
     ]);
   }
 }
+async function applyStepAssertions(step, result, assertions, assertionContexts, pageIndex) {
+  const findings = [];
+  const schemaInvalid = result.validations.some((v) => v.check === "response_schema" && validationFailsStep(v));
+  const rateSkip = result.skipped === true && result.skip_reason === "rate_limit_not_triggered";
+  for (const spec of assertions) {
+    if (!spec.onStep || stepDisablesAssertion(step.invariants, spec.id)) continue;
+    if (schemaInvalid) {
+      result.validations.push({
+        check: "assertion",
+        passed: true,
+        description: `${spec.id}: skipped \u2014 response failed schema validation (adcp-client#1709)`
+      });
+      continue;
+    }
+    const raw = await spec.onStep(assertionContexts.get(spec.id), {
+      ...result,
+      context: withoutProtectedCaptures(result.context ?? {})
+    });
+    for (const observed of raw) {
+      const description = `${pageIndex === void 0 ? "" : `[physical page ${pageIndex}] `}${observed.description}`;
+      findings.push({ ...observed, description, assertion_id: spec.id, scope: "step", step_id: step.id });
+      if (!rateSkip)
+        result.validations.push({
+          check: "assertion",
+          passed: observed.passed,
+          description: `${spec.id}: ${description}`,
+          ...observed.error !== void 0 && { error: observed.error },
+          ...pageIndex !== void 0 && !observed.passed && { request: result.request, response: result.response_record ?? null }
+        });
+      if (observed.hint) result.hints = [...result.hints ?? [], observed.hint];
+      if (!observed.passed && !rateSkip) result.passed = false;
+    }
+  }
+  return findings;
+}
+function productPageStepResult(step, phaseId, context, page, schemaVersion) {
+  const failedSchema = page.schemaFailure;
+  return {
+    step_id: step.id,
+    phase_id: phaseId,
+    task: "get_products",
+    title: step.title,
+    passed: page.schema_validated && page.result?.success === true,
+    duration_ms: page.response?.duration_ms ?? 0,
+    request: page.request,
+    ...page.response && { response_record: page.response },
+    response: redactSecrets(page.result?.data),
+    extraction: page.extraction,
+    context,
+    validations: failedSchema ? [
+      {
+        check: "response_schema",
+        passed: false,
+        description: `Physical product page ${page.page_index} satisfies the get_products response schema`,
+        error: failedSchema.detail,
+        json_pointer: null,
+        expected: failedSchema.schema_id,
+        actual: "schema_validation_failed",
+        schema_id: failedSchema.schema_id,
+        schema_url: failedSchema.schema_url,
+        request: page.request,
+        response: page.response,
+        strict: { valid: false, variant: "sync" }
+      }
+    ] : page.schema_validated ? [
+      {
+        check: "response_schema",
+        passed: true,
+        description: `Physical product page ${page.page_index} satisfies the get_products response schema`,
+        schema_id: `/schemas/${schemaVersion}/media-buy/get-products-response.json`,
+        schema_url: `https://adcontextprotocol.org/schemas/${schemaVersion}/media-buy/get-products-response.json`,
+        ...page.strict_schema_validated && { strict: { valid: true, variant: "sync" } }
+      }
+    ] : []
+  };
+}
 function unresolvedStepContextVars(step, request, context, runState) {
   const unavailableInputs = (step.context_inputs ?? []).filter(
     (input) => !Object.hasOwn(context, input.key) && (runState.capabilityUnavailableContextKeys?.has(input.key) === true || runState.missingPrerequisiteContextKeys?.has(input.key) === true)
@@ -5360,6 +5422,34 @@ async function executeStep(client, step, storyboardId, phaseId, context, allStep
     };
   }
   const useRawProbe = rawProbeHeaders !== void 0 && !useSdkAuthOverride;
+  if (step.collect_product_pages && (useRawProbe || request.buying_mode !== "wholesale" || Object.hasOwn(request, "idempotency_key") || request.pagination !== null && typeof request.pagination === "object" && "cursor" in request.pagination || ["if_none_match", "if_wholesale_feed_version", "if_pricing_version"].some((field) => request[field] !== void 0))) {
+    const detail = "collect_product_pages requires fresh unkeyed reads and an unconditional wholesale first page through the official SDK client";
+    return {
+      step_id: step.id,
+      phase_id: phaseId,
+      task: step.task,
+      title: step.title,
+      passed: false,
+      duration_ms: 0,
+      context,
+      extraction: { path: "none" },
+      error: detail,
+      validations: [
+        {
+          check: "product_page_collection",
+          passed: false,
+          description: detail,
+          json_pointer: null,
+          expected: "unkeyed unconditional wholesale query",
+          actual: redactSecrets(request),
+          schema_id: null,
+          schema_url: null,
+          request: null,
+          response: null
+        }
+      ]
+    };
+  }
   const stepClient = () => authOverrideClient ?? client;
   let taskResult;
   let stepResult;
@@ -5369,6 +5459,10 @@ async function executeStep(client, step, storyboardId, phaseId, context, allStep
   let requestUrl;
   let a2aEnvelope;
   let crossResponses;
+  let productPageCollection;
+  let collectedPageValidations = [];
+  let actualCollectedResponse;
+  let collectedRequestRecord;
   if (step.parallel_dispatch && !useRawProbe) {
     const contractsInScope = new Set(options.contracts ?? []);
     if (!contractsInScope.has(PARALLEL_DISPATCH_CONTRACT)) {
@@ -5537,7 +5631,96 @@ async function executeStep(client, step, storyboardId, phaseId, context, allStep
   } else {
     const captureA2a = options.protocol === "a2a";
     let a2aCaptures;
-    if (step.parallel_dispatch) {
+    if (step.collect_product_pages) {
+      const started = Date.now();
+      const pages = [];
+      const pageValidations = [];
+      let pagesPassed = true;
+      const collection = await collectWholesaleProductPages(stepClient(), options, request, {
+        retainRestartEvidence: true,
+        dispatch: (pageRequest) => executeStoryboardTask(stepClient(), effectiveStep.task, pageRequest, {
+          skipIdempotencyAutoInject: testsIdempotencyKeyOmission,
+          skipAccountValidation: testsMissingAccount,
+          skipRequestValidation: testsSchemaInvalidRequest,
+          preserveGovernedPayload: governedRequest,
+          responseProjection,
+          mediaBuyLifecycleCompatibility: options.mediaBuyLifecycleCompatibility,
+          signal: options.signal
+        }),
+        onPage: async (observation) => {
+          const physical = productPageStepResult(
+            step,
+            phaseId,
+            context,
+            observation,
+            options._serverAdcpVersion ?? options.adcpVersion ?? ADCP_VERSION
+          );
+          await runState.onCollectedProductPage?.(physical, observation.page_index);
+          pagesPassed &&= physical.passed;
+          pageValidations.push(...physical.validations);
+          const page = {
+            page_index: observation.page_index,
+            restart_count: observation.restart_count,
+            request: observation.request,
+            response: observation.response,
+            extraction: observation.extraction,
+            schema_validated: observation.schema_validated
+          };
+          if (pages.length >= 16 && page.response) {
+            page.response = {
+              ...page.response,
+              payload: {
+                response_not_retained: "Physical page was checked; response evidence exceeded the 16-page retention budget."
+              }
+            };
+          }
+          pages.push(page);
+        }
+      });
+      if (options.signal?.aborted) options.signal.throwIfAborted();
+      const logical = collection.ok ? {
+        ...collection.catalog.firstPage.result.data,
+        products: collection.catalog.products,
+        ...collection.catalog.errors.length > 0 && { errors: collection.catalog.errors }
+      } : void 0;
+      if (logical) delete logical.pagination;
+      productPageCollection = {
+        complete: collection.ok,
+        page_count: pages.length,
+        restart_count: pages.reduce((maximum, page) => Math.max(maximum, page.restart_count), 0),
+        pages,
+        ...logical && { logical_response: redactSecrets(logical) }
+      };
+      collectedRequestRecord = collection.ok ? collection.catalog.firstPage.request : collection.exchange?.request;
+      const observedResponse = collection.ok ? collection.catalog.firstPage.response : collection.exchange?.response;
+      responseRecord = observedResponse ?? void 0;
+      actualCollectedResponse = collection.ok ? collection.catalog.firstPage.result.data : collection.exchange?.response?.payload;
+      taskResult = collection.ok ? { ...collection.catalog.firstPage.result, data: logical } : {
+        success: false,
+        error: collection.error.replace(/^fixture discovery/, "Product page collection")
+      };
+      stepResult = {
+        duration_ms: Date.now() - started,
+        passed: collection.ok && pagesPassed,
+        ...!collection.ok && { error: collection.error.replace(/^fixture discovery/, "Product page collection") }
+      };
+      collectedPageValidations = pageValidations;
+      if (!collection.ok && !pageValidations.some((validation) => validationFailsStep(validation))) {
+        collectedPageValidations.push({
+          check: "product_page_collection",
+          passed: false,
+          description: "Wholesale collection completes one stable, duplicate-free feed",
+          error: collection.error,
+          json_pointer: null,
+          expected: "a complete stable wholesale collection",
+          actual: collection.error,
+          schema_id: null,
+          schema_url: null,
+          ...collection.exchange?.request && { request: collection.exchange.request },
+          response: collection.exchange?.response ?? null
+        });
+      }
+    } else if (step.parallel_dispatch) {
       const started = Date.now();
       crossResponses = await runParallelDispatches(stepClient(), effectiveStep.task, request, {
         spec: step.parallel_dispatch,
@@ -5625,7 +5808,7 @@ async function executeStep(client, step, storyboardId, phaseId, context, allStep
   const requestRecord = {
     transport: options.protocol === "a2a" ? "a2a" : "mcp",
     operation: effectiveStep.task,
-    payload: redactSecrets(request),
+    payload: collectedRequestRecord?.payload ?? redactSecrets(request),
     ...effectiveRequestUrl ? { url: redactOAuthUrlForOutput(effectiveRequestUrl) } : {}
   };
   const inputSchemaStripNotices = collectInputSchemaFieldStripNotices(
@@ -5813,9 +5996,9 @@ async function executeStep(client, step, storyboardId, phaseId, context, allStep
     success: true,
     data: schemaValidationError.data
   } : void 0);
-  let validations = [];
+  let validations = [...collectedPageValidations];
   if (step.validations?.length && (validationTaskResult || httpResult)) {
-    const resolvedValidations = step.validations.map((v) => {
+    const resolvedValidations = step.validations.filter((v) => !productPageCollection || v.check !== "response_schema").map((v) => {
       const resolved = { ...v };
       if (resolved.value !== void 0) {
         resolved.value = injectContext({ __v: resolved.value }, context, runState.runnerVars).__v;
@@ -5872,9 +6055,11 @@ async function executeStep(client, step, storyboardId, phaseId, context, allStep
         };
       })()
     };
-    validations = runValidations(
-      resolvedValidations.filter((validation) => validation.check !== "property_list_reference"),
-      vctx
+    validations.push(
+      ...runValidations(
+        resolvedValidations.filter((validation) => validation.check !== "property_list_reference"),
+        vctx
+      )
     );
     for (const validation of resolvedValidations.filter((validation2) => validation2.check === "property_list_reference")) {
       const result = effectiveStep.task !== "create_property_list" || !validationTaskResult?.success ? {
@@ -6144,6 +6329,14 @@ async function executeStep(client, step, storyboardId, phaseId, context, allStep
       }
     }
   }
+  if (productPageCollection) {
+    for (const validation of validations) {
+      if (collectedPageValidations.includes(validation)) continue;
+      if (validation.json_pointer)
+        validation.json_pointer = `/product_page_collection/logical_response${validation.json_pointer}`;
+      validation.description = `[logical product collection] ${validation.description ?? validation.check}`;
+    }
+  }
   if (protectedViolations.length > 0) validations.push(...protectedViolations);
   const allValidationsPassedFinal = validations.every((v) => !validationFailsStep(v));
   const stepFailed = !(passed && allValidationsPassedFinal);
@@ -6173,7 +6366,8 @@ async function executeStep(client, step, storyboardId, phaseId, context, allStep
     // Legacy `response` field (new code reads `response_record`).
     // Redact in case a downstream consumer still keys off it; the
     // modern `response_record.payload` path is already redacted.
-    response: redactSecrets(taskResult?.data),
+    response: redactSecrets(productPageCollection ? actualCollectedResponse : taskResult?.data),
+    ...productPageCollection && { product_page_collection: productPageCollection },
     validations,
     // NOT projected here: the full runner threads this map from step to
     // step, so stripping the reserved namespace would break the very
@@ -6197,7 +6391,10 @@ async function executeStep(client, step, storyboardId, phaseId, context, allStep
     next,
     request: requestRecord,
     ...responseRecord && { response_record: responseRecord },
-    extraction: extractionFromTaskResult(taskResult),
+    extraction: productPageCollection ? {
+      path: "none",
+      note: "Authored checks and context use product_page_collection.logical_response; response_record remains an actual physical page."
+    } : extractionFromTaskResult(taskResult),
     ...inputSchemaStripNotices.length > 0 && { notices: inputSchemaStripNotices },
     ...hints.length > 0 && { hints }
   };

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

@@ -21,9 +21,11 @@
  * `controller_seeding_failed`.
  */
 import { type TestClient } from '../client.mjs';
+import type { TaskResult } from '../types.mjs';
+import type { DebugLogEntry } from '../../types/adcp.mjs';
 import { FixtureBindingRegistry } from './fixture-resolution.mjs';
 import { type CollectionSelectionWitness } from './collection-selection.mjs';
-import type { ContextProvenanceEntry, FixtureResolutionRecord, Storyboard, StoryboardContext, StoryboardFixtures, StoryboardPhaseResult, StoryboardRunOptions } from './types.mjs';
+import type { ContextProvenanceEntry, RunnerExtractionRecord, RunnerRequestRecord, RunnerResponseRecord, FixtureResolutionRecord, Storyboard, StoryboardContext, StoryboardFixtures, StoryboardPhaseResult, StoryboardRunOptions } from './types.mjs';
 /** Synthetic phase id used in `StoryboardResult.phases[]` for the seed pass. */
 export declare const CONTROLLER_SEEDING_PHASE_ID = "__controller_seeding__";
 /** Seed scenario names. Kept local — the server-side `SEED_SCENARIOS`
@@ -101,4 +103,87 @@ export declare function runControllerSeeding(client: TestClient, storyboard: Sto
     client: TestClient;
     options: StoryboardRunOptions;
 }): Promise<ControllerSeedingResult | null>;
+/**
+ * One actual `get_products` exchange from the discovery ladder.
+ *
+ * `runner-output-contract.yaml` makes `request` and `response` required on
+ * a failing validation, with null reserved for pre-wire failures. A capture
+ * that cannot be built from a pinned entity is NOT pre-wire — the entity
+ * came off the wire — so the failing result has to carry the exchange that
+ * produced it rather than an explicit "no contact" null.
+ */
+export interface DiscoveryExchange {
+    request: RunnerRequestRecord;
+    response: RunnerResponseRecord;
+}
+export interface DiscoveryCatalog {
+    products: Array<Record<string, unknown>>;
+    firstPage: ProductPageObservation;
+    errors: unknown[];
+    evidence: {
+        page_count: number;
+        product_count: number;
+        cursors: string[];
+        restart_count?: number;
+    };
+    /** Per-page exchanges, in request order. */
+    exchanges: DiscoveryExchange[];
+    /** product_id → index into `exchanges`, so a failure cites ITS page. */
+    pageOfProduct: Map<string, number>;
+}
+export type DiscoveryCatalogResult = {
+    ok: true;
+    catalog: DiscoveryCatalog;
+} | {
+    ok: false;
+    error: string;
+    evidence?: unknown;
+    /**
+     * The actual exchange that failed, so the producer step can record
+     * truthful wire evidence instead of nothing. `response` is null only
+     * when the transport threw and no response was ever received — never
+     * a stand-in for one we did not capture.
+     */
+    exchange?: {
+        request: RunnerRequestRecord;
+        response: RunnerResponseRecord | null;
+        extraction?: RunnerExtractionRecord;
+    };
+    /** AJV detail when the page parsed but failed its response schema. */
+    unavailable?: true;
+    schemaFailure?: {
+        detail: string;
+        schema_id: string;
+        schema_url: string;
+    };
+};
+/** One actual page, observed before any restart can discard its products. */
+type ProductPageTaskResult = TaskResult & {
+    debug_logs?: DebugLogEntry[];
+};
+export interface ProductPageObservation {
+    page_index: number;
+    restart_count: number;
+    request: RunnerRequestRecord;
+    response: RunnerResponseRecord | null;
+    extraction: RunnerExtractionRecord;
+    result?: ProductPageTaskResult;
+    schema_validated: boolean;
+    /** A cached JSON-schema validator, rather than the legacy fallback, checked this page. */
+    strict_schema_validated?: boolean;
+    schemaFailure?: {
+        detail: string;
+        schema_id: string;
+        schema_url: string;
+    };
+}
+export interface ProductPageCollectionControls {
+    /** Preserve the normal step's execution policy and actual authored arguments. */
+    dispatch?: (request: Record<string, unknown>) => Promise<ProductPageTaskResult>;
+    /** Runs for every observed exchange, including pages later abandoned on restart. */
+    onPage?: (page: ProductPageObservation) => Promise<void>;
+    retainRestartEvidence?: boolean;
+}
+/** Shared strict unkeyed wholesale walker; callers own the initial query and logical view. */
+export declare function collectWholesaleProductPages(client: TestClient, options: StoryboardRunOptions, query: Record<string, unknown>, controls?: ProductPageCollectionControls): Promise<DiscoveryCatalogResult>;
 export {};

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

@@ -21,9 +21,11 @@
  * `controller_seeding_failed`.
  */
 import { type TestClient } from '../client';
+import type { TaskResult } from '../types';
+import type { DebugLogEntry } from '../../types/adcp';
 import { FixtureBindingRegistry } from './fixture-resolution';
 import { type CollectionSelectionWitness } from './collection-selection';
-import type { ContextProvenanceEntry, FixtureResolutionRecord, Storyboard, StoryboardContext, StoryboardFixtures, StoryboardPhaseResult, StoryboardRunOptions } from './types';
+import type { ContextProvenanceEntry, RunnerExtractionRecord, RunnerRequestRecord, RunnerResponseRecord, FixtureResolutionRecord, Storyboard, StoryboardContext, StoryboardFixtures, StoryboardPhaseResult, StoryboardRunOptions } from './types';
 /** Synthetic phase id used in `StoryboardResult.phases[]` for the seed pass. */
 export declare const CONTROLLER_SEEDING_PHASE_ID = "__controller_seeding__";
 /** Seed scenario names. Kept local — the server-side `SEED_SCENARIOS`
@@ -101,4 +103,87 @@ export declare function runControllerSeeding(client: TestClient, storyboard: Sto
     client: TestClient;
     options: StoryboardRunOptions;
 }): Promise<ControllerSeedingResult | null>;
+/**
+ * One actual `get_products` exchange from the discovery ladder.
+ *
+ * `runner-output-contract.yaml` makes `request` and `response` required on
+ * a failing validation, with null reserved for pre-wire failures. A capture
+ * that cannot be built from a pinned entity is NOT pre-wire — the entity
+ * came off the wire — so the failing result has to carry the exchange that
+ * produced it rather than an explicit "no contact" null.
+ */
+export interface DiscoveryExchange {
+    request: RunnerRequestRecord;
+    response: RunnerResponseRecord;
+}
+export interface DiscoveryCatalog {
+    products: Array<Record<string, unknown>>;
+    firstPage: ProductPageObservation;
+    errors: unknown[];
+    evidence: {
+        page_count: number;
+        product_count: number;
+        cursors: string[];
+        restart_count?: number;
+    };
+    /** Per-page exchanges, in request order. */
+    exchanges: DiscoveryExchange[];
+    /** product_id → index into `exchanges`, so a failure cites ITS page. */
+    pageOfProduct: Map<string, number>;
+}
+export type DiscoveryCatalogResult = {
+    ok: true;
+    catalog: DiscoveryCatalog;
+} | {
+    ok: false;
+    error: string;
+    evidence?: unknown;
+    /**
+     * The actual exchange that failed, so the producer step can record
+     * truthful wire evidence instead of nothing. `response` is null only
+     * when the transport threw and no response was ever received — never
+     * a stand-in for one we did not capture.
+     */
+    exchange?: {
+        request: RunnerRequestRecord;
+        response: RunnerResponseRecord | null;
+        extraction?: RunnerExtractionRecord;
+    };
+    /** AJV detail when the page parsed but failed its response schema. */
+    unavailable?: true;
+    schemaFailure?: {
+        detail: string;
+        schema_id: string;
+        schema_url: string;
+    };
+};
+/** One actual page, observed before any restart can discard its products. */
+type ProductPageTaskResult = TaskResult & {
+    debug_logs?: DebugLogEntry[];
+};
+export interface ProductPageObservation {
+    page_index: number;
+    restart_count: number;
+    request: RunnerRequestRecord;
+    response: RunnerResponseRecord | null;
+    extraction: RunnerExtractionRecord;
+    result?: ProductPageTaskResult;
+    schema_validated: boolean;
+    /** A cached JSON-schema validator, rather than the legacy fallback, checked this page. */
+    strict_schema_validated?: boolean;
+    schemaFailure?: {
+        detail: string;
+        schema_id: string;
+        schema_url: string;
+    };
+}
+export interface ProductPageCollectionControls {
+    /** Preserve the normal step's execution policy and actual authored arguments. */
+    dispatch?: (request: Record<string, unknown>) => Promise<ProductPageTaskResult>;
+    /** Runs for every observed exchange, including pages later abandoned on restart. */
+    onPage?: (page: ProductPageObservation) => Promise<void>;
+    retainRestartEvidence?: boolean;
+}
+/** Shared strict unkeyed wholesale walker; callers own the initial query and logical view. */
+export declare function collectWholesaleProductPages(client: TestClient, options: StoryboardRunOptions, query: Record<string, unknown>, controls?: ProductPageCollectionControls): Promise<DiscoveryCatalogResult>;
 export {};