@instruments/materialgraph 0.7.1 → 0.8.0

package/composition-types.d.ts

@@ -245,10 +245,28 @@ export interface PaletteDirection {
     colours: BriefColourCue[];
     sourceRefs: CompositionSourceRef[];
 }
+/**
+ * WHERE a slot's `category` came from (MG-954, extended MG-978): `resolved` —
+ * derived from the slot's own words against the catalog's category vectors;
+ * `resolved-coverage` — the words ended in a close race and the runner-up won it
+ * because the text winner held no value for one of the slot's required
+ * attributes; `model` — the interpreter's own draw stood because nothing
+ * resolved; `none` — neither produced one, so the slot has NO category and
+ * retrieval cannot gate it; `corrected` — a designer set it with a
+ * `set-slot-category` correction. Widened with {@link OpenEnum} so a newer
+ * server term still type-checks.
+ */
+export type SlotCategorySource = OpenEnum<"resolved" | "resolved-coverage" | "model" | "none" | "corrected">;
 /**
  * Suspend payload for the compose `review-programme` step: the FULL programme
  * picture — every space and slot tagged with its provenance — so the card can
  * show the whole thing and highlight what was inferred.
+ *
+ * Each slot also discloses the catalog `category` it will shop in and the
+ * `categorySource` that won it (MG-954). Both are OPTIONAL and additive: an
+ * ABSENT `category` means the slot has none — not that it has an empty one — and
+ * a slot in that state cannot be gated at retrieval, so it is skipped there with
+ * a counted shortfall unless a `set-slot-category` correction supplies one.
  */
 export interface ReviewProgrammeSuspendPayload {
     spaces: Array<{
@@ -262,12 +280,20 @@ export interface ReviewProgrammeSuspendPayload {
         name: string;
         spaceId?: string;
         element?: SlotElement;
+        category?: string;
+        categorySource?: SlotCategorySource;
         provenance: ProgrammeProvenance;
     }>;
 }
 /**
  * Resume grammar for the `review-programme` step: drop a slot, drop a space
- * (cascade-dropping its slots), or rename a space.
+ * (cascade-dropping its slots), rename a space, or set a slot's category.
+ *
+ * `set-slot-category` (MG-954) is an action INSIDE this same corrections array;
+ * its `category` must be one of the server's catalog category GROUP names (the
+ * same vocabulary the payload's `category` is drawn from) or the resume is
+ * refused. An empty `corrections` array stays legal however the step came to
+ * suspend — the suspension discloses, it does not coerce.
  */
 export interface ReviewProgrammeResumeData {
     corrections: Array<{
@@ -280,6 +306,10 @@ export interface ReviewProgrammeResumeData {
         action: "rename-space";
         spaceId: string;
         name: string;
+    } | {
+        action: "set-slot-category";
+        slotId: string;
+        category: string;
     }>;
 }
 /**

package/index.d.ts

@@ -15,6 +15,7 @@ export type * from "./run-events.js";
 export { MaterialGraphError } from "./errors.js";
 export type { MaterialGraphErrorInit, MaterialGraphErrorKind, MaterialGraphRequestMetadata, ProblemDetail, RateLimit, SanitizedErrorValue, SanitizedIssue, SimpleErrorBody, } from "./errors.js";
 export type * from "./types.js";
+export type * from "./by-colour-types.js";
 export { MATCH_IMAGE_TYPES, MATCH_MATERIAL_FUNCTIONS, MATCH_STREAM_EVENT_TYPES, MATCH_SURFACE_STATUSES, MATCH_WORKFLOW_STEPS, } from "./match-stream-types.js";
 export type * from "./match-stream-types.js";
 export { CodesClient } from "./codes-client.js";
@@ -23,6 +24,7 @@ export { ColoursClient } from "./colours-client.js";
 export type { ColoursTransport } from "./colours-client.js";
 export type * from "./colour-aggregate-types.js";
 export type * from "./palette-search-types.js";
+export type * from "./association-types.js";
 export type * from "./brand-types.js";
 export type * from "./material-asset-types.js";
 export type * from "./material-block-types.js";

package/material-types.d.ts

@@ -67,6 +67,14 @@ export interface MaterialTile {
     category: string | null;
     colour: MaterialColour;
     availability: MaterialAvailability;
+    /**
+     * The accepted Colour Name attribute — the colourway's true name where
+     * `variantName` collapsed to the product's (MG-940: 83.7% of visible
+     * colourway families name every variant after the product, e.g. all 10 CF
+     * Stinson "Drift" colourways share `variantName: "Drift"`). Absent means
+     * the attribute is absent — never render a missing key as "unnamed".
+     */
+    colourName?: string;
 }
 /**
  * A canonical attribute/term pair carried on a detail record.

package/operations.d.ts

@@ -1,5 +1,5 @@
 export declare const MATERIALGRAPH_API_VERSION = "0.7.0";
-declare const OPERATION_DEFINITIONS: readonly [readonly ["search", "POST", "/api/v1/search", "search_materials_post"], readonly ["searchGet", "GET", "/api/v1/search", "search_materials_get"], readonly ["match", "POST", "/api/v1/search/match", "match_material"], readonly ["byColour", "GET", "/api/v1/search/colours", "search_by_colour"], readonly ["material", "GET", "/api/v1/materials/{variantId}", "get_material"], readonly ["siblings", "GET", "/api/v1/materials/{variantId}/siblings", "get_material_siblings"], readonly ["materialBlocks", "GET", "/api/v1/materials/{variantId}/blocks", "list_material_blocks"], readonly ["materialAssets", "GET", "/api/v1/materials/{variantId}/assets", "list_material_assets"], readonly ["schema", "GET", "/api/v1/schema/blocks", "list_schema_blocks"], readonly ["schema", "GET", "/api/v1/schema/attributes", "list_schema_attributes"], readonly ["schema", "GET", "/api/v1/schema/verticals", "list_schema_verticals"], readonly ["schema", "GET", "/api/v1/schema/product-types", "list_schema_product_types"], readonly ["schema", "GET", "/api/v1/schema/units", "list_schema_units"], readonly ["schema", "GET", "/api/v1/schema/value-dictionaries", "list_schema_value_dictionaries"], readonly ["schema", "GET", "/api/v1/schema/source-requirements", "list_schema_source_requirements"], readonly ["schema", "GET", "/api/v1/schema/product-type-templates", "list_schema_product_type_templates"], readonly ["schema", "GET", "/api/v1/schema/mappings", "list_schema_mappings"], readonly ["pairings", "GET", "/api/v1/materials/{variantId}/pairings", "get_material_pairings"], readonly ["materials", "POST", "/api/v1/materials/batch", "get_materials_batch_post"], readonly ["materialsCached", "GET", "/api/v1/materials/batch", "get_materials_batch_get"], readonly ["browse", "GET", "/api/v1/search/browse", "search_browse_by_colour"], readonly ["colourFacets", "GET", "/api/v1/colours/facets", "get_colour_facets"], readonly ["colours.profiles", "GET", "/api/v1/colours/profiles", "get_category_colour_profiles"], readonly ["colours.stats", "GET", "/api/v1/colours/stats", "get_colour_stats"], readonly ["resolveColour", "GET", "/api/v1/search/colours/resolve", "resolve_colour_name"], readonly ["suggestColour", "GET", "/api/v1/search/colours/suggest", "suggest_colour_names"], readonly ["suggest", "GET", "/api/v1/search/suggest", "search_suggest"], readonly ["resolveAttribute", "GET", "/api/v1/catalog/attributes/resolve", "catalog_resolve_attribute"], readonly ["resolveAttributeValue", "GET", "/api/v1/catalog/attributes/{attributeId}/values/resolve", "catalog_resolve_value"], readonly ["searchVocabulary", "GET", "/api/v1/catalog/vocabulary/search", "catalog_vocabulary_search"], readonly ["bySpec", "GET", "/api/v1/search/specifications", "catalog_by_spec"], readonly ["taxonomy", "GET", "/api/v1/taxonomy/categories", "get_category_taxonomy"], readonly ["whoami", "GET", "/api/v1/whoami", "whoami"], readonly ["coordinate", "POST", "/api/v1/pairings/coordinate", "coordinate_materials"], readonly ["demand", "GET", "/api/v1/demand", "get_material_demand"], readonly ["colours.palette", "POST", "/api/v1/search/palettes", "search_by_palette"], readonly ["extractPalette", "POST", "/api/v1/search/palettes/extract", "extract_image_palette"], readonly ["colours.gradient", "POST", "/api/v1/search/gradients", "search_by_gradient"], readonly ["specificationFacets", "GET", "/api/v1/catalog/specifications/facets", "list_spec_facets"], readonly ["attributeValues", "GET", "/api/v1/catalog/attributes/{attributeId}/values", "list_attribute_values"], readonly ["applicableSpecs", "GET", "/api/v1/taxonomy/categories/{key}/specs", "get_applicable_specs"], readonly ["glossary", "GET", "/api/v1/glossary/{term}", "explain_material_term"], readonly ["brands", "GET", "/api/v1/brands", "list_brands"], readonly ["brand", "GET", "/api/v1/brands/{brandSlug}", "get_brand_profile"], readonly ["uploadSourceMaterial", "POST", "/api/v1/source-material", "upload_source_material"], readonly ["sourceMaterialBatch", "GET", "/api/v1/source-material/{batchId}", "get_source_material_batch"], readonly ["capabilities", "GET", "/api/v1/capabilities", "list_public_capabilities"], readonly ["createRun", "POST", "/api/v1/runs", "create_public_run"], readonly ["run", "GET", "/api/v1/runs/{runId}", "get_public_run"], readonly ["runSchedule", "GET", "/api/v1/runs/{runId}/schedule", "get_run_finish_schedule"], readonly ["streamRunEvents", "GET", "/api/v1/runs/{runId}/events", "list_public_run_events"], readonly ["resumeRun", "POST", "/api/v1/runs/{runId}/resume", "resume_public_run"], readonly ["cancelRun", "POST", "/api/v1/runs/{runId}/cancel", "cancel_public_run"], readonly ["varyScheme", "POST", "/api/v1/schemes/vary", "vary_schemes"], readonly ["createProject", "POST", "/api/v1/projects", "create_box_project"], readonly ["listProjects", "GET", "/api/v1/projects", "list_box_projects"], readonly ["getProject", "GET", "/api/v1/projects/{projectId}", "get_box_project"], readonly ["appendProjectEvent", "POST", "/api/v1/projects/{projectId}/events", "append_box_project_event"], readonly ["demandBatch", "POST", "/api/v1/demand/batch", "get_demand_batch"], readonly ["codeAdvisory", "POST", "/api/v1/codes/advisory", "resolveCodeAdvisory"], readonly ["codes.context", "GET", "/api/v1/codes/context", "list_code_context"], readonly ["codes.requirements", "GET", "/api/v1/codes/requirements", "list_code_requirements"]];
+declare const OPERATION_DEFINITIONS: readonly [readonly ["search", "POST", "/api/v1/search", "search_materials_post"], readonly ["searchGet", "GET", "/api/v1/search", "search_materials_get"], readonly ["match", "POST", "/api/v1/search/match", "match_material"], readonly ["byColour", "GET", "/api/v1/search/colours", "search_by_colour"], readonly ["material", "GET", "/api/v1/materials/{variantId}", "get_material"], readonly ["siblings", "GET", "/api/v1/materials/{variantId}/siblings", "get_material_siblings"], readonly ["materialBlocks", "GET", "/api/v1/materials/{variantId}/blocks", "list_material_blocks"], readonly ["materialAssets", "GET", "/api/v1/materials/{variantId}/assets", "list_material_assets"], readonly ["schema", "GET", "/api/v1/schema/blocks", "list_schema_blocks"], readonly ["schema", "GET", "/api/v1/schema/attributes", "list_schema_attributes"], readonly ["schema", "GET", "/api/v1/schema/verticals", "list_schema_verticals"], readonly ["schema", "GET", "/api/v1/schema/product-types", "list_schema_product_types"], readonly ["schema", "GET", "/api/v1/schema/units", "list_schema_units"], readonly ["schema", "GET", "/api/v1/schema/value-dictionaries", "list_schema_value_dictionaries"], readonly ["schema", "GET", "/api/v1/schema/source-requirements", "list_schema_source_requirements"], readonly ["schema", "GET", "/api/v1/schema/product-type-templates", "list_schema_product_type_templates"], readonly ["schema", "GET", "/api/v1/schema/mappings", "list_schema_mappings"], readonly ["pairings", "GET", "/api/v1/materials/{variantId}/pairings", "get_material_pairings"], readonly ["associatedFinishes", "GET", "/api/v1/associated/finishes", "list_associated_finishes"], readonly ["associatedProducts", "GET", "/api/v1/associated/products", "list_associated_products"], readonly ["materials", "POST", "/api/v1/materials/batch", "get_materials_batch_post"], readonly ["materialsCached", "GET", "/api/v1/materials/batch", "get_materials_batch_get"], readonly ["browse", "GET", "/api/v1/search/browse", "search_browse_by_colour"], readonly ["colourFacets", "GET", "/api/v1/colours/facets", "get_colour_facets"], readonly ["colours.profiles", "GET", "/api/v1/colours/profiles", "get_category_colour_profiles"], readonly ["colours.stats", "GET", "/api/v1/colours/stats", "get_colour_stats"], readonly ["resolveColour", "GET", "/api/v1/search/colours/resolve", "resolve_colour_name"], readonly ["suggestColour", "GET", "/api/v1/search/colours/suggest", "suggest_colour_names"], readonly ["suggest", "GET", "/api/v1/search/suggest", "search_suggest"], readonly ["resolveAttribute", "GET", "/api/v1/catalog/attributes/resolve", "catalog_resolve_attribute"], readonly ["resolveAttributeValue", "GET", "/api/v1/catalog/attributes/{attributeId}/values/resolve", "catalog_resolve_value"], readonly ["searchVocabulary", "GET", "/api/v1/catalog/vocabulary/search", "catalog_vocabulary_search"], readonly ["resolve", "POST", "/api/v1/resolve", "resolve_phrases"], readonly ["bySpec", "GET", "/api/v1/search/specifications", "catalog_by_spec"], readonly ["taxonomy", "GET", "/api/v1/taxonomy/categories", "get_category_taxonomy"], readonly ["whoami", "GET", "/api/v1/whoami", "whoami"], readonly ["coordinate", "POST", "/api/v1/pairings/coordinate", "coordinate_materials"], readonly ["demand", "GET", "/api/v1/demand", "get_material_demand"], readonly ["colours.palette", "POST", "/api/v1/search/palettes", "search_by_palette"], readonly ["extractPalette", "POST", "/api/v1/search/palettes/extract", "extract_image_palette"], readonly ["colours.gradient", "POST", "/api/v1/search/gradients", "search_by_gradient"], readonly ["specificationFacets", "GET", "/api/v1/catalog/specifications/facets", "list_spec_facets"], readonly ["attributeValues", "GET", "/api/v1/catalog/attributes/{attributeId}/values", "list_attribute_values"], readonly ["applicableSpecs", "GET", "/api/v1/taxonomy/categories/{key}/specs", "get_applicable_specs"], readonly ["glossary", "GET", "/api/v1/glossary/{term}", "explain_material_term"], readonly ["brands", "GET", "/api/v1/brands", "list_brands"], readonly ["brand", "GET", "/api/v1/brands/{brandSlug}", "get_brand_profile"], readonly ["uploadSourceMaterial", "POST", "/api/v1/source-material", "upload_source_material"], readonly ["sourceMaterialBatch", "GET", "/api/v1/source-material/{batchId}", "get_source_material_batch"], readonly ["capabilities", "GET", "/api/v1/capabilities", "list_public_capabilities"], readonly ["createRun", "POST", "/api/v1/runs", "create_public_run"], readonly ["listRuns", "GET", "/api/v1/runs", "list_public_runs"], readonly ["run", "GET", "/api/v1/runs/{runId}", "get_public_run"], readonly ["runSchedule", "GET", "/api/v1/runs/{runId}/schedule", "get_run_finish_schedule"], readonly ["streamRunEvents", "GET", "/api/v1/runs/{runId}/events", "list_public_run_events"], readonly ["resumeRun", "POST", "/api/v1/runs/{runId}/resume", "resume_public_run"], readonly ["cancelRun", "POST", "/api/v1/runs/{runId}/cancel", "cancel_public_run"], readonly ["varyScheme", "POST", "/api/v1/schemes/vary", "vary_schemes"], readonly ["createProject", "POST", "/api/v1/projects", "create_box_project"], readonly ["listProjects", "GET", "/api/v1/projects", "list_box_projects"], readonly ["getProject", "GET", "/api/v1/projects/{projectId}", "get_box_project"], readonly ["appendProjectEvent", "POST", "/api/v1/projects/{projectId}/events", "append_box_project_event"], readonly ["demandBatch", "POST", "/api/v1/demand/batch", "get_demand_batch"], readonly ["codeAdvisory", "POST", "/api/v1/codes/advisory", "resolveCodeAdvisory"], readonly ["codes.context", "GET", "/api/v1/codes/context", "list_code_context"], readonly ["codes.requirements", "GET", "/api/v1/codes/requirements", "list_code_requirements"]];
 export type SdkOperationId = (typeof OPERATION_DEFINITIONS)[number][3];
 export type SdkOperation = Readonly<{
     clientMethod: (typeof OPERATION_DEFINITIONS)[number][0];
@@ -10,6 +10,12 @@ export type SdkOperation = Readonly<{
 export declare const SDK_OPERATIONS: readonly SdkOperation[];
 /** Look up a registered operation by its OpenAPI `operationId`. */
 export declare function findSdkOperation(operationId: SdkOperationId): SdkOperation | undefined;
+/**
+ * Look up a registered operation, or throw. The lookup every caller that holds
+ * a literal `operationId` wants — lived as a private copy in `client.ts` and
+ * `projects.ts` before the association lens would have made it a third.
+ */
+export declare function resolveOperation(operationId: SdkOperationId): SdkOperation;
 /** Substitute `{param}` path placeholders with percent-encoded values. */
 export declare function operationPath(sdkOperation: SdkOperation, pathParams?: Readonly<Record<string, string>>): string;
 export {};

package/operations.js

@@ -1,3 +1,4 @@
+import { MaterialGraphError } from "./errors.js";
 export const MATERIALGRAPH_API_VERSION = "0.7.0";
 const OPERATION_DEFINITIONS = [
     ["search", "POST", "/api/v1/search", "search_materials_post"],
@@ -18,6 +19,8 @@ const OPERATION_DEFINITIONS = [
     ["schema", "GET", "/api/v1/schema/product-type-templates", "list_schema_product_type_templates"],
     ["schema", "GET", "/api/v1/schema/mappings", "list_schema_mappings"],
     ["pairings", "GET", "/api/v1/materials/{variantId}/pairings", "get_material_pairings"],
+    ["associatedFinishes", "GET", "/api/v1/associated/finishes", "list_associated_finishes"],
+    ["associatedProducts", "GET", "/api/v1/associated/products", "list_associated_products"],
     ["materials", "POST", "/api/v1/materials/batch", "get_materials_batch_post"],
     ["materialsCached", "GET", "/api/v1/materials/batch", "get_materials_batch_get"],
     ["browse", "GET", "/api/v1/search/browse", "search_browse_by_colour"],
@@ -35,6 +38,7 @@ const OPERATION_DEFINITIONS = [
         "catalog_resolve_value",
     ],
     ["searchVocabulary", "GET", "/api/v1/catalog/vocabulary/search", "catalog_vocabulary_search"],
+    ["resolve", "POST", "/api/v1/resolve", "resolve_phrases"],
     ["bySpec", "GET", "/api/v1/search/specifications", "catalog_by_spec"],
     ["taxonomy", "GET", "/api/v1/taxonomy/categories", "get_category_taxonomy"],
     ["whoami", "GET", "/api/v1/whoami", "whoami"],
@@ -58,6 +62,7 @@ const OPERATION_DEFINITIONS = [
     ["sourceMaterialBatch", "GET", "/api/v1/source-material/{batchId}", "get_source_material_batch"],
     ["capabilities", "GET", "/api/v1/capabilities", "list_public_capabilities"],
     ["createRun", "POST", "/api/v1/runs", "create_public_run"],
+    ["listRuns", "GET", "/api/v1/runs", "list_public_runs"],
     ["run", "GET", "/api/v1/runs/{runId}", "get_public_run"],
     ["runSchedule", "GET", "/api/v1/runs/{runId}/schedule", "get_run_finish_schedule"],
     ["streamRunEvents", "GET", "/api/v1/runs/{runId}/events", "list_public_run_events"],
@@ -78,6 +83,17 @@ export const SDK_OPERATIONS = Object.freeze(OPERATION_DEFINITIONS.map(([clientMe
 export function findSdkOperation(operationId) {
     return SDK_OPERATIONS.find((candidate) => candidate.operationId === operationId);
 }
+/**
+ * Look up a registered operation, or throw. The lookup every caller that holds
+ * a literal `operationId` wants — lived as a private copy in `client.ts` and
+ * `projects.ts` before the association lens would have made it a third.
+ */
+export function resolveOperation(operationId) {
+    const match = findSdkOperation(operationId);
+    if (!match)
+        throw MaterialGraphError.unexpected(`Unknown SDK operation: ${operationId}`);
+    return match;
+}
 /** Substitute `{param}` path placeholders with percent-encoded values. */
 export function operationPath(sdkOperation, pathParams = {}) {
     return Object.entries(pathParams).reduce((path, [name, value]) => path.replace(`{${name}}`, encodeURIComponent(value)), sdkOperation.path);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instruments/materialgraph",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "type": "module",
   "exports": {
     ".": {

package/resolve-client.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The VOCABULARY lens — words in, canonical tokens out. The two requests that
+ * answer "what is this phrase CALLED here?" rather than "what materials match
+ * it?", lifted out of the client facade so the facade stays a facade and the
+ * hover documentation has room to say what a caller actually needs.
+ *
+ * Standalone functions over the shared {@link HttpTransport}, not a namespace:
+ * `mg.resolve()` and `mg.searchVocabulary()` are flat methods on the public API
+ * and stay that way — `MaterialGraphClient` keeps a one-line delegating method
+ * for each, so nothing about the published surface moves. Same shape as
+ * `associations-client.ts`; auth, rate-limit accounting and error shaping stay
+ * in the one transport.
+ *
+ * ROUTING INTO AND OUT OF THIS LENS. It is the lens you reach for INSTEAD OF
+ * keeping a hand-written table of your users' words mapped onto this API's
+ * tokens: that table is a copy of a registry you do not own, and it drifts
+ * 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 want to complete a name as someone types → `mg.suggest()`.
+ * - You want MATERIALS → `mg.search()`. This lens never returns one.
+ */
+import type { HttpTransport } from "./http-transport.js";
+import type { ResolveResponse } from "./resolve-types.js";
+import type { VocabularySearchOptions, VocabularySearchResponse } from "./types.js";
+/**
+ * THE QUESTION: "I have words — what do they mean in YOUR vocabulary?" Send up
+ * to 50 phrases as your users typed them; each comes back with every canonical
+ * token MaterialGraph knows it as — brand, exact paint, colour family, category,
+ * attribute, value — best first, in request order. Backs `mg.resolve()`.
+ *
+ * A phrase can legitimately mean several things at once ("sage" is two vendor
+ * paints AND a colour family), so each entry carries a LIST of readings rather
+ * than a winner, and `kind` says which vocabulary each came from.
+ *
+ * Three rules worth reading before you spend a result:
+ * - **`unresolved` is stated, not inferred.** A phrase this vocabulary has no
+ *   word for returns `resolved: []` AND `unresolved: true`, so you can tell an
+ *   absent word from a dropped one. Absent is not false: it is a statement about
+ *   this vocabulary, never about the material world.
+ * - **Ids are opaque.** Hand them back verbatim (see `./identifiers.ts`);
+ *   `colour` and `attribute_value` ids arrive namespaced by their dictionary,
+ *   because a term id is unique only within one.
+ * - **`rung` says how it matched** — `exact`, `alias`, or `lexical`. There is no
+ *   semantic rung: every tier that would cost an embedding round-trip is off,
+ *   which is what keeps this millisecond-class. A phrase only a semantic match
+ *   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.
+ *
+ * @param phrases 1-50 phrases, each 1-200 characters. Sent as-is; each is
+ * resolved independently, so one meaningless phrase never spoils the batch.
+ */
+export declare function resolvePhrasesRequest(transport: HttpTransport, phrases: string[], signal?: AbortSignal): Promise<ResolveResponse>;
+/**
+ * THE QUESTION: "is 'FloorScore' an attribute or a value, and what is it called
+ * 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.
+ */
+export declare function searchVocabularyRequest(transport: HttpTransport, query: string, options?: VocabularySearchOptions, signal?: AbortSignal): Promise<VocabularySearchResponse>;

package/resolve-client.js

@@ -0,0 +1,51 @@
+import { resolveOperation } from "./operations.js";
+/**
+ * THE QUESTION: "I have words — what do they mean in YOUR vocabulary?" Send up
+ * to 50 phrases as your users typed them; each comes back with every canonical
+ * token MaterialGraph knows it as — brand, exact paint, colour family, category,
+ * attribute, value — best first, in request order. Backs `mg.resolve()`.
+ *
+ * A phrase can legitimately mean several things at once ("sage" is two vendor
+ * paints AND a colour family), so each entry carries a LIST of readings rather
+ * than a winner, and `kind` says which vocabulary each came from.
+ *
+ * Three rules worth reading before you spend a result:
+ * - **`unresolved` is stated, not inferred.** A phrase this vocabulary has no
+ *   word for returns `resolved: []` AND `unresolved: true`, so you can tell an
+ *   absent word from a dropped one. Absent is not false: it is a statement about
+ *   this vocabulary, never about the material world.
+ * - **Ids are opaque.** Hand them back verbatim (see `./identifiers.ts`);
+ *   `colour` and `attribute_value` ids arrive namespaced by their dictionary,
+ *   because a term id is unique only within one.
+ * - **`rung` says how it matched** — `exact`, `alias`, or `lexical`. There is no
+ *   semantic rung: every tier that would cost an embedding round-trip is off,
+ *   which is what keeps this millisecond-class. A phrase only a semantic match
+ *   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.
+ *
+ * @param phrases 1-50 phrases, each 1-200 characters. Sent as-is; each is
+ * resolved independently, so one meaningless phrase never spoils the batch.
+ */
+export function resolvePhrasesRequest(transport, phrases, signal) {
+    return transport.requestJson(resolveOperation("resolve_phrases"), {
+        body: { phrases },
+        signal,
+    });
+}
+/**
+ * THE QUESTION: "is 'FloorScore' an attribute or a value, and what is it called
+ * 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.
+ */
+export function searchVocabularyRequest(transport, query, options, signal) {
+    return transport.requestJson(resolveOperation("catalog_vocabulary_search"), { query: { q: query, limit: options?.limit, kind: options?.kind }, signal });
+}

package/resolve-types.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The vocabulary lens (MG-913) — the hand-mirrored wire types for
+ * `POST /api/v1/resolve`.
+ *
+ * Split out of `types.ts` for the repository's source-file size budget, the same
+ * reason `suggest-types.ts` sits beside it; both are re-exported from `types.ts`,
+ * so importers see no difference.
+ *
+ * THE LENS: it turns WORDS into vocabulary, never into materials.
+ * `mg.search()` answers "I want materials" and `mg.answer` questions want prose;
+ * this answers "what do these words mean in your vocabulary?" — the question you
+ * ask BEFORE you spend a token on a filter, a facet or a brand slug. It is the
+ * reason you should not keep a hand-written table mapping your users' words onto
+ * this API's tokens: that table is a copy of a registry you do not own, and it
+ * drifts silently the moment the registry moves.
+ */
+/**
+ * Which controlled vocabulary a reading came from — and therefore what `id`
+ * means and where you can spend it.
+ *
+ * - `brand` — a brand slug, for `mg.brand()` or a brand filter.
+ * - `paint_identity` — one exact vendor paint (a library colour), by its vendor
+ *   code where the library has one.
+ * - `colour` — a canonical colour-family term, namespaced (`colour_family.green`).
+ * - `category` — a product-category taxonomy node key.
+ * - `attribute` — a registry attribute id: the LEFT half of an `attribute:value`
+ *   pair, for `mg.bySpec()` or `search({ filters })`.
+ * - `attribute_value` — a value-dictionary term, namespaced (`ms_sheen.matte`):
+ *   the RIGHT half.
+ */
+export type ResolutionKind = "brand" | "paint_identity" | "colour" | "category" | "attribute" | "attribute_value";
+/**
+ * How the phrase matched, strongest first. `exact` — it IS the canonical token;
+ * `alias` — it IS a recorded alternative name for it; `lexical` — it resembles
+ * one closely enough to clear the resolver's own confidence floor.
+ *
+ * There is deliberately no `semantic` rung on this lens. Every tier that would
+ * cost an embedding round-trip is switched off, which is what keeps resolution
+ * millisecond-class; a phrase only a semantic match could have caught comes back
+ * unresolved rather than slow.
+ */
+export type ResolutionRung = "exact" | "alias" | "lexical";
+/** One thing a phrase turned out to mean. */
+export interface ResolvedMeaning {
+    kind: ResolutionKind;
+    /**
+     * The canonical token. OPAQUE — hand it back verbatim, never parse, tidy or
+     * construct one. The single thing worth knowing about the SHAPE: a
+     * value-dictionary term id is unique only within its dictionary, so `colour`
+     * and `attribute_value` ids arrive namespaced as `<dictionaryId>.<termId>`.
+     */
+    id: string;
+    /** The canonical display term — what to show a human, not what to send back. */
+    term: string;
+    rung: ResolutionRung;
+    /**
+     * The resolver's own confidence in [0,1], present only when the underlying
+     * resolver produces one. Its ABSENCE is meaningful rather than missing data:
+     * the rung is then the whole statement, because an exact paint identity is an
+     * equality and not a score.
+     */
+    confidence?: number;
+    /**
+     * Present only when the resolver reported a runner-up. A small `gap` means the
+     * answer was nearly something else; when the resolver refused to break the tie,
+     * every tied reading is listed and `gap` is 0.
+     */
+    ambiguity?: {
+        gap: number;
+    };
+}
+/** What one phrase resolved to — including, explicitly, nothing. */
+export interface PhraseResolution {
+    /** The phrase exactly as you sent it, so you can rejoin the batch by value. */
+    phrase: string;
+    /**
+     * The phrase in the one normalised form the resolvers fold to — the same
+     * `normalise` stage a search query passes through. Empty when the phrase was
+     * all punctuation.
+     */
+    normalised: string;
+    /**
+     * Everything the phrase means here, best first. A phrase can legitimately mean
+     * several things at once ("sage" is two vendor paints AND a colour family), so
+     * this is a list rather than a winner.
+     */
+    resolved: ResolvedMeaning[];
+    /**
+     * TRUE when nothing resolved. Read this rather than inferring it from
+     * `resolved.length`: the redundancy is deliberate, because a consumer that
+     * cannot SEE what failed to resolve cannot tell a word this vocabulary does
+     * not have from a word something quietly dropped. Absent is not false — an
+     * unresolved phrase is a statement about this vocabulary, never about the
+     * material world.
+     */
+    unresolved: boolean;
+}
+/** The resolve response: one entry per phrase, in the order you sent them. */
+export interface ResolveResponse {
+    /** One per phrase, in request order — never reordered, never deduplicated. */
+    resolutions: PhraseResolution[];
+}

package/resolve-types.js

@@ -0,0 +1,17 @@
+/**
+ * The vocabulary lens (MG-913) — the hand-mirrored wire types for
+ * `POST /api/v1/resolve`.
+ *
+ * Split out of `types.ts` for the repository's source-file size budget, the same
+ * reason `suggest-types.ts` sits beside it; both are re-exported from `types.ts`,
+ * so importers see no difference.
+ *
+ * THE LENS: it turns WORDS into vocabulary, never into materials.
+ * `mg.search()` answers "I want materials" and `mg.answer` questions want prose;
+ * this answers "what do these words mean in your vocabulary?" — the question you
+ * ask BEFORE you spend a token on a filter, a facet or a brand slug. It is the
+ * reason you should not keep a hand-written table mapping your users' words onto
+ * this API's tokens: that table is a copy of a registry you do not own, and it
+ * drifts silently the moment the registry moves.
+ */
+export {};

package/run-types.d.ts

@@ -233,6 +233,31 @@ export interface CreatePublicRunResponse {
 export interface PublicRunResponse {
     run: PublicRun;
 }
+/** Query for `GET /api/v1/runs` ({@link MaterialGraphClient.listRuns}). */
+export interface ListRunsOptions {
+    /**
+     * Return only Runs in this status. `"suspended"` is the recovery question:
+     * which of my Runs is still waiting on an answer?
+     */
+    status?: PublicRunStatus;
+    /** Page size, 1–100. Defaults to 20 server-side. */
+    limit?: number;
+    /**
+     * The previous page's {@link PublicRunListResponse.nextCursor}, round-tripped
+     * VERBATIM. It is opaque — never parse or construct one.
+     */
+    cursor?: string;
+    signal?: AbortSignal;
+}
+/** The `GET /api/v1/runs` response envelope — one page, newest first. */
+export interface PublicRunListResponse {
+    runs: PublicRun[];
+    /**
+     * Pass as {@link ListRunsOptions.cursor} for the next page. ABSENT — not
+     * empty-string, not null — once the last page has been served.
+     */
+    nextCursor?: string;
+}
 /** Body for `POST /api/v1/runs/{runId}/resume`. */
 export interface ResumePublicRunRequest {
     /** The resume payload, validated against the suspended step's resume schema. */

package/runs.d.ts

@@ -1,6 +1,6 @@
 import { HttpTransport } from "./http-transport.js";
 import type { FinishScheduleResponse, GetRunScheduleOptions } from "./schedule-types.js";
-import { type CapabilityManifestResponse, type CreatePublicRunRequest, type CreatePublicRunResponse, type DrainRunEventsOptions, type PublicRunResponse, type ResumeRunOptions, type RunEvent, type SourceMaterialBatchDetail, type SourceMaterialBatchReceipt, type StreamRunEventsOptions, type UploadSourceMaterialInput } from "./run-types.js";
+import { type CapabilityManifestResponse, type CreatePublicRunRequest, type CreatePublicRunResponse, type DrainRunEventsOptions, type ListRunsOptions, type PublicRunListResponse, type PublicRunResponse, type ResumeRunOptions, type RunEvent, type SourceMaterialBatchDetail, type SourceMaterialBatchReceipt, type StreamRunEventsOptions, type UploadSourceMaterialInput } from "./run-types.js";
 /**
  * Upload one atomic source-material batch (`POST /api/v1/source-material`).
  * Accepts the pile-of-files shape (`{ files }` → repeatable `files` field) or
@@ -25,6 +25,20 @@ export declare function getSourceMaterialBatch(transport: HttpTransport, batchId
 export declare function capabilities(transport: HttpTransport, signal?: AbortSignal): Promise<CapabilityManifestResponse>;
 /** Start an asynchronous capability Run (`POST /api/v1/runs`). */
 export declare function createRun(transport: HttpTransport, body: CreatePublicRunRequest, signal?: AbortSignal): Promise<CreatePublicRunResponse>;
+/**
+ * List your own Runs, newest first (`GET /api/v1/runs`).
+ *
+ * The recovery path for a client that still holds its API key but has lost a Run
+ * id — a reinstalled app, or a crash before the id from {@link createRun} was
+ * persisted. `{ status: "suspended" }` finds the Run still waiting on an answer.
+ *
+ * Only the calling principal's own Runs are ever returned; there is no
+ * cross-principal listing.
+ *
+ * Page by following `nextCursor` until it is ABSENT — a full page is not the
+ * signal to stop, and an absent cursor is the only one.
+ */
+export declare function listRuns(transport: HttpTransport, options?: ListRunsOptions): Promise<PublicRunListResponse>;
 /** Get a Run's current state (`GET /api/v1/runs/{runId}`). */
 export declare function getRun(transport: HttpTransport, runId: string, signal?: AbortSignal): Promise<PublicRunResponse>;
 /**

package/runs.js

@@ -99,6 +99,30 @@ export function createRun(transport, body, signal) {
         signal,
     });
 }
+/**
+ * List your own Runs, newest first (`GET /api/v1/runs`).
+ *
+ * The recovery path for a client that still holds its API key but has lost a Run
+ * id — a reinstalled app, or a crash before the id from {@link createRun} was
+ * persisted. `{ status: "suspended" }` finds the Run still waiting on an answer.
+ *
+ * Only the calling principal's own Runs are ever returned; there is no
+ * cross-principal listing.
+ *
+ * Page by following `nextCursor` until it is ABSENT — a full page is not the
+ * signal to stop, and an absent cursor is the only one.
+ */
+export function listRuns(transport, options = {}) {
+    const query = {
+        ...(options.status === undefined ? {} : { status: options.status }),
+        ...(options.limit === undefined ? {} : { limit: options.limit }),
+        ...(options.cursor === undefined ? {} : { cursor: options.cursor }),
+    };
+    return transport.requestJson(runOperation("list_public_runs"), {
+        ...(Object.keys(query).length > 0 ? { query } : {}),
+        ...(options.signal ? { signal: options.signal } : {}),
+    });
+}
 /** Get a Run's current state (`GET /api/v1/runs/{runId}`). */
 export function getRun(transport, runId, signal) {
     return transport.requestJson(runOperation("get_public_run"), {

package/schema-resource-types.d.ts

@@ -1,20 +1,23 @@
-/**
- * Wire types for the governed STATIC schema (`GET /api/v1/schema/*`).
- *
- * THE LENS: "what does the registry DEFINE?" — blocks, attributes, units, value
- * dictionaries, product types and their external mappings. Definitions, not
- * data: nothing here says how many materials carry an attribute or which values
- * the corpus holds. For that, use `mg.specificationFacets()` and
- * `mg.attributeValues()`; for one term explained in prose, `mg.glossary()`; for
- * what one material has been determined on, `mg.materialBlocks()`.
- *
- * Every id here (`attributeId`, `blockId`, product-type keys) is canonical
- * VOCABULARY, not an opaque token — this is where you discover it rather than
- * invent it.
- */
 import type { OpenEnum } from "./types.js";
 /** The nine governed static resources. */
 export type SchemaResource = "blocks" | "attributes" | "verticals" | "productTypes" | "units" | "valueDictionaries" | "sourceRequirements" | "productTypeTemplates" | "mappings";
+/**
+ * Resource → the operation that serves it. Internal to the SDK (`index.ts`
+ * re-exports this module's TYPES only), and it lives beside
+ * {@link SchemaResource} rather than in the client so the mapping and the union
+ * it must cover cannot drift apart.
+ */
+export declare const SCHEMA_RESOURCE_OPERATION_IDS: {
+    readonly blocks: "list_schema_blocks";
+    readonly attributes: "list_schema_attributes";
+    readonly verticals: "list_schema_verticals";
+    readonly productTypes: "list_schema_product_types";
+    readonly units: "list_schema_units";
+    readonly valueDictionaries: "list_schema_value_dictionaries";
+    readonly sourceRequirements: "list_schema_source_requirements";
+    readonly productTypeTemplates: "list_schema_product_type_templates";
+    readonly mappings: "list_schema_mappings";
+};
 export type SchemaResourceRequest = SchemaResource;
 export interface SchemaLifecycle {
     status: OpenEnum<"draft" | "active" | "deprecated">;

package/schema-resource-types.js

@@ -1 +1,17 @@
-export {};
+/**
+ * Resource → the operation that serves it. Internal to the SDK (`index.ts`
+ * re-exports this module's TYPES only), and it lives beside
+ * {@link SchemaResource} rather than in the client so the mapping and the union
+ * it must cover cannot drift apart.
+ */
+export const SCHEMA_RESOURCE_OPERATION_IDS = {
+    blocks: "list_schema_blocks",
+    attributes: "list_schema_attributes",
+    verticals: "list_schema_verticals",
+    productTypes: "list_schema_product_types",
+    units: "list_schema_units",
+    valueDictionaries: "list_schema_value_dictionaries",
+    sourceRequirements: "list_schema_source_requirements",
+    productTypeTemplates: "list_schema_product_type_templates",
+    mappings: "list_schema_mappings",
+};

package/search-result-validation.js

@@ -143,6 +143,9 @@ export function checkSearchResultItem(value, what, fail) {
     requireString(record.product, `${what}.product`, fail);
     requireNullableString(record.brandSlug, `${what}.brandSlug`, fail);
     requireNullableString(record.productId, `${what}.productId`, fail);
+    // `z.string().optional()` — absent, or a string. NOT nullable: the emit path
+    // omits the key rather than sending null when no MB identity is known.
+    requireOptionalString(record.materialBankId, `${what}.materialBankId`, fail);
     requireNullableString(record.color, `${what}.color`, fail);
     requireNullableString(record.variantName, `${what}.variantName`, fail);
     requireNullableString(record.imageUrl, `${what}.imageUrl`, fail);