@instruments/materialgraph 0.9.1 → 0.10.0

package/resolve-types.d.ts

@@ -27,8 +27,18 @@
  *   pair, for `mg.bySpec()` or `search({ filters })`.
  * - `attribute_value` — a value-dictionary term, namespaced (`ms_sheen.matte`):
  *   the RIGHT half.
+ * - `jurisdiction` — a code jurisdiction id (`us-tx`), for `mg.codeAdvisory()`.
+ * - `occupancy_group` — an IBC occupancy group (`R-1`), the other axis the code
+ *   endpoints are keyed on. BARE, not namespaced, even though the groups live in
+ *   a value dictionary: `R-1` is the token those endpoints take.
+ *
+ * The two code axes are half a context, not a whole one. `/codes/advisory` also
+ * needs a `spaceType` (or a `roomType` to correlate one from) and a
+ * `sprinklered` flag — neither of which a phrase can state — and it validates
+ * the combination before it answers, so send them and read its verdict rather
+ * than assuming a resolved pair is usable.
  */
-export type ResolutionKind = "brand" | "paint_identity" | "colour" | "category" | "attribute" | "attribute_value";
+export type ResolutionKind = "brand" | "paint_identity" | "colour" | "category" | "attribute" | "attribute_value" | "jurisdiction" | "occupancy_group";
 /**
  * How the phrase matched, strongest first. `exact` — it IS the canonical token;
  * `alias` — it IS a recorded alternative name for it; `lexical` — it resembles
@@ -68,6 +78,49 @@ export interface ResolvedMeaning {
     ambiguity?: {
         gap: number;
     };
+    /**
+     * How much of the catalogue stands behind this reading — so you never have to
+     * make a second, differently-shaped call to find out that a confident answer
+     * is empty.
+     *
+     * ABSENT means coverage could not be determined for this reading; it is a
+     * statement about the MEASUREMENT, never about the catalogue. A measured
+     * nothing is `{ variants: 0 }`. Do not collapse the two: `attribute` and
+     * `attribute_value` readings (and `brand`, whose corpus weight comes free)
+     * carry it; the rest have no equivalently cheap count behind them and report
+     * nothing rather than a figure measured a different way.
+     */
+    coverage?: MeaningCoverage;
+}
+/** How much of the catalogue stands behind one reading. */
+export interface MeaningCoverage {
+    /**
+     * How many variants carry this reading, CORPUS-WIDE and across every brand —
+     * never scoped to the `category` you sent, even when you sent one. `0` is a
+     * measured answer, not missing data: MaterialGraph knows the word and the
+     * catalogue holds nothing under it, which is the case worth catching before
+     * you spend the token on a filter.
+     *
+     * For an `attribute` reading over an ARRAY-valued attribute a variant is
+     * counted once per token it carries, so the figure is an upper bound on
+     * distinct variants there. It is exact for scalar attributes, exact for every
+     * `attribute_value`, and the zero is exact in every case.
+     */
+    variants: number;
+    /**
+     * Whether the `category` you sent holds ANY accepted value for the attribute
+     * behind this reading. Present only when you sent a category AND the answer
+     * could be determined — its absence is a statement about the measurement, not
+     * a `false`.
+     *
+     * `false` means no criterion built on this reading can be satisfied inside
+     * that category at any rung of retrieval's relaxation ladder, however large
+     * `variants` is. Read this rather than inferring reachability from the count:
+     * an attribute with forty thousand values across the catalogue can hold none
+     * at all in Wall Finishes. The probe is ATTRIBUTE-level, so `true` says the
+     * category holds SOME value for the attribute, not that it holds this one.
+     */
+    inCategory?: boolean;
 }
 /** What one phrase resolved to — including, explicitly, nothing. */
 export interface PhraseResolution {
@@ -95,6 +148,22 @@ export interface PhraseResolution {
      */
     unresolved: boolean;
 }
+/** Optional scoping for a resolve call. */
+export interface ResolvePhrasesOptions {
+    /**
+     * The product category you are grounding these words FOR — a slot, not a
+     * filter. It adds {@link MeaningCoverage.inCategory} to every `attribute` and
+     * `attribute_value` reading. Omit for corpus-wide only.
+     */
+    category?: string;
+    signal?: AbortSignal;
+}
+/**
+ * What `mg.resolve()` accepts as its second argument. A bare `AbortSignal` is
+ * still accepted, exactly as before {@link ResolvePhrasesOptions} existed, so no
+ * existing call site had to move.
+ */
+export type ResolvePhrasesScope = AbortSignal | ResolvePhrasesOptions;
 /** 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. */

package/run-events.d.ts

@@ -1,3 +1,4 @@
+import type { RunEvent } from "./run-types.js";
 /**
  * Typed payloads for the composition Run event family — the friction fix flagged
  * by the MG-443 walk. These narrow the loose {@link RunEvent.payloadJson} so
@@ -13,7 +14,6 @@
  * as standalone TS types (no cross-package import; the SDK is publishable).
  */
 import type { OpenEnum } from "./types.js";
-import type { RunEvent } from "./run-types.js";
 export declare const COMPOSITION_PHASE_EVENT_TYPES: readonly ["composition.phase", "material-box.phase"];
 export declare const COMPOSITION_PROGRAMME_EVENT_TYPES: readonly ["composition.programme", "material-box.brief"];
 export declare const COMPOSITION_REVIEW_CRITERIA_EVENT_TYPES: readonly ["composition.review-criteria", "material-box.review-criteria"];

package/run-events.js

@@ -1,5 +1,8 @@
 // ── Wire event-type strings (both generations) ───────────────────────────────
-export const COMPOSITION_PHASE_EVENT_TYPES = ["composition.phase", "material-box.phase"];
+export const COMPOSITION_PHASE_EVENT_TYPES = [
+    "composition.phase",
+    "material-box.phase",
+];
 export const COMPOSITION_PROGRAMME_EVENT_TYPES = [
     "composition.programme",
     "material-box.brief",

package/runs.d.ts

@@ -1,6 +1,6 @@
 import { HttpTransport } from "./http-transport.js";
-import type { FinishScheduleResponse, GetRunScheduleOptions } from "./schedule-types.js";
 import { type CapabilityManifestResponse, type CreatePublicRunRequest, type CreatePublicRunResponse, type DrainRunEventsOptions, type ListRunsOptions, type PublicRunListResponse, type PublicRunResponse, type ResumeRunOptions, type RunEvent, type SourceMaterialBatchDetail, type SourceMaterialBatchReceipt, type StreamRunEventsOptions, type UploadSourceMaterialInput } from "./run-types.js";
+import type { FinishScheduleResponse, GetRunScheduleOptions } from "./schedule-types.js";
 /**
  * Upload one atomic source-material batch (`POST /api/v1/source-material`).
  * Accepts the pile-of-files shape (`{ files }` → repeatable `files` field) or

package/runs.js

@@ -7,10 +7,10 @@
  */
 import { MaterialGraphError } from "./errors.js";
 import { HttpTransport } from "./http-transport.js";
-import { findSdkOperation, operationPath } from "./operations.js";
+import { findSdkOperation, operationPath, } from "./operations.js";
+import { TERMINAL_RUN_EVENT_TYPES, } from "./run-types.js";
 import { checkSourceMaterialBatchDetail } from "./source-material-validation.js";
 import { readSseFrames } from "./sse.js";
-import { TERMINAL_RUN_EVENT_TYPES, } from "./run-types.js";
 function runOperation(operationId) {
     const match = findSdkOperation(operationId);
     if (!match)
@@ -224,7 +224,9 @@ function decodeRunEvent(data) {
 export async function* streamRunEvents(transport, runId, options = {}) {
     const body = await transport.openStream(runOperation("list_public_run_events"), {
         pathParams: { runId },
-        ...(options.after === undefined ? {} : { query: { after: options.after } }),
+        ...(options.after === undefined
+            ? {}
+            : { query: { after: options.after } }),
         ...(options.signal ? { signal: options.signal } : {}),
         accept: "text/event-stream",
         subject: "run-event stream",
@@ -265,7 +267,9 @@ export async function drainRunEvents(transport, runId, options) {
         }
     }
     catch (error) {
-        const causedByDeadline = controller.signal.aborted && error instanceof MaterialGraphError && error.kind === "aborted";
+        const causedByDeadline = controller.signal.aborted &&
+            error instanceof MaterialGraphError &&
+            error.kind === "aborted";
         if (!causedByDeadline)
             throw error;
     }

package/search-refinement-types.d.ts

@@ -1,9 +1,10 @@
 /** Types for structured refinements returned by MaterialGraph search. */
 import type { SearchInput } from "./types.js";
 /**
- * A hard canonical-attribute filter accepted by the search engine — either a
- * term match (`{ attributeId, term }`) or a presence check
- * (`{ attributeId, hasValue: true }`). Applied as a restriction BEFORE ranking.
+ * A hard canonical-attribute filter accepted by the search engine — a term match
+ * (`{ attributeId, term }`), a presence check (`{ attributeId, hasValue: true }`)
+ * or a NUMERIC RANGE (`{ attributeId, min, max }`, bounds inclusive, at least one
+ * stated). Applied as a restriction BEFORE ranking.
  *
  * The `attributeId` may be a real registry id (`"fire_classifications"`,
  * `"environmental_product_declaration"`) OR the virtual
@@ -52,6 +53,13 @@ export type SearchFilter = {
     attributeId: string;
     hasValue: true;
     trust?: SearchFilterTrust;
+} | {
+    attributeId: string;
+    /** Inclusive lower bound. Omit for a ceiling-only range. */
+    min?: number;
+    /** Inclusive upper bound. Omit for a floor-only range. */
+    max?: number;
+    trust?: SearchFilterTrust;
 };
 /** One structured refinement returned with a search response. */
 export interface SearchSuggestion {

package/search-result-validation.js

@@ -12,17 +12,33 @@ export const VERDICT_STATES = [
 /** `attributeVerdictSchema.strength`. */
 export const VERDICT_STRENGTHS = ["required", "preferred"];
 /** `verdictBaselineSchema` discriminant — the four arms of what a cell was judged against. */
-export const VERDICT_BASELINE_KINDS = ["term", "presence", "seed", "image"];
+export const VERDICT_BASELINE_KINDS = [
+    "term",
+    "presence",
+    "seed",
+    "image",
+];
 /** The `image` baseline arm's own `source` enum. */
 export const VERDICT_IMAGE_SOURCES = ["variant", "vector"];
 /** `verdictDeviationSchema.direction`. */
-export const VERDICT_DEVIATION_DIRECTIONS = ["above", "below", "other"];
+export const VERDICT_DEVIATION_DIRECTIONS = [
+    "above",
+    "below",
+    "other",
+];
 /** `verdictTrustGapSchema` — why a real value did not clear the trust bar. */
-export const VERDICT_TRUST_GAPS = ["below_confidence", "basis_unmet", "proposed"];
+export const VERDICT_TRUST_GAPS = [
+    "below_confidence",
+    "basis_unmet",
+    "proposed",
+];
 /** `verdictGradeSchema` — the rolled-up card grade. */
 export const VERDICT_GRADES = ["meets_all", "close", "hard_no"];
 /** `visualMeaningSchema.basis` — where a meaning came from. */
-export const VISUAL_MEANING_BASES = ["canonical_attribute", "image_colour_analysis"];
+export const VISUAL_MEANING_BASES = [
+    "canonical_attribute",
+    "image_colour_analysis",
+];
 // ── Leaf checks ──────────────────────────────────────────────────────────────
 /** `palette[]` — `{ hex, proportion, name: string.nullable().optional() }`. */
 function checkPaletteSwatch(value, what, fail) {
@@ -165,6 +181,7 @@ export function checkSearchResultItem(value, what, fail) {
         checkSignals(record.signals, `${what}.signals`, fail);
     requireOptionalBoolean(record.retired, `${what}.retired`, fail);
     requireOptionalBoolean(record.belowFloor, `${what}.belowFloor`, fail);
+    requireOptionalBoolean(record.admittedOnColour, `${what}.admittedOnColour`, fail);
     if (record.siblingCount !== undefined) {
         requireIntegerAtLeast(record.siblingCount, `${what}.siblingCount`, fail, 1);
     }

package/source-material-validation.js

@@ -91,7 +91,9 @@ function checkFile(value, what, fail) {
         // fields is a canonical change to a schema shared with the upload path, and
         // belongs in its own ticket with this mirror following after.
         bytes: requireSafeInteger(record.bytes, `${what}.bytes`, fail),
-        pages: record.pages === null ? null : requireSafeInteger(record.pages, `${what}.pages`, fail),
+        pages: record.pages === null
+            ? null
+            : requireSafeInteger(record.pages, `${what}.pages`, fail),
         url: requireString(record.url, `${what}.url`, fail),
         analyses: analyses.map((analysis, index) => checkAnalysis(analysis, `${what}.analyses[${index}]`, fail)),
     };

package/spec-facet-types.d.ts

@@ -0,0 +1,53 @@
+export interface SpecFacetValue {
+    value: string;
+    variants: number;
+    brands: number;
+    label?: string;
+}
+/**
+ * A NUMERIC facet's observed span and the coverage behind it.
+ *
+ * A range, not buckets — no bucketing scheme has been decided, and one invented
+ * on the wire would be treated as canonical by everyone who read it. Both bounds
+ * are INCLUSIVE, matching `specRange`.
+ *
+ * READ `variants` BEFORE TRUSTING A FILTER. It is how many variants carry a
+ * value that parses as a number, i.e. how much of the corpus a range can reach;
+ * a facet that exists says the attribute is queryable, not that it is populated.
+ * `unparseableVariants` is the honesty companion: values recorded here that are
+ * not numbers, which a range EXCLUDES rather than reading as zero.
+ */
+export interface SpecFacetRange {
+    min: number;
+    max: number;
+    variants: number;
+    unparseableVariants: number;
+}
+export interface SpecFacet {
+    attributeId: string;
+    name: string;
+    isArray: boolean;
+    /**
+     * How this facet is queried. `token` — pick a value from `values` and send it
+     * as `attribute:value`. `numeric` — `values` is EMPTY and `range` carries the
+     * span; send inclusive bounds via `specRangeCriterion` instead.
+     */
+    kind: "token" | "numeric" | (string & {});
+    brands: number;
+    /** EMPTY for a `numeric` facet, which has no token vocabulary. */
+    values: SpecFacetValue[];
+    /** Present ONLY on a `numeric` facet. */
+    range?: SpecFacetRange;
+    description?: string;
+}
+export interface SpecFacetsListResponse {
+    mode: "facets";
+    count: number;
+    facets: SpecFacet[];
+}
+export interface SpecFacetsDistributionResponse {
+    mode: "distribution";
+    attributeId: string;
+    count: number;
+    values: SpecFacetValue[];
+}

package/spec-facet-types.js

@@ -0,0 +1,7 @@
+// ── Specification facets + attribute values ─────────────────────────────────
+//
+// Hand-maintained mirror of the `SpecificationFacet` OpenAPI schema (the source
+// of truth on the wire); the `sdk-openapi-parity` test gates this against the
+// generated spec. Split out of `types.ts` to keep that file under its growth
+// baseline; re-exported from `types.ts` so importers see no change.
+export {};

package/specifications.d.ts

@@ -57,6 +57,32 @@ export declare function certificationProgramme(programme: string): Certification
  * client.bySpec([specCriterion("primary_material", "textile"), specCriterion("fire_classifications", "astm_e84_class_a")]);
  */
 export declare function specCriterion(attributeId: string, value: string): string;
+/**
+ * An `attribute:min..max` RANGE criterion string for `bySpec`, for a
+ * NUMBER-valued spec (`light_reflectance_value`, `nrc_rating`,
+ * `slip_resistance_dcof`, …). Pass the result in `bySpec`'s `ranges` option.
+ *
+ * BOTH BOUNDS ARE INCLUSIVE — `{ min: 60 }` matches a value of exactly 60 —
+ * because spec language is written that way ("LRV of 60 or more", "DCOF ≥ 0.42")
+ * and because inclusive-both-ends means adjacent ranges overlap at the join
+ * rather than leaving a gap that hides products.
+ *
+ * At least one bound is REQUIRED: a range with neither is a presence check, and
+ * this throws rather than sending a criterion the server would have to refuse.
+ * Discover which attributes take a range — and the span they actually occupy —
+ * from `specificationFacets()`: those are the facets with `kind: "numeric"`.
+ *
+ * @example
+ * // light paints, every brand at once
+ * client.bySpec([], { ranges: [specRangeCriterion("light_reflectance_value", { min: 60 })] });
+ * @example
+ * // a mid-tone band
+ * specRangeCriterion("light_reflectance_value", { min: 30, max: 45 }); // "light_reflectance_value:30..45"
+ */
+export declare function specRangeCriterion(attributeId: string, bounds: {
+    min?: number;
+    max?: number;
+}): string;
 /**
  * An `attribute:value` criterion string for `bySpec` that filters by
  * certification PROGRAMME across all four certification buckets.

package/specifications.js

@@ -65,6 +65,38 @@ export function certificationProgramme(programme) {
 export function specCriterion(attributeId, value) {
     return `${attributeId}:${value}`;
 }
+/**
+ * An `attribute:min..max` RANGE criterion string for `bySpec`, for a
+ * NUMBER-valued spec (`light_reflectance_value`, `nrc_rating`,
+ * `slip_resistance_dcof`, …). Pass the result in `bySpec`'s `ranges` option.
+ *
+ * BOTH BOUNDS ARE INCLUSIVE — `{ min: 60 }` matches a value of exactly 60 —
+ * because spec language is written that way ("LRV of 60 or more", "DCOF ≥ 0.42")
+ * and because inclusive-both-ends means adjacent ranges overlap at the join
+ * rather than leaving a gap that hides products.
+ *
+ * At least one bound is REQUIRED: a range with neither is a presence check, and
+ * this throws rather than sending a criterion the server would have to refuse.
+ * Discover which attributes take a range — and the span they actually occupy —
+ * from `specificationFacets()`: those are the facets with `kind: "numeric"`.
+ *
+ * @example
+ * // light paints, every brand at once
+ * client.bySpec([], { ranges: [specRangeCriterion("light_reflectance_value", { min: 60 })] });
+ * @example
+ * // a mid-tone band
+ * specRangeCriterion("light_reflectance_value", { min: 30, max: 45 }); // "light_reflectance_value:30..45"
+ */
+export function specRangeCriterion(attributeId, bounds) {
+    const { min, max } = bounds;
+    if (min === undefined && max === undefined) {
+        throw new Error(`specRangeCriterion("${attributeId}") needs a min, a max, or both — a range with neither would match every recorded value. Use hasSpec() for a presence check.`);
+    }
+    if (min !== undefined && max !== undefined && min > max) {
+        throw new Error(`specRangeCriterion("${attributeId}") is inverted (min ${min} > max ${max}) and can only ever match nothing.`);
+    }
+    return `${attributeId}:${min ?? ""}..${max ?? ""}`;
+}
 /**
  * An `attribute:value` criterion string for `bySpec` that filters by
  * certification PROGRAMME across all four certification buckets.

package/sse.js

@@ -40,7 +40,9 @@ export class SseDecoder {
     flush() {
         if (this.#buffer.length > 0) {
             // At end of stream a deferred trailing CR is a real terminator, not data.
-            const line = this.#buffer.endsWith("\r") ? this.#buffer.slice(0, -1) : this.#buffer;
+            const line = this.#buffer.endsWith("\r")
+                ? this.#buffer.slice(0, -1)
+                : this.#buffer;
             this.#buffer = "";
             const frame = this.#consumeLine(line);
             if (frame)

package/suggest-types.js

@@ -21,6 +21,8 @@
  * Undefined members are dropped by the transport.
  */
 export function suggestQuery(q, options) {
-    const kind = Array.isArray(options?.kind) ? options.kind.join(",") : options?.kind;
+    const kind = Array.isArray(options?.kind)
+        ? options.kind.join(",")
+        : options?.kind;
     return { q, limit: options?.limit, kind };
 }

package/types.d.ts

@@ -121,10 +121,14 @@ export interface SearchResultItem {
     brandSlug: string | null;
     productId: ProductId | null;
     /**
-     * The variant's Material Bank SKU — the same `materialBankId` the material
-     * record carries, so a match card can render straight from a result instead of
-     * paying a per-result lookup. Populated on the MATCH lanes (`match()` and
-     * `matchStream()` frames).
+     * The variant's Material Bank SKU — the ONE EXTERNAL identifier on a result,
+     * in deliberate contrast to the opaque `variantId` above. `variantId` is ours
+     * and means nothing anywhere else; this is the id you are expected to match
+     * against Material Bank's own catalogue, so a result list can be joined to a
+     * cart, an order or an analytics event without a per-result lookup.
+     *
+     * Populated on EVERY lane: `search()` (all four arms), `match()`, and
+     * `matchStream()` frames.
      *
      * ABSENT means no MB identity is known for the variant — never that the SKU
      * cannot be ordered. Presence is the orderability tell; absence is silence.
@@ -189,6 +193,17 @@ export interface SearchResultItem {
      * dropped by default. Appended after the kept results.
      */
     belowFloor?: boolean;
+    /**
+     * Present (true) only on Match rows the colour probe admitted (match only):
+     * this material is as close in colour as the catalogue gets, and its image
+     * similarity is BELOW the match quality floor by design. It is on the page
+     * because nothing image-retrieved is nearer in colour, not because it cleared
+     * the floor — present it as a colour answer or suppress it knowingly. Absent
+     * (never `false`) on rows that came through image retrieval. Distinct from
+     * {@link SearchResultItem.belowFloor}, which marks rejects returned only under
+     * `includeBelowFloor`.
+     */
+    admittedOnColour?: boolean;
     siblingCount?: number;
     visualMeanings?: VisualMeaning[];
     /**
@@ -567,12 +582,24 @@ export interface SearchInput {
     mood?: string;
     sort?: OpenEnum<"relevance" | "light" | "dark" | "vivid" | "muted" | "colourful">;
     /**
-     * Seed a visual search from an existing variant's image (`variantId`) or a
-     * pre-computed image vector (`vector`). Only the `{ variantId }` form carries a
-     * seed variant, so it is the only form `verdicts` can diff a candidate against.
+     * Seed a visual search from an existing variant's image (`variantId`), from a
+     * Material Bank SKU (`materialBankId`), or from a pre-computed image vector
+     * (`vector`).
+     *
+     * `materialBankId` exists so a caller already holding a SKU does not have to
+     * ask us to translate it before it can ask us anything useful — one call, not
+     * two. It resolves to the variant server-side and then behaves identically to
+     * the `{ variantId }` form, seed verdicts included. A SKU that names no
+     * variant is a 400 carrying the offending value: never an empty result set,
+     * never a silent fall back to unseeded search.
+     *
+     * The `{ vector }` form carries no seed variant, so it is the only one
+     * `verdicts` cannot diff a candidate against.
      */
     similarTo?: {
         variantId: VariantId;
+    } | {
+        materialBankId: string;
     } | {
         vector: string;
     };
@@ -691,6 +718,13 @@ export interface ResolveAttributeOptions {
 /** Options for `search/specifications`. */
 export interface BySpecOptions {
     limit?: number;
+    /**
+     * Numeric range criteria as `attribute:min..max` strings, ANDed with the
+     * `spec` criteria. Build them with `specRangeCriterion` rather than by hand —
+     * both bounds are inclusive and at least one is required, and a hand-built
+     * token with neither is refused by the server rather than matching everything.
+     */
+    ranges?: string[];
 }
 export type * from "./demand-types.js";
 /** One quarter's tally. Sparse across a series — an absent quarter is not a zero. */
@@ -731,31 +765,7 @@ export interface ExtractedPalette {
 export interface ExtractPaletteResponse {
     palette: ExtractedPalette | null;
 }
-export interface SpecFacetValue {
-    value: string;
-    variants: number;
-    brands: number;
-    label?: string;
-}
-export interface SpecFacet {
-    attributeId: string;
-    name: string;
-    isArray: boolean;
-    brands: number;
-    values: SpecFacetValue[];
-    description?: string;
-}
-export interface SpecFacetsListResponse {
-    mode: "facets";
-    count: number;
-    facets: SpecFacet[];
-}
-export interface SpecFacetsDistributionResponse {
-    mode: "distribution";
-    attributeId: string;
-    count: number;
-    values: SpecFacetValue[];
-}
+export type * from "./spec-facet-types.js";
 export interface ApplicableSpecAttribute {
     id: string;
     name: string;