@instruments/materialgraph 0.9.0 → 0.10.0

package/http-transport.js

@@ -19,7 +19,10 @@ function parseRateLimit(headers) {
     const remaining = parseIntOrNull(headers.get("x-ratelimit-remaining"));
     const reset = parseIntOrNull(headers.get("x-ratelimit-reset"));
     const retryAfter = parseIntOrNull(headers.get("retry-after"));
-    if (limit === null && remaining === null && reset === null && retryAfter === null) {
+    if (limit === null &&
+        remaining === null &&
+        reset === null &&
+        retryAfter === null) {
         return null;
     }
     return { limit, remaining, reset, retryAfter };
@@ -39,7 +42,11 @@ export class HttpTransport {
     }
     /** The bearer + JSON `Accept` headers, plus any per-request additions. */
     authHeaders(extra) {
-        return { Authorization: `Bearer ${this.apiKey}`, Accept: "application/json", ...extra };
+        return {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: "application/json",
+            ...extra,
+        };
     }
     buildUrl(path, query) {
         const url = new URL(`${this.baseUrl}${path}`);
@@ -83,7 +90,11 @@ export class HttpTransport {
             });
         }
         catch (cause) {
-            throw MaterialGraphError.fromTransport({ ...metadata, cause, callerSignal: input.signal });
+            throw MaterialGraphError.fromTransport({
+                ...metadata,
+                cause,
+                callerSignal: input.signal,
+            });
         }
         const rateLimit = parseRateLimit(response.headers);
         this.#lastRateLimit = rateLimit;
@@ -92,7 +103,11 @@ export class HttpTransport {
             text = await response.text();
         }
         catch (cause) {
-            throw MaterialGraphError.fromTransport({ ...metadata, cause, callerSignal: input.signal });
+            throw MaterialGraphError.fromTransport({
+                ...metadata,
+                cause,
+                callerSignal: input.signal,
+            });
         }
         let parsed;
         if (text.length > 0) {
@@ -147,7 +162,11 @@ export class HttpTransport {
             });
         }
         catch (cause) {
-            throw MaterialGraphError.fromTransport({ ...metadata, cause, callerSignal: options.signal });
+            throw MaterialGraphError.fromTransport({
+                ...metadata,
+                cause,
+                callerSignal: options.signal,
+            });
         }
         const rateLimit = parseRateLimit(response.headers);
         this.#lastRateLimit = rateLimit;

package/index.d.ts

@@ -1,4 +1,4 @@
-export { MaterialGraphClient, DEFAULT_BASE_URL, MAX_BATCH_IDS } from "./client.js";
+export { MaterialGraphClient, DEFAULT_BASE_URL, MAX_BATCH_IDS, } from "./client.js";
 export type { MaterialGraphClientOptions, BrowseNamespace } from "./client.js";
 export { MATERIALGRAPH_API_VERSION, SDK_OPERATIONS } from "./operations.js";
 export type { SdkOperation, SdkOperationId } from "./operations.js";
@@ -27,10 +27,11 @@ 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 "./fan-deck-types.js";
 export type * from "./material-asset-types.js";
 export type * from "./material-block-types.js";
 export type * from "./schema-resource-types.js";
 export type * from "./search-refinement-types.js";
 export { CERTIFICATION_PROGRAMME_ATTRIBUTE_ID } from "./spec-types.js";
 export type * from "./spec-types.js";
-export { certificationProgramme, certificationProgrammeCriterion, hasSpec, specCriterion, specTerm, } from "./specifications.js";
+export { certificationProgramme, certificationProgrammeCriterion, hasSpec, specCriterion, specRangeCriterion, specTerm, } from "./specifications.js";

package/index.js

@@ -1,4 +1,4 @@
-export { MaterialGraphClient, DEFAULT_BASE_URL, MAX_BATCH_IDS } from "./client.js";
+export { MaterialGraphClient, DEFAULT_BASE_URL, MAX_BATCH_IDS, } from "./client.js";
 export { MATERIALGRAPH_API_VERSION, SDK_OPERATIONS } from "./operations.js";
 export { TERMINAL_RUN_EVENT_TYPES } from "./run-types.js";
 export { VARY_AXES } from "./composition-types.js";
