@adcp/sdk 16.2.0 → 16.4.0

package/dist/lib/testing/storyboard/collection-selection.mjs

@@ -0,0 +1,348 @@
+const PAIR_LIMIT_DEFAULT = 1e4;
+const COLLECTION_PAIR_LIMIT = PAIR_LIMIT_DEFAULT;
+const COLLECTION_DIAGNOSTIC_LIMIT = 20;
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function utf8Compare(a, b) {
+  return Buffer.compare(Buffer.from(a, "utf8"), Buffer.from(b, "utf8"));
+}
+function compareCollectionPairs(a, b) {
+  const domain = utf8Compare(a.publisher_domain, b.publisher_domain);
+  if (domain !== 0) return domain;
+  if (a.collection_id === b.collection_id) return 0;
+  if (a.collection_id === null) return -1;
+  if (b.collection_id === null) return 1;
+  return utf8Compare(a.collection_id, b.collection_id);
+}
+function formatCollectionPair(pair) {
+  return pair.collection_id === null ? `${JSON.stringify(pair.publisher_domain)}:*` : `${JSON.stringify(pair.publisher_domain)}:${JSON.stringify(pair.collection_id)}`;
+}
+function pairKey(pair) {
+  return pair.collection_id === null ? `${JSON.stringify(pair.publisher_domain)}\0` : `${JSON.stringify(pair.publisher_domain)}\0${JSON.stringify(pair.collection_id)}`;
+}
+function normalizeCollectionSelectors(value, options = {}) {
+  const limit = options.limit ?? PAIR_LIMIT_DEFAULT;
+  if (!Array.isArray(value)) {
+    return {
+      ok: false,
+      failure: {
+        code: "not_an_array",
+        detail: `expected an array of collection selectors; received ${describe(value)}`
+      }
+    };
+  }
+  const seen = /* @__PURE__ */ new Map();
+  for (let index = 0; index < value.length; index++) {
+    const selector = value[index];
+    if (!isRecord(selector)) {
+      return {
+        ok: false,
+        failure: {
+          code: "selector_not_object",
+          detail: `collections[${index}] must be an object; received ${describe(selector)}`
+        }
+      };
+    }
+    const domain = selector.publisher_domain;
+    if (typeof domain !== "string" || domain.length === 0) {
+      return {
+        ok: false,
+        failure: {
+          code: "publisher_domain_invalid",
+          detail: `collections[${index}].publisher_domain must be a non-empty string; received ${describe(domain)}`
+        }
+      };
+    }
+    const ids = selector.collection_ids;
+    if (ids === void 0 || ids === null) {
+      addPair(seen, { publisher_domain: domain, collection_id: null });
+    } else {
+      if (!Array.isArray(ids) || ids.length === 0) {
+        return {
+          ok: false,
+          failure: {
+            code: "collection_ids_invalid",
+            detail: `collections[${index}].collection_ids must be a non-empty array when present; received ${describe(ids)}`
+          }
+        };
+      }
+      for (let idIndex = 0; idIndex < ids.length; idIndex++) {
+        const id = ids[idIndex];
+        if (typeof id !== "string") {
+          return {
+            ok: false,
+            failure: {
+              code: "collection_id_invalid",
+              detail: `collections[${index}].collection_ids[${idIndex}] must be a string; received ${describe(id)}`
+            }
+          };
+        }
+        addPair(seen, { publisher_domain: domain, collection_id: id });
+        if (seen.size > limit) return pairLimitExceeded(limit, index);
+      }
+    }
+    if (seen.size > limit) return pairLimitExceeded(limit, index);
+  }
+  const pairs = [...seen.values()].sort(compareCollectionPairs);
+  const domains = [...new Set(pairs.map((pair) => pair.publisher_domain))].sort(utf8Compare);
+  return { ok: true, value: { pairs, selector_count: value.length, domains } };
+}
+function pairLimitExceeded(limit, index) {
+  return {
+    ok: false,
+    failure: {
+      code: "pair_limit_exceeded",
+      detail: `normalized collection pairs exceeded the ${limit}-pair safety limit at collections[${index}]`
+    }
+  };
+}
+function addPair(seen, pair) {
+  const key = pairKey(pair);
+  if (!seen.has(key)) seen.set(key, pair);
+}
+function describe(value) {
+  if (value === void 0) return "undefined";
+  if (value === null) return "null";
+  if (Array.isArray(value)) return `an array of length ${value.length}`;
+  return typeof value === "object" ? "an object" : JSON.stringify(value);
+}
+function diffCollectionPairSets(actual, expected) {
+  const expectedKeys = new Set(expected.map(pairKey));
+  const actualKeys = new Set(actual.map(pairKey));
+  const missing = expected.filter((pair) => !actualKeys.has(pairKey(pair)));
+  const unexpected = actual.filter((pair) => !expectedKeys.has(pairKey(pair)));
+  return { equal: missing.length === 0 && unexpected.length === 0, missing, unexpected };
+}
+function summarizeCollectionPairs(pairs) {
+  const shown = pairs.slice(0, COLLECTION_DIAGNOSTIC_LIMIT).map(formatCollectionPair);
+  const elided = pairs.length - shown.length;
+  return elided > 0 ? `${shown.join(", ")} (+${elided} more)` : shown.join(", ");
+}
+const COLLECTION_TARGETING_MODES = ["selectable", "fixed", "any"];
+function normalizeCollectionSelectionSelector(value, location) {
+  if (!isRecord(value)) throw new Error(`${location}: must be an object`);
+  const unknown = Object.keys(value).filter(
+    (key) => !["collection_targeting", "minimum_pairs", "require_cross_publisher_collection"].includes(key)
+  );
+  if (unknown.length > 0) {
+    throw new Error(`${location}: unknown key(s): ${unknown.join(", ")}; the operand is closed`);
+  }
+  const targeting = value.collection_targeting;
+  if (typeof targeting !== "string" || !COLLECTION_TARGETING_MODES.includes(targeting)) {
+    throw new Error(`${location}.collection_targeting: must be one of ${COLLECTION_TARGETING_MODES.join(", ")}`);
+  }
+  let minimumPairs = 1;
+  if (value.minimum_pairs !== void 0) {
+    if (value.minimum_pairs !== 1 && value.minimum_pairs !== 2) {
+      throw new Error(`${location}.minimum_pairs: must be 1 or 2`);
+    }
+    minimumPairs = value.minimum_pairs;
+  }
+  if (value.require_cross_publisher_collection !== void 0 && typeof value.require_cross_publisher_collection !== "boolean") {
+    throw new Error(`${location}.require_cross_publisher_collection: must be boolean`);
+  }
+  return {
+    collection_targeting: targeting,
+    minimum_pairs: minimumPairs,
+    require_cross_publisher_collection: value.require_cross_publisher_collection === true
+  };
+}
+function collectHostDomains(candidate) {
+  const domains = /* @__PURE__ */ new Set();
+  const properties = candidate.publisher_properties;
+  if (Array.isArray(properties)) {
+    for (const entry of properties) {
+      if (!isRecord(entry)) continue;
+      if (typeof entry.publisher_domain === "string" && entry.publisher_domain.length > 0) {
+        domains.add(entry.publisher_domain);
+      }
+    }
+  }
+  return [...domains].sort(utf8Compare);
+}
+function cloneSelectorBundle(value) {
+  return value.map((selector) => ({
+    publisher_domain: selector.publisher_domain,
+    ...Array.isArray(selector.collection_ids) && { collection_ids: [...selector.collection_ids] }
+  }));
+}
+function buildUndeclaredCollectionIdSelectors(domain, pairs) {
+  const taken = new Set(pairs.filter((pair) => pair.publisher_domain === domain).map((pair) => pair.collection_id));
+  let candidate = "adcp-absent-collection";
+  for (let suffix = 0; taken.has(candidate); suffix++) {
+    candidate = `adcp-absent-collection-${suffix}`;
+  }
+  return [{ publisher_domain: domain, collection_ids: [candidate] }];
+}
+function buildUndeclaredPublisherDomainSelectors(domains, collectionId) {
+  let candidate = "adcp-absent-owner.invalid";
+  for (let suffix = 0; domains.has(candidate); suffix++) {
+    candidate = `adcp-absent-owner-${suffix}.invalid`;
+  }
+  return [{ publisher_domain: candidate, collection_ids: [collectionId] }];
+}
+function evaluateCollectionSelection(candidate, selector) {
+  if (selector !== null && typeof selector === "object" && "declared_selectors" in selector) {
+    throw new Error(
+      'evaluateCollectionSelection: received a CollectionSelectionWitness where a CollectionSelectionSelector was expected. A witness is the OUTPUT of an evaluation, not an operand; build the operand explicitly, e.g. { collection_targeting: "selectable", minimum_pairs: 2 }.'
+    );
+  }
+  const resolved = {
+    collection_targeting: selector.collection_targeting,
+    minimum_pairs: selector.minimum_pairs ?? 1,
+    require_cross_publisher_collection: selector.require_cross_publisher_collection === true
+  };
+  return evaluateResolvedCollectionSelection(candidate, resolved);
+}
+function evaluateResolvedCollectionSelection(candidate, selector) {
+  if (!isRecord(candidate)) return { eligible: false, reason: "candidate is not an object" };
+  const flag = candidate.collection_targeting_allowed;
+  if (flag !== void 0 && typeof flag !== "boolean") {
+    return {
+      eligible: false,
+      reason: `collection_targeting_allowed must be boolean or absent; observed ${describe(flag)}`
+    };
+  }
+  const effectiveTargeting = flag === true ? "selectable" : "fixed";
+  if (selector.collection_targeting !== "any" && selector.collection_targeting !== effectiveTargeting) {
+    return {
+      eligible: false,
+      reason: selector.collection_targeting === "fixed" ? "collection_targeting_allowed is true; a fixed bundle requires literal false or absence" : "collection_targeting_allowed is not literal true"
+    };
+  }
+  const normalized = normalizeCollectionSelectors(candidate.collections);
+  if (!normalized.ok) {
+    return { eligible: false, reason: `collections did not normalize: ${normalized.failure.detail}` };
+  }
+  if (normalized.value.pairs.some((pair) => pair.collection_id === null)) {
+    return {
+      eligible: false,
+      reason: "product collections contain a domain-only bulk-grant selector; product composition requires explicit collection_ids on every entry"
+    };
+  }
+  const concrete = normalized.value.pairs;
+  if (concrete.length < selector.minimum_pairs) {
+    return {
+      eligible: false,
+      reason: `product exposes ${concrete.length} distinct concrete collection pair(s); ${selector.minimum_pairs} required`
+    };
+  }
+  const hostDomains = collectHostDomains(candidate);
+  const bundle = cloneSelectorBundle(candidate.collections);
+  let relation = null;
+  if (selector.require_cross_publisher_collection) {
+    const hostSet = new Set(hostDomains);
+    const externalDomain = normalized.value.domains.find((domain) => !hostSet.has(domain));
+    if (externalDomain === void 0) {
+      return {
+        eligible: false,
+        reason: hostDomains.length === 0 ? "product declares no publisher_properties domains, so no owner/host relation is observable" : "every collection namespace is also a declared property namespace"
+      };
+    }
+    const carrying = bundle.filter((entry) => entry.publisher_domain === externalDomain).sort((left, right) => {
+      const l = JSON.stringify([...left.collection_ids ?? []].sort());
+      const r = JSON.stringify([...right.collection_ids ?? []].sort());
+      return l < r ? -1 : l > r ? 1 : 0;
+    })[0];
+    relation = {
+      collection_publisher_domain: externalDomain,
+      property_publisher_domains: hostDomains,
+      selector: {
+        ...carrying,
+        ...carrying.collection_ids && { collection_ids: [...carrying.collection_ids] }
+      }
+    };
+  }
+  const subsetSource = relation === null ? concrete[0] : (
+    // Non-null is sound, not optimism: `relation.collection_publisher_domain`
+    // is taken from `normalized.value.domains`, which is derived from
+    // `concrete`, so the domain is present by construction. The previous
+    // `?? concrete[0]` read as a carriage-vs-local fallback and was not
+    // one — it could only ever have masked a normalizer bug.
+    concrete.find((pair) => pair.publisher_domain === relation.collection_publisher_domain)
+  );
+  const strictSubset = concrete.length >= 2 ? [{ publisher_domain: subsetSource.publisher_domain, collection_ids: [subsetSource.collection_id] }] : null;
+  const witness = {
+    product_id: typeof candidate.product_id === "string" ? candidate.product_id : null,
+    collection_targeting: effectiveTargeting,
+    collection_targeting_allowed: flag,
+    declared_selectors: bundle,
+    distinct_pairs: concrete,
+    strict_subset: strictSubset,
+    undeclared_collection_id_selectors: buildUndeclaredCollectionIdSelectors(
+      subsetSource.publisher_domain,
+      normalized.value.pairs
+    ),
+    undeclared_publisher_domain_selectors: buildUndeclaredPublisherDomainSelectors(
+      new Set(normalized.value.domains),
+      subsetSource.collection_id
+    ),
+    cross_publisher_relation: relation,
+    property_publisher_domains: hostDomains
+  };
+  return { eligible: true, witness };
+}
+function productSatisfiesCollectionSelection(candidate, selector) {
+  return evaluateCollectionSelection(candidate, selector).eligible;
+}
+const COLLECTION_WITNESS_KINDS = [
+  "declared_selectors",
+  "distinct_pairs",
+  "strict_subset",
+  "undeclared_collection_id_selectors",
+  "undeclared_publisher_domain_selectors",
+  "cross_publisher_relation",
+  "property_publisher_domains"
+];
+function readCollectionWitness(witness, kind) {
+  if (!witness) {
+    return {
+      ok: false,
+      detail: `witness capture "${kind}" requires a collection_selection_satisfies predicate on the same declaration`
+    };
+  }
+  switch (kind) {
+    case "declared_selectors":
+      return { ok: true, value: witness.declared_selectors };
+    case "distinct_pairs":
+      return { ok: true, value: witness.distinct_pairs };
+    case "strict_subset":
+      if (witness.strict_subset === null) {
+        return {
+          ok: false,
+          detail: "strict_subset requires a product with at least two distinct concrete collection pairs; declare minimum_pairs: 2"
+        };
+      }
+      return { ok: true, value: witness.strict_subset };
+    case "undeclared_collection_id_selectors":
+      return { ok: true, value: witness.undeclared_collection_id_selectors };
+    case "undeclared_publisher_domain_selectors":
+      return { ok: true, value: witness.undeclared_publisher_domain_selectors };
+    case "cross_publisher_relation":
+      if (witness.cross_publisher_relation === null) {
+        return {
+          ok: false,
+          detail: "cross_publisher_relation requires require_cross_publisher_collection: true on the collection_selection_satisfies operand"
+        };
+      }
+      return { ok: true, value: witness.cross_publisher_relation };
+    case "property_publisher_domains":
+      return { ok: true, value: witness.property_publisher_domains };
+  }
+}
+export {
+  COLLECTION_DIAGNOSTIC_LIMIT,
+  COLLECTION_PAIR_LIMIT,
+  COLLECTION_TARGETING_MODES,
+  COLLECTION_WITNESS_KINDS,
+  compareCollectionPairs,
+  diffCollectionPairSets,
+  evaluateCollectionSelection,
+  formatCollectionPair,
+  normalizeCollectionSelectionSelector,
+  normalizeCollectionSelectors,
+  productSatisfiesCollectionSelection,
+  readCollectionWitness,
+  summarizeCollectionPairs
+};

