@instruments/materialgraph 0.16.0 → 0.18.0

package/search-request-types.d.ts

@@ -32,8 +32,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 +100,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 +126,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.
@@ -156,7 +163,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 +173,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 +214,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. */

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

@@ -1,17 +1,55 @@
 /**
  * @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";
-/** The single candidate source a query resolved to. */
+/** 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">;
@@ -23,11 +61,22 @@ export type SearchQueryTransformStage = {
 };
 /** Explain-only category gate selected by query understanding. */
 export interface 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<"synonym" | "display-name" | "vector">;
+    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. */
@@ -52,7 +101,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;
@@ -60,6 +112,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;
@@ -78,7 +137,7 @@ export interface CompoundColourAbundanceReceipt {
  * text query. Counts describe the bounded candidate pool, not the whole corpus.
  */
 export interface CompoundColourConstraintReceipt {
-    provenance: OpenEnum<"explicit" | "detected-strong">;
+    basis: OpenEnum<"explicit" | "detected-strong">;
     family: string;
     queryHexes: string[];
     considered: number;
@@ -88,3 +147,25 @@ export interface CompoundColourConstraintReceipt {
     adjacent: number;
     abundance?: CompoundColourAbundanceReceipt;
 }
+/** Why a hard form constraint returned a full or short page. */
+export interface 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 interface CompoundFormConstraintReceipt {
+    instruction: OpenEnum<"subway" | "plank" | "square" | "hexagon" | "penny-round">;
+    considered: number;
+    kept: number;
+    dropped: number;
+    contradicted: number;
+    unknown: number;
+    abundance: CompoundFormAbundanceReceipt;
+}

package/search-result-validation.js

@@ -49,6 +49,23 @@ function checkPaletteSwatch(value, what, fail) {
     if (record.name !== undefined)
         requireNullableString(record.name, `${what}.name`, fail);
 }
+/**
+ * `variants[]` — one entry of a product-collapsed result's ranked variant list
+ * (`collapsedVariantSchema`). A SLIM projection, not a nested result item: the
+ * checks here are the whole shape.
+ */
+function checkCollapsedVariant(value, what, fail) {
+    const record = requireRecord(value, what, fail);
+    requireString(record.variantId, `${what}.variantId`, fail);
+    requireNullableString(record.variantName, `${what}.variantName`, fail);
+    requireNullableString(record.color, `${what}.color`, fail);
+    // `.optional()`, NOT nullable: the emit path omits the key when no palette is
+    // on record rather than sending null.
+    requireOptionalString(record.hex, `${what}.hex`, fail);
+    requireNullableString(record.imageUrl, `${what}.imageUrl`, fail);
+    requireOptionalString(record.materialBankId, `${what}.materialBankId`, fail);
+    requireNumber(record.score, `${what}.score`, fail);
+}
 /** `colourMeta` — three independently optional strings. */
 function checkColourMeta(value, what, fail) {
     const record = requireRecord(value, what, fail);
@@ -56,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);
     }
@@ -192,6 +212,10 @@ export function checkSearchResultItem(value, what, fail) {
     if (record.siblingCount !== undefined) {
         requireIntegerAtLeast(record.siblingCount, `${what}.siblingCount`, fail, 1);
     }
+    if (record.variants !== undefined) {
+        const variants = requireArray(record.variants, `${what}.variants`, fail);
+        variants.forEach((variant, index) => checkCollapsedVariant(variant, `${what}.variants[${index}]`, fail));
+    }
     if (record.visualMeanings !== undefined) {
         const meanings = requireArray(record.visualMeanings, `${what}.visualMeanings`, fail);
         meanings.forEach((meaning, index) => checkVisualMeaning(meaning, `${what}.visualMeanings[${index}]`, fail));

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/spec-types.d.ts

@@ -70,10 +70,16 @@ export interface SpecTermFilter {
  * {@link CERTIFICATION_PROGRAMME_ATTRIBUTE_ID} (a programme is matched by name,
  * never by bare presence).
  */
-export interface SpecPresenceFilter {
+export type SpecPresenceFilter = {
     attributeId: string;
     hasValue: true;
 }
+/** Date-sensitive presence is currently executable only for EPD expiration. */
+ | {
+    attributeId: "epd_expiration_date";
+    hasValue: true;
+    asOf: string;
+};
 /**
  * A certification-programme criterion — a {@link SpecTermFilter} pinned to the
  * virtual {@link CERTIFICATION_PROGRAMME_ATTRIBUTE_ID}. Structurally assignable

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/types.d.ts

@@ -30,8 +30,9 @@ import type { CorpusScopeReceipt } from "./corpus-scope-types.js";
 import type { Cursor, ProductId, VariantId } from "./identifiers.js";
 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, SearchExecutionPlan, SearchMode, SearchRerankReport } from "./search-response-receipt-types.js";
+import type { CompoundColourConstraintReceipt, CompoundFormConstraintReceipt, SearchExecutionPlan, SearchMode, 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 OpenEnum<T extends string> = T | (string & {});
@@ -89,11 +90,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. */
@@ -107,15 +110,6 @@ export interface VisualMeaning {
     version?: string;
     appliedAt?: string;
 }
-/** One member of a collapsed result's {@link SearchResultItem.anatomy}. */
-export interface SearchAnatomyMember {
-    /** Opaque — round-trip verbatim. */
-    variantId: VariantId;
-    variantName: string | null;
-    color: string | null;
-    score: number;
-    signals: SearchResultSignals;
-}
 /**
  * One material in a search / match result list.
  *
@@ -198,7 +192,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
@@ -248,7 +242,10 @@ export interface SearchResultItem {
      * `includeBelowFloor`.
      */
     admittedOnColour?: boolean;
+    /** Variants HIDDEN behind this card by `collapse: "product"` — the COMPLETE tally, even when {@link variants} is capped. */
     siblingCount?: number;
+    /** The product's matching variants, MOST RELEVANT FIRST — present exactly under `collapse: "product"`, capped, and led by the group's RANKING representative, which is NOT always this item. {@link CollapsedVariant} states the full contract. */
+    variants?: CollapsedVariant[];
     visualMeanings?: VisualMeaning[];
     /**
      * The shared report card for this hit against the request's `filters` (required
@@ -403,20 +400,19 @@ 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[];
     suggestions: SearchSuggestion[];
     mode: SearchMode;
     maxScore: number;
-    /** Opaque keyset for the next page. Absent = end of the walk, not an error. */
     cursor?: Cursor;
-    /** Boundedness and retrieval-cost receipt on current Search responses. */
     window?: SearchWindowReceipt;
     rerank?: SearchRerankReport;
-    /** Hard compound-colour eligibility and abundance receipt, when applied. */
+    /** Hard compound eligibility and abundance receipts, when applied. */
     colourConstraint?: CompoundColourConstraintReceipt;
+    formConstraint?: CompoundFormConstraintReceipt;
     /** Explain-only receipt of the query shape and transform ledger that ran. */
     plan?: SearchExecutionPlan;
     counts?: SearchCounts;
@@ -443,8 +439,9 @@ export interface SearchResponse {
     /** A detected mood term overridden by a stronger colour reading. */
     supersededMoodId?: string;
     /**
-     * Present when the query had TWO defensible readings. Says which one ran and
-     * offers the other as a complete executable request.
+     * Present when the query had multiple defensible readings. Says which one
+     * ran, or leaves every reading non-default when the engine chose none. Every
+     * reading carries a complete executable replacement request.
      */
     disambiguation?: SearchDisambiguation;
     /** Structured receipt of the standard query-understanding decisions. */