@@ -9,4 +9,4 @@ export { MATCH_IMAGE_TYPES, MATCH_OUTCOMES, MATCH_MATERIAL_FUNCTIONS, MATCH_STRE
 export { CodesClient } from "./codes-client.js";
 export { ColoursClient } from "./colours-client.js";
 export { CERTIFICATION_PROGRAMME_ATTRIBUTE_ID } from "./spec-types.js";
-export { certificationProgramme, certificationProgrammeCriterion, hasSpec, specCriterion, specTerm, } from "./specifications.js";
+export { certificationProgramme, certificationProgrammeCriterion, hasSpec, specCriterion, specRangeCriterion, specTerm, } from "./specifications.js";

package/match-stream-types.d.ts

@@ -1,3 +1,4 @@
+import type { MatchCategoryInference, MatchColourReading } from "./match-types.js";
 /**
  * The Material Match PROGRESS-STREAM contracts — the wire vocabulary of
  * {@link MaterialGraphClient.matchStream} (`POST /api/v1/search/match` under
@@ -16,7 +17,6 @@
  * UI legend from the same source the validator uses.
  */
 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];
@@ -26,8 +26,16 @@ export type MatchMaterialFunction = (typeof MATCH_MATERIAL_FUNCTIONS)[number];
 /** The workflow's coarse progress phase, narrated by a `step` event. */
 export declare const MATCH_WORKFLOW_STEPS: readonly ["classifying", "decomposing", "matching", "complete"];
 export type MatchWorkflowStep = (typeof MATCH_WORKFLOW_STEPS)[number];
-/** Where one surface stands in the run. */
-export declare const MATCH_SURFACE_STATUSES: readonly ["pending", "matching", "complete", "error"];
+/**
+ * Where one surface stands in the run.
+ *
+ * `colour_fallback` (appended, additive): the surface completed, but through
+ * the colour lane — its visible sample was too small to read texture, so the
+ * results match the region's palette, scoped to the detected category. Such a
+ * surface carries a `note` saying so and no `senseCheck` verdicts (there is no
+ * texture to verify).
+ */
+export declare const MATCH_SURFACE_STATUSES: readonly ["pending", "matching", "complete", "error", "colour_fallback"];
 export type MatchSurfaceStatus = (typeof MATCH_SURFACE_STATUSES)[number];
 /** Every frame type the stream can carry — the union's discriminant values. */
 export declare const MATCH_STREAM_EVENT_TYPES: readonly ["step", "classified", "surfaces", "surface", "heartbeat", "complete", "error"];
@@ -112,9 +120,10 @@ export interface MatchSurfaceResult {
     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.
+     * is still reading them. Render the rows immediately. The follow-up frame
+     * carries the SAME rows with verdicts attached, settled once into verdict
+     * bands (confirmed → abstained → rejected, stable within each band) — the
+     * page's one settling reorder. Nothing is ever removed.
      */
     senseCheckPending?: boolean;
     /**
@@ -128,6 +137,12 @@ export interface MatchSurfaceResult {
         hex: string;
         proportion: number;
     }>;
+    /**
+     * One sentence of provenance a consumer may render verbatim, when the server
+     * sent one — e.g. the `colour_fallback` explanation carrying the refused
+     * sample's pixel size. Absent on ordinary surfaces.
+     */
+    note?: string;
     /** Present only on `status: "error"` — why this one surface failed. */
     error?: string;
 }
