@instruments/materialgraph 0.19.0 → 0.21.0

package/substitute-types.d.ts

@@ -57,6 +57,33 @@ export interface AvailableSubstitutesResponse {
     items: SubstituteResultItem[];
     candidatePoolSize: number;
     droppedUnavailable: number;
+    /**
+     * MG-1686, MG-1783. True when the candidate read hit the bounded pool ceiling,
+     * so more materials match the signature than were ranked. A cut pool is an
+     * even SAMPLE across the id keyspace rather than its lowest window, so the
+     * ranked set is representative of the match set without being all of it —
+     * treat the items as the best of a sample, never as the best that exist. A cut
+     * pool that produced NO items answers `inconclusive` instead, so `available`
+     * with an empty `items` always means a complete search that found nothing.
+     */
+    poolTruncated: boolean;
+    supersededBy: MaterialSuccessor | null;
+    nextCursor?: string;
+}
+/**
+ * MG-1686. The search read a bounded window of the matches and nothing in it
+ * reached the page, while more matches existed past the window. It is not an
+ * answer of "nothing can replace this" — that answer is `available` with an
+ * empty `items`. `reason` names what happened and the next move; follow
+ * `nextCursor` when it is present.
+ */
+export interface InconclusiveSubstitutesResponse {
+    status: "inconclusive";
+    signatureUsed: AvailableSubstituteSignature;
+    items: [];
+    candidatePoolSize: number;
+    droppedUnavailable: number;
+    reason: string;
     supersededBy: MaterialSuccessor | null;
     nextCursor?: string;
 }
@@ -72,4 +99,4 @@ export interface InsufficientSubstitutesResponse {
     items: [];
     supersededBy: MaterialSuccessor | null;
 }
-export type FindSubstitutesResponse = AvailableSubstitutesResponse | UnsupportedSubstitutesResponse | InsufficientSubstitutesResponse;
+export type FindSubstitutesResponse = AvailableSubstitutesResponse | InconclusiveSubstitutesResponse | UnsupportedSubstitutesResponse | InsufficientSubstitutesResponse;

package/types.d.ts

@@ -1,7 +1,8 @@
+export type { SearchResponse } from "./search-response-types.js";
+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).
- *
  * These interfaces intentionally have NO runtime dependency on any
  * `@materialgraph/*` package — they are a standalone, publishable mirror of the
  * shapes in `apps/web/public/openapi.yaml` and the captured fixtures under
@@ -31,6 +32,7 @@ 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, SearchRefinementReceipt, SearchRerankReport, SearchResponseExplainReceipts } from "./search-response-receipt-types.js";
 import type { SearchWindowReceipt } from "./search-window-types.js";
@@ -114,6 +116,8 @@ 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`. */
@@ -263,42 +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 {
-    /** Accepted sampleability fact. Absent means unknown, never false. */
-    sampleable?: boolean;
-    /** 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).
@@ -390,12 +358,30 @@ export interface SearchFacets {
  * you asked for it. Follow `cursor` for the rest. "I found 24 materials" is
  * wrong whenever `limit` was 24.
  */
-export interface SearchResponse extends SearchResponseExplainReceipts {
+export interface SearchData 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;
@@ -432,7 +418,7 @@ export interface SearchResponse extends SearchResponseExplainReceipts {
      * 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;
+    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
@@ -453,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;
@@ -606,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. */

package/webmcp.d.ts

@@ -0,0 +1,17 @@
+/** Canonical operation contracts. Consumers validate both boundaries and supply their own transport. */
+export interface WebMcpToolContract {
+    readonly name: "identify" | "search" | "compare" | "create_correction";
+    readonly operationId: string;
+    readonly path: string;
+    readonly method: "POST";
+    readonly description: string;
+    readonly inputSchema: Readonly<Record<string, unknown>>;
+    readonly outputSchema: Readonly<Record<string, unknown>>;
+    readonly annotations: {
+        readonly readOnlyHint: boolean;
+        readonly untrustedContentHint: boolean;
+    };
+    readonly requiresVisibleConfirmation: boolean;
+    readonly requiredHeaders: readonly string[];
+}
+export { WEBMCP_TOOLS } from "./webmcp.generated.js";

package/webmcp.generated.d.ts

@@ -0,0 +1,2 @@
+import type { WebMcpToolContract } from "./webmcp.js";
+export declare const WEBMCP_TOOLS: readonly WebMcpToolContract[];