@adcp/sdk 16.2.0 → 16.3.0

package/dist/lib/testing/index.js

@@ -20,6 +20,10 @@ var testing_exports = {};
 __export(testing_exports, {
   AdagentsJsonSchema: () => import_storyboard.AdagentsJsonSchema,
   BrandJsonSchema: () => import_storyboard.BrandJsonSchema,
+  COLLECTION_DIAGNOSTIC_LIMIT: () => import_storyboard2.COLLECTION_DIAGNOSTIC_LIMIT,
+  COLLECTION_PAIR_LIMIT: () => import_storyboard2.COLLECTION_PAIR_LIMIT,
+  COLLECTION_TARGETING_MODES: () => import_storyboard2.COLLECTION_TARGETING_MODES,
+  COLLECTION_WITNESS_KINDS: () => import_storyboard2.COLLECTION_WITNESS_KINDS,
   CONTROLLER_SCENARIOS: () => import_test_controller.CONTROLLER_SCENARIOS,
   CapabilityResolutionError: () => import_storyboard.CapabilityResolutionError,
   DEFAULT_SCENARIOS: () => import_agent_tester.DEFAULT_SCENARIOS,
@@ -27,6 +31,11 @@ __export(testing_exports, {
   FixtureBindingRegistry: () => import_storyboard.FixtureBindingRegistry,
   GovernanceAgentStub: () => import_stubs.GovernanceAgentStub,
   MCP_SESSION_PROBE_TASK: () => import_storyboard.MCP_SESSION_PROBE_TASK,
+  PREPARED_FIXTURES_CONTRACT_VERSION: () => import_storyboard2.PREPARED_FIXTURES_CONTRACT_VERSION,
+  PROTECTED_CONTEXT_PREFIX: () => import_storyboard2.PROTECTED_CONTEXT_PREFIX,
+  PreparedFixturesDeniedError: () => import_errors.PreparedFixturesDeniedError,
+  PreparedStoryboardFixtures: () => import_storyboard2.PreparedStoryboardFixtures,
+  ProtectedContextViolation: () => import_storyboard2.ProtectedContextViolation,
   RATE_LIMIT_TRIP_CONTRACT: () => import_storyboard.RATE_LIMIT_TRIP_CONTRACT,
   RATE_LIMIT_TRIP_DEFAULT_REPLAY_MAX_WAIT_SECONDS: () => import_storyboard.RATE_LIMIT_TRIP_DEFAULT_REPLAY_MAX_WAIT_SECONDS,
   RATE_LIMIT_TRIP_MAX_ATTEMPTS_MAX: () => import_storyboard.RATE_LIMIT_TRIP_MAX_ATTEMPTS_MAX,
@@ -61,7 +70,9 @@ __export(testing_exports, {
   createTestAgent: () => import_test_helpers.createTestAgent,
   createTestClient: () => import_agent_tester.createTestClient,
   creativeAgent: () => import_test_helpers.creativeAgent,
+  diffCollectionPairSets: () => import_storyboard2.diffCollectionPairSets,
   enforceMapCap: () => import_test_controller.enforceMapCap,
+  evaluateCollectionSelection: () => import_storyboard2.evaluateCollectionSelection,
   executeStoryboardTask: () => import_storyboard.executeStoryboardTask,
   expandCreativeAssetDirectives: () => import_storyboard.expandCreativeAssetDirectives,
   expectControllerError: () => import_controller_assertions.expectControllerError,
@@ -75,6 +86,7 @@ __export(testing_exports, {
   filterValidSeededProducts: () => import_test_controller_bridge.filterValidSeededProducts,
   findBundleById: () => import_storyboard.findBundleById,
   findUnresolvedCreativeAssetDirectives: () => import_storyboard.findUnresolvedCreativeAssetDirectives,
+  formatCollectionPair: () => import_storyboard2.formatCollectionPair,
   formatComplianceResults: () => import_compliance.formatComplianceResults,
   formatComplianceResultsJSON: () => import_compliance.formatComplianceResultsJSON,
   formatSuiteResults: () => import_agent_tester.formatSuiteResults,
@@ -100,8 +112,10 @@ __export(testing_exports, {
   hasSITools: () => import_agent_tester.hasSITools,
   injectContext: () => import_storyboard.injectContext,
   isComplianceVersionSupported: () => import_storyboard.isComplianceVersionSupported,
+  isProtectedContextKey: () => import_storyboard2.isProtectedContextKey,
   isSandboxDomain: () => import_storyboard.isSandboxDomain,
   isSandboxRequest: () => import_test_controller_bridge.isSandboxRequest,
+  isTrustedPreparedFixtures: () => import_storyboard2.isTrustedPreparedFixtures,
   likelySupportsV3: () => import_agent_tester.likelySupportsV3,
   listAllComplianceStoryboards: () => import_storyboard.listAllComplianceStoryboards,
   listAssertions: () => import_storyboard.listAssertions,
@@ -124,12 +138,16 @@ __export(testing_exports, {
   mergeSeededCreativesIntoResponse: () => import_test_controller_bridge.mergeSeededCreativesIntoResponse,
   mergeSeededMediaBuysIntoResponse: () => import_test_controller_bridge.mergeSeededMediaBuysIntoResponse,
   mergeSeededProductsIntoResponse: () => import_test_controller_bridge.mergeSeededProductsIntoResponse,
+  normalizeCollectionSelectors: () => import_storyboard2.normalizeCollectionSelectors,
   normalizeFixtureMatchExpression: () => import_storyboard.normalizeFixtureMatchExpression,
   normalizeOAuthResourceForComparison: () => import_storyboard.normalizeOAuthResourceForComparison,
   normalizeValidationOnlyTasks: () => import_storyboard.normalizeValidationOnlyTasks,
   overlayById: () => import_seed_merge.overlayById,
   parseStoryboard: () => import_storyboard.parseStoryboard,
   pickSeededAccountFinancialsForRequest: () => import_test_controller_bridge.pickSeededAccountFinancialsForRequest,
+  prepareStoryboardFixtures: () => import_storyboard2.prepareStoryboardFixtures,
+  productSatisfiesCollectionSelection: () => import_storyboard2.productSatisfiesCollectionSelection,
+  readCollectionWitness: () => import_storyboard2.readCollectionWitness,
   redactOAuthUrlForOutput: () => import_storyboard.redactOAuthUrlForOutput,
   registerAssertion: () => import_storyboard.registerAssertion,
   registerExternalSchemaRoot: () => import_validation.registerExternalSchemaRoot,
@@ -139,7 +157,7 @@ __export(testing_exports, {
   resolveAccountForMediaBuy: () => import_agent_tester.resolveAccountForMediaBuy,
   resolveAssertions: () => import_storyboard.resolveAssertions,
   resolveBundleOrStoryboard: () => import_storyboard.resolveBundleOrStoryboard,
-  resolveCreativeBuildProbe: () => import_storyboard2.resolveCreativeBuildProbe,
+  resolveCreativeBuildProbe: () => import_storyboard3.resolveCreativeBuildProbe,
   resolvePath: () => import_storyboard.resolvePath,
   resolveStoryboardsForCapabilities: () => import_storyboard.resolveStoryboardsForCapabilities,
   runAgainstLocalAgent: () => import_local_agent_runner.runAgainstLocalAgent,
@@ -149,6 +167,7 @@ __export(testing_exports, {
   runStoryboardStep: () => import_storyboard.runStoryboardStep,
   runValidations: () => import_storyboard.runValidations,
   setAgentTesterLogger: () => import_agent_tester.setAgentTesterLogger,
+  summarizeCollectionPairs: () => import_storyboard2.summarizeCollectionPairs,
   testAccountStateMachine: () => import_agent_tester.testAccountStateMachine,
   testAgent: () => import_test_helpers.testAgent,
   testAgentA2A: () => import_test_helpers.testAgentA2A,
@@ -191,14 +210,16 @@ __export(testing_exports, {
   testTerminalStateEnforcement: () => import_agent_tester.testTerminalStateEnforcement,
   testValidation: () => import_agent_tester.testValidation,
   unregisterExternalSchemaRoot: () => import_validation.unregisterExternalSchemaRoot,
-  validateCreativeBuildProbeSpec: () => import_storyboard2.validateCreativeBuildProbeSpec,
+  validateCreativeBuildProbeSpec: () => import_storyboard3.validateCreativeBuildProbeSpec,
   validateFixtureResolutionDeclarations: () => import_storyboard.validateFixtureResolutionDeclarations,
   validateRateLimitTripSpec: () => import_storyboard.validateRateLimitTripSpec,
   withExternalSchemaRoot: () => import_validation.withExternalSchemaRoot,
+  withPreparedFixtures: () => import_storyboard2.withPreparedFixtures,
   withServedReleaseSchemaRoots: () => import_validation.withServedReleaseSchemaRoots
 });
 module.exports = __toCommonJS(testing_exports);
 var import_pending_web_flow_store = require('./pending-web-flow-store.js');
+var import_errors = require('../errors/index.js');
 var import_test_helpers = require('./test-helpers.js');
 var import_agent_tester = require('./agent-tester.js');
 var import_compliance = require('./compliance/index.js');
@@ -212,10 +233,15 @@ var import_local_agent_runner = require('./local-agent-runner.js');
 var import_validation = require('../validation/index.js');
 var import_storyboard = require('./storyboard/index.js');
 var import_storyboard2 = require('./storyboard/index.js');
+var import_storyboard3 = require('./storyboard/index.js');
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AdagentsJsonSchema,
   BrandJsonSchema,
+  COLLECTION_DIAGNOSTIC_LIMIT,
+  COLLECTION_PAIR_LIMIT,
+  COLLECTION_TARGETING_MODES,
+  COLLECTION_WITNESS_KINDS,
   CONTROLLER_SCENARIOS,
   CapabilityResolutionError,
   DEFAULT_SCENARIOS,
@@ -223,6 +249,11 @@ var import_storyboard2 = require('./storyboard/index.js');
   FixtureBindingRegistry,
   GovernanceAgentStub,
   MCP_SESSION_PROBE_TASK,
+  PREPARED_FIXTURES_CONTRACT_VERSION,
+  PROTECTED_CONTEXT_PREFIX,
+  PreparedFixturesDeniedError,
+  PreparedStoryboardFixtures,
+  ProtectedContextViolation,
   RATE_LIMIT_TRIP_CONTRACT,
   RATE_LIMIT_TRIP_DEFAULT_REPLAY_MAX_WAIT_SECONDS,
   RATE_LIMIT_TRIP_MAX_ATTEMPTS_MAX,
@@ -257,7 +288,9 @@ var import_storyboard2 = require('./storyboard/index.js');
   createTestAgent,
   createTestClient,
   creativeAgent,
+  diffCollectionPairSets,
   enforceMapCap,
+  evaluateCollectionSelection,
   executeStoryboardTask,
   expandCreativeAssetDirectives,
   expectControllerError,
@@ -271,6 +304,7 @@ var import_storyboard2 = require('./storyboard/index.js');
   filterValidSeededProducts,
   findBundleById,
   findUnresolvedCreativeAssetDirectives,
+  formatCollectionPair,
   formatComplianceResults,
   formatComplianceResultsJSON,
   formatSuiteResults,
@@ -296,8 +330,10 @@ var import_storyboard2 = require('./storyboard/index.js');
   hasSITools,
   injectContext,
   isComplianceVersionSupported,
+  isProtectedContextKey,
   isSandboxDomain,
   isSandboxRequest,
+  isTrustedPreparedFixtures,
   likelySupportsV3,
   listAllComplianceStoryboards,
   listAssertions,
@@ -320,12 +356,16 @@ var import_storyboard2 = require('./storyboard/index.js');
   mergeSeededCreativesIntoResponse,
   mergeSeededMediaBuysIntoResponse,
   mergeSeededProductsIntoResponse,
+  normalizeCollectionSelectors,
   normalizeFixtureMatchExpression,
   normalizeOAuthResourceForComparison,
   normalizeValidationOnlyTasks,
   overlayById,
   parseStoryboard,
   pickSeededAccountFinancialsForRequest,
+  prepareStoryboardFixtures,
+  productSatisfiesCollectionSelection,
+  readCollectionWitness,
   redactOAuthUrlForOutput,
   registerAssertion,
   registerExternalSchemaRoot,
@@ -345,6 +385,7 @@ var import_storyboard2 = require('./storyboard/index.js');
   runStoryboardStep,
   runValidations,
   setAgentTesterLogger,
+  summarizeCollectionPairs,
   testAccountStateMachine,
   testAgent,
   testAgentA2A,
@@ -391,5 +432,6 @@ var import_storyboard2 = require('./storyboard/index.js');
   validateFixtureResolutionDeclarations,
   validateRateLimitTripSpec,
   withExternalSchemaRoot,
+  withPreparedFixtures,
   withServedReleaseSchemaRoots
 });

package/dist/lib/testing/index.mjs

@@ -1,4 +1,5 @@
 import { assertPendingWebFlowStoreRoundTrip } from "./pending-web-flow-store.mjs";
+import { PreparedFixturesDeniedError } from "../errors/index.mjs";
 import {
   testAgent,
   testAgentA2A,
@@ -189,10 +190,35 @@ import {
   AdagentsJsonSchema,
   MCP_SESSION_PROBE_TASK
 } from "./storyboard/index.mjs";
+import {
+  COLLECTION_DIAGNOSTIC_LIMIT,
+  COLLECTION_PAIR_LIMIT,
+  COLLECTION_TARGETING_MODES,
+  COLLECTION_WITNESS_KINDS,
+  diffCollectionPairSets,
+  evaluateCollectionSelection,
+  formatCollectionPair,
+  isProtectedContextKey,
+  isTrustedPreparedFixtures,
+  normalizeCollectionSelectors,
+  prepareStoryboardFixtures,
+  PREPARED_FIXTURES_CONTRACT_VERSION,
+  PreparedStoryboardFixtures,
+  productSatisfiesCollectionSelection,
+  PROTECTED_CONTEXT_PREFIX,
+  summarizeCollectionPairs,
+  ProtectedContextViolation,
+  readCollectionWitness,
+  withPreparedFixtures
+} from "./storyboard/index.mjs";
 import { resolveCreativeBuildProbe, validateCreativeBuildProbeSpec } from "./storyboard/index.mjs";
 export {
   AdagentsJsonSchema,
   BrandJsonSchema,
+  COLLECTION_DIAGNOSTIC_LIMIT,
+  COLLECTION_PAIR_LIMIT,
+  COLLECTION_TARGETING_MODES,
+  COLLECTION_WITNESS_KINDS,
   CONTROLLER_SCENARIOS,
   CapabilityResolutionError,
   DEFAULT_SCENARIOS,
@@ -200,6 +226,11 @@ export {
   FixtureBindingRegistry,
   GovernanceAgentStub,
   MCP_SESSION_PROBE_TASK,
+  PREPARED_FIXTURES_CONTRACT_VERSION,
+  PROTECTED_CONTEXT_PREFIX,
+  PreparedFixturesDeniedError,
+  PreparedStoryboardFixtures,
+  ProtectedContextViolation,
   RATE_LIMIT_TRIP_CONTRACT,
   RATE_LIMIT_TRIP_DEFAULT_REPLAY_MAX_WAIT_SECONDS,
   RATE_LIMIT_TRIP_MAX_ATTEMPTS_MAX,
@@ -234,7 +265,9 @@ export {
   createTestAgent,
   createTestClient,
   creativeAgent,
+  diffCollectionPairSets,
   enforceMapCap,
+  evaluateCollectionSelection,
   executeStoryboardTask,
   expandCreativeAssetDirectives,
   expectControllerError,
@@ -248,6 +281,7 @@ export {
   filterValidSeededProducts,
   findBundleById,
   findUnresolvedCreativeAssetDirectives,
+  formatCollectionPair,
   formatComplianceResults,
   formatComplianceResultsJSON,
   formatSuiteResults,
@@ -273,8 +307,10 @@ export {
   hasSITools,
   injectContext,
   isComplianceVersionSupported,
+  isProtectedContextKey,
   isSandboxDomain,
   isSandboxRequest,
+  isTrustedPreparedFixtures,
   likelySupportsV3,
   listAllComplianceStoryboards,
   listAssertions,
@@ -297,12 +333,16 @@ export {
   mergeSeededCreativesIntoResponse,
   mergeSeededMediaBuysIntoResponse,
   mergeSeededProductsIntoResponse,
+  normalizeCollectionSelectors,
   normalizeFixtureMatchExpression,
   normalizeOAuthResourceForComparison,
   normalizeValidationOnlyTasks,
   overlayById,
   parseStoryboard,
   pickSeededAccountFinancialsForRequest,
+  prepareStoryboardFixtures,
+  productSatisfiesCollectionSelection,
+  readCollectionWitness,
   redactOAuthUrlForOutput,
   registerAssertion,
   registerExternalSchemaRoot,
@@ -322,6 +362,7 @@ export {
   runStoryboardStep,
   runValidations,
   setAgentTesterLogger,
+  summarizeCollectionPairs,
   testAccountStateMachine,
   testAgent,
   testAgentA2A,
@@ -368,5 +409,6 @@ export {
   validateFixtureResolutionDeclarations,
   validateRateLimitTripSpec,
   withExternalSchemaRoot,
+  withPreparedFixtures,
   withServedReleaseSchemaRoots
 };

package/dist/lib/testing/storyboard/collection-selection.d.mts

@@ -0,0 +1,259 @@
+/**
+ * Domain-qualified collection identity: one normalizer, one eligibility
+ * predicate, one witness builder, one set comparison.
+ *
+ * Every consumer of collection identity in the runner goes through this
+ * module — the fixture predicate (`collection_selection_satisfies`), the
+ * derived witness captures published by fixture preparation, and the
+ * `collection_set_equals_context` validator. Splitting those three would let
+ * "what counts as the same collection" drift between selection and grading,
+ * which is exactly the failure the upstream contract calls out.
+ *
+ * Identity rules, and the reasons they are what they are:
+ *
+ *   - A selector is normalized to atomic `(publisher_domain, collection_id)`
+ *     pairs. IDs are never flattened without their domain: two publishers may
+ *     legitimately declare the same `collection_id`.
+ *   - `collection_ids` is optional on `CollectionSelector` and means "every
+ *     collection declared in that domain's adagents.json". That bulk-grant
+ *     form is a *different* selector from an explicit enumeration, so it
+ *     normalizes to a pair with `collection_id: null` rather than silently
+ *     comparing equal to an enumerated set. Product composition is required
+ *     to name explicit ids, so `null` pairs do not count toward
+ *     `minimum_pairs`.
+ *   - Schema-valid redundancy collapses: repeated ids inside one selector,
+ *     and overlapping atomic pairs across differently-grouped selectors, are
+ *     one pair. Neither `product.collections[]` nor `collection_ids[]`
+ *     carries a uniqueness constraint, so redundancy is legal *product
+ *     composition*. The readback arm is stricter:
+ *     `core/collection-selection.json` declares `uniqueItems: true` on
+ *     `collections` in `mode: selected`. Normalizing here is for COMPARISON
+ *     only and never excuses that — the surrounding response is still
+ *     schema-validated, which is what rejects a duplicated outer entry.
+ *     Schema-invalid input (a non-array, a non-object entry, an empty
+ *     `collection_ids`) stays a visible failure here and is additionally
+ *     rejected by ordinary response-schema validation upstream.
+ *   - Ordering is bytewise over UTF-8, on the *pairs*, so outer grouping and
+ *     inner id order never affect the result while non-ASCII identifiers stay
+ *     lossless. Nothing is case-folded, trimmed, punycoded or otherwise
+ *     rewritten. `collection_id` is a plain string with no `minLength` and no
+ *     declared normalization form, so inventing one would grade agents
+ *     against a rule the protocol does not state. `publisher_domain` is
+ *     separately pattern-constrained to lowercase LDH by
+ *     `core/collection-selector.json`, which response-schema validation
+ *     already enforces — canonicalizing it here would be redundant at best
+ *     and would mask a non-conformant catalog at worst.
+ */
+/** Maximum distinct pairs any single normalization will materialize. */
+export declare const COLLECTION_PAIR_LIMIT = 10000;
+/** Maximum pairs echoed into a diagnostic before it is elided. */
+export declare const COLLECTION_DIAGNOSTIC_LIMIT = 20;
+/** One atomic, domain-qualified collection identity. */
+export interface CollectionPair {
+    publisher_domain: string;
+    /** `null` is the domain-only bulk-grant selector, not an empty id. */
+    collection_id: string | null;
+}
+/** A concrete `CollectionSelector` as it appears on the wire. */
+export interface CollectionSelectorObject {
+    publisher_domain: string;
+    collection_ids?: string[];
+}
+export interface NormalizedCollectionSelectors {
+    /** Distinct pairs in bytewise order. */
+    pairs: CollectionPair[];
+    /** Outer selector entries observed, before normalization. */
+    selector_count: number;
+    /** Distinct publisher domains, bytewise ordered. */
+    domains: string[];
+}
+export type CollectionNormalizationCode = 'not_an_array' | 'selector_not_object' | 'publisher_domain_invalid' | 'collection_ids_invalid' | 'collection_id_invalid' | 'pair_limit_exceeded';
+export interface CollectionNormalizationFailure {
+    code: CollectionNormalizationCode;
+    detail: string;
+}
+export type CollectionNormalizationResult = {
+    ok: true;
+    value: NormalizedCollectionSelectors;
+} | {
+    ok: false;
+    failure: CollectionNormalizationFailure;
+};
+/** Total bytewise order over pairs. Domain first, then id; `null` sorts first. */
+export declare function compareCollectionPairs(a: CollectionPair, b: CollectionPair): number;
+/** Stable, unambiguous rendering for diagnostics and dedup keys. */
+export declare function formatCollectionPair(pair: CollectionPair): string;
+/**
+ * Normalize an array of `CollectionSelector` objects into distinct atomic
+ * pairs. Used for product catalog entries, authored expected sets and
+ * seller-returned `selected.collections` alike — same definition everywhere.
+ */
+export declare function normalizeCollectionSelectors(value: unknown, options?: {
+    limit?: number;
+}): CollectionNormalizationResult;
+/** Exact set difference over normalized pairs, with bounded diagnostics. */
+export declare function diffCollectionPairSets(actual: readonly CollectionPair[], expected: readonly CollectionPair[]): {
+    equal: boolean;
+    missing: CollectionPair[];
+    unexpected: CollectionPair[];
+};
+/** Render at most `COLLECTION_DIAGNOSTIC_LIMIT` pairs, flagging elision. */
+export declare function summarizeCollectionPairs(pairs: readonly CollectionPair[]): string;
+/**
+ * Operand of the `collection_selection_satisfies` fixture predicate.
+ *
+ * `collection_targeting` encodes the schema's omitted-false default
+ * explicitly rather than teaching every `equals` comparison to apply
+ * arbitrary defaults. It is deliberately NOT named `mode`: the wire's
+ * `collection_selection.mode` is `selected | default`, and the two appear in
+ * the same storyboard file.
+ *
+ *   - `fixed`      — `collection_targeting_allowed` is literal `false` OR
+ *                    absent (the normative default). `true` does not qualify.
+ *   - `selectable` — literal `true` only.
+ *   - `any`        — either, as long as the flag is absent or a boolean.
+ *
+ * A non-boolean, non-absent flag never qualifies in any mode: that is a
+ * schema failure of the seller's catalog, surfaced by response-schema
+ * validation during discovery, not something this predicate repairs.
+ */
+export interface CollectionSelectionSelector {
+    collection_targeting: 'selectable' | 'fixed' | 'any';
+    /**
+     * Distinct concrete pairs the product must expose. Defaults to `1`, which
+     * covers default materialization / full-bundle restatement; `2` is
+     * required before a genuine strict subset exists to exercise.
+     */
+    minimum_pairs?: 1 | 2;
+    /**
+     * Require a wire-visible owner/host relation: at least one collection
+     * selector whose publisher domain is outside every declared property
+     * (host) domain of the same product. Defaults to `false`.
+     */
+    require_cross_publisher_collection?: boolean;
+}
+/**
+ * Post-normalization operand the evaluator consumes, with both defaults
+ * applied.
+ *
+ * Kept separate from the authored form so the type accepts exactly what the
+ * loader accepts: `{ collection_targeting: 'fixed' }` is valid YAML and must type-check,
+ * while an index signature would have let a typo'd key compile clean and
+ * then fail at load against the closed-operand rule.
+ */
+export interface ResolvedCollectionSelectionSelector {
+    collection_targeting: 'selectable' | 'fixed' | 'any';
+    minimum_pairs: 1 | 2;
+    require_cross_publisher_collection: boolean;
+}
+export declare const COLLECTION_TARGETING_MODES: readonly ["selectable", "fixed", "any"];
+/** Validate and default the closed operand. Throws on authoring errors. */
+export declare function normalizeCollectionSelectionSelector(value: unknown, location: string): ResolvedCollectionSelectionSelector;
+/** The declared owner/host relation observed on one product. */
+export interface CrossPublisherCollectionRelation {
+    /**
+     * The collection namespace that lies outside every property namespace of
+     * the SAME selected product.
+     */
+    collection_publisher_domain: string;
+    /** Property namespaces declared by that same product. */
+    property_publisher_domains: string[];
+    /**
+     * The concrete selector carrying it. `selector.publisher_domain` always
+     * equals `collection_publisher_domain`.
+     */
+    selector: CollectionSelectorObject;
+}
+/**
+ * Everything the resolver retains about the product it actually selected.
+ * Built once, from the selected candidate, and never recomputed from a
+ * different response.
+ */
+export interface CollectionSelectionWitness {
+    product_id: string | null;
+    /**
+     * Effective targeting of the selected product, with the schema's
+     * omitted-false default applied. Distinct from the native seller field
+     * `collection_targeting_allowed`, whose raw observed value is reported
+     * beside it, and from the wire's `collection_selection.mode`.
+     */
+    collection_targeting: 'selectable' | 'fixed';
+    /** The flag exactly as observed — `undefined` when the seller omitted it. */
+    collection_targeting_allowed: boolean | undefined;
+    /** The product's complete, concrete collection selector bundle. */
+    declared_selectors: CollectionSelectorObject[];
+    /** Distinct concrete pairs (bulk-grant entries excluded). */
+    distinct_pairs: CollectionPair[];
+    /**
+     * A one-entry selector array naming exactly one of the bundle's pairs, so
+     * it is a strict subset whenever the bundle has two or more. Shaped as an
+     * array because that is the shape a `collections` field takes on the wire,
+     * so a storyboard can substitute it whole.
+     *
+     * When `require_cross_publisher_collection` was requested, the pair is drawn from the
+     * retained external owner, so the subset actually exercises the carriage
+     * relation rather than the host's own inventory.
+     *
+     * `null` when the product exposes fewer than two distinct concrete pairs —
+     * a one-pair product still qualifies for default materialization, so the
+     * absence of a subset witness must not suppress that coverage.
+     */
+    strict_subset: CollectionSelectorObject[] | null;
+    /**
+     * One-entry selector array naming an id verified absent from this
+     * product's pairs, under a domain the product does carry.
+     */
+    undeclared_collection_id_selectors: CollectionSelectorObject[];
+    /**
+     * One-entry selector array whose domain is verified absent from every
+     * COLLECTION namespace this product declares.
+     *
+     * Property namespaces (`publisher_properties[].publisher_domain`) are not
+     * checked — the synthesized domain is a `.invalid` name, which RFC 2606
+     * reserves and no real publisher can hold, so a collision is not possible
+     * in practice. Stated precisely because "every namespace this product
+     * declares" read as including the property side, and it does not.
+     */
+    undeclared_publisher_domain_selectors: CollectionSelectorObject[];
+    /** Present only when the relation was requested and found. */
+    cross_publisher_relation: CrossPublisherCollectionRelation | null;
+    /** Declared property namespaces, bytewise ordered. */
+    property_publisher_domains: string[];
+}
+export type CollectionSelectionEvaluation = {
+    eligible: true;
+    witness: CollectionSelectionWitness;
+} | {
+    eligible: false;
+    reason: string;
+};
+/**
+ * Decide whether one discovered product qualifies, and retain the witness
+ * for the candidate that is actually selected.
+ *
+ * Qualification is evaluated against the complete validated candidate before
+ * any deterministic ordering is applied, so a nonqualifying first product can
+ * never hide a later qualifying one.
+ */
+export declare function evaluateCollectionSelection(candidate: unknown, selector: CollectionSelectionSelector): CollectionSelectionEvaluation;
+/** Boolean form for the legacy matcher. */
+export declare function productSatisfiesCollectionSelection(candidate: unknown, selector: CollectionSelectionSelector): boolean;
+/** Derived witness captures a declaration may bind to a context key. */
+export declare const COLLECTION_WITNESS_KINDS: readonly ["declared_selectors", "distinct_pairs", "strict_subset", "undeclared_collection_id_selectors", "undeclared_publisher_domain_selectors", "cross_publisher_relation", "property_publisher_domains"];
+export type CollectionWitnessKind = (typeof COLLECTION_WITNESS_KINDS)[number];
+export type CollectionWitnessReadResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    detail: string;
+};
+/**
+ * Read one derived capture off a retained witness.
+ *
+ * A declared capture that cannot be built is a setup failure, never an
+ * unsupported/not-applicable downgrade — the storyboard asked for state the
+ * selected product does not provide, and silently proceeding would grade the
+ * agent against a request the author did not write.
+ */
+export declare function readCollectionWitness(witness: CollectionSelectionWitness | undefined, kind: CollectionWitnessKind): CollectionWitnessReadResult;