@instruments/materialgraph 0.17.0 → 0.19.0

package/search-request-types.d.ts

@@ -1,3 +1,4 @@
+/** 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
@@ -32,8 +33,8 @@ export interface SearchInput {
     };
     mood?: string;
     /**
-     * Re-order the final scored results. `relevance` (default) keeps the fused
-     * score; `light` / `dark` / `vivid` / `muted` / `colourful` are the colour
+     * 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.
@@ -100,12 +101,18 @@ export interface SearchInput {
         boost?: string;
         filter?: string[];
     };
+    /**
+     * 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.
+     */
     weights?: {
         image?: number;
         category?: number;
         colour?: number;
         lexical?: number;
-        /** Text rerank multiplier applied when a seeded search also carries `text` (default 0.4). */
+        /** Compatibility field; seeded text does not activate secondary scoring. */
         text?: number;
     };
     filters?: SearchFilter[];
@@ -120,6 +127,7 @@ export interface SearchInput {
     /** 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.
@@ -141,6 +149,8 @@ export interface SearchInput {
     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
@@ -156,7 +166,7 @@ export interface SearchInput {
      * `"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, category boost, colour rerank, refinement suggestions,
+     * semantic fallback, secondary scoring, refinement suggestions,
      * counts, or meanings. `textModes` is ignored under typeahead.
      */
     intent?: OpenEnum<"search" | "typeahead">;
@@ -166,22 +176,26 @@ export interface SearchInput {
      * **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 scopes gate on CHANNEL membership, which is what "can someone buy
-     * this" means: `"materialBankNaOrderable"` (Material Bank North America,
+     * 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 three above.
+     * orderable, use one of the channel-backed scopes above.
      *
-     * A scope answers what is BUYABLE. It never answers what is SUITABLE: scope
-     * on channel, then refine on sector. A trade-only material can be right for a
-     * room and still unbuyable, and most of what a consumer can buy is
-     * commercial-suited product.
+     * 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.
@@ -203,6 +217,8 @@ export interface SearchGetParams {
     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. */
@@ -214,6 +230,8 @@ export interface SearchGetParams {
     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. */
     view?: OpenEnum<"full" | "card">;
     /**

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

@@ -1,17 +1,63 @@
 /**
  * @module sdk/search-response-receipt-types
- * @description Inspectable routing, rerank, and compound-constraint receipts
- * emitted by ordinary Search responses.
+ * @description Inspectable routing, compatibility, and compound-constraint
+ * receipts emitted by ordinary Search responses.
  */
 import type { OpenEnum } from "./types.js";
+/** Inspectable metadata for an opaque, principal-bound search refinement receipt. */
+export interface 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">;
-/** Rerank-term report (absent in colour mode — there colour IS the source). */
+/**
+ * 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 interface SearchRerankReport {
     colour?: OpenEnum<"ok" | "failed" | "skipped">;
     colourWeight?: number;
     colourLabel?: string;
 }
+/** Stage counts retained when an explain-enabled search returns no results. */
+export interface SearchEmptyOutcomeCounts {
+    retrieved: number;
+    afterPrune: number;
+    final: number;
+}
+/**
+ * Explain-only evidence for why a completed search returned no results.
+ * `proven-corpus-empty` is exhaustive; every other empty remains explicitly
+ * unproven rather than being presented as catalogue absence.
+ */
+export type SearchEmptyOutcome = {
+    kind: "proven-corpus-empty";
+    basis: OpenEnum<"spec-allowlist" | "brand-scope">;
+    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;
+};
+/** Explain-only coverage of substantive query terms in the lexical projection. */
+export interface SearchTermCoverageReceipt {
+    status: OpenEnum<"covered" | "uncovered" | "unavailable" | "skipped">;
+    terms: string[];
+    note?: string;
+}
+/** Explain-only outcome receipts shared by full and card search responses. */
+export interface SearchResponseExplainReceipts {
+    emptyOutcome?: SearchEmptyOutcome;
+    termCoverage?: SearchTermCoverageReceipt;
+}
 /** One stage in the explain-only ledger of transformations that actually ran. */
 export type SearchQueryTransformStage = {
     stage: OpenEnum<"normalise" | "resolve-spec" | "resolve-paint" | "resolve-brand">;
@@ -63,7 +109,10 @@ export interface SearchBrandSkip {
  */
 export interface 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;
@@ -71,6 +120,13 @@ export interface SearchExecutionPlan {
         text: number;
     };
     queryTransform: SearchQueryTransformStage[];
+    /** Ordered, explain-only request-understanding execution trace. */
+    steps?: Array<{
+        key: string;
+        status: OpenEnum<"executed" | "skipped">;
+        reason: string;
+        durationMs: number;
+    }>;
     categoryAnchor?: SearchCategoryAnchor;
     brandAnchor?: SearchBrandAnchor;
     brandSkipped?: SearchBrandSkip;

package/search-result-validation.js

@@ -73,9 +73,12 @@ function checkColourMeta(value, what, fail) {
     requireOptionalString(record.dominantFamily, `${what}.dominantFamily`, fail);
     requireOptionalString(record.dominantHex, `${what}.dominantHex`, fail);
 }
-/** `searchResultSignalsSchema` — five nullable numbers, all required keys. */
+/** `searchResultSignalsSchema` — five required scores plus additive portrait. */
 function checkSignals(value, what, fail) {
     const record = requireRecord(value, what, fail);
+    if (record.portrait !== undefined) {
+        requireNullableNumber(record.portrait, `${what}.portrait`, fail);
+    }
     for (const signal of ["image", "category", "colour", "lexical", "text"]) {
         requireNullableNumber(record[signal], `${what}.${signal}`, fail);
     }
@@ -140,6 +143,15 @@ function checkAttributeVerdict(value, what, fail) {
     requireNullableString(record.value, `${what}.value`, fail);
     requireNullableBoundedNumber(record.confidence, `${what}.confidence`, fail, 0, 1);
     requireNullableString(record.sourceBasis, `${what}.sourceBasis`, fail);
+    if (record.citation !== undefined) {
+        const citation = requireRecord(record.citation, `${what}.citation`, fail);
+        requireNonEmptyString(citation.citationId, `${what}.citation.citationId`, fail);
+        requireNonEmptyString(citation.sourceType, `${what}.citation.sourceType`, fail);
+        const count = requireNumber(citation.count, `${what}.citation.count`, fail);
+        if (!Number.isInteger(count) || count <= 0) {
+            throw fail(`${what}.citation.count must be a positive integer`);
+        }
+    }
     const deviation = record.deviation;
     if (deviation !== null)
         checkVerdictDeviation(deviation, `${what}.deviation`, fail);
@@ -204,6 +216,7 @@ export function checkSearchResultItem(value, what, fail) {
     if (record.signals !== undefined)
         checkSignals(record.signals, `${what}.signals`, fail);
     requireOptionalBoolean(record.retired, `${what}.retired`, fail);
+    requireOptionalBoolean(record.sampleable, `${what}.sampleable`, fail);
     requireOptionalBoolean(record.belowFloor, `${what}.belowFloor`, fail);
     requireOptionalBoolean(record.admittedOnColour, `${what}.admittedOnColour`, fail);
     if (record.siblingCount !== undefined) {

package/search-window-types.d.ts

@@ -4,14 +4,22 @@ export interface SearchWindowReceipt {
     profile: "interactive-r1" | (string & {});
     /** Candidate depth used by the final retrieval. */
     candidateTier: number;
-    /** Every candidate retrieval, including required fallbacks and optional recovery. */
+    /** Candidate retrieval count; `searchMaterials` reports exactly one selected retrieval. */
     retrievalRounds: number;
     /** Candidate-retrieval wall time only, in milliseconds. */
     retrievalMs: number;
     /** True when the serving source proved there were no more candidates. */
     exhaustive: boolean;
-    /** True when product-grain scarcity caused one jump to the deep ceiling. */
-    deepened: boolean;
-    /** True when a still-short page exhausted its bounded recovery allowance. */
-    budgetExhausted: boolean;
+    /**
+     * Candidate attrition through the selected retrieval source. Absent when the
+     * response path did not perform ordinary retrieval (for example typeahead).
+     */
+    candidateCounts?: {
+        /** Provider-returned matches before bounded selection; null for SQL/exact arms. */
+        rawProviderMatches: number | null;
+        /** Matches selected from that provider response; null for SQL/exact arms. */
+        selectedMatches: number | null;
+        /** Canonical candidates returned by the selected retrieval arm. */
+        hydratedCanonicalCandidates: number;
+    };
 }

package/slot-pool-types.d.ts

@@ -25,6 +25,7 @@
  * TOLERANT-PARSING CONTRACT: response enums are widened with {@link OpenEnum}
  * so a new server value still type-checks; objects are read structurally.
  */
+import type { VerdictCitation } from "./citation-types.js";
 import type { VariantId } from "./identifiers.js";
 import type { OpenEnum } from "./types.js";
 /**
@@ -147,6 +148,7 @@ export interface SlotPoolVerdictCell {
      */
     sourceBasis: string | null;
     trustGap: OpenEnum<"below_confidence" | "basis_unmet" | "proposed"> | null;
+    citation?: VerdictCitation;
 }
 /** Why a candidate is labelled. An eligible candidate carries none of these. */
 export type SlotPoolFlag = OpenEnum<"below-floor" | "required-not-applied" | "discontinued" | "superseded" | "unverified-value">;

package/spec-types.d.ts

@@ -64,6 +64,11 @@ export interface SpecTermFilter {
     attributeId: string;
     term: string;
 }
+/** A negative spec criterion; absence of a value remains unproven. */
+export interface SpecExclusionFilter {
+    attributeId: string;
+    excludesTerm: string;
+}
 /**
  * A presence spec criterion: the attribute must have ANY accepted value —
  * "has an EPD on record", "has a measured slip figure at all". Not supported for
@@ -94,4 +99,4 @@ export interface CertificationProgrammeFilter {
  * presence check. The union the search engine applies as a restriction BEFORE
  * ranking. Identical in shape to the SDK's `SearchFilter`.
  */
-export type SpecFilter = SpecTermFilter | SpecPresenceFilter;
+export type SpecFilter = SpecTermFilter | SpecExclusionFilter | SpecPresenceFilter;

package/specifications.d.ts

@@ -14,7 +14,9 @@
  * hand-format the `attribute:value` string the `bySpec` route splits on its
  * first `:`.
  */
-import { type CertificationProgrammeFilter, type SpecPresenceFilter, type SpecTermFilter } from "./spec-types.js";
+import { type CertificationProgrammeFilter, type SpecExclusionFilter, type SpecPresenceFilter, type SpecTermFilter } from "./spec-types.js";
+/** A hard criterion excluding one known canonical value while retaining only variants with known values. */
+export declare function excludeSpec(attributeId: string, excludesTerm: string): SpecExclusionFilter;
 /**
  * A term-equality criterion for `search({ filters })` — the attribute must
  * carry this canonical value.

package/specifications.js

@@ -15,6 +15,10 @@
  * first `:`.
  */
 import { CERTIFICATION_PROGRAMME_ATTRIBUTE_ID, } from "./spec-types.js";
+/** A hard criterion excluding one known canonical value while retaining only variants with known values. */
+export function excludeSpec(attributeId, excludesTerm) {
+    return { attributeId, excludesTerm };
+}
 /**
  * A term-equality criterion for `search({ filters })` — the attribute must
  * carry this canonical value.

package/substitute-types.d.ts

@@ -0,0 +1,75 @@
+import type { BySpecVerdict } from "./by-spec-types.js";
+import type { VariantId } from "./identifiers.js";
+import type { MaterialSuccessor } from "./material-types.js";
+export type SubstituteSignatureFamily = "textile" | "tile" | "coating" | "lighting_electrical" | "acoustic" | "surface" | "furniture" | "sanitaryware" | "fittings" | "architectural_hardware";
+export interface SubstituteSignatureCriterion {
+    role: "primary_material" | "performance";
+    attributeId: string;
+    term: string;
+}
+export interface AvailableSubstituteSignature {
+    family: SubstituteSignatureFamily;
+    form: string;
+    criteria: [SubstituteSignatureCriterion, SubstituteSignatureCriterion];
+}
+export interface UnsupportedSubstituteSignature {
+    family: SubstituteSignatureFamily;
+    form: string;
+    reason: string;
+}
+export interface InsufficientSubstituteSignature {
+    family: SubstituteSignatureFamily;
+    form: string;
+    missingRoles: ("primary_material" | "performance")[];
+}
+export interface FindSubstitutesOptions {
+    excludeBrands?: string[];
+    diversityBoost?: number;
+    limit?: number;
+    cursor?: string;
+    includeSamplingArtifacts?: boolean;
+    includeUnavailable?: boolean;
+}
+export interface SubstituteMatchedCriterion {
+    attributeId: string;
+    confidence: number | null;
+    sourceBasis: string | null;
+}
+export interface SubstituteResultItem {
+    variantId: VariantId;
+    brandSlug: string;
+    brand: string;
+    product: string;
+    variant: string;
+    color: string | null;
+    imageUrl: string | null;
+    hex: string | null;
+    matched: SubstituteMatchedCriterion[];
+    minConfidence: number | null;
+    baseScore: number;
+    diversityAdjustment: number;
+    score: number;
+    verdict: BySpecVerdict;
+}
+export interface AvailableSubstitutesResponse {
+    status: "available";
+    signatureUsed: AvailableSubstituteSignature;
+    items: SubstituteResultItem[];
+    candidatePoolSize: number;
+    droppedUnavailable: number;
+    supersededBy: MaterialSuccessor | null;
+    nextCursor?: string;
+}
+export interface UnsupportedSubstitutesResponse {
+    status: "unsupported";
+    signature: UnsupportedSubstituteSignature;
+    items: [];
+    supersededBy: MaterialSuccessor | null;
+}
+export interface InsufficientSubstitutesResponse {
+    status: "insufficient_signature";
+    signature: InsufficientSubstituteSignature;
+    items: [];
+    supersededBy: MaterialSuccessor | null;
+}
+export type FindSubstitutesResponse = AvailableSubstitutesResponse | UnsupportedSubstitutesResponse | InsufficientSubstitutesResponse;

package/substitute-types.js

@@ -0,0 +1 @@
+export {};

package/suggest-types.d.ts

@@ -12,6 +12,7 @@
  * `mg.searchVocabulary()` covers attribute/value tokens. Suggestions are a page
  * of the best matches, never a census of matching entities.
  */
+import type { CorpusScope, CorpusScopeReceipt } from "./corpus-scope-types.js";
 /** Which kind of entity a suggestion is — and therefore what `refId` means. */
 export type SuggestKind = "product" | "brand" | "category";
 /** How the query met the suggestion's label. Strongest first. */
@@ -44,6 +45,8 @@ export interface SuggestResponse {
     query: string;
     /** Ranked best-match-first. Empty when nothing came close — a miss, not an error. */
     suggestions: Suggestion[];
+    /** Present only when a narrowing governed corpus was applied. */
+    corpusScope?: CorpusScopeReceipt;
 }
 /** Options for {@link MaterialGraphClient.suggest}. */
 export interface SuggestOptions {
@@ -51,6 +54,8 @@ export interface SuggestOptions {
     limit?: number;
     /** Restrict to these kinds. Omit for all of them. */
     kind?: SuggestKind | SuggestKind[];
+    /** Governed corpus membership; absent means the whole graph. */
+    corpusScope?: CorpusScope;
 }
 /**
  * Shape the query string for a suggest call.
@@ -64,4 +69,5 @@ export declare function suggestQuery(q: string, options?: SuggestOptions): {
     q: string;
     limit?: number;
     kind?: string;
+    corpusScope?: CorpusScope;
 };

package/suggest-types.js

@@ -24,5 +24,5 @@ export function suggestQuery(q, options) {
     const kind = Array.isArray(options?.kind)
         ? options.kind.join(",")
         : options?.kind;
-    return { q, limit: options?.limit, kind };
+    return { q, limit: options?.limit, kind, corpusScope: options?.corpusScope };
 }

package/taxonomy-coverage-types.d.ts

@@ -0,0 +1,34 @@
+/** Exact, source-path-grained status coverage for primary product typing. */
+export interface ProductTypeStatusCoverageCounts {
+    variants: number;
+    accepted: number;
+    proposed: number;
+    proposedBelowThreshold: number;
+    /** Proposed rows with no confidence remain explicit rather than thresholded. */
+    proposedUnknownConfidence: number;
+    otherStatus: number;
+    missingPrimary: number;
+}
+export interface ProductTypeStatusCoverageSourcePath extends ProductTypeStatusCoverageCounts {
+    /** Complete stored source path; null means the product retained no path. */
+    sourcePath: string | null;
+}
+/** Current primary-assignment coverage, never an inferred acceptance decision. */
+export interface ProductTypeStatusCoverage {
+    computedAt: string;
+    basis: {
+        count: "exact";
+        universe: "non_superseded_variants";
+        assignment: "variant_primary_only";
+        sourcePath: "products.source_category_path";
+        /** Reporting cutoff only: higher-confidence proposals remain proposed. */
+        comparisonThreshold: number;
+    };
+    totals: ProductTypeStatusCoverageCounts;
+    sourcePaths: ProductTypeStatusCoverageSourcePath[];
+}
+export interface ProductTypeCoverageOptions {
+    [key: string]: number | undefined;
+    /** Reporting cutoff in [0,1], default 0.85; it never accepts a proposal. */
+    comparisonThreshold?: number;
+}

package/taxonomy-coverage-types.js

@@ -0,0 +1 @@
+export {};

package/types.d.ts

@@ -32,18 +32,12 @@ import type { MaterialDetail, MaterialTile } from "./material-types.js";
 import type { QueryUnderstanding } from "./query-understanding-types.js";
 import type { CollapsedVariant, SearchAnatomyMember } from "./search-collapse-types.js";
 import type { SearchDisambiguation, SearchSuggestion } from "./search-refinement-types.js";
-import type { CompoundColourConstraintReceipt, CompoundFormConstraintReceipt, SearchExecutionPlan, SearchMode, SearchRerankReport } from "./search-response-receipt-types.js";
+import type { CompoundColourConstraintReceipt, CompoundFormConstraintReceipt, SearchExecutionPlan, SearchMode, SearchRefinementReceipt, SearchRerankReport, SearchResponseExplainReceipts } from "./search-response-receipt-types.js";
 import type { SearchWindowReceipt } from "./search-window-types.js";
 export type * from "./search-response-receipt-types.js";
+export type { MoodInterpretation } from "./search-mood-types.js";
 export type OpenEnum<T extends string> = T | (string & {});
-/**
- * A JSON value, recursively — exactly what survives a `jsonb` round-trip
- * unchanged. Used where a payload's SHAPE belongs to its producer but its values
- * must still be JSON: `Date`, `bigint`, `undefined`, and functions are not.
- */
-export type JsonValue = string | number | boolean | null | JsonValue[] | {
-    [key: string]: JsonValue;
-};
+export type { JsonValue } from "./json-value-types.js";
 /**
  * One palette swatch of a material's main image — colour DERIVED FROM PRODUCT
  * IMAGERY, so read it as visual likeness, never as a declared colour spec.
@@ -90,11 +84,13 @@ export type ImageSource = OpenEnum<"r2" | "origin">;
 export type { DimensionEntry, MaterialAvailability, MaterialDetail, MaterialFacet, MaterialSuccessor, MaterialTile, } from "./material-types.js";
 /** Per-signal scores, present on a result when `explain` was requested. */
 export interface SearchResultSignals {
+    /** Voyage similarity in the dedicated variant text-portrait space. */
+    portrait?: number | null;
     image: number | null;
     category: number | null;
     colour: number | null;
     lexical: number | null;
-    /** Text→image RERANK cosine — non-null only for a seeded search carrying `text`. */
+    /** Compatibility slot for retired seeded secondary scoring; currently null. */
     text: number | null;
 }
 /** An accepted/measured visual meaning — descriptive evidence, never a ranking cause. */
@@ -118,6 +114,8 @@ export interface VisualMeaning {
  * `visualMeanings` is not "this material has no visual meaning".
  */
 export interface SearchResultItem {
+    /** Accepted sampleability fact. Absent means unknown, never false. */
+    sampleable?: boolean;
     /** Opaque — round-trip verbatim into `material()`, `pairings()`, `similarTo`. */
     variantId: VariantId;
     brand: string;
@@ -132,7 +130,7 @@ export interface SearchResultItem {
      * Populated on EVERY lane: `search()` (all four arms), `match()`, and
      * `matchStream()` frames.
      * ABSENT means no MB identity is known for the variant — never that the SKU
-     * cannot be ordered. Presence is the orderability tell; absence is silence.
+     * cannot be ordered. Presence identifies the source; it does not establish sampleability.
      */
     materialBankId?: string;
     manufacturerCode?: string;
@@ -190,7 +188,7 @@ export interface SearchResultItem {
         siblings?: SearchAnatomyMember[];
         siblingsTruncated?: boolean;
     };
-    /** Fused score — range [0, sum of active weights]; see `maxScore`. */
+    /** Selected mode's weighted primary score; see `maxScore`. */
     score: number;
     /**
      * Match only. How close this material is to the query, as an ABSOLUTE
@@ -274,6 +272,8 @@ export interface SearchResultItem {
  * card does not carry.
  */
 export interface SearchCardItem {
+    /** Accepted sampleability fact. Absent means unknown, never false. */
+    sampleable?: boolean;
     /** Opaque — round-trip verbatim. */
     variantId: VariantId;
     productId: ProductId | null;
@@ -378,14 +378,6 @@ export interface SearchFacets {
     absent: SearchAbsentFacet[];
     counts: Record<string, SearchFacetCount>;
 }
-/** Inspectable metadata for an opaque, principal-bound search refinement receipt. */
-export interface SearchRefinementReceipt {
-    token: string;
-    expiresAt: string;
-    poolSize: number;
-    schemaVersion: string;
-    projectionVersion: number;
-}
 /**
  * The search response envelope. `view` discriminates the `results` union:
  * `"full"` (default) carries {@link SearchResultItem}s, `"card"` the lean
@@ -398,7 +390,7 @@ export interface SearchRefinementReceipt {
  * you asked for it. Follow `cursor` for the rest. "I found 24 materials" is
  * wrong whenever `limit` was 24.
  */
-export interface SearchResponse {
+export interface SearchResponse extends SearchResponseExplainReceipts {
     view: OpenEnum<"full" | "card">;
     /** THIS PAGE. Its length is a page size, never a total. */
     results: SearchResultItem[];
@@ -436,6 +428,11 @@ export interface SearchResponse {
     timings?: Record<string, number>;
     /** A detected mood term overridden by a stronger colour reading. */
     supersededMoodId?: string;
+    /**
+     * Explicit standard-search mood reading; null ids mean no selected mood.
+     * Absent when mood was not evaluated or an older server produced the result.
+     */
+    moodInterpretation?: import("./search-mood-types.js").MoodInterpretation;
     /**
      * Present when the query had multiple defensible readings. Says which one
      * ran, or leaves every reading non-default when the engine chose none. Every
@@ -711,6 +708,8 @@ export interface PairingsOptions {
     categories?: string;
     /** Page size, 1–24 inclusive (default 12). The server rejects (400), not clamps, values outside this range. */
     limit?: number;
+    /** Return sampled order evidence only, without board or colour fallback. */
+    sampledOnly?: boolean;
     /** Graph-owned order applied within fixed cospec → considered → colour tiers. */
     order?: PairingOrderMode;
     /** Optional Material Bank/orderable gate; requires an explicit `order`. */