@adcp/sdk 16.1.0 → 16.3.0

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;

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

@@ -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;