@adcp/sdk 16.1.0 → 16.3.0

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

@@ -8,8 +8,12 @@ import {
   buildFixtureResolutionSpecs,
   applyFixtureBindingsToRequest,
   FixtureBindingRegistry,
-  matchesFixtureRequirements
+  matchesFixtureRequirements,
+  matchFixtureRequirementsWithWitness
 } from "./fixture-resolution.mjs";
+import { readCollectionWitness } from "./collection-selection.mjs";
+import { resolvePath } from "./path.mjs";
+import { redactSecrets } from "../../utils/redact-secrets.mjs";
 const CONTROLLER_SEEDING_PHASE_ID = "__controller_seeding__";
 function buildSeedCalls(fixtures) {
   if (!fixtures) return [];
@@ -359,6 +363,10 @@ async function runRoutedControllerSeeding(storyboard, calls, context, resolveFix
     failedCount
   };
 }
+function discoveryExchangeFor(catalog, productId) {
+  const index = productId === void 0 ? void 0 : catalog.pageOfProduct.get(productId);
+  return catalog.exchanges[index ?? catalog.exchanges.length - 1];
+}
 async function runDeclaredFixtureResolution(seedClient, discoveryClient, storyboard, options, context, calls, resolveFixtureAgent) {
   const start = Date.now();
   const authoringErrorResult = buildAuthoringErrorResult(storyboard, calls, context, start);
@@ -387,6 +395,11 @@ async function runDeclaredFixtureResolution(seedClient, discoveryClient, storybo
   const claimedProducts = /* @__PURE__ */ new Map();
   const claimedPricingOptions = /* @__PURE__ */ new Map();
   const productStatuses = /* @__PURE__ */ new Map();
+  const pendingCaptures = [];
+  const retainedWitnesses = /* @__PURE__ */ new Map();
+  let captureFailure;
+  const captureFailures = /* @__PURE__ */ new Map();
+  const captureFailedHandles = /* @__PURE__ */ new Set();
   const seedContext = { correlation_id: `${storyboardCorrelationPrefix(storyboard)}--__seeding__` };
   let seedOptions = options;
   let discoveryOptions = options;
@@ -519,6 +532,43 @@ async function runDeclaredFixtureResolution(seedClient, discoveryClient, storybo
           const data = raw.data;
           if (raw.success && data?.success === true) {
             boundIds = bindSeededFixture(spec, bindings);
+            const seedSnapshot = {
+              ...spec.fixture,
+              ...spec.entityType === "product" ? { product_id: boundIds.product_id } : { pricing_option_id: boundIds.pricing_option_id }
+            };
+            const seedWitness = matchFixtureRequirementsWithWitness(seedSnapshot, spec.clauses).witness;
+            if (seedWitness) retainedWitnesses.set(spec.handle, seedWitness);
+            const seedCaptures = collectDeclaredCaptures(spec, seedSnapshot, seedWitness);
+            if (!seedCaptures.ok) {
+              failure = seedCaptures.detail;
+              captureFailure ??= seedCaptures.detail;
+              captureFailures.set(spec.handle, {
+                ...seedCaptures.path !== void 0 && { pointer: toJsonPointer(seedCaptures.path) },
+                exchange: {
+                  request: {
+                    transport: "mcp",
+                    operation: "comply_test_controller",
+                    // The object actually handed to `callControllerRaw`,
+                    // not `controllerRequest` — the call substitutes
+                    // `call.params` when the bound params are not a plain
+                    // record, and adds the seeding correlation context.
+                    payload: redactSecrets({
+                      scenario: call.scenario,
+                      params: isPlainRecord(controllerRequest.params) ? controllerRequest.params : call.params,
+                      context: seedContext
+                    })
+                  },
+                  response: { transport: "mcp", payload: redactSecrets(raw.data ?? raw.error ?? null) }
+                }
+              });
+              captureFailedHandles.add(spec.handle);
+              attempts.push({ strategy, disposition: "failed", detail: seedCaptures.detail });
+              boundIds = void 0;
+              break;
+            }
+            pendingCaptures.push(
+              ...seedCaptures.captures.map((c) => ({ ...c, sourceTask: "comply_test_controller" }))
+            );
             if (spec.entityType === "product") {
               recordIdentityClaim(claimedProducts, boundIds.product_id, spec.allowReuse);
             } else {
@@ -574,7 +624,10 @@ async function runDeclaredFixtureResolution(seedClient, discoveryClient, storybo
           discovered.catalog.products,
           bindings,
           claimedProducts,
-          claimedPricingOptions
+          claimedPricingOptions,
+          spec.entityType === "product" ? specs.filter(
+            (candidate) => candidate.entityType === "product_pricing_option" && candidate.parentProductHandle === spec.handle
+          ) : []
         );
         if (!selected.ok) {
           if (selected.failed) {
@@ -597,6 +650,27 @@ async function runDeclaredFixtureResolution(seedClient, discoveryClient, storybo
         }
         boundIds = selected.boundIds;
         chosenStrategy = strategy;
+        if (selected.witness) retainedWitnesses.set(spec.handle, selected.witness);
+        const collected = collectDeclaredCaptures(spec, selected.snapshot, selected.witness);
+        if (!collected.ok) {
+          failure = collected.detail;
+          captureFailure ??= collected.detail;
+          const failureExchange = discoveryExchangeFor(discovered.catalog, selected.boundIds.product_id);
+          captureFailures.set(spec.handle, {
+            ...collected.path !== void 0 && { pointer: toJsonPointer(collected.path) },
+            ...failureExchange && { exchange: failureExchange }
+          });
+          captureFailedHandles.add(spec.handle);
+          attempts.push({
+            strategy,
+            disposition: "failed",
+            detail: collected.detail,
+            response: { ...discovered.catalog.evidence, selected: selected.boundIds }
+          });
+          boundIds = void 0;
+          break;
+        }
+        pendingCaptures.push(...collected.captures.map((c) => ({ ...c, sourceTask: "get_products" })));
         attempts.push({
           strategy,
           disposition: "resolved",
@@ -620,6 +694,7 @@ async function runDeclaredFixtureResolution(seedClient, discoveryClient, storybo
     };
     records.push(record);
     if (status !== "unsatisfied") {
+      const captureFailed = status === "failed" && captureFailedHandles.has(spec.handle);
       steps.push({
         storyboard_id: storyboard.id,
         step_id: call.step_id,
@@ -628,7 +703,29 @@ async function runDeclaredFixtureResolution(seedClient, discoveryClient, storybo
         task: chosenStrategy === "discover" ? "get_products" : "comply_test_controller",
         passed: status !== "failed",
         duration_ms: Date.now() - stepStart,
-        validations: [],
+        // An unbuildable capture gets a `check` discriminator like the other
+        // two failure classes, so a report renderer keys on `check` for all
+        // three instead of regexing prose for this one.
+        validations: captureFailed ? [
+          {
+            check: "fixture_capture_unbuildable",
+            passed: false,
+            description: "Every declared fixture capture must be buildable from the pinned entity",
+            error: failure,
+            // The contract's analogue, `capture_path_not_resolvable`,
+            // requires the RFC 6901 form of the `context_outputs` path
+            // that failed. `null` only for the witness and size/depth
+            // arms, which genuinely have no path.
+            json_pointer: captureFailures.get(spec.handle)?.pointer ?? null,
+            expected: "a value at the declared selected-entity path, or a derivable witness",
+            actual: null,
+            // required_on_failure: null only when the check is not a
+            // response_schema check, which this never is.
+            schema_id: null,
+            schema_url: null,
+            ...captureFailures.get(spec.handle)?.exchange ?? {}
+          }
+        ] : [],
         context,
         extraction: { path: "none" },
         ...failure && { error: failure }
@@ -639,6 +736,23 @@ async function runDeclaredFixtureResolution(seedClient, discoveryClient, storybo
     else passedCount++;
   }
   const allPassed = failedCount === 0;
+  const graphComplete = allPassed && !fixtureUnsatisfied && captureFailure === void 0 && records.every((r) => r.status === "resolved");
+  const preparedCaptures = graphComplete && pendingCaptures.length > 0 ? {
+    values: Object.fromEntries(pendingCaptures.map((entry) => [entry.key, entry.value])),
+    provenance: Object.fromEntries(
+      pendingCaptures.map((entry) => [
+        entry.key,
+        {
+          source_step_id: CONTROLLER_SEEDING_PHASE_ID,
+          source_kind: "fixture_preparation",
+          source_task: entry.sourceTask,
+          fixture_handle: entry.spec.handle,
+          ...entry.spec.parentProductHandle && { fixture_product_handle: entry.spec.parentProductHandle }
+        }
+      ])
+    ),
+    witnesses: Object.fromEntries(retainedWitnesses)
+  } : void 0;
   return {
     phase: {
       phase_id: CONTROLLER_SEEDING_PHASE_ID,
@@ -652,8 +766,76 @@ async function runDeclaredFixtureResolution(seedClient, discoveryClient, storybo
     failedCount,
     fixtureUnsatisfied,
     bindings,
-    resolutionRecords: records
+    resolutionRecords: records,
+    ...preparedCaptures && { preparedCaptures }
+  };
+}
+function toJsonPointer(path) {
+  if (path === void 0 || path.length === 0) return void 0;
+  const segments = path.replace(/\[(\d+)\]/g, ".$1").split(".").filter((segment) => segment.length > 0).map((segment) => segment.replace(/~/g, "~0").replace(/\//g, "~1"));
+  return segments.length > 0 ? `/${segments.join("/")}` : void 0;
+}
+const DISCOVERY_RETAINED_RESPONSE_PAGES = 16;
+const CAPTURE_MAX_DEPTH = 64;
+const CAPTURE_MAX_BYTES = 512 * 1024;
+function describeUncapturableValue(value, key) {
+  let depth = 0;
+  const walk = (node, level) => {
+    if (level > depth) depth = level;
+    if (depth > CAPTURE_MAX_DEPTH) return false;
+    if (node === null || typeof node !== "object") return true;
+    if (Array.isArray(node)) return node.every((item) => walk(item, level + 1));
+    return Object.values(node).every((item) => walk(item, level + 1));
   };
+  if (!walk(value, 1)) {
+    return `fixture capture "${key}" nests deeper than the ${CAPTURE_MAX_DEPTH}-level capture limit`;
+  }
+  let size;
+  try {
+    size = Buffer.byteLength(JSON.stringify(value) ?? "", "utf8");
+  } catch {
+    return `fixture capture "${key}" is not JSON-serializable and cannot be detached`;
+  }
+  if (size > CAPTURE_MAX_BYTES) {
+    return `fixture capture "${key}" serializes to ${size} bytes, over the ${CAPTURE_MAX_BYTES}-byte capture limit`;
+  }
+  return void 0;
+}
+function collectDeclaredCaptures(spec, snapshot, witness) {
+  if (spec.contextOutputs.length === 0) return { ok: true, captures: [] };
+  const captures = [];
+  for (const output of spec.contextOutputs) {
+    if (output.snapshot !== void 0) {
+      captures.push({ spec, key: output.key, value: redactSecrets(snapshot) });
+      continue;
+    }
+    if (output.witness !== void 0) {
+      const read = readCollectionWitness(witness, output.witness);
+      if (!read.ok) {
+        return {
+          ok: false,
+          detail: `fixture capture "${output.key}" for handle "${spec.handle}" could not be built: ${read.detail}`
+        };
+      }
+      captures.push({ spec, key: output.key, value: read.value });
+      continue;
+    }
+    const value = resolvePath(redactSecrets(snapshot), output.path);
+    if (value === void 0 || value === null || value === "") {
+      const pinned = spec.entityType === "product" ? `product "${String(snapshot.product_id ?? spec.handle)}"` : `pricing option "${String(snapshot.pricing_option_id ?? spec.handle)}" on product "${spec.parentProductHandle}"`;
+      return {
+        ok: false,
+        path: output.path,
+        detail: `fixture capture "${output.key}" (handle "${spec.handle}", pinned ${pinned}) found no usable value at selected-entity path "${output.path}" \u2014 resolved to ${value === void 0 ? "absent" : JSON.stringify(value)}. Either the path does not exist on this entity shape (top-level keys: ${Object.keys(snapshot).join(", ")}), or this seller does not populate it. If the field is OPTIONAL in the schema (fixed_price and min_spend_per_package both are), capture the whole entity with { key: "${output.key}", snapshot: selected_entity } so absence stays absence. Add a match predicate for "${output.path}" only when carrying that field is a real eligibility requirement \u2014 gating on it stops a conformant seller qualifying at all.`
+      };
+    }
+    captures.push({ spec, key: output.key, value });
+  }
+  for (const capture of captures) {
+    const unusable = describeUncapturableValue(capture.value, capture.key);
+    if (unusable) return { ok: false, detail: unusable };
+  }
+  return { ok: true, captures };
 }
 function resolutionSpecKey(spec) {
   return spec.entityType === "product" ? `seed_product\0${spec.handle}` : `seed_pricing_option\0${spec.parentProductHandle}\0${spec.handle}`;
@@ -759,6 +941,8 @@ async function discoverProductCatalog(client, options, context) {
   const seenCursors = /* @__PURE__ */ new Set();
   let cursor;
   let pageCount = 0;
+  const exchanges = [];
+  const pageOfProduct = /* @__PURE__ */ new Map();
   do {
     if (pageCount >= 1e3) {
       return { ok: false, error: "fixture discovery pagination exceeded the 1,000-page safety limit" };
@@ -772,6 +956,7 @@ async function discoverProductCatalog(client, options, context) {
       ext: { adcp: { creative_wire: "canonical" } }
     };
     let result;
+    const pageStart = Date.now();
     try {
       result = await executeStoryboardTask(client, "get_products", request, { signal: options.signal });
     } catch (err) {
@@ -781,6 +966,19 @@ async function discoverProductCatalog(client, options, context) {
       };
     }
     pageCount++;
+    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
+        ) : {
+          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;
     if (!result.success) {
       return {
         ok: false,
@@ -842,6 +1040,7 @@ async function discoverProductCatalog(client, options, context) {
           seenPricingIds.add(option.pricing_option_id);
         }
       }
+      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" };
@@ -865,7 +1064,12 @@ async function discoverProductCatalog(client, options, context) {
   } while (cursor);
   return {
     ok: true,
-    catalog: { products, evidence: { page_count: pageCount, product_count: products.length, cursors } }
+    catalog: {
+      products,
+      evidence: { page_count: pageCount, product_count: products.length, cursors },
+      exchanges,
+      pageOfProduct
+    }
   };
 }
 function isPlainRecord(value) {
@@ -874,19 +1078,47 @@ function isPlainRecord(value) {
 function utf8Compare(a, b) {
   return Buffer.compare(Buffer.from(a, "utf8"), Buffer.from(b, "utf8"));
 }
-function selectDiscoveredFixture(spec, products, bindings, claimedProducts, claimedPricingOptions) {
+function selectDiscoveredFixture(spec, products, bindings, claimedProducts, claimedPricingOptions, dependentPricingSpecs = []) {
   if (spec.entityType === "product") {
-    const candidates2 = products.filter((product2) => matchesFixtureRequirements(product2, spec.clauses)).filter((product2) => identityCanBeClaimed(claimedProducts, product2.product_id, spec.allowReuse)).sort((a, b) => utf8Compare(a.product_id, b.product_id));
-    const selected2 = candidates2[0];
-    if (!selected2)
-      return { ok: false, failed: false, detail: "no discovered product satisfied the authored requirements" };
+    const rejections = /* @__PURE__ */ new Map();
+    let claimedElsewhere = 0;
+    let strandedChild = 0;
+    const matched = [];
+    for (const product2 of products) {
+      const match = matchFixtureRequirementsWithWitness(product2, spec.clauses);
+      if (!match.matched) {
+        const reason = match.reason ?? "did not satisfy the authored match predicates";
+        rejections.set(reason, (rejections.get(reason) ?? 0) + 1);
+        continue;
+      }
+      if (!identityCanBeClaimed(claimedProducts, product2.product_id, spec.allowReuse)) {
+        claimedElsewhere++;
+        continue;
+      }
+      if (!dependentPricingSpecs.every((child) => productCanSatisfyPricingSpec(product2, child))) {
+        strandedChild++;
+        continue;
+      }
+      matched.push({ product: product2, ...match.witness && { witness: match.witness } });
+    }
+    matched.sort((a, b) => utf8Compare(a.product.product_id, b.product.product_id));
+    const selected2 = matched[0]?.product;
+    if (!selected2) {
+      return {
+        ok: false,
+        failed: false,
+        detail: describeProductNoMatch(spec, products.length, rejections, claimedElsewhere, strandedChild)
+      };
+    }
     const productId = selected2.product_id;
     bindings.bindProduct(spec.handle, productId);
     recordIdentityClaim(claimedProducts, productId, spec.allowReuse);
     return {
       ok: true,
       boundIds: { product_id: productId },
-      detail: `selected product_id "${productId}" by UTF-8 bytewise order`
+      detail: `selected product_id "${productId}" by UTF-8 bytewise order`,
+      snapshot: selected2,
+      ...matched[0].witness && { witness: matched[0].witness }
     };
   }
   const parentHandle = spec.parentProductHandle;
@@ -921,7 +1153,7 @@ function selectDiscoveredFixture(spec, products, bindings, claimedProducts, clai
     return {
       ok: false,
       failed: false,
-      detail: "no pricing option on the bound product satisfied the authored requirements"
+      detail: `no pricing option on bound product "${sellerProductId}" satisfied fixture handle "${parentHandle}/${spec.handle}" \u2014 ${options.length} option(s) on the pinned product` + (options.length > 0 ? `, pricing_option_id(s): ${options.filter(isPlainRecord).map((option) => String(option.pricing_option_id)).slice(0, 10).join(", ")}` : "")
     };
   }
   const pricingOptionId = selected.pricing_option_id;
@@ -930,9 +1162,38 @@ function selectDiscoveredFixture(spec, products, bindings, claimedProducts, clai
   return {
     ok: true,
     boundIds: { product_id: sellerProductId, pricing_option_id: pricingOptionId },
-    detail: `selected pricing option "${sellerProductId}\0${pricingOptionId}" by UTF-8 bytewise order`
+    detail: `selected pricing option "${sellerProductId}\0${pricingOptionId}" by UTF-8 bytewise order`,
+    // The scoped price comes out of the same pinned product graph, so a
+    // captured currency / fixed_price / min_spend_per_package describes the
+    // option the buy will actually reference.
+    snapshot: selected
   };
 }
+function describeProductNoMatch(spec, candidateCount, rejections, claimedElsewhere, strandedChild) {
+  const parts = [
+    `no discovered product satisfied fixture handle "${spec.handle}" \u2014 ${candidateCount} candidate(s) enumerated from the complete paginated catalog`
+  ];
+  const top = [...rejections].sort((a, b) => b[1] - a[1]).slice(0, 3).map(([reason, count]) => `${count}x ${reason}`);
+  if (top.length > 0) parts.push(`rejected by the authored match: ${top.join(" | ")}`);
+  if (claimedElsewhere > 0) {
+    parts.push(
+      `${claimedElsewhere} otherwise-matching product(s) were already pinned to another handle \u2014 set allow_reuse: true on this declaration to share one seller entity`
+    );
+  }
+  if (strandedChild > 0) {
+    parts.push(
+      `${strandedChild} matched but carried no pricing option the declared child pricing_options could bind \u2014 loosen the child match, or give the child a seed strategy`
+    );
+  }
+  return parts.join(". ");
+}
+function productCanSatisfyPricingSpec(product, child) {
+  if (child.strategies.length !== 1 || child.strategies[0] !== "discover") return true;
+  const options = Array.isArray(product.pricing_options) ? product.pricing_options : [];
+  return options.filter(isPlainRecord).some(
+    (option) => typeof option.pricing_option_id === "string" && option.pricing_option_id.length > 0 && matchesFixtureRequirements(option, child.clauses)
+  );
+}
 function identityCanBeClaimed(claims, identity, allowReuse) {
   const existingAllowsReuse = claims.get(identity);
   return existingAllowsReuse === void 0 || existingAllowsReuse && allowReuse;