@adcp/sdk 16.2.0 → 16.3.0

package/dist/lib/testing/storyboard/fixture-resolution.js

@@ -21,7 +21,9 @@ __export(fixture_resolution_exports, {
   FixtureBindingRegistry: () => FixtureBindingRegistry,
   applyFixtureBindingsToRequest: () => applyFixtureBindingsToRequest,
   buildFixtureResolutionSpecs: () => buildFixtureResolutionSpecs,
+  matchFixtureRequirementsWithWitness: () => matchFixtureRequirementsWithWitness,
   matchesFixtureRequirements: () => matchesFixtureRequirements,
+  normalizeFixtureContextOutputs: () => normalizeFixtureContextOutputs,
   normalizeFixtureMatchExpression: () => normalizeFixtureMatchExpression,
   validateFixtureResolutionDeclarations: () => validateFixtureResolutionDeclarations
 });
@@ -30,8 +32,18 @@ var import_node_util = require("node:util");
 var import_version = require('../../version.js');
 var import_schema_loader = require('../../validation/schema-loader.js');
 var import_canonical_format_satisfaction = require('./canonical-format-satisfaction.js');
-const OPERATORS = ["equals", "present", "contains_all", "any_match", "canonical_format_satisfies"];
-const DECLARATION_KEYS = /* @__PURE__ */ new Set(["handle", "strategies", "match", "allow_reuse"]);
+var import_collection_selection = require('./collection-selection.js');
+var import_path = require('./path.js');
+var import_protected_context = require('./protected-context.js');
+const OPERATORS = [
+  "equals",
+  "present",
+  "contains_all",
+  "any_match",
+  "canonical_format_satisfies",
+  "collection_selection_satisfies"
+];
+const DECLARATION_KEYS = /* @__PURE__ */ new Set(["handle", "strategies", "match", "allow_reuse", "context_outputs"]);
 const PRICING_DECLARATION_KEYS = /* @__PURE__ */ new Set([...DECLARATION_KEYS, "product_handle"]);
 function isRecord(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -103,6 +115,12 @@ function normalizeClause(value, location) {
         operator,
         where: normalizeFixtureMatchExpression(value.where, `${location}.where`)
       };
+    case "collection_selection_satisfies":
+      return {
+        path: value.path,
+        operator,
+        value: (0, import_collection_selection.normalizeCollectionSelectionSelector)(value.value, `${location}.value`)
+      };
     case "canonical_format_satisfies":
       assertPlainObject(value.value, `${location}.value`);
       if (typeof value.value.format_kind !== "string" || value.value.format_kind.length === 0) {
@@ -114,7 +132,7 @@ function normalizeClause(value, location) {
       return { path: value.path, operator, value: value.value };
   }
 }
-function validateDeclaration(declaration, location, allowedKeys) {
+function validateDeclaration(declaration, location, allowedKeys, entityKind = "product") {
   assertPlainObject(declaration, location);
   const unknown = Object.keys(declaration).filter((key) => !allowedKeys.has(key));
   if (unknown.length > 0) throw new Error(`${location}: unknown key(s): ${unknown.join(", ")}`);
@@ -142,10 +160,87 @@ function validateDeclaration(declaration, location, allowedKeys) {
   if (Array.isArray(declaration.strategies) && declaration.strategies.includes("discover") && clauses.length === 0) {
     throw new Error(`${location}.match: discover strategy requires at least one authored predicate`);
   }
+  normalizeFixtureContextOutputs(declaration.context_outputs, `${location}.context_outputs`, clauses, entityKind);
+}
+const FIXTURE_CONTEXT_OUTPUT_KEYS = /* @__PURE__ */ new Set(["key", "path", "witness", "snapshot"]);
+function normalizeFixtureContextOutputs(value, location, clauses, entityKind = "product") {
+  if (value === void 0) return [];
+  assertArray(value, location);
+  if (value.length === 0) throw new Error(`${location}: must contain at least one capture when present`);
+  const hasCollectionPredicate = clauses.some((clause) => clause.operator === "collection_selection_satisfies");
+  const seen = /* @__PURE__ */ new Set();
+  return value.map((raw, index) => {
+    const entryLocation = `${location}[${index}]`;
+    assertPlainObject(raw, entryLocation);
+    const unknown = Object.keys(raw).filter((key) => !FIXTURE_CONTEXT_OUTPUT_KEYS.has(key));
+    if (unknown.length > 0) {
+      throw new Error(`${entryLocation}: unknown key(s): ${unknown.join(", ")}`);
+    }
+    if (typeof raw.key !== "string" || raw.key.length === 0) {
+      throw new Error(`${entryLocation}.key: must be a non-empty string`);
+    }
+    if (!(0, import_protected_context.isProtectedContextKey)(raw.key)) {
+      throw new Error(
+        `${entryLocation}.key: fixture captures must use the reserved "__adcp_fixture_" prefix so later steps, caller context and seller responses cannot replace them; received "${raw.key}"`
+      );
+    }
+    (0, import_protected_context.assertWellFormedProtectedKey)(raw.key, entryLocation + ".key");
+    if (seen.has(raw.key)) throw new Error(`${entryLocation}.key: duplicate capture key "${raw.key}"`);
+    seen.add(raw.key);
+    const forms = ["path", "witness", "snapshot"].filter((form) => Object.hasOwn(raw, form));
+    if (forms.length !== 1) {
+      throw new Error(
+        `${entryLocation}: must set exactly one of 'path', 'witness' or 'snapshot'; received ${forms.length === 0 ? "none" : forms.join(" + ")}`
+      );
+    }
+    const hasPath = forms[0] === "path";
+    if (forms[0] === "snapshot") {
+      if (raw.snapshot !== "selected_entity") {
+        throw new Error(`${entryLocation}.snapshot: must be 'selected_entity'`);
+      }
+      return { key: raw.key, snapshot: "selected_entity" };
+    }
+    if (hasPath) {
+      if (typeof raw.path !== "string" || raw.path.length === 0) {
+        throw new Error(`${entryLocation}.path: must be a non-empty string`);
+      }
+      if (raw.path.startsWith("/")) {
+        throw new Error(
+          `${entryLocation}.path: capture paths use the dotted storyboard grammar ("currency", "pricing_options[0].rate"), not the RFC 6901 pointers that match[].path takes; drop the leading "/" \u2014 received "${raw.path}"`
+        );
+      }
+      if ((0, import_path.parsePath)(raw.path).length === 0) {
+        throw new Error(
+          `${entryLocation}.path: must name at least one field in the dotted storyboard grammar ("currency", "pricing_options[0].rate") \u2014 received "${raw.path}", which resolves to the whole selected entity. To capture the whole entity, say so: snapshot: 'selected_entity'.`
+        );
+      }
+      if (raw.path.split(".").some((segment) => segment.length === 0)) {
+        throw new Error(`${entryLocation}.path: every dotted segment must name a field \u2014 received "${raw.path}".`);
+      }
+      return { key: raw.key, path: raw.path };
+    }
+    if (typeof raw.witness !== "string" || !import_collection_selection.COLLECTION_WITNESS_KINDS.includes(raw.witness)) {
+      throw new Error(`${entryLocation}.witness: must be one of ${import_collection_selection.COLLECTION_WITNESS_KINDS.join(", ")}`);
+    }
+    if (entityKind === "pricing_option") {
+      throw new Error(
+        `${entryLocation}.witness: a collection witness describes the product, not one of its pricing options; declare it under fixture_resolution.products.<product_handle>.context_outputs instead`
+      );
+    }
+    if (!hasCollectionPredicate) {
+      throw new Error(
+        `${entryLocation}.witness: requires a collection_selection_satisfies predicate on the same declaration`
+      );
+    }
+    return { key: raw.key, witness: raw.witness };
+  });
 }
 function validateFixtureResolutionDeclarations(storyboard) {
   const root = storyboard.fixture_resolution;
-  if (root === void 0) return;
+  if (root === void 0) {
+    assertNoReservedOrdinaryKeys(storyboard);
+    return;
+  }
   assertPlainObject(root, `[${storyboard.id}] fixture_resolution`);
   const unknownRoot = Object.keys(root).filter((key) => key !== "products" && key !== "pricing_options");
   if (unknownRoot.length > 0) {
@@ -195,7 +290,7 @@ function validateFixtureResolutionDeclarations(storyboard) {
     for (let index = 0; index < root.pricing_options.length; index++) {
       const declaration = root.pricing_options[index];
       const location = `[${storyboard.id}] fixture_resolution.pricing_options[${index}]`;
-      validateDeclaration(declaration, location, PRICING_DECLARATION_KEYS);
+      validateDeclaration(declaration, location, PRICING_DECLARATION_KEYS, "pricing_option");
       const typedDeclaration = declaration;
       if (typeof typedDeclaration.product_handle !== "string" || typedDeclaration.product_handle.length === 0) {
         throw new Error(`${location}.product_handle: must be a non-empty string`);
@@ -212,6 +307,68 @@ function validateFixtureResolutionDeclarations(storyboard) {
       }
     }
   }
+  assertNoReservedOrdinaryKeys(storyboard);
+  assertUniqueFixtureCaptureKeys(storyboard);
+}
+function assertNoReservedOrdinaryKeys(storyboard) {
+  const reject = (key, location) => {
+    if ((0, import_protected_context.isProtectedContextKey)(key)) {
+      throw new Error(
+        `${location}: "${key}" uses the reserved "__adcp_fixture_" prefix, which is owned by fixture preparation. Rename it to any key not starting with "__adcp_fixture_".`
+      );
+    }
+    if (key === "__proto__" || key === "constructor" || key === "prototype") {
+      throw new Error(
+        `${location}: "${key}" is a prototype-sensitive context key and cannot be used; rename it to anything other than __proto__, constructor or prototype`
+      );
+    }
+  };
+  for (const key of Object.keys(storyboard.context ?? {})) {
+    reject(key, `[${storyboard.id}] context`);
+  }
+  for (const phase of storyboard.phases ?? []) {
+    for (const step of phase.steps ?? []) {
+      for (const output of step.context_outputs ?? []) {
+        if (typeof output.key !== "string") continue;
+        if ((0, import_protected_context.isProtectedContextKey)(output.key)) {
+          throw new Error(
+            `[${storyboard.id}] phase '${phase.id}' step '${step.id}': context_outputs entry "${output.key}" uses the reserved "__adcp_fixture_" prefix; step captures cannot write fixture-preparation state. Declare it under fixture_resolution instead, or rename the key.`
+          );
+        }
+        reject(output.key, `[${storyboard.id}] phase '${phase.id}' step '${step.id}' context_outputs`);
+      }
+      const gates = step.not_applicable_if;
+      for (const gate of gates === void 0 ? [] : Array.isArray(gates) ? gates : [gates]) {
+        for (const key of gate.context_keys ?? []) {
+          if (typeof key === "string") {
+            reject(key, `[${storyboard.id}] phase '${phase.id}' step '${step.id}' not_applicable_if.context_keys`);
+          }
+        }
+      }
+    }
+  }
+}
+function assertUniqueFixtureCaptureKeys(storyboard) {
+  const owners = /* @__PURE__ */ new Map();
+  const claim = (key, owner) => {
+    const existing = owners.get(key);
+    if (existing !== void 0) {
+      throw new Error(
+        `[${storyboard.id}] fixture_resolution: capture key "${key}" is declared by both ${existing} and ${owner}`
+      );
+    }
+    owners.set(key, owner);
+  };
+  for (const declaration of storyboard.fixture_resolution?.products ?? []) {
+    for (const output of declaration.context_outputs ?? []) {
+      claim(output.key, `products."${declaration.handle}"`);
+    }
+  }
+  for (const declaration of storyboard.fixture_resolution?.pricing_options ?? []) {
+    for (const output of declaration.context_outputs ?? []) {
+      claim(output.key, `pricing_options."${declaration.product_handle}/${declaration.handle}"`);
+    }
+  }
 }
 function resolveCandidatePath(candidate, pointer) {
   let current = candidate;
@@ -235,9 +392,38 @@ function matchesFixtureRequirements(candidate, clauses) {
         return Array.isArray(actual) && actual.some((value) => matchesFixtureRequirements(value, clause.where ?? []));
       case "canonical_format_satisfies":
         return (0, import_canonical_format_satisfaction.productCanonicalFormatSatisfies)(actual, clause.value);
+      case "collection_selection_satisfies":
+        return (0, import_collection_selection.evaluateCollectionSelection)(actual, clause.value).eligible;
     }
   });
 }
+function matchFixtureRequirementsWithWitness(candidate, clauses) {
+  let witness;
+  let matched = true;
+  let reason;
+  for (const clause of clauses) {
+    if (clause.operator !== "collection_selection_satisfies") {
+      if (matched && !matchesFixtureRequirements(candidate, [clause])) {
+        matched = false;
+        reason = `${clause.operator} at "${clause.path || "(whole candidate)"}" did not match`;
+      }
+      continue;
+    }
+    const actual = resolveCandidatePath(candidate, clause.path);
+    const evaluation = (0, import_collection_selection.evaluateCollectionSelection)(actual, clause.value);
+    if (!evaluation.eligible) {
+      if (matched) reason = evaluation.reason;
+      matched = false;
+      continue;
+    }
+    witness = evaluation.witness;
+  }
+  return {
+    matched,
+    ...witness && { witness },
+    ...reason !== void 0 && { reason }
+  };
+}
 function buildFixtureResolutionSpecs(storyboard) {
   const specs = [];
   const productFixtures = new Map(
@@ -260,13 +446,22 @@ function buildFixtureResolutionSpecs(storyboard) {
     if (!fixture) continue;
     if (typeof fixture.product_id !== "string" || fixture.product_id.length === 0) continue;
     const { product_id: handle, ...requirementFixture } = fixture;
+    const productClauses = normalizeFixtureMatchExpression(
+      declaration?.match,
+      `fixture_resolution.products.${handle}.match`
+    );
     specs.push({
       entityType: "product",
       handle,
       fixture: requirementFixture,
       strategies: [...declaration?.strategies ?? ["seed"]],
-      clauses: normalizeFixtureMatchExpression(declaration?.match, `fixture_resolution.products.${handle}.match`),
-      allowReuse: declaration?.allow_reuse === true
+      clauses: productClauses,
+      allowReuse: declaration?.allow_reuse === true,
+      contextOutputs: normalizeFixtureContextOutputs(
+        declaration?.context_outputs,
+        `fixture_resolution.products.${handle}.context_outputs`,
+        productClauses
+      )
     });
   }
   const declaredPricing = storyboard.fixture_resolution?.pricing_options ?? [];
@@ -288,17 +483,24 @@ function buildFixtureResolutionSpecs(storyboard) {
     const handle = fixture.pricing_option_id;
     if (typeof parent !== "string" || !parent || typeof handle !== "string" || !handle) continue;
     const { product_id: _parent, pricing_option_id: _handle, ...requirementFixture } = fixture;
+    const pricingClauses = normalizeFixtureMatchExpression(
+      declaration?.match,
+      `fixture_resolution.pricing_options.${parent}/${handle}.match`
+    );
     specs.push({
       entityType: "product_pricing_option",
       handle,
       parentProductHandle: parent,
       fixture: requirementFixture,
       strategies: [...declaration?.strategies ?? ["seed"]],
-      clauses: normalizeFixtureMatchExpression(
-        declaration?.match,
-        `fixture_resolution.pricing_options.${parent}/${handle}.match`
-      ),
-      allowReuse: declaration?.allow_reuse === true
+      clauses: pricingClauses,
+      allowReuse: declaration?.allow_reuse === true,
+      contextOutputs: normalizeFixtureContextOutputs(
+        declaration?.context_outputs,
+        `fixture_resolution.pricing_options.${parent}/${handle}.context_outputs`,
+        pricingClauses,
+        "pricing_option"
+      )
     });
   }
   return specs;
@@ -417,7 +619,9 @@ function applyFixtureBindingsToRequest(request, toolName, bindings, version = im
   FixtureBindingRegistry,
   applyFixtureBindingsToRequest,
   buildFixtureResolutionSpecs,
+  matchFixtureRequirementsWithWitness,
   matchesFixtureRequirements,
+  normalizeFixtureContextOutputs,
   normalizeFixtureMatchExpression,
   validateFixtureResolutionDeclarations
 });

package/dist/lib/testing/storyboard/fixture-resolution.mjs

@@ -2,8 +2,22 @@ import { isDeepStrictEqual } from "node:util";
 import { ADCP_VERSION } from "../../version.mjs";
 import { getRequestSchemaEntityPaths } from "../../validation/schema-loader.mjs";
 import { productCanonicalFormatSatisfies } from "./canonical-format-satisfaction.mjs";
-const OPERATORS = ["equals", "present", "contains_all", "any_match", "canonical_format_satisfies"];
-const DECLARATION_KEYS = /* @__PURE__ */ new Set(["handle", "strategies", "match", "allow_reuse"]);
+import {
+  COLLECTION_WITNESS_KINDS,
+  evaluateCollectionSelection,
+  normalizeCollectionSelectionSelector
+} from "./collection-selection.mjs";
+import { parsePath } from "./path.mjs";
+import { assertWellFormedProtectedKey, isProtectedContextKey } from "./protected-context.mjs";
+const OPERATORS = [
+  "equals",
+  "present",
+  "contains_all",
+  "any_match",
+  "canonical_format_satisfies",
+  "collection_selection_satisfies"
+];
+const DECLARATION_KEYS = /* @__PURE__ */ new Set(["handle", "strategies", "match", "allow_reuse", "context_outputs"]);
 const PRICING_DECLARATION_KEYS = /* @__PURE__ */ new Set([...DECLARATION_KEYS, "product_handle"]);
 function isRecord(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -75,6 +89,12 @@ function normalizeClause(value, location) {
         operator,
         where: normalizeFixtureMatchExpression(value.where, `${location}.where`)
       };
+    case "collection_selection_satisfies":
+      return {
+        path: value.path,
+        operator,
+        value: normalizeCollectionSelectionSelector(value.value, `${location}.value`)
+      };
     case "canonical_format_satisfies":
       assertPlainObject(value.value, `${location}.value`);
       if (typeof value.value.format_kind !== "string" || value.value.format_kind.length === 0) {
@@ -86,7 +106,7 @@ function normalizeClause(value, location) {
       return { path: value.path, operator, value: value.value };
   }
 }
-function validateDeclaration(declaration, location, allowedKeys) {
+function validateDeclaration(declaration, location, allowedKeys, entityKind = "product") {
   assertPlainObject(declaration, location);
   const unknown = Object.keys(declaration).filter((key) => !allowedKeys.has(key));
   if (unknown.length > 0) throw new Error(`${location}: unknown key(s): ${unknown.join(", ")}`);
@@ -114,10 +134,87 @@ function validateDeclaration(declaration, location, allowedKeys) {
   if (Array.isArray(declaration.strategies) && declaration.strategies.includes("discover") && clauses.length === 0) {
     throw new Error(`${location}.match: discover strategy requires at least one authored predicate`);
   }
+  normalizeFixtureContextOutputs(declaration.context_outputs, `${location}.context_outputs`, clauses, entityKind);
+}
+const FIXTURE_CONTEXT_OUTPUT_KEYS = /* @__PURE__ */ new Set(["key", "path", "witness", "snapshot"]);
+function normalizeFixtureContextOutputs(value, location, clauses, entityKind = "product") {
+  if (value === void 0) return [];
+  assertArray(value, location);
+  if (value.length === 0) throw new Error(`${location}: must contain at least one capture when present`);
+  const hasCollectionPredicate = clauses.some((clause) => clause.operator === "collection_selection_satisfies");
+  const seen = /* @__PURE__ */ new Set();
+  return value.map((raw, index) => {
+    const entryLocation = `${location}[${index}]`;
+    assertPlainObject(raw, entryLocation);
+    const unknown = Object.keys(raw).filter((key) => !FIXTURE_CONTEXT_OUTPUT_KEYS.has(key));
+    if (unknown.length > 0) {
+      throw new Error(`${entryLocation}: unknown key(s): ${unknown.join(", ")}`);
+    }
+    if (typeof raw.key !== "string" || raw.key.length === 0) {
+      throw new Error(`${entryLocation}.key: must be a non-empty string`);
+    }
+    if (!isProtectedContextKey(raw.key)) {
+      throw new Error(
+        `${entryLocation}.key: fixture captures must use the reserved "__adcp_fixture_" prefix so later steps, caller context and seller responses cannot replace them; received "${raw.key}"`
+      );
+    }
+    assertWellFormedProtectedKey(raw.key, entryLocation + ".key");
+    if (seen.has(raw.key)) throw new Error(`${entryLocation}.key: duplicate capture key "${raw.key}"`);
+    seen.add(raw.key);
+    const forms = ["path", "witness", "snapshot"].filter((form) => Object.hasOwn(raw, form));
+    if (forms.length !== 1) {
+      throw new Error(
+        `${entryLocation}: must set exactly one of 'path', 'witness' or 'snapshot'; received ${forms.length === 0 ? "none" : forms.join(" + ")}`
+      );
+    }
+    const hasPath = forms[0] === "path";
+    if (forms[0] === "snapshot") {
+      if (raw.snapshot !== "selected_entity") {
+        throw new Error(`${entryLocation}.snapshot: must be 'selected_entity'`);
+      }
+      return { key: raw.key, snapshot: "selected_entity" };
+    }
+    if (hasPath) {
+      if (typeof raw.path !== "string" || raw.path.length === 0) {
+        throw new Error(`${entryLocation}.path: must be a non-empty string`);
+      }
+      if (raw.path.startsWith("/")) {
+        throw new Error(
+          `${entryLocation}.path: capture paths use the dotted storyboard grammar ("currency", "pricing_options[0].rate"), not the RFC 6901 pointers that match[].path takes; drop the leading "/" \u2014 received "${raw.path}"`
+        );
+      }
+      if (parsePath(raw.path).length === 0) {
+        throw new Error(
+          `${entryLocation}.path: must name at least one field in the dotted storyboard grammar ("currency", "pricing_options[0].rate") \u2014 received "${raw.path}", which resolves to the whole selected entity. To capture the whole entity, say so: snapshot: 'selected_entity'.`
+        );
+      }
+      if (raw.path.split(".").some((segment) => segment.length === 0)) {
+        throw new Error(`${entryLocation}.path: every dotted segment must name a field \u2014 received "${raw.path}".`);
+      }
+      return { key: raw.key, path: raw.path };
+    }
+    if (typeof raw.witness !== "string" || !COLLECTION_WITNESS_KINDS.includes(raw.witness)) {
+      throw new Error(`${entryLocation}.witness: must be one of ${COLLECTION_WITNESS_KINDS.join(", ")}`);
+    }
+    if (entityKind === "pricing_option") {
+      throw new Error(
+        `${entryLocation}.witness: a collection witness describes the product, not one of its pricing options; declare it under fixture_resolution.products.<product_handle>.context_outputs instead`
+      );
+    }
+    if (!hasCollectionPredicate) {
+      throw new Error(
+        `${entryLocation}.witness: requires a collection_selection_satisfies predicate on the same declaration`
+      );
+    }
+    return { key: raw.key, witness: raw.witness };
+  });
 }
 function validateFixtureResolutionDeclarations(storyboard) {
   const root = storyboard.fixture_resolution;
-  if (root === void 0) return;
+  if (root === void 0) {
+    assertNoReservedOrdinaryKeys(storyboard);
+    return;
+  }
   assertPlainObject(root, `[${storyboard.id}] fixture_resolution`);
   const unknownRoot = Object.keys(root).filter((key) => key !== "products" && key !== "pricing_options");
   if (unknownRoot.length > 0) {
@@ -167,7 +264,7 @@ function validateFixtureResolutionDeclarations(storyboard) {
     for (let index = 0; index < root.pricing_options.length; index++) {
       const declaration = root.pricing_options[index];
       const location = `[${storyboard.id}] fixture_resolution.pricing_options[${index}]`;
-      validateDeclaration(declaration, location, PRICING_DECLARATION_KEYS);
+      validateDeclaration(declaration, location, PRICING_DECLARATION_KEYS, "pricing_option");
       const typedDeclaration = declaration;
       if (typeof typedDeclaration.product_handle !== "string" || typedDeclaration.product_handle.length === 0) {
         throw new Error(`${location}.product_handle: must be a non-empty string`);
@@ -184,6 +281,68 @@ function validateFixtureResolutionDeclarations(storyboard) {
       }
     }
   }
+  assertNoReservedOrdinaryKeys(storyboard);
+  assertUniqueFixtureCaptureKeys(storyboard);
+}
+function assertNoReservedOrdinaryKeys(storyboard) {
+  const reject = (key, location) => {
+    if (isProtectedContextKey(key)) {
+      throw new Error(
+        `${location}: "${key}" uses the reserved "__adcp_fixture_" prefix, which is owned by fixture preparation. Rename it to any key not starting with "__adcp_fixture_".`
+      );
+    }
+    if (key === "__proto__" || key === "constructor" || key === "prototype") {
+      throw new Error(
+        `${location}: "${key}" is a prototype-sensitive context key and cannot be used; rename it to anything other than __proto__, constructor or prototype`
+      );
+    }
+  };
+  for (const key of Object.keys(storyboard.context ?? {})) {
+    reject(key, `[${storyboard.id}] context`);
+  }
+  for (const phase of storyboard.phases ?? []) {
+    for (const step of phase.steps ?? []) {
+      for (const output of step.context_outputs ?? []) {
+        if (typeof output.key !== "string") continue;
+        if (isProtectedContextKey(output.key)) {
+          throw new Error(
+            `[${storyboard.id}] phase '${phase.id}' step '${step.id}': context_outputs entry "${output.key}" uses the reserved "__adcp_fixture_" prefix; step captures cannot write fixture-preparation state. Declare it under fixture_resolution instead, or rename the key.`
+          );
+        }
+        reject(output.key, `[${storyboard.id}] phase '${phase.id}' step '${step.id}' context_outputs`);
+      }
+      const gates = step.not_applicable_if;
+      for (const gate of gates === void 0 ? [] : Array.isArray(gates) ? gates : [gates]) {
+        for (const key of gate.context_keys ?? []) {
+          if (typeof key === "string") {
+            reject(key, `[${storyboard.id}] phase '${phase.id}' step '${step.id}' not_applicable_if.context_keys`);
+          }
+        }
+      }
+    }
+  }
+}
+function assertUniqueFixtureCaptureKeys(storyboard) {
+  const owners = /* @__PURE__ */ new Map();
+  const claim = (key, owner) => {
+    const existing = owners.get(key);
+    if (existing !== void 0) {
+      throw new Error(
+        `[${storyboard.id}] fixture_resolution: capture key "${key}" is declared by both ${existing} and ${owner}`
+      );
+    }
+    owners.set(key, owner);
+  };
+  for (const declaration of storyboard.fixture_resolution?.products ?? []) {
+    for (const output of declaration.context_outputs ?? []) {
+      claim(output.key, `products."${declaration.handle}"`);
+    }
+  }
+  for (const declaration of storyboard.fixture_resolution?.pricing_options ?? []) {
+    for (const output of declaration.context_outputs ?? []) {
+      claim(output.key, `pricing_options."${declaration.product_handle}/${declaration.handle}"`);
+    }
+  }
 }
 function resolveCandidatePath(candidate, pointer) {
   let current = candidate;
@@ -207,9 +366,38 @@ function matchesFixtureRequirements(candidate, clauses) {
         return Array.isArray(actual) && actual.some((value) => matchesFixtureRequirements(value, clause.where ?? []));
       case "canonical_format_satisfies":
         return productCanonicalFormatSatisfies(actual, clause.value);
+      case "collection_selection_satisfies":
+        return evaluateCollectionSelection(actual, clause.value).eligible;
     }
   });
 }
+function matchFixtureRequirementsWithWitness(candidate, clauses) {
+  let witness;
+  let matched = true;
+  let reason;
+  for (const clause of clauses) {
+    if (clause.operator !== "collection_selection_satisfies") {
+      if (matched && !matchesFixtureRequirements(candidate, [clause])) {
+        matched = false;
+        reason = `${clause.operator} at "${clause.path || "(whole candidate)"}" did not match`;
+      }
+      continue;
+    }
+    const actual = resolveCandidatePath(candidate, clause.path);
+    const evaluation = evaluateCollectionSelection(actual, clause.value);
+    if (!evaluation.eligible) {
+      if (matched) reason = evaluation.reason;
+      matched = false;
+      continue;
+    }
+    witness = evaluation.witness;
+  }
+  return {
+    matched,
+    ...witness && { witness },
+    ...reason !== void 0 && { reason }
+  };
+}
 function buildFixtureResolutionSpecs(storyboard) {
   const specs = [];
   const productFixtures = new Map(
@@ -232,13 +420,22 @@ function buildFixtureResolutionSpecs(storyboard) {
     if (!fixture) continue;
     if (typeof fixture.product_id !== "string" || fixture.product_id.length === 0) continue;
     const { product_id: handle, ...requirementFixture } = fixture;
+    const productClauses = normalizeFixtureMatchExpression(
+      declaration?.match,
+      `fixture_resolution.products.${handle}.match`
+    );
     specs.push({
       entityType: "product",
       handle,
       fixture: requirementFixture,
       strategies: [...declaration?.strategies ?? ["seed"]],
-      clauses: normalizeFixtureMatchExpression(declaration?.match, `fixture_resolution.products.${handle}.match`),
-      allowReuse: declaration?.allow_reuse === true
+      clauses: productClauses,
+      allowReuse: declaration?.allow_reuse === true,
+      contextOutputs: normalizeFixtureContextOutputs(
+        declaration?.context_outputs,
+        `fixture_resolution.products.${handle}.context_outputs`,
+        productClauses
+      )
     });
   }
   const declaredPricing = storyboard.fixture_resolution?.pricing_options ?? [];
@@ -260,17 +457,24 @@ function buildFixtureResolutionSpecs(storyboard) {
     const handle = fixture.pricing_option_id;
     if (typeof parent !== "string" || !parent || typeof handle !== "string" || !handle) continue;
     const { product_id: _parent, pricing_option_id: _handle, ...requirementFixture } = fixture;
+    const pricingClauses = normalizeFixtureMatchExpression(
+      declaration?.match,
+      `fixture_resolution.pricing_options.${parent}/${handle}.match`
+    );
     specs.push({
       entityType: "product_pricing_option",
       handle,
       parentProductHandle: parent,
       fixture: requirementFixture,
       strategies: [...declaration?.strategies ?? ["seed"]],
-      clauses: normalizeFixtureMatchExpression(
-        declaration?.match,
-        `fixture_resolution.pricing_options.${parent}/${handle}.match`
-      ),
-      allowReuse: declaration?.allow_reuse === true
+      clauses: pricingClauses,
+      allowReuse: declaration?.allow_reuse === true,
+      contextOutputs: normalizeFixtureContextOutputs(
+        declaration?.context_outputs,
+        `fixture_resolution.pricing_options.${parent}/${handle}.context_outputs`,
+        pricingClauses,
+        "pricing_option"
+      )
     });
   }
   return specs;
@@ -388,7 +592,9 @@ export {
   FixtureBindingRegistry,
   applyFixtureBindingsToRequest,
   buildFixtureResolutionSpecs,
+  matchFixtureRequirementsWithWitness,
   matchesFixtureRequirements,
+  normalizeFixtureContextOutputs,
   normalizeFixtureMatchExpression,
   validateFixtureResolutionDeclarations
 };

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

@@ -16,9 +16,16 @@ export type { CapturedWebhook, CapturedWebhookChallenge, CreateWebhookReceiverOp
 export { createRunnerVariables } from './context.mjs';
 export type { RunnerVariables } from './context.mjs';
 export { WEBHOOK_ASSERTION_TASKS } from './webhook-assertions.mjs';
-export { runStoryboard, runStoryboardStep, applyAdcpVersionRunOptions, applyStoryboardVersionOptions, getFirstStepPreview, summarizeStrictValidation, listStrictOnlyFailures, resolveCapabilityPath, evaluateCapabilityPredicate, describeStoryboardCapabilityGates, buildDiscoveryFailedResult, } from './runner.mjs';
+export { prepareStoryboardFixtures, runStoryboard, runStoryboardStep, applyAdcpVersionRunOptions, applyStoryboardVersionOptions, getFirstStepPreview, summarizeStrictValidation, listStrictOnlyFailures, resolveCapabilityPath, evaluateCapabilityPredicate, describeStoryboardCapabilityGates, buildDiscoveryFailedResult, } from './runner.mjs';
 export { parseStoryboard, loadStoryboardFile, normalizeValidationOnlyTasks, VALIDATION_ONLY_TASK } from './loader.mjs';
-export { applyFixtureBindingsToRequest, buildFixtureResolutionSpecs, FixtureBindingRegistry, matchesFixtureRequirements, normalizeFixtureMatchExpression, validateFixtureResolutionDeclarations, } from './fixture-resolution.mjs';
+export { applyFixtureBindingsToRequest, buildFixtureResolutionSpecs, FixtureBindingRegistry, matchesFixtureRequirements, matchFixtureRequirementsWithWitness, normalizeFixtureContextOutputs, normalizeFixtureMatchExpression, validateFixtureResolutionDeclarations, } from './fixture-resolution.mjs';
+export type { FixtureContextOutput } from './types.mjs';
+export { COLLECTION_DIAGNOSTIC_LIMIT, COLLECTION_PAIR_LIMIT, COLLECTION_TARGETING_MODES, COLLECTION_WITNESS_KINDS, compareCollectionPairs, diffCollectionPairSets, evaluateCollectionSelection, formatCollectionPair, normalizeCollectionSelectionSelector, normalizeCollectionSelectors, productSatisfiesCollectionSelection, readCollectionWitness, summarizeCollectionPairs, } from './collection-selection.mjs';
+export type { ResolvedCollectionSelectionSelector, CollectionNormalizationCode, CollectionNormalizationFailure, CollectionNormalizationResult, CrossPublisherCollectionRelation, CollectionPair, CollectionSelectionEvaluation, CollectionSelectionSelector, CollectionSelectionWitness, CollectionSelectorObject, CollectionWitnessKind, CollectionWitnessReadResult, NormalizedCollectionSelectors, } from './collection-selection.mjs';
+export { isProtectedContextKey, PROTECTED_CONTEXT_PREFIX, ProtectedContextViolation } from './protected-context.mjs';
+export type { ProtectedContextViolationCode } from './protected-context.mjs';
+export { isTrustedPreparedFixtures, PREPARED_FIXTURES_CONTRACT_VERSION, PreparedStoryboardFixtures, withPreparedFixtures, } from './prepared-fixtures.mjs';
+export type { PreparedFixtureBinding, PreparedFixtureSelection, PreparedFixturesAuthorizer, PreparedFixturesDecision, PreparedFixturesDisposition, PreparedFixturesLookup, PreparedFixturesRefusal, PreparedFixturesRefusalCode, PreparedFixturesReference, PreparedSchemaArtifact, } from './prepared-fixtures.mjs';
 export { getComplianceCacheDir, getExternalSchemaRootForCompliance, loadComplianceIndex, listBundles, loadBundleStoryboards, listAllComplianceStoryboards, getComplianceStoryboardById, findBundleById, resolveBundleOrStoryboard, resolveStoryboardsForCapabilities, isComplianceVersionSupported, loadSpecialismDetail, listSpecialisms, CapabilityResolutionError, PROTOCOL_TO_PATH, UNBASELINED_SUPPORTED_PROTOCOLS, } from './compliance.mjs';
 export type { AgentCapabilities, BundleKind, BundleRef, CapabilityResolutionCode, ComplianceIndex, ComplianceIndexProtocol, ComplianceIndexSpecialism, NotApplicableStoryboard, ResolveOptions, ResolvedBundle, ResolvedStoryboards, SpecialismDetail, } from './compliance.mjs';
 export { TASK_TO_METHOD, executeStoryboardTask } from './task-map.mjs';