@instruments/materialgraph 0.7.1 → 0.9.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,7 +15,9 @@ 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 { 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-types.js";
+export type * from "./by-colour-types.js";
+export { MATCH_IMAGE_TYPES, MATCH_OUTCOMES, 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";
 export type * from "./codes-types.js";
@@ -23,6 +25,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/index.js

@@ -5,7 +5,7 @@ export { VARY_AXES } from "./composition-types.js";
 export { PROJECT_EVENT_KINDS } from "./project-types.js";
 export { COMPOSITION_PHASE_EVENT_TYPES, COMPOSITION_PROGRAMME_EVENT_TYPES, COMPOSITION_REVIEW_CRITERIA_EVENT_TYPES, parseRunEvent, } from "./run-events.js";
 export { MaterialGraphError } from "./errors.js";
-export { MATCH_IMAGE_TYPES, MATCH_MATERIAL_FUNCTIONS, MATCH_STREAM_EVENT_TYPES, MATCH_SURFACE_STATUSES, MATCH_WORKFLOW_STEPS, } from "./match-stream-types.js";
+export { MATCH_IMAGE_TYPES, MATCH_OUTCOMES, MATCH_MATERIAL_FUNCTIONS, MATCH_STREAM_EVENT_TYPES, MATCH_SURFACE_STATUSES, MATCH_WORKFLOW_STEPS, } from "./match-stream-types.js";
 export { CodesClient } from "./codes-client.js";
 export { ColoursClient } from "./colours-client.js";
 export { CERTIFICATION_PROGRAMME_ATTRIBUTE_ID } from "./spec-types.js";

package/match-stream-types.d.ts

@@ -15,7 +15,8 @@
  * The value lists are exported so a consumer can build an exhaustive switch or a
  * UI legend from the same source the validator uses.
  */
-import type { MatchCategoryInference, SearchResultItem } from "./types.js";
+import type { SearchResultItem } from "./types.js";
+import type { MatchCategoryInference, MatchColourReading } from "./match-types.js";
 /** How the workflow classified the uploaded image. */
 export declare const MATCH_IMAGE_TYPES: readonly ["swatch", "installation", "flatplan"];
 export type MatchImageType = (typeof MATCH_IMAGE_TYPES)[number];
@@ -57,21 +58,99 @@ export interface MatchDetectedSurface {
  * arrives repeatedly as the run progresses (`matching` → `complete` / `error`);
  * render by replacing on id rather than appending.
  *
+ * A `complete` surface can arrive TWICE: the first frame delivers its finished
+ * results as soon as they exist, and a second repeats them unchanged with the
+ * verifier's per-candidate verdicts attached (`senseCheck`).
+ * Replacing on id handles both; the results never change between them, so
+ * nothing a user is looking at moves when the second lands.
+ *
  * `results` and `inferredCategories` are always present on a yielded event: the
  * canonical schema defaults each to `[]`, and the reader fills them when the
  * server omits them, so neither ever arrives as `undefined`.
  */
+/**
+ * What a Match actually compared, so a consumer can tell "the catalogue holds
+ * nothing close" from "everything ranked badly" (MG-1031). Without it both
+ * arrive as an empty list and the difference is unrecoverable.
+ *
+ * UNITS: `qualityFloor` and `bestRejected` are absolute image-arm cosines in
+ * [0,1] — the same unit as each result's `confidence` — so they belong on one
+ * axis. `poolSize` and `droppedBelowFloor` are counts and belong on neither.
+ */
+export interface MatchComparison {
+    /** Candidates retrieved before the quality floor and product dedup. */
+    poolSize: number;
+    /** How many of those the quality floor rejected. */
+    droppedBelowFloor: number;
+    /** The floor they were held to, as an absolute image cosine in [0,1]. */
+    qualityFloor: number;
+    /**
+     * The closest REJECTED candidate, same unit as `qualityFloor`. Absent when
+     * nothing was rejected, or when the rejects carried no readable signal.
+     */
+    bestRejected?: number;
+}
 export interface MatchSurfaceResult {
     surface: MatchDetectedSurface;
     status: MatchSurfaceStatus;
     results: SearchResultItem[];
     inferredCategories: MatchCategoryInference[];
+    /** What this surface compared against. Absent means the server did not report it. */
+    comparison?: MatchComparison;
+    /**
+     * The verifier's reading of each candidate, when it ran.
+     *
+     * ABSENT means the stage did not run — it is opt-out, and the swatch route
+     * never runs it — OR that it is still running, which `senseCheckPending`
+     * distinguishes. Neither is the same as every candidate abstaining, and a
+     * consumer must not conflate them.
+     *
+     * `abstained` is NOT a soft rejection: it means the candidate was not judged
+     * (no image, no answer, or the judge was unavailable). Never render an
+     * abstention as a negative signal about the material.
+     */
+    senseCheck?: MatchSenseCheckCell[];
+    /**
+     * TRUE on the interim frame that delivers finished results while the verifier
+     * is still reading them. The verifier annotates; it never filters and never
+     * reorders, so this says "badges are coming", never "these results may
+     * change". Render the rows immediately.
+     */
+    senseCheckPending?: boolean;
+    /**
+     * Per-candidate colour readings against this surface's own crop, when the
+     * colour re-rank ran. `results` are already ordered by the blended score when
+     * this is present; this array is the receipt for that order.
+     */
+    colour?: MatchColourReading[];
+    /** The segment's own extracted palette — what the colour stage matched against. */
+    segmentPalette?: Array<{
+        hex: string;
+        proportion: number;
+    }>;
     /** Present only on `status: "error"` — why this one surface failed. */
     error?: string;
 }
+/** The verifier's reading of one candidate, keyed back to its variant. */
+export interface MatchSenseCheckCell {
+    variantId: string;
+    verdict: MatchSenseCheckVerdict;
+    reason: string;
+}
+export declare const MATCH_SENSE_CHECK_VERDICTS: readonly ["confirmed", "rejected", "abstained"];
+export type MatchSenseCheckVerdict = (typeof MATCH_SENSE_CHECK_VERDICTS)[number];
 /** The terminal Match workflow result — every surface in its final state. */
+/**
+ * How a Match run ended. `no_surfaces` means the detector worked and found no
+ * material in the photo — a finding, not a failure. Branch on this rather than
+ * on an error message. Absent means `matched`.
+ */
+export declare const MATCH_OUTCOMES: readonly ["matched", "no_surfaces"];
+export type MatchOutcome = (typeof MATCH_OUTCOMES)[number];
 export interface MatchWorkflowResult {
     imageType: MatchImageType;
+    /** How the run ended. Absent means `matched`. */
+    outcome?: MatchOutcome;
     surfaces: MatchSurfaceResult[];
     /** Present for swatch / single-surface runs that skip decompose. */
     results?: SearchResultItem[];
@@ -82,6 +161,11 @@ export interface MatchWorkflowResult {
      * "nothing above the floor". Do not fold `surfaces[]` to tell those apart.
      */
     totals: MatchRunTotals;
+    /**
+     * What a SWATCH run compared against — a swatch detects no surfaces, so it has
+     * nowhere else to put this. A scene run reports per surface instead.
+     */
+    comparison?: MatchComparison;
 }
 /** Progress narration for the phase the workflow just entered. */
 export interface MatchStreamStepEvent {

package/match-stream-types.js

@@ -26,3 +26,11 @@ export const MATCH_STREAM_EVENT_TYPES = [
     "complete",
     "error",
 ];
+export const MATCH_SENSE_CHECK_VERDICTS = ["confirmed", "rejected", "abstained"];
+/** The terminal Match workflow result — every surface in its final state. */
+/**
+ * How a Match run ended. `no_surfaces` means the detector worked and found no
+ * material in the photo — a finding, not a failure. Branch on this rather than
+ * on an error message. Absent means `matched`.
+ */
+export const MATCH_OUTCOMES = ["matched", "no_surfaces"];

package/match-stream.d.ts

@@ -1,6 +1,6 @@
 import type { HttpTransport } from "./http-transport.js";
 import { type MatchStreamEvent } from "./match-stream-types.js";
-import type { MatchInput } from "./types.js";
+import type { MatchInput } from "./match-types.js";
 /**
  * Decode one NDJSON line into a validated {@link MatchStreamEvent}, raising a
  * {@link MaterialGraphError} on anything the contract does not allow. Exported

package/match-types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * @module sdk/match-types
+ * @description The buffered Material Match request and response, hand-mirrored
+ * from the server's Zod contracts.
+ *
+ * Split out of `types.ts` — which is at the repository's source-size limit —
+ * along its natural seam: everything a caller of `client.match()` needs, and
+ * nothing else. The STREAMING contracts live in `match-stream-types.ts`.
+ */
+import type { SearchFilter } from "./search-refinement-types.js";
+import type { OpenEnum, PaletteSwatch, SearchResultItem } from "./types.js";
+/** An inferred product-type category from the query image, with its boost. */
+export interface MatchCategoryInference {
+    productTypeId: string;
+    displayName: string;
+    boost: number;
+}
+/**
+ * The Material Match response (non-streaming form).
+ *
+ * `poolSize` is the candidate pool the floor was applied to, NOT a corpus total
+ * and NOT "how many materials look like this". An empty `results` with
+ * `droppedBelowFloor > 0` means "candidates existed and none was good enough" —
+ * a different answer from `poolSize: 0`, which means the image found nothing to
+ * search against at all.
+ */
+/**
+ * One candidate's colour reading against the query crop. `measurable: false`
+ * means the material carries no palette on record — UNKNOWN, never "no colour"
+ * and never "the wrong colour".
+ */
+export interface MatchColourReading {
+    variantId: string;
+    colourDistance: number | null;
+    colourBand: string | null;
+    measurable: boolean;
+}
+export interface MatchResponse {
+    /** THIS answer, capped by `limit`. Not a total. */
+    results: SearchResultItem[];
+    inferredCategories: MatchCategoryInference[];
+    qualityFloor: number;
+    poolSize: number;
+    droppedBelowFloor: number;
+    droppedAsDuplicateProduct: number;
+    /**
+     * The closest candidate the quality floor REJECTED, in the same [0,1] unit as
+     * `qualityFloor`. This is what turns "no matches" into "the closest thing in
+     * the catalogue read 0.48 against a 0.55 bar" — the one number that separates
+     * an engine that failed from a corpus that does not hold the material. Absent
+     * when nothing was rejected; null when the rejects carried no readable signal.
+     */
+    bestRejected?: number | null;
+    /** The maximum score achievable under the weights this query ran — `score`'s denominator. */
+    maxScore: number;
+    /**
+     * Per-candidate colour readings against the query crop, in `results` order.
+     * `null` means the colour stage DID NOT RUN (no image bytes, or it was turned
+     * off) — never "no colour".
+     */
+    colour?: MatchColourReading[] | null;
+    /** The query crop's own extracted palette — what the colour stage compared against. */
+    segmentPalette?: PaletteSwatch[] | null;
+    note?: string;
+}
+/** The Material Match request body — exactly one of `imageBase64`, `imageUrl`, `vector`. */
+export interface MatchInput {
+    imageBase64?: string;
+    imageUrl?: string;
+    vector?: string;
+    limit?: number;
+    qualityFloor?: number;
+    categoryTopK?: number;
+    categoryMinBoost?: number;
+    detectionLabel?: string;
+    /**
+     * The detector's fuller reading of the surface — a SENTENCE, where
+     * `detectionLabel` is a phrase. Fused WITH the image into ONE multimodal
+     * query vector and preferred over the label when both are present.
+     *
+     * Distinct from `detectionLabel`, which also buys the category scope: a
+     * request can narrow the scope by label and steer retrieval by description in
+     * the same call.
+     */
+    detectionDescription?: string;
+    materialFunction?: string;
+    detectionCategory?: string;
+    /**
+     * Opt-in: also return quality-floor rejects, flagged `belowFloor: true` and
+     * appended after the kept results. Absent/false = default behaviour;
+     * `droppedBelowFloor` is unchanged.
+     */
+    includeBelowFloor?: boolean;
+    requestedType?: OpenEnum<"swatch" | "installation" | "flatplan">;
+    /** Hard spec gates forwarded verbatim to the inner search — term match or presence, each with an optional trust bar. */
+    filters?: SearchFilter[];
+    /** Soft criteria (rank-never-exclude). A miss demotes within the page but never removes a hit. */
+    preferences?: SearchFilter[];
+    /** Opt in to seed-relative verdict cells; inert unless the inner search carries a variant seed. */
+    verdicts?: boolean;
+}

package/match-types.js

@@ -0,0 +1 @@
+export {};

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.9.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 });
+}