@instruments/materialgraph 0.26.0 → 0.27.0

package/palette-search-types.d.ts

@@ -1,3 +1,4 @@
+import type { ColourCategoryGate } from "./by-colour-types.js";
 import type { CorpusScope, CorpusScopeReceipt } from "./corpus-scope-types.js";
 /**
  * Wire types for MULTI-COLOUR search — `POST /api/v1/search/palettes` and
@@ -21,12 +22,12 @@ export type PaletteQueryColour = {
     hex?: string;
     oklab?: OklabTriple;
     /**
-     * Share of the surface this colour should occupy, in (0,1]. Stating it
-     * CHANGES the ranking: a colour asked for at 0.6 rewards candidates whose own
-     * swatch sits near 0.6, not merely candidates that contain the colour.
+     * Share of the surface this colour should occupy, in (0,1]. A colour stated
+     * below 5% is dropped; otherwise not applied, since a palette is ordered by
+     * its first colour alone.
      */
     proportion?: number;
-    /** Relative importance; defaults to 1 and is normalised across the query. */
+    /** Relative importance. Not applied: a palette is ordered by its first colour. */
     weight?: number;
 };
 /** One gradient stop — exactly one of `hex` or `oklab`. Order is meaningful. */
@@ -35,19 +36,34 @@ export type GradientStop = {
     oklab?: OklabTriple;
 };
 export type SearchPaletteInput = {
+    /**
+     * HARD category filter: category-group or product-type names or keys.
+     * Absent, the page holds surface materials only, so lights, taps and
+     * furniture are left out.
+     */
+    category?: string[];
     corpusScope?: CorpusScope;
-    /** The palette to match, 1–8 colours. */
+    /**
+     * The palette to match, 1–8 colours. The page is ordered by the FIRST colour;
+     * the rest come back in `query.droppedColours`.
+     */
     colours: PaletteQueryColour[];
     /**
-     * `all` (the default) requires every queried colour to clear a per-colour
-     * eligibility floor and scores the weighted geometric mean; `any` is a
-     * noisy-OR and never rejects a candidate for missing one colour.
+     * Kept so existing callers still parse: the one search orders the page by
+     * the first colour with no eligibility floor, so `all` and `any` return the
+     * same page.
      */
     logic?: PaletteLogic;
     /** Results to return; defaults to 24, capped at 48. */
     limit?: number;
 };
 export type SearchGradientInput = {
+    /**
+     * HARD category filter: category-group or product-type names or keys.
+     * Absent, the page holds surface materials only, so lights, taps and
+     * furniture are left out.
+     */
+    category?: string[];
     corpusScope?: CorpusScope;
     /** The ordered colour transition, 2–6 stops. */
     stops: GradientStop[];
@@ -67,14 +83,23 @@ export type CandidateSwatch = {
 /** Why a queried colour (or gradient sample) scored what it scored. */
 export type ColourMatchReceipt = {
     queryHex: string;
-    /** `colourScore × proportionScore` for the best-matching swatch. */
+    /** `colourScore × proportionScore`, so `colourScore` on the one search. */
     score: number;
-    /** OKLab closeness alone, in [0,1]. */
+    /**
+     * Closeness in [0,1] of the matched swatch to the queried colour, from plain
+     * OKLab distance with lightness counted in full. Not a confidence.
+     */
     colourScore: number;
-    /** Proportion agreement alone, in [0,1]. */
+    /** Proportion agreement; always 1, since no proportion is applied. */
     proportionScore: number;
     /** The swatch that produced the score, or null when nothing matched. */
     matched: CandidateSwatch | null;
+    /**
+     * Whether `matched` has a hue compatible with the queried colour, at the
+     * response's `hueGate` thresholds. A flag, never a gate: an incompatible
+     * swatch still scores and ranks. Absent when there is no `matched` swatch.
+     */
+    hueCompatible?: boolean;
 };
 /** Identity and evidence shared by both multi-colour match shapes. */
 export type MultiColourMatchBase = {
@@ -87,6 +112,11 @@ export type MultiColourMatchBase = {
     color: string | null;
     variantName: string | null;
     imageUrl: string | null;
+    /**
+     * SHA-256 of the displayed image `imageUrl` points at, as a hex digest.
+     * ABSENT means no hash is on record, never that there is no image.
+     */
+    imageSha256?: string;
     /** MB has retired or hidden this SKU. */
     retired: boolean;
     /**
@@ -103,7 +133,10 @@ export type MultiColourMatchBase = {
     category: string | null;
     /** The candidate's full extracted palette — the evidence scored against. */
     palette: CandidateSwatch[];
-    /** The aggregate match score in [0,1]; higher is closer. */
+    /**
+     * Closeness in [0,1] of the material's own colour to the searched colour,
+     * the page's order. Not a confidence or a percentage.
+     */
     score: number;
 };
 export type PaletteMatch = {
@@ -112,22 +145,18 @@ export type PaletteMatch = {
 } & MultiColourMatchBase;
 export type GradientMatch = {
     /**
-     * Distinct matched thirds of the path over 3. A material owning only one end
-     * of the transition caps out around 0.33 — coverage is what separates a real
-     * gradient match from a good match on a single stop.
+     * Thirds of the path where the material holds a swatch near a sampled point,
+     * over 3. A receipt beside the order, which is by the first stop.
      */
     coverage: number;
     /** One receipt per sampled point along the path, in path order. */
     samples: ColourMatchReceipt[];
 } & MultiColourMatchBase;
 /**
- * The hue-family ADMISSION gate the page was scored under: a candidate swatch
- * may satisfy a query colour only if colorscope's `isHueCompatible` admits it
- * at these exact thresholds. A refused swatch is absent from that colour's
- * matching entirely — it did not merely rank low. Admission, not ranking: it
- * decides which swatches count, never their order. Server-side and fixed (no
- * request knob); the receipt exists so a threshold change is visible on the
- * wire.
+ * The thresholds behind every receipt's `hueCompatible`: the exact values
+ * passed to colorscope's `isHueCompatible`, fixed server-side with no request
+ * knob. A FLAG, never admission or ranking: every swatch still scores, and the
+ * page and its order are the same with or without it.
  */
 export type HueGateReceipt = {
     /** Below this query chroma the colour is achromatic and any hue is admitted. */
@@ -162,20 +191,26 @@ export type SearchPaletteResponse = {
         /** `no_effective_colours` means no material query ran. */
         outcome: OpenEnum<"matches" | "no_effective_colours">;
     };
-    /** The hue-family admission gate this page was scored under. */
-    hueGate: HueGateReceipt;
+    /** The category gate the page ran under. */
+    categoryGate?: ColourCategoryGate;
+    /** The thresholds behind each receipt's `hueCompatible`. Absent only on responses stored before it existed. */
+    hueGate?: HueGateReceipt;
     /** `matches.length`, capped by `limit`. Never a corpus total. */
     count: number;
     matches: PaletteMatch[];
 };
 /** A PAGE, NOT A CORPUS — see {@link SearchPaletteResponse}. */
 export type SearchGradientResponse = {
+    /** The category gate the page ran under. */
+    categoryGate?: ColourCategoryGate;
     corpusScope?: CorpusScopeReceipt;
     query: {
         stops: string[];
         /** The sampled path points the search actually ran against. */
         samples: string[];
     };
+    /** The thresholds behind each sample receipt's `hueCompatible`. */
+    hueGate?: HueGateReceipt;
     /** `matches.length`, capped by `limit`. Never a corpus total. */
     count: number;
     matches: GradientMatch[];

package/query-understanding-types.d.ts

@@ -183,14 +183,14 @@ export type QueryAmbiguityReceipt = {
     productTypeIds: string[];
     changedArm: boolean;
 };
-export interface QueryCategoryScopeReceipt {
+export type QueryCategoryScopeReceipt = {
     source: OpenEnum<"caller" | "anchor">;
     mechanism: OpenEnum<"sql-predicate" | "provider-filter" | "allowlist" | "prune">;
     variantCount: number | null;
     ceiling: number;
     specScanBounded?: boolean;
     [key: string]: unknown;
-}
+};
 export type QuerySpecAllowlistReceipt = {
     limit: number;
     returned: number;
@@ -199,6 +199,27 @@ export type QuerySpecAllowlistReceipt = {
     emptyMeansScarcity: boolean;
     outcome?: OpenEnum<"corpus-scarcity" | "retrieval-miss" | "unknown">;
 };
+/**
+ * Whether the phrase-reading step turned the query's descriptive words into
+ * filters and preferences. Present only on the workflow lane.
+ */
+export type QueryPhraseReadingReceipt = {
+    outcome: OpenEnum<"skipped">;
+    reason: string;
+} | {
+    outcome: OpenEnum<"read">;
+    /** Which model read the phrase: `jev`, or `second` behind it. */
+    reader: OpenEnum<"jev" | "second">;
+    elapsedMs: number;
+    leftAsText: string[];
+    rows: {
+        kind: OpenEnum<"want" | "avoid">;
+        attributeId: string;
+        values: string[];
+        confidence: number;
+        applied: boolean;
+    }[];
+};
 export type QueryUnsatisfiableNarrowing = {
     narrowing: OpenEnum<"product-type">;
     gate: OpenEnum<"hard">;
@@ -213,13 +234,13 @@ export type QueryUnsatisfiableNarrowing = {
     relaxedTo: OpenEnum<"head-noun" | "none">;
 };
 /** Inspectable interpretation of the raw query by ordinary MaterialGraph search. */
-export interface QueryUnderstanding {
+export type QueryUnderstanding = {
     version: OpenEnum<"1">;
     rawQuery: string;
     normalisedQuery: string;
     residualText: string;
     status: OpenEnum<"resolved" | "ambiguous" | "partial" | "unresolved">;
-    mode: OpenEnum<"image" | "colour" | "text" | "lexical" | "entity-browse">;
+    mode: OpenEnum<"image" | "colour" | "text" | "lexical" | "entity-browse" | "attribute">;
     senses: QuerySense[];
     canonicalLexical?: CanonicalLexicalReceipt;
     criteria?: QueryCriteriaReceipt;
@@ -229,4 +250,5 @@ export interface QueryUnderstanding {
     categoryScope?: QueryCategoryScopeReceipt;
     specAllowlist?: QuerySpecAllowlistReceipt;
     unsatisfiableNarrowing?: QueryUnsatisfiableNarrowing;
-}
+    phraseReading?: QueryPhraseReadingReceipt;
+};

package/resolve-client.d.ts

@@ -17,9 +17,7 @@
  * silently the moment the registry moves.
  * - The whole phrase, any vocabulary → {@link resolvePhrasesRequest}. Batched,
  *   deterministic, and it says so out loud when a word means nothing here.
- * - You already know it is an attribute, or a value under a known attribute →
- *   `mg.resolveAttribute()` / `mg.resolveAttributeValue()`.
- * - You want to EXPLAIN a token you already hold → `mg.glossary(term)`.
+ * - You already know it is an attribute → `mg.listAttributes({ query })`.
  * - You want to complete a name as someone types → `mg.suggest()`.
  * - You want MATERIALS → `mg.search()`. This lens never returns one.
  */
@@ -56,9 +54,8 @@ import type { VocabularySearchOptions, VocabularySearchResponse } from "./types.
  *   could have caught comes back unresolved rather than slow.
  *
  * Deterministic — the same batch resolves to the same bytes every time. Instead
- * use `mg.search()` when you want materials rather than words, `mg.suggest()` to
- * complete a name as someone types, and `mg.glossary()` to EXPLAIN a token you
- * have already resolved.
+ * use `mg.search()` when you want materials rather than words, and
+ * `mg.suggest()` to complete a name as someone types.
  *
  * - **Every reading says what stands behind it.** `coverage.variants` is how
  *   many variants carry it corpus-wide, and `0` is a measured answer rather
@@ -82,9 +79,8 @@ export declare const resolvePhrasesRequest: (transport: HttpTransport, phrases:
  * here?" The catch-all for ONE phrase when you do not know which half of an
  * `attribute:value` pair it belongs to. Backs `mg.searchVocabulary()`.
  *
- * Instead use `mg.resolveAttribute()` / `mg.resolveAttributeValue()` once you do
- * know, {@link resolvePhrasesRequest} when you have SEVERAL phrases or the
- * phrase might name a brand, paint, colour or category rather than a spec, and
- * `mg.glossary()` to EXPLAIN a term rather than find it.
+ * Instead use `mg.listAttributes({ query })` once you do know the attribute,
+ * or {@link resolvePhrasesRequest} when you have SEVERAL phrases or the phrase
+ * might name a brand, paint, colour or category rather than a spec.
  */
 export declare const searchVocabularyRequest: (transport: HttpTransport, query: string, options?: VocabularySearchOptions, signal?: AbortSignal) => Promise<VocabularySearchResponse>;

package/resolve-client.js

@@ -29,9 +29,8 @@ import { resolveOperation } from "./operations.js";
  *   could have caught comes back unresolved rather than slow.
  *
  * Deterministic — the same batch resolves to the same bytes every time. Instead
- * use `mg.search()` when you want materials rather than words, `mg.suggest()` to
- * complete a name as someone types, and `mg.glossary()` to EXPLAIN a token you
- * have already resolved.
+ * use `mg.search()` when you want materials rather than words, and
+ * `mg.suggest()` to complete a name as someone types.
  *
  * - **Every reading says what stands behind it.** `coverage.variants` is how
  *   many variants carry it corpus-wide, and `0` is a measured answer rather
@@ -68,9 +67,8 @@ export const resolvePhrasesRequest = async (transport, phrases, scope) => {
  * here?" The catch-all for ONE phrase when you do not know which half of an
  * `attribute:value` pair it belongs to. Backs `mg.searchVocabulary()`.
  *
- * Instead use `mg.resolveAttribute()` / `mg.resolveAttributeValue()` once you do
- * know, {@link resolvePhrasesRequest} when you have SEVERAL phrases or the
- * phrase might name a brand, paint, colour or category rather than a spec, and
- * `mg.glossary()` to EXPLAIN a term rather than find it.
+ * Instead use `mg.listAttributes({ query })` once you do know the attribute,
+ * or {@link resolvePhrasesRequest} when you have SEVERAL phrases or the phrase
+ * might name a brand, paint, colour or category rather than a spec.
  */
 export const searchVocabularyRequest = async (transport, query, options, signal) => await transport.requestJson(resolveOperation("catalog_vocabulary_search"), { query: { kind: options?.kind, limit: options?.limit, q: query }, signal });

package/response-schemas.d.ts

@@ -0,0 +1,20 @@
+import type { RESPONSE_SCHEMA_OPERATION_IDS } from "./response-schemas.generated.js";
+export { RESPONSE_SCHEMA_API_VERSION, RESPONSE_SCHEMA_OPERATION_IDS, } from "./response-schemas.generated.js";
+/** Every operation {@link responseSchema} answers for. */
+export type ResponseSchemaOperationId = (typeof RESPONSE_SCHEMA_OPERATION_IDS)[number];
+/** A JSON Schema document or subschema, as plain JSON. */
+export type JsonSchema = {
+    [keyword: string]: unknown;
+};
+/** A self-contained schema: every `$ref` resolves inside its own `$defs`. */
+export type ResponseJsonSchema = JsonSchema & {
+    $schema: typeof JSON_SCHEMA_DIALECT;
+    $defs?: Record<string, JsonSchema>;
+};
+declare const JSON_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
+/**
+ * The success-response schema for one operation, self-contained and carrying
+ * only the definitions it reaches. Each call returns a fresh copy, so a caller
+ * that annotates or mutates it cannot change what the next caller gets.
+ */
+export declare const responseSchema: (operationId: ResponseSchemaOperationId) => ResponseJsonSchema;

package/response-schemas.generated.d.ts

@@ -0,0 +1,5 @@
+/** The API contract version the schemas were generated from. */
+export declare const RESPONSE_SCHEMA_API_VERSION = "0.7.0";
+/** Every SDK operation whose success response has a published JSON Schema. */
+export declare const RESPONSE_SCHEMA_OPERATION_IDS: readonly ["samplize_colorvec_cache", "samplize_catalogue_search", "list_catalog_documents", "list_catalog_pages", "get_catalog_page_representation", "list_catalog_product_references", "search_materials_post", "retrieval.identify", "match_material", "search_suggest", "get_colour_stats", "coordinate_materials", "plan_material_query", "samplize_catalogue_products", "search_materials_get", "search_by_colour", "get_material", "get_catalogue_references_batch", "list_catalogue_channel_collections", "get_catalogue_document_access", "list_material_blocks", "list_variant_assets", "list_material_documents", "get_composition_report", "list_schema_blocks", "list_schema_attributes", "list_schema_verticals", "list_schema_product_types", "list_schema_units", "list_schema_value_dictionaries", "list_schema_source_requirements", "list_schema_product_type_templates", "list_schema_mappings", "get_material_pairings", "list_associated_finishes", "list_associated_products", "get_applicability", "list_variants", "list_variant_facets", "get_category_colour_profiles", "resolve_colour_name", "suggest_colour_names", "catalog_list_attributes", "catalog_vocabulary_search", "resolve_phrases", "list_categories", "get_category", "get_product_type_status_coverage", "whoami", "get_material_demand", "search_by_palette", "extract_image_palette", "search_by_gradient", "list_spec_facets", "list_brands", "upload_source_material", "get_source_material_batch", "list_source_material_comments", "post_source_material_comment", "create_public_run", "get_public_run", "get_verdict_citation", "get_demand_batch", "resolveCodeAdvisory", "list_code_context", "list_code_requirements"];
+export declare const RESPONSE_SCHEMA_CATALOGUE_JSON: string;