@instruments/materialgraph 0.8.0 → 0.9.0

package/by-colour-types.d.ts

@@ -67,6 +67,20 @@ export interface ColourFamilyGate {
      */
     dropped: number;
 }
+/**
+ * Receipt for the colour-identity collapse that turns a variant-grain ranking
+ * into a page of TILES — one per (brand, product, dominant hex), one per stored
+ * photograph. The live endpoint always sends it; it is optional here only so
+ * responses captured before the collapse existed still type-check.
+ */
+export interface ColourCollapse {
+    /** Ranked rows the collapse examined — this page's pool, never a corpus total. */
+    considered: number;
+    /** Rows dropped for repeating a better-ranked row's brand, product and hex. */
+    droppedByIdentity: number;
+    /** Rows dropped for resolving to a better-ranked row's stored photograph. */
+    droppedBySharedImage: number;
+}
 /** The `search/colours` response. */
 export interface ByColourResponse {
     query: {
@@ -85,6 +99,12 @@ export interface ByColourResponse {
      * what says so in counts rather than adjectives.
      */
     familyGate?: ColourFamilyGate;
+    /**
+     * What the colour-identity collapse cost this page. Matches are TILES: a page
+     * can be SHORTER than `limit` when the pool collapsed harder than the
+     * overfetch allowed, and this says so in counts rather than adjectives.
+     */
+    collapse?: ColourCollapse;
 }
 /** Params for `search/colours`. */
 export interface ByColourParams {

package/client.d.ts

@@ -18,7 +18,8 @@ import type { MaterialBlockProjection } from "./material-block-types.js";
 import type { SchemaResource, SchemaResourceResponse } from "./schema-resource-types.js";
 import type { BatchId, ProjectId, RunId, VariantId } from "./identifiers.js";
 import type { ByColourParams, ByColourResponse } from "./by-colour-types.js";
-import type { ApplicableSpecsResponse, BrandOptions, BrandProfileResponse, BySpecOptions, BySpecResponse, ColourFacetsResponse, CoordinateInput, CoordinateResponse, DemandBatchInput, DemandBatchResponse, DemandParams, DemandResponse, ExtractPaletteInput, ExtractPaletteResponse, GlossaryTermResponse, MaterialResponse, MaterialsBatchDetailResponse, MaterialsBatchGetOptions, MaterialsBatchOptions, MaterialsBatchTileResponse, MatchInput, MatchResponse, PairingsOptions, PairingsResponse, ResolveAttributeOptions, ResolveAttributeResponse, ResolveAttributeValueOptions, ResolveAttributeValueResponse, ResolveColourResponse, SearchGetParams, SearchInput, SearchResponse, SiblingsResponse, SpecFacetsDistributionResponse, SpecFacetsListResponse, SuggestColourResponse, SuggestOptions, SuggestResponse, TaxonomyResponse, VocabularySearchOptions, WhoamiResponse } from "./types.js";
+import type { ApplicableSpecsResponse, BrandOptions, BrandProfileResponse, BySpecOptions, BySpecResponse, ColourFacetsResponse, CoordinateInput, CoordinateResponse, DemandBatchInput, DemandBatchResponse, DemandParams, DemandResponse, ExtractPaletteInput, ExtractPaletteResponse, GlossaryTermResponse, MaterialResponse, MaterialsBatchDetailResponse, MaterialsBatchGetOptions, MaterialsBatchOptions, MaterialsBatchTileResponse, PairingsOptions, PairingsResponse, ResolveAttributeOptions, ResolveAttributeResponse, ResolveAttributeValueOptions, ResolveAttributeValueResponse, ResolveColourResponse, SearchGetParams, SearchInput, SearchResponse, SiblingsResponse, SpecFacetsDistributionResponse, SpecFacetsListResponse, SuggestColourResponse, SuggestOptions, SuggestResponse, TaxonomyResponse, VocabularySearchOptions, WhoamiResponse } from "./types.js";
+import type { MatchInput, MatchResponse } from "./match-types.js";
 /**
  * The MaterialGraph client — every lens on the graph, on one object.
  *

package/index.d.ts

@@ -15,8 +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 type * from "./match-types.js";
 export type * from "./by-colour-types.js";
-export { MATCH_IMAGE_TYPES, MATCH_MATERIAL_FUNCTIONS, MATCH_STREAM_EVENT_TYPES, MATCH_SURFACE_STATUSES, MATCH_WORKFLOW_STEPS, } from "./match-stream-types.js";
+export { 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";

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/package.json

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

package/run-events.d.ts

@@ -50,7 +50,18 @@ export interface CompositionReviewCriteriaSuggestion {
 export interface CompositionReviewCriteriaUnresolved {
     slotId: string;
     raw: string;
+    /**
+     * Ranked corrections, best first. MG-994: every one of these is an attribute
+     * the slot's own category holds accepted values for, so accepting the top
+     * suggestion can never leave the slot unfillable.
+     */
     suggestions: CompositionReviewCriteriaSuggestion[];
+    /**
+     * MG-994: attribute ids ranked for this phrase and then withheld — the slot's
+     * category holds no accepted value for them. ABSENT when nothing was withheld
+     * (absent means nothing was removed, not that nothing could be).
+     */
+    withheld?: string[];
 }
 /**
  * Payload of a `composition.review-criteria` / `material-box.review-criteria`

package/search-result-validation.js

@@ -146,6 +146,11 @@ export function checkSearchResultItem(value, what, fail) {
     // `z.string().optional()` — absent, or a string. NOT nullable: the emit path
     // omits the key rather than sending null when no MB identity is known.
     requireOptionalString(record.materialBankId, `${what}.materialBankId`, fail);
+    // Same shape as `materialBankId`: absent, or a string. The emit path omits
+    // the key when no primary product type is on record rather than sending null,
+    // so "we don't know what this is" and "this is a null kind of thing" cannot
+    // be confused.
+    requireOptionalString(record.productType, `${what}.productType`, fail);
     requireNullableString(record.color, `${what}.color`, fail);
     requireNullableString(record.variantName, `${what}.variantName`, fail);
     requireNullableString(record.imageUrl, `${what}.imageUrl`, fail);

package/types.d.ts

@@ -130,6 +130,20 @@ export interface SearchResultItem {
      * cannot be ordered. Presence is the orderability tell; absence is silence.
      */
     materialBankId?: string;
+    /**
+     * What kind of material this is — the variant's primary product type, as a
+     * display name (`"Wall Tile"`, `"Modular Carpet"`, `"Interior Paint"`).
+     *
+     * This is the field that lets you tell a wall tile from a bar stool without
+     * parsing `product`. Before it existed, callers grading Match results had to
+     * regex the product's NAME, and one such grader scored pendant lights and
+     * electrical sockets as correct answers for a wall — because they are neither
+     * a stool nor a chair.
+     *
+     * ABSENT means no primary type is on record for the variant. Unknown, never
+     * "uncategorised" and never "not a material".
+     */
+    productType?: string;
     color: string | null;
     variantName: string | null;
     imageUrl: string | null;
@@ -138,6 +152,35 @@ export interface SearchResultItem {
     colourMeta?: ColourMeta;
     /** Fused score — range [0, sum of active weights]; see `maxScore`. */
     score: number;
+    /**
+     * Match only. How close this material is to the query, as an ABSOLUTE
+     * image-space similarity in [0,1] adjusted for colour — the same unit as
+     * `qualityFloor` and `comparison.bestRejected`, so all three sit on one axis.
+     *
+     * Never normalised against the page, so the same material reads the same in
+     * two different searches. It is the TRUE value and MAY reach 1 — rendering it
+     * so that no card claims "100%" is yours to do (round toward zero, or show
+     * "99%+"); `Math.round` prints 100% from 0.995 up. Capping it server-side
+     * would put it on a different ceiling from `comparison.bestRejected`, which
+     * publishes the same unit uncapped, and the two are meant to be comparable.
+     * `score` is the ranking value and lives on a different scale.
+     */
+    confidence?: number;
+    /**
+     * `confidence` as a word — `strong` >= 0.85, `good` >= 0.72, `fair` >= 0.55
+     * (the default quality floor), `weak` below it and only reachable under
+     * `includeBelowFloor`. Present exactly when `confidence` is.
+     */
+    confidenceBand?: "strong" | "good" | "fair" | "weak";
+    /**
+     * Match only. Proportion-weighted OKLab distance from the query crop's palette
+     * to this material's. `null` means the material carries no stored palette —
+     * UNKNOWN colour, never "no colour" and never "distant". Absent when the
+     * colour stage did not run.
+     */
+    colourDistance?: number | null;
+    /** `colourDistance` as a word, or null when unmeasurable. */
+    colourBand?: string | null;
     signals?: SearchResultSignals;
     retired?: boolean;
     /**
@@ -244,31 +287,6 @@ export interface SearchCardResponse extends Omit<SearchResponse, "view" | "resul
     view: OpenEnum<"card">;
     results: SearchCardItem[];
 }
-/** 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.
- */
-export interface MatchResponse {
-    /** THIS answer, capped by `limit`. Not a total. */
-    results: SearchResultItem[];
-    inferredCategories: MatchCategoryInference[];
-    qualityFloor: number;
-    poolSize: number;
-    droppedBelowFloor: number;
-    droppedAsDuplicateProduct: number;
-    note?: string;
-}
 /** One item from the pure colour-scalar browse. */
 export interface BrowseResultItem {
     /** Opaque — round-trip verbatim. */
@@ -640,32 +658,6 @@ export interface BrowseParams {
      */
     types?: 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;
-    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;
-}
 /** Options for a batch material read. */
 export interface MaterialsBatchOptions {
     /** Projection depth. `tile` omits fields rather than reporting them absent. */