@instruments/materialgraph 0.7.0 → 0.8.0

package/client.js

@@ -1,33 +1,20 @@
 import { MaterialGraphError } from "./errors.js";
 import { HttpTransport } from "./http-transport.js";
-import { findSdkOperation } from "./operations.js";
-import { cancelRun, capabilities as capabilitiesRun, createRun, drainRunEvents, getRun, getRunSchedule, getSourceMaterialBatch as getSourceMaterialBatchCall, resumeRun, streamRunEvents, uploadSourceMaterial, } from "./runs.js";
+// Aliased to `operation` — the local name every call site here already used.
+import { resolveOperation as operation } from "./operations.js";
+import { cancelRun, capabilities as capabilitiesRun, createRun, drainRunEvents, getRun, getRunSchedule, getSourceMaterialBatch as getSourceMaterialBatchCall, listRuns, resumeRun, streamRunEvents, uploadSourceMaterial, } from "./runs.js";
+import { DEFAULT_BASE_URL, MAX_BATCH_IDS } from "./client-config.js";
+// Re-exported whole so `index.ts` and every existing importer keep their path.
+export * from "./client-config.js";
 import { browseQuery, createBrowseNamespace } from "./client-browse.js";
 import { suggestQuery } from "./suggest-types.js";
 import { matchStream as matchStreamCall } from "./match-stream.js";
 import { appendProjectEvent as appendProjectEventCall, createProject as createProjectCall, getProject as getProjectCall, listProjects as listProjectsCall, } from "./projects.js";
 import { CodesClient } from "./codes-client.js";
 import { ColoursClient } from "./colours-client.js";
-export const DEFAULT_BASE_URL = "https://beta.materialgraph.com";
-export const MAX_BATCH_IDS = 100;
-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",
-};
-function operation(operationId) {
-    const match = findSdkOperation(operationId);
-    if (!match) {
-        throw MaterialGraphError.unexpected(`Unknown SDK operation: ${operationId}`);
-    }
-    return match;
-}
+import { resolvePhrasesRequest, searchVocabularyRequest } from "./resolve-client.js";
+import { declaredFinishes, declaredProducts } from "./associations-client.js";
+import { SCHEMA_RESOURCE_OPERATION_IDS } from "./schema-resource-types.js";
 /**
  * The MaterialGraph client — every lens on the graph, on one object.
  *
@@ -41,18 +28,25 @@ function operation(operationId) {
  * | "which materials, from anyone, meet this hard spec?" | {@link MaterialGraphClient.bySpec} |
  * | "what's near this colour / this palette / this gradient?" | {@link MaterialGraphClient.byColour}, `colours.palette()`, `colours.gradient()` |
  * | "what goes with THIS material?" | {@link MaterialGraphClient.pairings}, {@link MaterialGraphClient.siblings}, {@link MaterialGraphClient.coordinate} |
+ * | "what does the manufacturer say is AVAILABLE on this?" | {@link MaterialGraphClient.associatedFinishes}, {@link MaterialGraphClient.associatedProducts} |
  * | "how much is this specified?" | {@link MaterialGraphClient.demand}, {@link MaterialGraphClient.demandBatch} |
  * | "is this allowed in an A-2 corridor?" | `codes.*` |
  * | "what can I even ask for?" | {@link MaterialGraphClient.specificationFacets}, {@link MaterialGraphClient.attributeValues}, {@link MaterialGraphClient.taxonomy}, {@link MaterialGraphClient.colourFacets}, {@link MaterialGraphClient.glossary} |
+ * | "I have words — what do they mean in YOUR vocabulary?" | {@link MaterialGraphClient.resolve} |
  * | "do the whole job for me, async" | {@link MaterialGraphClient.createRun} + `mg:compose` |
  *
- * Two structural rules that fall out of that table:
+ * Three structural rules that fall out of that table:
  * - **Colour is a separate lens.** {@link MaterialGraphClient.search} matches
  *   WORDS. A colour word in `text` finds materials whose text mentions it, not
  *   materials that look it. Route visual intent to the colour lenses.
  * - **Relationships hang off a material, not off a query.** You cannot ask "what
  *   pairs with beige oak"; you resolve a material first, then ask what pairs
  *   with THAT `variantId`.
+ * - **Declared is not inferred.** `associatedFinishes()` /
+ *   `associatedProducts()` return compatibility the MANUFACTURER stated;
+ *   `pairings()` returns companionship the graph INFERRED. The response shapes
+ *   share no field, on purpose — render them as separate sections and never
+ *   concatenate them.
  *
  * And three reading rules that apply to every lens: ids are opaque (see
  * `./identifiers.ts`), absent is not false, and a page is not a corpus.
@@ -208,6 +202,8 @@ export class MaterialGraphClient {
      * {@link MaterialGraphClient.browse} to walk by lightness/vividness, and
      * {@link MaterialGraphClient.search} when colour is one signal among many.
      * Report matches as visual likeness, never a stated colour specification.
+     * `family` gates the answer to ONE colorscope colour family when nearness
+     * alone crosses a hue boundary; a gated page can be shorter than `limit`.
      */
     byColour(params, signal) {
         return this.#get("search_by_colour", {
@@ -217,6 +213,7 @@ export class MaterialGraphClient {
             a: params.a,
             b: params.b,
             category: params.category,
+            family: params.family,
             limit: params.limit,
         }, signal);
     }
