@instruments/materialgraph 0.26.0 → 0.27.0

package/search-request-types.d.ts

@@ -1,86 +1,75 @@
-/** samplizeCatalogue admits published US Samplize paint colours, regardless of stock. */
 /**
  * @module search-request-types
- * The two request shapes for the `/search` surface — the POST JSON body and the
+ * The two request shapes for the `/search` surface: the POST JSON body and the
  * GET query-string form. Split out of `types.ts` so neither file outgrows the
  * repo's source-size gate; every name here is re-exported from `types.ts`, so
  * no import path changes.
  */
 import type { CorpusScope } from "./corpus-scope-types.js";
 import type { Cursor, VariantId } from "./identifiers.js";
-import type { SearchFilter } from "./search-refinement-types.js";
-import type { ColourInput, OpenEnum, SearchImageInput } from "./types.js";
+import type { OpenEnum, SearchImageInput } from "./types.js";
 /**
- * The POST `/search` JSON body — the `searchMaterials` contract. Every field is
- * optional; supply at least one signal (`text`, `colours`, `mood`, `similarTo`,
- * or `image`). Passed through to the server verbatim.
+ * One attribute filter the one search runs as a hard token set on its index
+ * (ADR 0031, MG-2158). Entries on one attribute are OR'd; entries on different
+ * attributes AND together.
+ *
+ * - `term`: the value must carry this canonical term.
+ * - `terms`: any one of these terms satisfies it.
+ * - `excludesTerm`: the value must not carry this term. A material that states
+ *   nothing for the attribute passes.
+ * - `hasValue: true`: any stated value.
+ * - `min` and/or `max`: an inclusive numeric range, on a numeric attribute
+ *   (`"nrc_rating"`), a dimensions lens in millimetres
+ *   (`"dimensions.thickness_mm"`, `"dimensions.short_side_mm"`) or a
+ *   composition share on 0 to 1 (`"composition_weighted.wool"`). It is read as
+ *   the number bands wholly inside it, so a bound between two band edges is
+ *   read inward; a range no band fits inside is a 400.
+ *
+ * `attributeId` is an attribute the index carries tokens for, or
+ * `"certification_programme"` for any certification programme. Terms are
+ * canonical dictionary terms, not display names. Numeric attributes take
+ * `hasValue` or a range. An attribute or term the index does not carry is a
+ * 400 naming it.
+ */
+export type SearchIndexFilter = {
+    attributeId: string;
+    term: string;
+} | {
+    attributeId: string;
+    terms: string[];
+} | {
+    attributeId: string;
+    excludesTerm: string;
+} | {
+    attributeId: string;
+    hasValue: true;
+} | {
+    attributeId: string;
+    min?: number;
+    max?: number;
+};
+/**
+ * The POST `/search` JSON body (ADR 0031): the words, or a look-alike seed, and
+ * the page wanted. `category`, `filters`, `corpusScope`, `colour` and `brands`
+ * become fields of the query's plan and run in the same index query. The order
+ * is the index's own, so nothing here sets weights, a blend or a sort. Send
+ * `text`, `similarTo`, `image`, `colour`, `category`, `filters` or `brands`; a
+ * corpus scope alone does not say what to find. Any other field is a 400
+ * naming it.
  */
 export type SearchInput = {
-    text?: string;
-    textModes?: OpenEnum<"visual" | "lexical">[];
-    colours?: ColourInput[];
-    colourLogic?: OpenEnum<"all" | "any">;
-    colourTolerance?: OpenEnum<"tight" | "normal" | "loose">;
-    colourAppearance?: {
-        lightness?: {
-            min: number;
-            max: number;
-        };
-        warmth?: {
-            min: number;
-            max: number;
-        };
-    };
-    mood?: string;
     /**
-     * Re-order the final scored results. `relevance` (default) keeps the selected
-     * mode's primary score; `light` / `dark` / `vivid` / `muted` / `colourful` are the colour
-     * ramps; `name` (A→Z), `name_desc` (Z→A) and `recent` (newest first) are the
-     * catalogue orders — the same three `/search/browse` walks the corpus in, so
-     * one word means one order on both lanes.
+     * Free text ("oak flooring", "sage green velvet", "Kvadrat wool"). Brands,
+     * categories, colours and attributes are read from the words unless
+     * `brands`, `category` or `colour` says so instead; a corrected word is
+     * reported under `correctedQuery`.
      */
-    sort?: OpenEnum<"relevance" | "light" | "dark" | "vivid" | "muted" | "colourful" | "name" | "name_desc" | "recent">;
-    /**
-     * Sort along ONE attribute's declared value ladder — a SEPARATE axis from
-     * `sort`, which stays the closed relevance / colour / catalogue vocabulary.
-     *
-     * `direction` defaults to `"asc"`. Sent together with `sort`, `orderBy` wins
-     * and the response `note` says so — a UI holding both controls can send both.
-     *
-     * Ordering is DECLARED, never inferred from how a value is spelled: an
-     * attribute with no stated ladder is a 400 carrying the orderable set in
-     * `orderable_attributes`, not a quiet fall back to relevance. A material whose
-     * value is off the ladder, or which carries no value at all, sorts LAST in
-     * both directions — it is still a real material, it just has no rung.
-     */
-    orderBy?: {
-        attributeId: string;
-        direction?: OpenEnum<"asc" | "desc">;
-    };
-    /**
-     * Attribute ids whose resolved value should ride each result under
-     * `attributes` — so a page you filtered by `price_tier` can DISPLAY the tier
-     * without a second call per material. Up to 8.
-     *
-     * Three response states, all different: no `attributes` key means you did not
-     * ask, a key with `null` means nothing is on record for that material, and
-     * anything else is the value. An unknown attribute id is a 400 naming it.
-     */
-    returnAttributes?: string[];
+    text?: string;
+    /** A query image (URL or base64); `text`, when also given, narrows it. */
+    image?: SearchImageInput;
     /**
-     * Seed a visual search from an existing variant's image (`variantId`), from a
-     * Material Bank SKU (`materialBankId`), or from a pre-computed image vector
-     * (`vector`).
-     *
-     * `materialBankId` exists so a caller already holding a SKU does not have to
-     * ask us to translate it before it can ask us anything useful — one call, not
-     * two. It resolves to the variant server-side and then behaves identically to
-     * the `{ variantId }` form, seed verdicts included. A SKU that names no
-     * variant is a 400 carrying the offending value: never an empty result set,
-     * never a silent fall back to unseeded search.
-     *
-     * The `{ vector }` form carries no seed variant, so it is the only one
-     * `verdicts` cannot diff a candidate against.
+     * Materials that LOOK like a seed: an existing variant, a Material Bank SKU
+     * (an unknown SKU is a 400 naming it), or a pre-computed image vector.
      */
     similarTo?: {
         variantId: VariantId;
@@ -90,156 +79,84 @@ export type SearchInput = {
         vector: string;
     };
     /**
-     * Canonical variants that must not appear in the returned page. The server
-     * applies these exclusions before the page limit, so consumers can request
-     * unseen results without shortening an already-bounded page client-side.
-     * Maximum 256; ids are opaque.
+     * A hard category gate: public category-group or product-type names, or
+     * taxonomy keys. It replaces the category the words were read as. An
+     * unknown value is a 400 listing every valid name.
      */
-    excludeVariantIds?: VariantId[];
-    image?: SearchImageInput;
     category?: {
-        boost?: string;
-        filter?: string[];
+        filter: string[];
     };
+    /** Hard attribute filters, 1 to 24. See {@link SearchIndexFilter}. */
+    filters?: SearchIndexFilter[];
     /**
-     * Optional multipliers for the selected mode's one ordering signal. At most
-     * one is applied: image for image/image-text, lexical for lexical/browse, and
-     * colour for colour mode. Non-mode keys are accepted for compatibility but
-     * cannot activate secondary scoring.
+     * Order the page by a colour: a `hex`, or `variantId` for the colour of an
+     * existing Variant. The page is the colour's family, nearest first by OKLab
+     * distance; it replaces any colour read from `text`. A Variant with no colour
+     * on the index is a 400.
      */
-    weights?: {
-        image?: number;
-        category?: number;
-        colour?: number;
-        lexical?: number;
-        /** Compatibility field; seeded text does not activate secondary scoring. */
-        text?: number;
+    colour?: {
+        hex: string;
+    } | {
+        variantId: VariantId;
     };
-    filters?: SearchFilter[];
-    /**
-     * SOFT spec criteria (rank-never-exclude). Same shape as `filters`; a preference
-     * never removes a result — it adds a `preferred` cell to each hit's `verdict` and
-     * demotes a failed/missing preferred hit WITHIN its page only.
-     */
-    preferences?: SearchFilter[];
-    /** Results per page (default 60, max 60), never a bound on the match set. */
-    limit?: number;
-    /** The previous response's `cursor`, passed back verbatim. Never synthesise one. */
-    cursor?: Cursor;
-    explain?: boolean;
-    /** Public POST defaults to distinct products; send `"none"` for individual variants. */
-    collapse?: OpenEnum<"none" | "product">;
     /**
-     * Opt-in feed total: EXACT up to 1,000, `lowerBound` beyond / for ANN pools.
-     * Without it the response states NO total — and a page size is not one.
+     * Makers the page must come from: canonical brand ids, exact slugs
+     * ("sherwin-williams") or exact display names ("Sherwin-Williams"), up to
+     * 50. They replace the makers `text` was read as. An empty list is the
+     * same request as omitting it — every brand. An unrecognised value is a
+     * 400 naming it; a display name shared by more than one brand is a 400
+     * naming the exact slugs to choose between; a brand MaterialGraph holds no
+     * materials under is a 400 naming a populated sibling when one exists.
      */
-    count?: boolean;
+    brands?: string[];
     /**
-     * Opt-in per-query facet counts (MG-1010): up to 10 facet ids — `"brand"`,
-     * `"category"`, or spec attribute ids — and the response carries a `facets`
-     * block counting each facet's values WITHIN this query's match set. An
-     * unknown id is a 400 naming it; a known but uncountable id lands in
-     * `facets.absent`. Absent = no `facets` in the response, no counting cost.
+     * Attribute ids (at most 8) whose resolved value should ride each result
+     * under `attributes`, keyed by attribute id. Not a plan field: it changes
+     * no ordering and plays no part in the cursor. An attribute you did not
+     * ask for is not a key on `attributes` at all; one you asked for that a
+     * result carries no accepted value for is `null`; anything else is the
+     * value. An unknown attribute id is a 400 naming it.
      */
-    facetCounts?: string[];
-    /**
-     * Opaque five-minute receipt from a prior pool-derived faceted search.
-     * Resubmitting it may only narrow that exact finalized pool.
-     */
-    refinementToken?: string;
-    /** Only return materials with at least one catalog image. Default false (full catalog). */
-    hasImages?: boolean;
-    /** Require a recorded accepted sampleable=true fact; unknown and false are excluded. */
-    sampleableOnly?: boolean;
-    /**
-     * Opt-in seed-relative verdict cells (MG-629). Only meaningful with
-     * `similarTo: { variantId }`: each hit's `verdict` gains `preferred` cells
-     * diffing its comparable attributes (numeric + a `colour` axis) against the
-     * seed's, with directional deviations. Inert on every other seed form.
-     */
-    verdicts?: boolean;
-    /** Result projection — `"full"` (default) or the lean `"card"` grid form. */
-    view?: OpenEnum<"full" | "card">;
-    /**
-     * Budget profile for the search primitive.
-     *
-     * `"search"` (default) is the full engine. `"typeahead"` is the as-you-type
-     * profile: lexical-only with prefix match on the final token, forced
-     * `view: "card"`, `limit` capped at 24, and no mood/colour detection tiers,
-     * semantic fallback, secondary scoring, refinement suggestions,
-     * counts, or meanings. `textModes` is ignored under typeahead.
-     */
-    intent?: OpenEnum<"search" | "typeahead">;
+    returnAttributes?: string[];
     /**
-     * Which corpus to answer from.
-     *
-     * **ABSENT means the WHOLE GRAPH** — every material MaterialGraph knows,
-     * orderable or not. Absence is never a narrower default, so a caller that
-     * says nothing gets materials it may not be able to buy.
-     * Three transaction-oriented scopes gate on governed CHANNEL membership:
-     * `"materialBankNaOrderable"` (Material Bank North America,
-     * ~277,000 materials), `"materialBankEuOrderable"` (Material Bank Europe,
-     * ~65,000) and `"designShopOrderable"` (DesignShop, ~34,000, with the
-     * products DesignShop hides from browse excluded).
-     * `"materialBankNaAndCatalogue"` is a governed discovery corpus: the single
-     * producer-side union of Material Bank North America and Catalogue editorial
-     * membership. It is not a buyability claim, and a catalogue reference alone
-     * does not establish membership.
-     *
-     * `"materialBankOrderable"` is NOT one of them, despite the name. It selects
-     * materials carrying a Material Bank identity — a PROVENANCE signal, not a
-     * storefront — and admits about 98% of the graph. Use it to exclude the
-     * crawl-sourced brands that were never in the Material Bank feed; if you mean
-     * orderable, use one of the channel-backed scopes above.
-     *
-     * A scope answers membership in its named distribution or visibility
-     * surface; the token-specific description states whether that means
-     * transaction or editorial inclusion. It never answers what is SUITABLE:
-     * scope on channel, then refine on sector.
-     *
-     * The scope is applied INSIDE the query: `limit` fills with eligible rows,
-     * `counts` describe the SCOPED corpus, and the response echoes the scope.
-     * That is what post-filtering a page cannot give you — a client-side filter
-     * shortens the page exactly when the query drifts toward the corpus beyond
-     * the Material Bank feed, which is unpredictable from outside.
+     * Which corpus to answer from, applied inside the index query. ABSENT (or
+     * `"all"`) means the whole graph. `"materialBankOrderable"` is a provenance
+     * signal (a Material Bank identity), not a storefront; the channel-backed
+     * scopes (`"materialBankNaOrderable"`, `"materialBankEuOrderable"`,
+     * `"designShopOrderable"`) answer where a material can be ordered,
+     * `"materialBankNaAndCatalogue"` is a governed discovery corpus (the union
+     * of Material Bank North America and Catalogue editorial membership, not a
+     * buyability claim), and `"samplizeCatalogue"` admits published US Samplize
+     * paint colours, regardless of stock.
      */
     corpusScope?: CorpusScope;
+    /** Products per page (max 60). Absent, the search's own page size. */
+    limit?: number;
     /**
-     * OPS/AUDIT escape hatch — do NOT use for normal search. Default behaviour
-     * (absent or false) excludes sampling-artifact products: multi-swatch sample
-     * cards, which are orderable samples and never specifiable materials.
+     * The previous response's `cursor`, passed back verbatim. A cursor from
+     * another query (other words, filters or scope) is a 409.
      */
-    includeSamplingArtifacts?: boolean;
+    cursor?: Cursor;
+    /** Add `timings` and `explain.plan`, the plan the search ran on. */
+    explain?: boolean;
+    /** Result projection: `"full"` (default) or the lean `"card"` grid form. */
+    view?: OpenEnum<"full" | "card">;
 };
-/** Query-string params for the GET `/search` form. */
+/**
+ * Query-string params for the GET `/search` form. `category` and `filters`
+ * have no query-string form; send them through `search()`.
+ */
 export type SearchGetParams = {
     q?: string;
-    colours?: string;
-    logic?: OpenEnum<"all" | "any">;
-    mood?: string;
-    /** Governed corpus applied inside retrieval; absent means the whole graph. */
-    corpusScope?: CorpusScope;
-    sort?: OpenEnum<"relevance" | "light" | "dark" | "vivid" | "muted" | "colourful" | "name" | "name_desc" | "recent">;
-    tol?: OpenEnum<"tight" | "normal" | "loose">;
-    /** Seed the search from this variant's image. Opaque — pass it through verbatim. */
+    /** Seed the search from this variant's image. Opaque; pass it through verbatim. */
     variantId?: VariantId;
+    /** Corpus applied inside the index query; absent means the whole graph. */
+    corpusScope?: CorpusScope;
     limit?: number;
-    /** "0" or "1" — include per-signal `signals` on each result. */
-    explain?: OpenEnum<"0" | "1">;
-    /** "true" — opt in to a `counts.variants` feed total. */
-    count?: OpenEnum<"true">;
-    /** "true" — only return materials with at least one catalog image. */
-    hasImages?: OpenEnum<"true">;
-    /** Require a recorded accepted sampleable=true fact. */
-    sampleableOnly?: OpenEnum<"true" | "false">;
-    /** Result projection — `"full"` (default) or the lean `"card"` grid form. */
+    /** The previous response's `cursor`, passed back verbatim. */
+    cursor?: Cursor;
+    /** Result projection: `"full"` (default) or the lean `"card"` grid form. */
     view?: OpenEnum<"full" | "card">;
-    /**
-     * One JSON OBJECT, e.g. `{"attributeId":"price_tier","direction":"desc"}` —
-     * the `orderBy` field of the POST body, JSON-encoded because a query string
-     * has no nested values. Same spelling as `filters=` on `/search/browse`.
-     */
-    orderBy?: string;
-    /** Comma-separated attribute ids — the `returnAttributes` list. */
-    returnAttributes?: string;
+    /** `"1"` adds `timings` and `explain.plan`. */
+    explain?: OpenEnum<"0" | "1">;
 };

package/search-response-receipt-types.d.ts

@@ -1,280 +1,24 @@
 /**
  * @module sdk/search-response-receipt-types
- * @description Inspectable routing, compatibility, and compound-constraint
- * receipts emitted by ordinary Search responses.
+ * @description The ranking source and the explain-only plan receipt a Search
+ * response carries.
  */
+import type { SearchPlanReceipt } from "./search-index-plan-types.js";
 import type { OpenEnum } from "./types.js";
-/** Inspectable metadata for an opaque, principal-bound search refinement receipt. */
-export type SearchRefinementReceipt = {
-    token: string;
-    expiresAt: string;
-    poolSize: number;
-    schemaVersion: string;
-    projectionVersion: number;
-};
-/** The primary ranking source a query resolved to and reports as its mode. */
-export type SearchMode = OpenEnum<"image" | "colour" | "text" | "lexical" | "entity-browse" | "agent">;
-/**
- * Compatibility receipt for non-mode colour handling. Current one-signal
- * ordering reports it skipped at weight 0; colour may still be diagnostic or a
- * hard displayed-image constraint, but does not blend into score.
- */
-export type SearchRerankReport = {
-    colour?: OpenEnum<"ok" | "failed" | "skipped">;
-    colourWeight?: number;
-    colourLabel?: string;
-};
-/**
- * A part of the search that can fail without stopping it.
- *
- * Coarse on purpose: a caller needs to know that something did not answer, not
- * which provider it was. OPEN, and it will grow — read it with a default
- * branch.
- */
-export type SearchDegradedPart = OpenEnum<"filter-coverage" | "term-coverage">;
-/**
- * Which parts of the search did not answer, on EVERY response (MG-1913).
- *
- * `parts: []` says no part reported a failure. It does NOT promise every check
- * ran: a check the request never needed is skipped rather than failed. ABSENT
- * means the response came from a server that does not report this, never that
- * nothing was degraded.
- */
-export type SearchDegraded = {
-    parts: SearchDegradedPart[];
-};
-/** Stage counts retained when a search returns no results. */
-export type SearchEmptyOutcomeCounts = {
-    retrieved: number;
-    afterPrune: number;
-    final: number;
-};
-/**
- * Why a search returned no results, on EVERY empty response (MG-1911).
- *
- * `proven-corpus-empty` is exhaustive and is the only member that supports
- * telling someone the catalogue holds nothing. `unproven-empty` is an honest
- * end to a search that ran without establishing that. `search-degraded` means
- * part of the search did not answer, so the empty page describes the runtime
- * rather than the catalogue, and the right response is to retry.
- *
- * Read it by `kind` with a default branch: this union has grown once and the
- * reason and basis enums are open.
- */
-export type SearchEmptyOutcome = {
-    kind: "proven-corpus-empty";
-    basis: OpenEnum<"spec-allowlist" | "brand-scope" | "brand-product-type">;
-    exhaustive: true;
-    sourceEmpty?: boolean | null;
-    counts?: SearchEmptyOutcomeCounts;
-} | {
-    kind: "unproven-empty";
-    reason: OpenEnum<"allowlist-truncated" | "retrieval-window-not-exhaustive" | "source-empty" | "post-retrieval-rejected" | "pagination-empty" | "no-authoritative-empty-proof">;
-    sourceEmpty?: boolean | null;
-    counts?: SearchEmptyOutcomeCounts;
-} | {
-    kind: "search-degraded";
-    /** Which parts did not answer. Coarse: never a provider's name. */
-    parts: SearchDegradedPart[];
-    sourceEmpty?: boolean | null;
-    counts?: SearchEmptyOutcomeCounts;
-};
-/** Explain-only coverage of substantive query terms in the lexical projection. */
 /**
- * Which of the query's substantive words the catalogue holds at all
- * (MG-1858), on every text-family response. `terms` names the words found in
- * no document; `checkedTerms` is how many were asked about; `noneMatched` is
- * true when no checked word is attested anywhere. `unavailable` means the read
- * failed and never means everything matched; `skipped` means this mode never
- * claimed to match words.
- */
-export type SearchTermCoverageReceipt = {
-    status: OpenEnum<"covered" | "uncovered" | "unavailable" | "skipped">;
-    terms: string[];
-    checkedTerms: number;
-    noneMatched: boolean;
-    note?: string;
-};
-/** The Search workflow run a ledger receipt belongs to. */
-export type SearchRunRef = {
-    contextId: string;
-    runId: string;
-    schemaVersion: 1;
-};
-/** One artifact a Search workflow step read or wrote. */
-export type SearchRunArtifactRef = {
-    artifactId: string;
-    kind: string;
-    producedBy: string;
-    runRef: SearchRunRef;
-    schemaVersion: 1;
-};
-/** What one Search workflow step did: its reads, its write and its time. */
-export type SearchStageReceipt = {
-    stageId: string;
-    status: "succeeded";
-    /** The step's own work, excluding reading and writing its artifacts. */
-    durationMs: number;
-    inputArtifacts: SearchRunArtifactRef[];
-    outputArtifact: SearchRunArtifactRef;
-    inputCount: number | null;
-    outputCount: number | null;
-    runRef: SearchRunRef;
-    /** The outcome the step chose, when it chooses one. */
-    outcome?: string;
-    /** The arm a fork took and why. */
-    branch?: {
-        decision: string;
-        reason: string;
-    };
-};
-/** One ledger line: a step's receipt and its span since the run opened. */
-export type SearchRunLedgerEntry = {
-    receipt: SearchStageReceipt;
-    /** The nested workflows the step ran under, outermost first. */
-    workflowPath: string[];
-    startedAtMs: number;
-    endedAtMs: number;
-};
-/**
- * Outcome receipts shared by full and card search responses. `degraded`,
- * `emptyOutcome` and `termCoverage` are on every response; `diagnostics` and
- * `explain` are explain-only.
+ * What ordered the page: `image` (a look-alike), `colour` (colour distance
+ * inside the named colour's family), `lexical` (the query's words, by text
+ * rank on the index), `attribute` (the category and filters alone define the
+ * page) or `agent` (the search agent chose the variants and their order).
  */
+export type SearchMode = OpenEnum<"image" | "colour" | "lexical" | "agent" | "attribute">;
+/** The explain-only receipt shared by full and card search responses. */
 export type SearchResponseExplainReceipts = {
-    degraded?: SearchDegraded;
-    emptyOutcome?: SearchEmptyOutcome;
-    termCoverage?: SearchTermCoverageReceipt;
     /**
-     * The engine's notes written for an engineer (tier timings, cache states,
-     * index names), under `explain` only. `note` carries the reader's sentences
-     * alone (MG-1919).
-     */
-    diagnostics?: string[];
-    /**
-     * Present under `explain` when the Search workflow answered the request:
-     * every step receipt, in completion order. Absent when the engine answered.
+     * Present under `explain` only: the receipt of the plan the one search ran
+     * on, with the plan itself (ADR 0031). Diagnostic, like `timings`.
      */
     explain?: {
-        ledger: readonly SearchRunLedgerEntry[];
+        plan: SearchPlanReceipt;
     };
 };
-/** One stage in the explain-only ledger of transformations that actually ran. */
-export type SearchQueryTransformStage = {
-    stage: OpenEnum<"normalise" | "resolve-spec" | "resolve-paint" | "resolve-brand">;
-    applied: true;
-} | {
-    stage: OpenEnum<"normalise" | "resolve-spec" | "resolve-paint" | "resolve-brand">;
-    applied: false;
-    reason: string;
-};
-/** Explain-only category gate selected by query understanding. */
-export type SearchCategoryAnchor = {
-    /**
-     * A leaf type id; the group key when `source` is `"group"`; or the canonical
-     * category noun when `source` is `"head-noun"`. Gate on `productTypeIds`.
-     */
-    productTypeId: string;
-    /**
-     * The leaf type ids a `"group"` or `"head-noun"` anchor expanded to; absent
-     * for leaf sources.
-     */
-    productTypeIds?: readonly string[];
-    displayName: string;
-    similarity: number;
-    margin: number | null;
-    source: OpenEnum<"taxonomy" | "synonym" | "display-name" | "group" | "head-noun" | "vector">;
-    /** Hard category eligibility is applied inside lexical candidate selection. */
-    candidateSource?: OpenEnum<"lexical">;
-    applied: boolean;
-};
-/** Explain-only brand gate selected by query understanding. */
-export type SearchBrandAnchor = {
-    brandSlug: string;
-    brandName: string;
-    confidence: number;
-    margin: number | null;
-    tier: OpenEnum<"exact_id" | "exact_alias" | "lexical" | "semantic">;
-    variantCount: number;
-    applied: boolean;
-};
-/** A real brand candidate the engine deliberately declined to gate on. */
-export type SearchBrandSkip = {
-    reason: OpenEnum<"ambiguous" | "weak-tier" | "too-broad">;
-    candidates?: string[];
-};
-/**
- * EXPLAIN-only receipt of the query shape that executed. This is distinct from
- * the separate Search Plan compiler operation: it reports execution and never
- * causes it.
- */
-export type SearchExecutionPlan = {
-    grain: OpenEnum<"variant" | "product">;
-    /** Which 2048D Voyage projection served a text-mode request. */
-    textLane?: OpenEnum<"image-text" | "variant-text">;
-    weights: {
-        portrait: number;
-        image: number;
-        category: number;
-        colour: number;
-        lexical: number;
-        text: number;
-    };
-    queryTransform: SearchQueryTransformStage[];
-    /** Ordered, explain-only request-understanding execution trace. */
-    steps?: {
-        key: string;
-        status: OpenEnum<"executed" | "skipped">;
-        reason: string;
-        durationMs: number;
-    }[];
-    categoryAnchor?: SearchCategoryAnchor;
-    brandAnchor?: SearchBrandAnchor;
-    brandSkipped?: SearchBrandSkip;
-};
-/** Why a compound colour constraint returned a full or short page. */
-export type CompoundColourAbundanceReceipt = {
-    grain: OpenEnum<"variant" | "product">;
-    requested: number;
-    eligible: number;
-    candidateWindow: number;
-    sourceExhausted: boolean;
-    state: OpenEnum<"filled" | "corpus_scarcity" | "evidence_unavailable" | "retrieval_window_exhausted">;
-};
-/**
- * Eligibility proof for an explicit or taxonomy-backed colour inside a compound
- * text query. Counts describe the bounded candidate pool, not the whole corpus.
- */
-export type CompoundColourConstraintReceipt = {
-    basis: OpenEnum<"explicit" | "detected-strong">;
-    family: string;
-    queryHexes: string[];
-    considered: number;
-    kept: number;
-    dropped: number;
-    unknown: number;
-    adjacent: number;
-    abundance?: CompoundColourAbundanceReceipt;
-};
-/** Why a hard form constraint returned a full or short page. */
-export type CompoundFormAbundanceReceipt = {
-    grain: OpenEnum<"variant" | "product">;
-    requested: number;
-    eligible: number;
-    candidateWindow: number;
-    sourceExhausted: boolean;
-    state: OpenEnum<"filled" | "corpus_scarcity" | "evidence_unavailable" | "retrieval_window_exhausted">;
-};
-/**
- * Hard form eligibility for a compound text query. Product and variant names
- * may retrieve a candidate but never prove that it satisfies the form.
- */
-export type CompoundFormConstraintReceipt = {
-    instruction: OpenEnum<"subway" | "plank" | "square" | "hexagon" | "penny-round">;
-    considered: number;
-    kept: number;
-    dropped: number;
-    contradicted: number;
-    unknown: number;
-    abundance: CompoundFormAbundanceReceipt;
-};