package/dist/lib/testing/storyboard/context.js

@@ -32,6 +32,7 @@ __export(context_exports, {
 module.exports = __toCommonJS(context_exports);
 var import_node_crypto = require("node:crypto");
 var import_path = require('./path.js');
+var import_protected_context = require('./protected-context.js');
 var import_media_buy_status = require('../../utils/media-buy-status.js');
 var import_path2 = require('./path.js');
 const PRODUCT_CONTEXT_KEYS = [
@@ -393,7 +394,7 @@ const aliasCaches = /* @__PURE__ */ new WeakMap();
 function getAliasCache(context) {
   let cache = aliasCaches.get(context);
   if (!cache) {
-    cache = {};
+    cache = /* @__PURE__ */ Object.create(null);
     aliasCaches.set(context, cache);
   }
   return cache;
@@ -419,14 +420,15 @@ function deepReplace(value, context, runnerVars) {
     const ctxMatch = expanded.match(/^\$context\.(\w+)$/);
     if (ctxMatch?.[1]) {
       const key = ctxMatch[1];
-      return key in context ? context[key] : expanded;
+      if (!Object.hasOwn(context, key)) return expanded;
+      return (0, import_protected_context.isProtectedContextKey)(key) ? (0, import_protected_context.detachProtectedValue)(context[key]) : context[key];
     }
     const genMatch = expanded.match(/^\$generate:(uuid_v4|opaque_id)(?:#([A-Za-z0-9_.-]+))?$/);
     if (genMatch) {
       const alias = genMatch[2];
       if (alias) {
         const cache = getAliasCache(context);
-        if (!(alias in cache)) cache[alias] = (0, import_node_crypto.randomUUID)();
+        if (!Object.hasOwn(cache, alias)) cache[alias] = (0, import_node_crypto.randomUUID)();
         return cache[alias];
       }
       return (0, import_node_crypto.randomUUID)();
@@ -521,7 +523,7 @@ function applyContextOutputsWithProvenance(data, outputs, stepId, taskName, cont
       }
       const cache = getAliasCache(context);
       let value;
-      if (output.key in cache) {
+      if (Object.hasOwn(cache, output.key)) {
         value = cache[output.key];
       } else {
         value = (0, import_node_crypto.randomUUID)();
@@ -558,8 +560,12 @@ function applyContextOutputsWithProvenance(data, outputs, stepId, taskName, cont
 function applyContextInputs(request, inputs, context) {
   const result = structuredClone(request);
   for (const input of inputs) {
-    if (input.key in context) {
-      (0, import_path.setPath)(result, input.inject_at, context[input.key]);
+    if (Object.hasOwn(context, input.key)) {
+      (0, import_path.setPath)(
+        result,
+        input.inject_at,
+        (0, import_protected_context.isProtectedContextKey)(input.key) ? (0, import_protected_context.detachProtectedValue)(context[input.key]) : context[input.key]
+      );
     }
   }
   return result;

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

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { resolvePath, setPath } from "./path.mjs";
+import { detachProtectedValue, isProtectedContextKey } from "./protected-context.mjs";
 import { getAuthoritativeMediaBuyStatus } from "../../utils/media-buy-status.mjs";
 const PRODUCT_CONTEXT_KEYS = [
   "product",
@@ -360,7 +361,7 @@ const aliasCaches = /* @__PURE__ */ new WeakMap();
 function getAliasCache(context) {
   let cache = aliasCaches.get(context);
   if (!cache) {
-    cache = {};
+    cache = /* @__PURE__ */ Object.create(null);
     aliasCaches.set(context, cache);
   }
   return cache;
@@ -386,14 +387,15 @@ function deepReplace(value, context, runnerVars) {
     const ctxMatch = expanded.match(/^\$context\.(\w+)$/);
     if (ctxMatch?.[1]) {
       const key = ctxMatch[1];
-      return key in context ? context[key] : expanded;
+      if (!Object.hasOwn(context, key)) return expanded;
+      return isProtectedContextKey(key) ? detachProtectedValue(context[key]) : context[key];
     }
     const genMatch = expanded.match(/^\$generate:(uuid_v4|opaque_id)(?:#([A-Za-z0-9_.-]+))?$/);
     if (genMatch) {
       const alias = genMatch[2];
       if (alias) {
         const cache = getAliasCache(context);
-        if (!(alias in cache)) cache[alias] = randomUUID();
+        if (!Object.hasOwn(cache, alias)) cache[alias] = randomUUID();
         return cache[alias];
       }
       return randomUUID();
@@ -488,7 +490,7 @@ function applyContextOutputsWithProvenance(data, outputs, stepId, taskName, cont
       }
       const cache = getAliasCache(context);
       let value;
-      if (output.key in cache) {
+      if (Object.hasOwn(cache, output.key)) {
         value = cache[output.key];
       } else {
         value = randomUUID();
@@ -525,8 +527,12 @@ function applyContextOutputsWithProvenance(data, outputs, stepId, taskName, cont
 function applyContextInputs(request, inputs, context) {
   const result = structuredClone(request);
   for (const input of inputs) {
-    if (input.key in context) {
-      setPath(result, input.inject_at, context[input.key]);
+    if (Object.hasOwn(context, input.key)) {
+      setPath(
+        result,
+        input.inject_at,
+        isProtectedContextKey(input.key) ? detachProtectedValue(context[input.key]) : context[input.key]
+      );
     }
   }
   return result;

package/dist/lib/testing/storyboard/fixture-resolution.d.mts

@@ -1,11 +1,47 @@
 import { type SchemaEntityPath } from '../../validation/schema-loader.mjs';
-import type { FixtureMatchClause, FixtureResolutionStrategy, Storyboard } from './types.mjs';
+import { type CollectionSelectionWitness } from './collection-selection.mjs';
+import type { FixtureContextOutput, FixtureMatchClause, FixtureResolutionStrategy, Storyboard } from './types.mjs';
 /** Normalize and validate the closed fixture matching DSL. */
 export declare function normalizeFixtureMatchExpression(expression: unknown, location: string): FixtureMatchClause[];
+/**
+ * Validate the declaration-local capture block.
+ *
+ * A `witness:` entry is only authorable when the same declaration carries a
+ * `collection_selection_satisfies` predicate — the witness is retained from
+ * that evaluation, so asking for one without the predicate is an authoring
+ * error rather than a runtime surprise on an agent that happens to answer
+ * differently.
+ */
+export declare function normalizeFixtureContextOutputs(value: unknown, location: string, clauses: readonly FixtureMatchClause[], 
+/**
+ * `'pricing_option'` refuses `witness:` captures. A collection witness
+ * describes a PRODUCT — its selectors, its pairs, its cross-publisher
+ * relation — and a pricing option has none of its own. Accepting one
+ * here loaded fine and then failed at run with a message about a missing
+ * `collection_selection_satisfies` predicate that was right there in the
+ * declaration, and the two strategies disagreed about it besides (seed
+ * retained the parent's witness, discover did not). Declare the witness
+ * on the parent product.
+ */
+entityKind?: 'product' | 'pricing_option'): FixtureContextOutput[];
 /** Loader/runtime authoring validation for the AdCP 3.2 declaration block. */
 export declare function validateFixtureResolutionDeclarations(storyboard: Storyboard): void;
 /** True when a seller catalog entity satisfies every authored clause. */
 export declare function matchesFixtureRequirements(candidate: unknown, clauses: readonly FixtureMatchClause[]): boolean;
+/**
+ * Match a candidate and retain the collection witness for it.
+ *
+ * The boolean `matchesFixtureRequirements` keeps its signature for existing
+ * callers. This variant exists so the resolver can retain the witness for the
+ * candidate it *actually selects*, rather than recomputing one later from an
+ * unrelated response — which is precisely how a selected-entity snapshot
+ * drifts away from the entity that was purchased.
+ */
+export declare function matchFixtureRequirementsWithWitness(candidate: unknown, clauses: readonly FixtureMatchClause[]): {
+    matched: boolean;
+    witness?: CollectionSelectionWitness;
+    reason?: string;
+};
 export interface FixtureResolutionSpec {
     entityType: 'product' | 'product_pricing_option';
     handle: string;
@@ -14,6 +50,8 @@ export interface FixtureResolutionSpec {
     strategies: FixtureResolutionStrategy[];
     clauses: FixtureMatchClause[];
     allowReuse: boolean;
+    /** Declaration-local captures published after the whole graph resolves. */
+    contextOutputs: FixtureContextOutput[];
 }
 /** Normalize fixture rows + optional metadata into the ordered handle list. */
 export declare function buildFixtureResolutionSpecs(storyboard: Storyboard): FixtureResolutionSpec[];

package/dist/lib/testing/storyboard/fixture-resolution.d.ts

@@ -1,11 +1,47 @@
 import { type SchemaEntityPath } from '../../validation/schema-loader';
-import type { FixtureMatchClause, FixtureResolutionStrategy, Storyboard } from './types';
+import { type CollectionSelectionWitness } from './collection-selection';
+import type { FixtureContextOutput, FixtureMatchClause, FixtureResolutionStrategy, Storyboard } from './types';
 /** Normalize and validate the closed fixture matching DSL. */
 export declare function normalizeFixtureMatchExpression(expression: unknown, location: string): FixtureMatchClause[];
+/**
+ * Validate the declaration-local capture block.
+ *
+ * A `witness:` entry is only authorable when the same declaration carries a
+ * `collection_selection_satisfies` predicate — the witness is retained from
+ * that evaluation, so asking for one without the predicate is an authoring
+ * error rather than a runtime surprise on an agent that happens to answer
+ * differently.
+ */
+export declare function normalizeFixtureContextOutputs(value: unknown, location: string, clauses: readonly FixtureMatchClause[], 
+/**
+ * `'pricing_option'` refuses `witness:` captures. A collection witness
+ * describes a PRODUCT — its selectors, its pairs, its cross-publisher
+ * relation — and a pricing option has none of its own. Accepting one
+ * here loaded fine and then failed at run with a message about a missing
+ * `collection_selection_satisfies` predicate that was right there in the
+ * declaration, and the two strategies disagreed about it besides (seed
+ * retained the parent's witness, discover did not). Declare the witness
+ * on the parent product.
+ */
+entityKind?: 'product' | 'pricing_option'): FixtureContextOutput[];
 /** Loader/runtime authoring validation for the AdCP 3.2 declaration block. */
 export declare function validateFixtureResolutionDeclarations(storyboard: Storyboard): void;
 /** True when a seller catalog entity satisfies every authored clause. */
 export declare function matchesFixtureRequirements(candidate: unknown, clauses: readonly FixtureMatchClause[]): boolean;
+/**
+ * Match a candidate and retain the collection witness for it.
+ *
+ * The boolean `matchesFixtureRequirements` keeps its signature for existing
+ * callers. This variant exists so the resolver can retain the witness for the
+ * candidate it *actually selects*, rather than recomputing one later from an
+ * unrelated response — which is precisely how a selected-entity snapshot
+ * drifts away from the entity that was purchased.
+ */
+export declare function matchFixtureRequirementsWithWitness(candidate: unknown, clauses: readonly FixtureMatchClause[]): {
+    matched: boolean;
+    witness?: CollectionSelectionWitness;
+    reason?: string;
+};
 export interface FixtureResolutionSpec {
     entityType: 'product' | 'product_pricing_option';
     handle: string;
@@ -14,6 +50,8 @@ export interface FixtureResolutionSpec {
     strategies: FixtureResolutionStrategy[];
     clauses: FixtureMatchClause[];
     allowReuse: boolean;
+    /** Declaration-local captures published after the whole graph resolves. */
+    contextOutputs: FixtureContextOutput[];
 }
 /** Normalize fixture rows + optional metadata into the ordered handle list. */
 export declare function buildFixtureResolutionSpecs(storyboard: Storyboard): FixtureResolutionSpec[];