@@ -298,6 +295,14 @@ export class MaterialGraphClient {
             variantId,
         });
     }
+    /** "What finishes does the manufacturer declare for THIS product?" — {@link declaredFinishes}. */
+    associatedFinishes(variantId, options, signal) {
+        return declaredFinishes(this.#transport, variantId, options, signal);
+    }
+    /** "What products does the manufacturer declare THIS finish for?" — {@link declaredProducts}. */
+    associatedProducts(variantId, options, signal) {
+        return declaredProducts(this.#transport, variantId, options, signal);
+    }
     materials(ids, options, signal) {
         if (ids.length > MAX_BATCH_IDS) {
             throw MaterialGraphError.unexpected(`MaterialGraphClient.materials(): at most ${MAX_BATCH_IDS} ids per call, received ${ids.length}. Split into multiple batches.`);
@@ -379,16 +384,13 @@ export class MaterialGraphClient {
     resolveAttributeValue(attributeId, query, options, signal) {
         return this.#get("catalog_resolve_value", { q: query, limit: options?.limit }, signal, { attributeId });
     }
-    /**
-     * THE QUESTION: "is 'FloorScore' an attribute or a value, and what is it called
-     * here?" The catch-all when you do not know which half of an `attribute:value`
-     * pair a phrase belongs to. Instead use
-     * {@link MaterialGraphClient.resolveAttribute} /
-     * {@link MaterialGraphClient.resolveAttributeValue} once you do, and
-     * {@link MaterialGraphClient.glossary} to EXPLAIN a term rather than find it.
-     */
+    /** "Is this phrase an attribute or a value?" — see {@link searchVocabularyRequest}. */
     searchVocabulary(query, options, signal) {
-        return this.#get("catalog_vocabulary_search", { q: query, limit: options?.limit, kind: options?.kind }, signal);
+        return searchVocabularyRequest(this.#transport, query, options, signal);
+    }
+    /** "I have words — what do they mean in YOUR vocabulary?" — see {@link resolvePhrasesRequest}. */
+    resolve(phrases, signal) {
+        return resolvePhrasesRequest(this.#transport, phrases, signal);
     }
     /**
      * THE QUESTION: "which materials, from ANYONE, are ASTM E84 Class A AND
@@ -398,7 +400,10 @@ export class MaterialGraphClient {
      * Instead use `search({ filters })` when the spec merely GATES a ranked
      * question, `codes.advisory()` when the real question is what a space demands,
      * and {@link MaterialGraphClient.specificationFacets} first if you do not know
-     * the canonical tokens — guessing one returns an honest, empty answer.
+     * the canonical tokens. Guessing one no longer returns a silently empty
+     * answer: an unresolvable criterion means the query NEVER RAN, and the
+     * response says so — read {@link BySpecResponse.unresolvedCriteria} before
+     * treating an empty `matches` as "nothing qualifies".
      *
      * A PAGE, NOT A CORPUS, unusually so: `totalMatches` is the size of the
      * returned sample under `limit`, not a corpus count. See {@link BySpecResponse}.
@@ -642,6 +647,18 @@ export class MaterialGraphClient {
     run(runId, signal) {
         return getRun(this.#transport, runId, signal);
     }
+    /**
+     * THE QUESTION: "which Runs are mine?" — your own Runs, newest first, paged
+     * (GET `/api/v1/runs`). This is how a client that lost a Run id finds its work
+     * again: `{ status: "suspended" }` returns the Runs still waiting on an
+     * answer, whose ids you can then feed to {@link MaterialGraphClient.resumeRun}.
+     *
+     * Only your own Runs are ever returned. Page by following `nextCursor` until
+     * it is ABSENT — a full page is not the signal to stop.
+     */
+    listRuns(options) {
+        return listRuns(this.#transport, options);
+    }
     /**
      * Export a completed compose Run's scheme as a finish schedule — one row per
      * slot, every attribute value carrying its source and verification state

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.0",
+  "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. */