@@ -161,6 +176,21 @@ export interface MatchWorkflowResult {
      * "nothing above the floor". Do not fold `surfaces[]` to tell those apart.
      */
     totals: MatchRunTotals;
+    /**
+     * Whole-image palette matches, sent ONLY when an installation photo yielded
+     * no usable surfaces at all. These match the image's overall palette — they
+     * are not material identifications, and the note says so. A consumer that
+     * ignores this field sees exactly the empty run it saw before the field
+     * existed.
+     */
+    paletteMatches?: {
+        results: SearchResultItem[];
+        palette: Array<{
+            hex: string;
+            proportion: number;
+        }>;
+        note: string;
+    };
     /**
      * 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.

package/match-stream-types.js

@@ -1,5 +1,9 @@
 /** How the workflow classified the uploaded image. */
-export const MATCH_IMAGE_TYPES = ["swatch", "installation", "flatplan"];
+export const MATCH_IMAGE_TYPES = [
+    "swatch",
+    "installation",
+    "flatplan",
+];
 /** What a detected surface is FOR — the element the material would serve. */
 export const MATCH_MATERIAL_FUNCTIONS = [
     "flooring",
@@ -13,9 +17,28 @@ export const MATCH_MATERIAL_FUNCTIONS = [
     "sample",
 ];
 /** The workflow's coarse progress phase, narrated by a `step` event. */
-export const MATCH_WORKFLOW_STEPS = ["classifying", "decomposing", "matching", "complete"];
-/** Where one surface stands in the run. */
-export const MATCH_SURFACE_STATUSES = ["pending", "matching", "complete", "error"];
+export const MATCH_WORKFLOW_STEPS = [
+    "classifying",
+    "decomposing",
+    "matching",
+    "complete",
+];
+/**
+ * Where one surface stands in the run.
+ *
+ * `colour_fallback` (appended, additive): the surface completed, but through
+ * the colour lane — its visible sample was too small to read texture, so the
+ * results match the region's palette, scoped to the detected category. Such a
+ * surface carries a `note` saying so and no `senseCheck` verdicts (there is no
+ * texture to verify).
+ */
+export const MATCH_SURFACE_STATUSES = [
+    "pending",
+    "matching",
+    "complete",
+    "error",
+    "colour_fallback",
+];
 /** Every frame type the stream can carry — the union's discriminant values. */
 export const MATCH_STREAM_EVENT_TYPES = [
     "step",
@@ -26,7 +49,11 @@ export const MATCH_STREAM_EVENT_TYPES = [
     "complete",
     "error",
 ];
-export const MATCH_SENSE_CHECK_VERDICTS = ["confirmed", "rejected", "abstained"];
+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

package/match-stream.js

@@ -55,16 +55,21 @@
  * invariants.
  */
 import { MaterialGraphError } from "./errors.js";
-import { findSdkOperation } from "./operations.js";
 import { MATCH_IMAGE_TYPES, MATCH_MATERIAL_FUNCTIONS, MATCH_STREAM_EVENT_TYPES, MATCH_SURFACE_STATUSES, MATCH_WORKFLOW_STEPS, } from "./match-stream-types.js";
 import { readNdjsonLines } from "./ndjson.js";
+import { findSdkOperation, } from "./operations.js";
 import { checkSearchResultItems } from "./search-result-validation.js";
 import { requireArray, requireBoundedNumber, requireDefaultedArray, requireEnum, requireIntegerAtLeast, requireNumber, requireOptionalString, requireRecord, requireString, } from "./validation.js";
 /** The NDJSON media type the Match route negotiates the scene workflow on. */
 const MATCH_STREAM_ACCEPT = "application/x-ndjson";
 /** How much of an offending frame a diagnostic quotes (crops can be megabytes). */
 const MAX_FRAME_PREVIEW = 200;
-const BOUNDING_BOX_CORNERS = Object.freeze(["x0", "y0", "x1", "y1"]);
+const BOUNDING_BOX_CORNERS = Object.freeze([
+    "x0",
+    "y0",
+    "x1",
+    "y1",
+]);
 function operation(operationId) {
     const found = findSdkOperation(operationId);
     if (!found)
@@ -76,7 +81,9 @@ function operation(operationId) {
  * offending path and quoting a bounded slice of the frame.
  */
 function frameFailure(line) {
-    const preview = line.length > MAX_FRAME_PREVIEW ? `${line.slice(0, MAX_FRAME_PREVIEW)}…` : line;
+    const preview = line.length > MAX_FRAME_PREVIEW
+        ? `${line.slice(0, MAX_FRAME_PREVIEW)}…`
+        : line;
     return (reason) => MaterialGraphError.unexpected(`MaterialGraph match stream sent a malformed NDJSON frame: ${reason}. Frame: ${preview}`);
 }
 /** Check one `MatchCategoryInference` item. */
@@ -190,7 +197,10 @@ function readFrame(value, fail) {
             // Payload-free by contract — there is nothing else to check.
             return record;
         case "complete":
-            return { ...record, result: readWorkflowResult(record.result, "`result`", fail) };
+            return {
+                ...record,
+                result: readWorkflowResult(record.result, "`result`", fail),
+            };
         case "error":
             requireString(record.message, "`message`", fail);
             return record;

package/material-types.d.ts

@@ -1,3 +1,4 @@
+import type { ProductId, VariantId } from "./identifiers.js";
 /**
  * Hand-mirrored wire types for the material projections — the grid-card tile,
  * the detail record, and the availability/successor block they carry.
@@ -22,7 +23,6 @@
  * that says which.
  */
 import type { ImageSource, MaterialColour, OpenEnum, PaletteSwatch } from "./types.js";
-import type { ProductId, VariantId } from "./identifiers.js";
 /**
  * Whether a material can still be bought.
  *

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 ["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"]];
+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 ["brandColourDeck", "GET", "/api/v1/brands/{brandSlug}/colours", "brand_colour_deck"], 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];

package/operations.js

@@ -6,38 +6,118 @@ const OPERATION_DEFINITIONS = [
     ["match", "POST", "/api/v1/search/match", "match_material"],
     ["byColour", "GET", "/api/v1/search/colours", "search_by_colour"],
     ["material", "GET", "/api/v1/materials/{variantId}", "get_material"],
-    ["siblings", "GET", "/api/v1/materials/{variantId}/siblings", "get_material_siblings"],
-    ["materialBlocks", "GET", "/api/v1/materials/{variantId}/blocks", "list_material_blocks"],
-    ["materialAssets", "GET", "/api/v1/materials/{variantId}/assets", "list_material_assets"],
+    [
+        "siblings",
+        "GET",
+        "/api/v1/materials/{variantId}/siblings",
+        "get_material_siblings",
+    ],
+    [
+        "materialBlocks",
+        "GET",
+        "/api/v1/materials/{variantId}/blocks",
+        "list_material_blocks",
+    ],
+    [
+        "materialAssets",
+        "GET",
+        "/api/v1/materials/{variantId}/assets",
+        "list_material_assets",
+    ],
     ["schema", "GET", "/api/v1/schema/blocks", "list_schema_blocks"],
     ["schema", "GET", "/api/v1/schema/attributes", "list_schema_attributes"],
     ["schema", "GET", "/api/v1/schema/verticals", "list_schema_verticals"],
-    ["schema", "GET", "/api/v1/schema/product-types", "list_schema_product_types"],
+    [
+        "schema",
+        "GET",
+        "/api/v1/schema/product-types",
+        "list_schema_product_types",
+    ],
     ["schema", "GET", "/api/v1/schema/units", "list_schema_units"],
-    ["schema", "GET", "/api/v1/schema/value-dictionaries", "list_schema_value_dictionaries"],
-    ["schema", "GET", "/api/v1/schema/source-requirements", "list_schema_source_requirements"],
-    ["schema", "GET", "/api/v1/schema/product-type-templates", "list_schema_product_type_templates"],
+    [
+        "schema",
+        "GET",
+        "/api/v1/schema/value-dictionaries",
+        "list_schema_value_dictionaries",
+    ],
+    [
+        "schema",
+        "GET",
+        "/api/v1/schema/source-requirements",
+        "list_schema_source_requirements",
+    ],
+    [
+        "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"],
+    [
+        "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"],
+    [
+        "materialsCached",
+        "GET",
+        "/api/v1/materials/batch",
+        "get_materials_batch_get",
+    ],
     ["browse", "GET", "/api/v1/search/browse", "search_browse_by_colour"],
     ["colourFacets", "GET", "/api/v1/colours/facets", "get_colour_facets"],
-    ["colours.profiles", "GET", "/api/v1/colours/profiles", "get_category_colour_profiles"],
+    [
+        "colours.profiles",
+        "GET",
+        "/api/v1/colours/profiles",
+        "get_category_colour_profiles",
+    ],
     ["colours.stats", "GET", "/api/v1/colours/stats", "get_colour_stats"],
-    ["resolveColour", "GET", "/api/v1/search/colours/resolve", "resolve_colour_name"],
-    ["suggestColour", "GET", "/api/v1/search/colours/suggest", "suggest_colour_names"],
+    [
+        "resolveColour",
+        "GET",
+        "/api/v1/search/colours/resolve",
+        "resolve_colour_name",
+    ],
+    [
+        "suggestColour",
+        "GET",
+        "/api/v1/search/colours/suggest",
+        "suggest_colour_names",
+    ],
     ["suggest", "GET", "/api/v1/search/suggest", "search_suggest"],
-    ["resolveAttribute", "GET", "/api/v1/catalog/attributes/resolve", "catalog_resolve_attribute"],
+    [
+        "resolveAttribute",
+        "GET",
+        "/api/v1/catalog/attributes/resolve",
+        "catalog_resolve_attribute",
+    ],
     [
         "resolveAttributeValue",
         "GET",
         "/api/v1/catalog/attributes/{attributeId}/values/resolve",
         "catalog_resolve_value",
     ],
-    ["searchVocabulary", "GET", "/api/v1/catalog/vocabulary/search", "catalog_vocabulary_search"],
+    [
+        "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"],
@@ -45,38 +125,94 @@ const OPERATION_DEFINITIONS = [
     ["coordinate", "POST", "/api/v1/pairings/coordinate", "coordinate_materials"],
     ["demand", "GET", "/api/v1/demand", "get_material_demand"],
     ["colours.palette", "POST", "/api/v1/search/palettes", "search_by_palette"],
-    ["extractPalette", "POST", "/api/v1/search/palettes/extract", "extract_image_palette"],
-    ["colours.gradient", "POST", "/api/v1/search/gradients", "search_by_gradient"],
-    ["specificationFacets", "GET", "/api/v1/catalog/specifications/facets", "list_spec_facets"],
+    [
+        "extractPalette",
+        "POST",
+        "/api/v1/search/palettes/extract",
+        "extract_image_palette",
+    ],
+    [
+        "colours.gradient",
+        "POST",
+        "/api/v1/search/gradients",
+        "search_by_gradient",
+    ],
+    [
+        "specificationFacets",
+        "GET",
+        "/api/v1/catalog/specifications/facets",
+        "list_spec_facets",
+    ],
     [
         "attributeValues",
         "GET",
         "/api/v1/catalog/attributes/{attributeId}/values",
         "list_attribute_values",
     ],
-    ["applicableSpecs", "GET", "/api/v1/taxonomy/categories/{key}/specs", "get_applicable_specs"],
+    [
+        "applicableSpecs",
+        "GET",
+        "/api/v1/taxonomy/categories/{key}/specs",
+        "get_applicable_specs",
+    ],
     ["glossary", "GET", "/api/v1/glossary/{term}", "explain_material_term"],
     ["brands", "GET", "/api/v1/brands", "list_brands"],
     ["brand", "GET", "/api/v1/brands/{brandSlug}", "get_brand_profile"],
-    ["uploadSourceMaterial", "POST", "/api/v1/source-material", "upload_source_material"],
-    ["sourceMaterialBatch", "GET", "/api/v1/source-material/{batchId}", "get_source_material_batch"],
+    [
+        "brandColourDeck",
+        "GET",
+        "/api/v1/brands/{brandSlug}/colours",
+        "brand_colour_deck",
+    ],
+    [
+        "uploadSourceMaterial",
+        "POST",
+        "/api/v1/source-material",
+        "upload_source_material",
+    ],
+    [
+        "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"],
+    [
+        "runSchedule",
+        "GET",
+        "/api/v1/runs/{runId}/schedule",
+        "get_run_finish_schedule",
+    ],
+    [
+        "streamRunEvents",
+        "GET",
+        "/api/v1/runs/{runId}/events",
+        "list_public_run_events",
+    ],
     ["resumeRun", "POST", "/api/v1/runs/{runId}/resume", "resume_public_run"],
     ["cancelRun", "POST", "/api/v1/runs/{runId}/cancel", "cancel_public_run"],
     ["varyScheme", "POST", "/api/v1/schemes/vary", "vary_schemes"],
     ["createProject", "POST", "/api/v1/projects", "create_box_project"],
     ["listProjects", "GET", "/api/v1/projects", "list_box_projects"],
     ["getProject", "GET", "/api/v1/projects/{projectId}", "get_box_project"],
-    ["appendProjectEvent", "POST", "/api/v1/projects/{projectId}/events", "append_box_project_event"],
+    [
+        "appendProjectEvent",
+        "POST",
+        "/api/v1/projects/{projectId}/events",
+        "append_box_project_event",
+    ],
     ["demandBatch", "POST", "/api/v1/demand/batch", "get_demand_batch"],
     ["codeAdvisory", "POST", "/api/v1/codes/advisory", "resolveCodeAdvisory"],
     ["codes.context", "GET", "/api/v1/codes/context", "list_code_context"],
-    ["codes.requirements", "GET", "/api/v1/codes/requirements", "list_code_requirements"],
+    [
+        "codes.requirements",
+        "GET",
+        "/api/v1/codes/requirements",
+        "list_code_requirements",
+    ],
 ];
 export const SDK_OPERATIONS = Object.freeze(OPERATION_DEFINITIONS.map(([clientMethod, method, path, operationId]) => Object.freeze({ clientMethod, method, path, operationId })));
 /** Look up a registered operation by its OpenAPI `operationId`. */

package/package.json

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

package/resolve-client.d.ts

@@ -24,13 +24,19 @@
  * - 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 { ResolvePhrasesScope, 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()`.
+ * attribute, value, and the two code axes (jurisdiction, occupancy group) — best
+ * first, in request order. Backs `mg.resolve()`.
+ *
+ * The code axes read out of a sentence: "a maximum security prison in Kansas"
+ * returns `us-ks` and `I-3`, the pair `mg.codeAdvisory()` is keyed on. They are
+ * half a context, not a whole one — that call also wants a space type and a
+ * sprinklered flag, and validates the combination before it answers.
  *
  * 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
@@ -54,10 +60,23 @@ import type { VocabularySearchOptions, VocabularySearchResponse } from "./types.
  * complete a name as someone types, and `mg.glossary()` to EXPLAIN a token you
  * have already resolved.
  *
+ * - **Every reading says what stands behind it.** `coverage.variants` is how
+ *   many variants carry it corpus-wide, and `0` is a measured answer rather
+ *   than missing data — a word this vocabulary knows and the catalogue holds
+ *   nothing under. That is the case you would otherwise discover only by making
+ *   a second call, on a hot path, where a second call gets skipped. An ABSENT
+ *   `coverage` means it could not be determined; never read it as none.
+ *
+ * Pass `category` when you are grounding these words for a SLOT, and read
+ * `coverage.inCategory`: a corpus-wide count is not a promise the reading is
+ * reachable inside a given category, and that conflation is what turns a
+ * top-ranked suggestion into an unsatisfiable requirement.
+ *
  * @param phrases 1-50 phrases, each 1-200 characters. Sent as-is; each is
  * resolved independently, so one meaningless phrase never spoils the batch.
+ * @param options `category` to scope the coverage answer, and an `AbortSignal`.
  */
-export declare function resolvePhrasesRequest(transport: HttpTransport, phrases: string[], signal?: AbortSignal): Promise<ResolveResponse>;
+export declare function resolvePhrasesRequest(transport: HttpTransport, phrases: string[], scope?: ResolvePhrasesScope): 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