@instruments/materialgraph 0.18.0 → 0.20.0

package/types.d.ts

@@ -1,3 +1,4 @@
+import type { ResponseAttribution } from "./attribution-types.js";
 import type { BySpecVerdict } from "./by-spec-types.js";
 /**
  * Hand-mirrored wire types for the MaterialGraph public API (spec 0.5.0).
@@ -31,19 +32,14 @@ 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 { MoodInterpretation } from "./search-mood-types.js";
 import type { SearchDisambiguation, SearchSuggestion } from "./search-refinement-types.js";
-import type { CompoundColourConstraintReceipt, CompoundFormConstraintReceipt, SearchExecutionPlan, SearchMode, SearchRerankReport, SearchResponseExplainReceipts } 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.
@@ -120,6 +116,10 @@ export interface VisualMeaning {
  * `visualMeanings` is not "this material has no visual meaning".
  */
 export interface SearchResultItem {
+    /** This hit's attribution key — see {@link ResponseAttribution}. Opaque. */
+    resultId?: string;
+    /** Accepted sampleability fact. Absent means unknown, never false. */
+    sampleable?: boolean;
     /** Opaque — round-trip verbatim into `material()`, `pairings()`, `similarTo`. */
     variantId: VariantId;
     brand: string;
@@ -134,7 +134,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;
@@ -267,40 +267,6 @@ export interface SearchResultItem {
      */
     attributes?: Record<string, string | string[] | null>;
 }
-/**
- * The lean `view:"card"` result item — identity + name + thumbnail + score.
- *
- * A PROJECTION, not a smaller answer: a field the card omits (palette, verdict,
- * signals, availability) is unread here, never known-absent. Re-read the same
- * `variantId` at `view: "full"` or via `material()` before claiming anything the
- * card does not carry.
- */
-export interface SearchCardItem {
-    /** Opaque — round-trip verbatim. */
-    variantId: VariantId;
-    productId: ProductId | null;
-    brandSlug: string | null;
-    brand: string;
-    /** Product name (the full item's `product`). */
-    name: string;
-    variantName: string | null;
-    imageUrl: string | null;
-    projectSaveCapability?: "allowed";
-    sourceStatus?: "provisional";
-    score: number;
-    /**
-     * Resolved values for the attribute ids sent in `returnAttributes`, keyed by
-     * attribute id. ABSENT entirely when `returnAttributes` was not sent.
-     *
-     * Three states, all different, and reading them as two is the mistake this
-     * shape exists to prevent: no `attributes` key means you did not ask; a key
-     * whose value is `null` means this material carries no accepted value for that
-     * attribute; anything else is what the graph holds. Values resolve with the
-     * normal variant-over-product precedence, and an array is a multi-valued
-     * attribute rather than a list of candidates.
-     */
-    attributes?: Record<string, string | string[] | null>;
-}
 /**
  * A feed total with its honesty basis — THE CLAIM ABOUT THE MATCH SET, which is
  * a different number from `results.length` (this page).
@@ -380,14 +346,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
@@ -401,11 +359,29 @@ export interface SearchRefinementReceipt {
  * wrong whenever `limit` was 24.
  */
 export interface SearchResponse extends SearchResponseExplainReceipts {
+    /** Result attribution — see {@link ResponseAttribution}. `basis` is `mode` verbatim here. */
+    attribution?: ResponseAttribution;
     view: OpenEnum<"full" | "card">;
     /** THIS PAGE. Its length is a page size, never a total. */
     results: SearchResultItem[];
     suggestions: SearchSuggestion[];
     mode: SearchMode;
+    /**
+     * Which dense text lane answered, when one did (MG-1796). `image-text` — the
+     * query carried evidence it describes appearance, so it was ranked against
+     * image vectors; `variant-text` — ranked against each variant's written
+     * portrait.
+     *
+     * ABSENT means the answer did not come from the dense text arm at all: `mode`
+     * was never `text`, or the text arm resolved without a lane. Absence is
+     * UNKNOWN and never a default of `image-text` — treating it as one asserts a
+     * dense reading of a lexical, colour or browse answer. Absent too from any
+     * response produced by a server predating MG-1793.
+     *
+     * An {@link OpenEnum} because the lane vocabulary can grow: a value you do
+     * not recognise is a lane this client predates, not a malformed response.
+     */
+    textLane?: OpenEnum<"image-text" | "variant-text">;
     maxScore: number;
     cursor?: Cursor;
     window?: SearchWindowReceipt;
@@ -438,6 +414,11 @@ export interface SearchResponse extends SearchResponseExplainReceipts {
     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?: 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
@@ -458,11 +439,6 @@ export interface SearchResponse extends SearchResponseExplainReceipts {
     /** A `getVariantBrief` echo of the seed variant, present only in `variantId` seed mode. */
     seed?: MaterialTile | Record<string, unknown>;
 }
-/** The `view:"card"` response form — the lean grid projection of {@link SearchResponse}. */
-export interface SearchCardResponse extends Omit<SearchResponse, "view" | "results"> {
-    view: OpenEnum<"card">;
-    results: SearchCardItem[];
-}
 export type ColourDictionaryId = OpenEnum<"colour_family" | "colour_mood" | "colour_undertone">;
 export interface ColourFacetTerm {
     id: string;
@@ -611,6 +587,13 @@ export interface PairingsResponse {
      * check it before presenting the rail as demand evidence.
      */
     cospecCount: number;
+    /**
+     * Candidates dropped at hydration for violating the material contract
+     * (MG-985). Present ONLY when > 0. A non-zero count means the rail is
+     * shorter than the evidence behind it — read it before calling the rail
+     * complete.
+     */
+    skippedCandidates?: number;
     /** Present only when `order` was requested. Evidence tiers remain independent. */
     ordering?: PairingOrdering;
     /** Opaque continuation bound to the seed, filters, corpus, and order. */
@@ -713,6 +696,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`. */