@instruments/materialgraph 0.18.0 → 0.20.0

package/client.js

@@ -5,6 +5,7 @@ import { HttpTransport } from "./http-transport.js";
 // Aliased to `operation` — the local name every call site here already used.
 import { resolveOperation as operation, } from "./operations.js";
 import { cancelRun, capabilities as capabilitiesRun, createRun, drainRunEvents, getRun, getRunSchedule, getSourceMaterialBatch as getSourceMaterialBatchCall, listRuns, resumeRun, streamRunEvents, uploadSourceMaterial, } from "./runs.js";
+import { ScheduleReferencesClient } from "./schedule-references-client.js";
 // Re-exported whole so `index.ts` and every existing importer keep their path.
 export * from "./client-config.js";
 import { browseQuery, createBrowseNamespace, } from "./client-browse.js";
@@ -12,16 +13,16 @@ import { createExplorationNamespace, } from "./client-exploration.js";
 import { createSourceMaterialCommentsNamespace, } from "./client-source-material-comments.js";
 import * as assoc from "./associations-client.js";
 import { brandColourDeck, brandProfile, listBrands } from "./brands-client.js";
+import { colourFacets as colourFacetsCall, resolveAttribute as resolveAttributeCall, resolveAttributeValue as resolveAttributeValueCall, resolveColour as resolveColourCall, suggest as suggestCall, suggestColour as suggestColourCall, } from "./client-vocabulary.js";
 import { CodesClient } from "./codes-client.js";
 import { ColoursClient } from "./colours-client.js";
 import { slotPools as slotPoolsCall, varyScheme as varySchemeCall, } from "./composition-client.js";
 import { coordinate as coordinateCall } from "./coordinate-client.js";
 import { matchStream as matchStreamCall } from "./match-stream.js";
-import { materialAssets as materialAssetsCall, materialBlocks as materialBlocksCall, materialDocuments as materialDocumentsCall, } from "./material-resources-client.js";
+import { materialAssets as materialAssetsCall, materialRenderAssets as materialRenderAssetsCall, materialBlocks as materialBlocksCall, materialDocuments as materialDocumentsCall, } from "./material-resources-client.js";
 import { appendProjectEvent as appendProjectEventCall, createProject as createProjectCall, getProject as getProjectCall, listProjects as listProjectsCall, } from "./projects.js";
 import { resolvePhrasesRequest as resolvePhrases, searchVocabularyRequest, } from "./resolve-client.js";
 import { SCHEMA_RESOURCE_OPERATION_IDS } from "./schema-resource-types.js";
-import { suggestQuery } from "./suggest-types.js";
 /**
  * The MaterialGraph client — every lens on the graph, on one object.
  *
@@ -58,6 +59,7 @@ import { suggestQuery } from "./suggest-types.js";
  * `./identifiers.ts`), absent is not false, and a page is not a corpus.
  */
 export class MaterialGraphClient extends CatalogueClient {
+    scheduleReferences;
     baseUrl;
     /**
      * THE QUESTION: "show me everything in this category / this brand, in a plain
@@ -121,6 +123,7 @@ export class MaterialGraphClient extends CatalogueClient {
         super(transport);
         this.#transport = transport;
         this.baseUrl = transport.baseUrl;
+        this.scheduleReferences = new ScheduleReferencesClient(transport);
         this.browse = createBrowseNamespace((params, signal) => this.#get("search_browse_by_colour", browseQuery(params), signal));
         this.codes = new CodesClient({
             get: (operationId, query, signal) => this.#get(operationId, query, signal),
@@ -143,10 +146,11 @@ export class MaterialGraphClient extends CatalogueClient {
             pathParams,
         });
     }
-    #post(operationId, body, signal) {
+    #post(operationId, body, signal, pathParams) {
         return this.#transport.requestJson(operation(operationId), {
             body,
             signal,
+            pathParams,
         });
     }
     /**
@@ -245,6 +249,8 @@ export class MaterialGraphClient extends CatalogueClient {
             category: params.category,
             brand: params.brand,
             family: params.family,
+            order: params.order,
+            maxColourDistance: params.maxColourDistance,
             corpusScope: params.corpusScope,
             limit: params.limit,
         }, signal);
@@ -282,6 +288,9 @@ export class MaterialGraphClient extends CatalogueClient {
     materialAssets(variantId, signal) {
         return materialAssetsCall(this.#transport, variantId, signal);
     }
+    materialRenderAssets(variantId, signal) {
+        return materialRenderAssetsCall(this.#transport, variantId, signal);
+    }
     materialDocuments(variantId, options, signal) {
         return materialDocumentsCall(this.#transport, variantId, options, signal);
     }
@@ -306,7 +315,7 @@ export class MaterialGraphClient extends CatalogueClient {
      *
      * READ `item.source` BEFORE PHRASING: the rail mixes three tiers of evidence —
      * `cospec` (real orders), `considered` (board activity), `colour` (palette
-     * look-alike). Only `cospec` supports "specified together". `cospecCount` tells
+     * look-alike). Only `cospec` supports "sampled together". `cospecCount` tells
      * you how much of the rail is real order evidence.
      */
     pairings(variantId, options, signal) {
@@ -314,6 +323,10 @@ export class MaterialGraphClient extends CatalogueClient {
             variantId,
         });
     }
+    /** Find bounded, exact-spec substitutes for one opaque variant id. */
+    findSubstitutes(variantId, options = {}, signal) {
+        return this.#post("find_material_substitutes", options, signal, { variantId });
+    }
     /** "What finishes does the manufacturer declare for THIS product?" — {@link declaredFinishes}. */
     associatedFinishes(variantId, options, signal) {
         return assoc.declaredFinishes(this.#transport, variantId, options, signal);
@@ -345,70 +358,30 @@ export class MaterialGraphClient extends CatalogueClient {
             idKind: options?.idKind ?? "variantId",
         }, signal);
     }
-    // ── Colour helpers ───────────────────────────────────────────────────────────
-    /**
-     * THE QUESTION: "what colour WORDS may I use?" — family, mood and undertone
-     * with live counts. Vocabulary, not values: instead use `colours.profiles()`
-     * for a category's palette, {@link MaterialGraphClient.byColour} to search by a
-     * colour, {@link MaterialGraphClient.resolveColour} to turn a NAME into a hex.
-     */
+    /** Vocabulary families and counts; use `colours.profiles()` for a material palette. */
     colourFacets(signal) {
-        return this.#get("get_colour_facets", undefined, signal);
+        return colourFacetsCall(this.#transport, signal);
     }
-    /**
-     * THE QUESTION: "what hex is 'Hague Blue'?" — the step before
-     * {@link MaterialGraphClient.byColour} when you hold a name rather than a hex.
-     * A `null` match means unrecognised, not "no such colour".
-     */
+    /** Resolve a colour name to its canonical hex when recognised. */
     resolveColour(name, signal) {
-        return this.#get("resolve_colour_name", { name }, signal);
+        return resolveColourCall(this.#transport, name, signal);
     }
     /** Ranked colour-name typeahead (GET `/api/v1/search/colours/suggest`). */
     suggestColour(q, options, signal) {
-        return this.#get("suggest_colour_names", { q, limit: options?.limit }, signal);
+        return suggestColourCall(this.#transport, q, options, signal);
     }
-    /**
-     * THE QUESTION: "what is the user starting to type?" It ranks NAMES, not
-     * materials — instead use {@link MaterialGraphClient.search} once they commit,
-     * {@link MaterialGraphClient.suggestColour} for colour names, and
-     * {@link MaterialGraphClient.searchVocabulary} for attribute/value tokens.
-     *
-     * Entity typeahead across products, brands and categories
-     * (GET `/api/v1/search/suggest`). Built for per-keystroke use: one indexed
-     * lookup, no embedding call and no model. Every suggestion carries the
-     * `refId` it resolves to — a product id, a brand slug, or a product-type key
-     * — so selecting one should navigate to that entity rather than re-running
-     * `label` as a search.
-     *
-     * @example
-     * const { suggestions } = await client.suggest("carr", { kind: "product" });
-     */
+    /** Entity typeahead. Navigate using the selected `refId`; use `search()` for materials. */
     suggest(q, options, signal) {
-        return this.#get("search_suggest", suggestQuery(q, options), signal);
+        return suggestCall(this.#transport, q, options, signal);
     }
     // ── Catalog ──────────────────────────────────────────────────────────────────
-    /**
-     * THE QUESTION: "the user said 'fire rating' — which canonical attribute is
-     * that?" Free text in, canonical `attributeId`s out; pair with
-     * {@link MaterialGraphClient.resolveAttributeValue} for the VALUE, then spend
-     * the pair on {@link MaterialGraphClient.bySpec} or `search({ filters })`.
-     * Instead use {@link MaterialGraphClient.specificationFacets} to browse rather
-     * than resolve.
-     */
+    /** Resolve free text to a canonical attribute id. */
     resolveAttribute(q, options, signal) {
-        return this.#get("catalog_resolve_attribute", { q, limit: options?.limit, facetableOnly: options?.facetableOnly }, signal);
+        return resolveAttributeCall(this.#transport, q, options, signal);
     }
-    /**
-     * THE QUESTION: "the user said 'class A' — what canonical term is that, under
-     * THIS attribute?" The value half of the pair
-     * {@link MaterialGraphClient.resolveAttribute} starts. Read
-     * `resolution.recommendedAction`, not just `best`: `ambiguous` means ask.
-     *
-     * @param attributeId Canonical vocabulary, not an opaque id — discover it, do
-     * not invent it.
-     */
+    /** Resolve a value under a canonical attribute id; inspect `recommendedAction` for ambiguity. */
     resolveAttributeValue(attributeId, query, options, signal) {
-        return this.#get("catalog_resolve_value", { q: query, limit: options?.limit }, signal, { attributeId });
+        return resolveAttributeValueCall(this.#transport, attributeId, query, options, signal);
     }
     /** "Is this phrase an attribute or a value?" — see {@link searchVocabularyRequest}. */
     searchVocabulary(query, options, signal) {
@@ -457,6 +430,14 @@ export class MaterialGraphClient extends CatalogueClient {
     taxonomy(signal) {
         return this.#get("get_category_taxonomy", undefined, signal);
     }
+    /**
+     * Exact current primary-type status counts by retained source category path.
+     * `comparisonThreshold` is a reporting cutoff only: it never promotes a
+     * proposal into an accepted category.
+     */
+    productTypeCoverage(options, signal) {
+        return this.#get("get_product_type_status_coverage", options, signal);
+    }
     /**
      * THE QUESTION: "what is this key allowed to do?" Check `scopes` before
      * offering a capability: the write surfaces need `mg:ingest` / `mg:compose`,
@@ -676,6 +657,10 @@ export class MaterialGraphClient extends CatalogueClient {
     runSchedule(runId, options) {
         return getRunSchedule(this.#transport, runId, options);
     }
+    /** Follow a verdict cell's citation handle to its canonical claim source. */
+    citation(citationId, signal) {
+        return this.#get("get_verdict_citation", undefined, signal, { citationId });
+    }
     /**
      * Resume a suspended Run (POST `/api/v1/runs/{runId}/resume`).
      *

package/colours-client.d.ts

@@ -1,3 +1,6 @@
+import type { CategoryColourProfilesResponse, ColourProfilesParams, ColourStatsParams, ColourStatsResponse } from "./colour-aggregate-types.js";
+import type { QueryParams } from "./http-transport.js";
+import type { SdkOperationId } from "./operations.js";
 /**
  * The colour surface, namespaced as `mg.colours` — the aggregate reads
  * (`stats`, `profiles`) plus MULTI-COLOUR search (`palette`, `gradient`).
@@ -32,9 +35,7 @@
  * FROM PRODUCT IMAGERY, not declared by the manufacturer. Report visual
  * likeness, never a stated colour specification.
  */
-import type { CategoryColourProfilesResponse, ColourProfilesParams, ColourStatsParams, ColourStatsResponse } from "./colour-aggregate-types.js";
-import type { QueryParams } from "./http-transport.js";
-import type { SdkOperationId } from "./operations.js";
+import type { PaletteCompleteInput, PaletteCompleteResponse, PaletteDiscoverInput, PaletteDiscoverResponse } from "./palette-completion-types.js";
 import type { SearchGradientInput, SearchGradientResponse, SearchPaletteInput, SearchPaletteResponse } from "./palette-search-types.js";
 /** The client's own request primitives, handed down so this file owns no transport. */
 export interface ColoursTransport {
@@ -44,6 +45,10 @@ export interface ColoursTransport {
 export declare class ColoursClient {
     #private;
     constructor(transport: ColoursTransport);
+    /** Complete exact retained colors against a shared published interior reference. No Cart mutation. */
+    complete(input: PaletteCompleteInput, signal?: AbortSignal): Promise<PaletteCompleteResponse>;
+    /** Browse diverse published interior compositions against a version-pinned eligible catalogue. */
+    discover(input: PaletteDiscoverInput, signal?: AbortSignal): Promise<PaletteDiscoverResponse>;
     /**
      * THE QUESTION: "what colours does this CATEGORY come in?" — the representative
      * palette of 1–8 categories in ONE call (GET `/api/v1/colours/profiles`).

package/colours-client.js

@@ -3,6 +3,14 @@ export class ColoursClient {
     constructor(transport) {
         this.#transport = transport;
     }
+    /** Complete exact retained colors against a shared published interior reference. No Cart mutation. */
+    complete(input, signal) {
+        return this.#transport.post("complete_interior_palette", input, signal);
+    }
+    /** Browse diverse published interior compositions against a version-pinned eligible catalogue. */
+    discover(input, signal) {
+        return this.#transport.get("discover_interior_palettes", { ...input }, signal);
+    }
     /**
      * THE QUESTION: "what colours does this CATEGORY come in?" — the representative
      * palette of 1–8 categories in ONE call (GET `/api/v1/colours/profiles`).

package/composition-types.d.ts

@@ -12,6 +12,7 @@
  * TOLERANT-PARSING CONTRACT: response enums are widened with {@link OpenEnum}
  * so a new server value still type-checks; objects are read structurally.
  */
+import type { VerdictCitation } from "./citation-types.js";
 import type { RunId, SchemeId, SlotId, VariantId } from "./identifiers.js";
 import type { OpenEnum } from "./types.js";
 /**
@@ -158,6 +159,7 @@ export interface CompositionMatch {
     value?: string | null;
     /** Why an `unverified` cell missed the trust bar (MG-627), else null. */
     trustGap?: "below_confidence" | "basis_unmet" | "proposed" | null;
+    citation?: VerdictCitation;
 }
 /** One slot's chosen material plus the reason it was picked. */
 export interface CompositionPick {
@@ -303,6 +305,10 @@ export interface ReviewProgrammeSuspendPayload {
         element?: SlotElement;
         category?: string;
         categorySource?: SlotCategorySource;
+        /** Criteria grounding exhausted its one bounded retry; absent otherwise. */
+        groundingFailure?: {
+            reason: "criteria-resolution-failed";
+        };
         provenance: ProgrammeProvenance;
     }>;
     /**

package/corpus-scope-types.d.ts

@@ -43,7 +43,7 @@ import { type OpenEnum } from "./types.js";
  * that were never in the Material Bank feed; if you mean orderable, use one of
  * the channel-backed scopes above.
  */
-export type CorpusScope = OpenEnum<"all" | "designShopOrderable" | "materialBankEuOrderable" | "materialBankNaAndCatalogue" | "materialBankNaOrderable" | "materialBankOrderable">;
+export type CorpusScope = OpenEnum<"samplizeCatalogue" | "all" | "designShopOrderable" | "materialBankEuOrderable" | "materialBankNaAndCatalogue" | "materialBankNaOrderable" | "materialBankOrderable">;
 /**
  * The corpus a response AND its counts were drawn from. Present only when a
  * narrowing scope applied — absence means the whole graph. Read it alongside

package/errors.d.ts

@@ -89,7 +89,7 @@ interface TransportErrorInput extends MaterialGraphRequestMetadata {
  * member to a problem response means adding it here too, and
  * `problem-extension-parity.test.ts` fails when the two disagree.
  */
-export declare const MATERIALGRAPH_PROBLEM_EXTENSIONS: readonly ["content_length", "did_you_mean", "empty_brands", "limit_bytes", "missing_env", "orderable_attributes", "populated_alternatives", "unknown_attributes", "unknown_brands", "unknown_fields", "unorderable_attribute", "valid_group_keys", "valid_type_keys"];
+export declare const MATERIALGRAPH_PROBLEM_EXTENSIONS: readonly ["ambiguous_brands", "brand_candidates", "content_length", "did_you_mean", "empty_brands", "limit_bytes", "missing_env", "orderable_attributes", "populated_alternatives", "unknown_attributes", "unknown_brands", "unknown_fields", "unorderable_attribute", "valid_group_keys", "valid_type_keys"];
 /** The one error class thrown by all SDK transport and HTTP failures. */
 export declare class MaterialGraphError extends Error {
     readonly kind: MaterialGraphErrorKind;

package/errors.js

@@ -23,6 +23,8 @@ const RETRIABLE_STATUS = new Set([502, 503, 504]);
  * `problem-extension-parity.test.ts` fails when the two disagree.
  */
 export const MATERIALGRAPH_PROBLEM_EXTENSIONS = [
+    "ambiguous_brands",
+    "brand_candidates",
     "content_length",
     "did_you_mean",
     "empty_brands",

package/identify-types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Public wire types for `POST /api/v1/identify`.
+ *
+ * These intentionally mirror the domain-owned Zod contract rather than
+ * importing it: the published SDK must carry no workspace package dependency.
+ */
+export interface IdentifySelectedPageInput {
+    url: string;
+    title?: string;
+    selectedText?: string;
+    productLabels?: string[];
+    brandLabels?: string[];
+    /** Manufacturer code visibly supplied by the selected page. */
+    manufacturerCode?: string;
+    imageUrls?: string[];
+    colourHexes?: string[];
+}
+export interface IdentifySelectedPageSubject {
+    kind: "variant" | "product" | "brand";
+    id: string;
+    name: string;
+    brand?: {
+        id: string;
+        name: string;
+        slug: string;
+    };
+}
+export interface IdentifySelectedPageEvidence {
+    kind: "manufacturer-url" | "brand-homepage" | "visible-identity" | "visual" | "colour";
+    url?: string;
+    detail: string;
+}
+interface IdentifySelectedPageDataBase {
+    receipt: {
+        submittedUrl: string;
+        normalizedUrl: string;
+        normalizationSteps: string[];
+    };
+    evidence: IdentifySelectedPageEvidence[];
+}
+export type IdentifySelectedPageData = (IdentifySelectedPageDataBase & {
+    outcome: "identified";
+    rung: "lookup" | "disambiguate";
+    subject: IdentifySelectedPageSubject & {
+        kind: "variant";
+    };
+}) | (IdentifySelectedPageDataBase & {
+    outcome: "placed";
+    rung: "lookup";
+    subject: IdentifySelectedPageSubject & {
+        kind: "product" | "brand";
+    };
+}) | (IdentifySelectedPageDataBase & {
+    outcome: "ambiguous";
+    rung: "lookup" | "disambiguate" | "match" | "color";
+    candidates: IdentifySelectedPageSubject[];
+    truncated: boolean;
+}) | (IdentifySelectedPageDataBase & {
+    outcome: "unresolved";
+    rung?: "match" | "color";
+});
+/** The canonical callable-operation envelope returned by `identify()`. */
+export interface IdentifySelectedPageResult {
+    data: IdentifySelectedPageData;
+    meta: {
+        operationId: "retrieval.identify";
+        requestId: string;
+    };
+    links: Record<string, never>;
+    warnings: [];
+}
+export {};

package/identify-types.js

@@ -0,0 +1,7 @@
+/**
+ * Public wire types for `POST /api/v1/identify`.
+ *
+ * These intentionally mirror the domain-owned Zod contract rather than
+ * importing it: the published SDK must carry no workspace package dependency.
+ */
+export {};

package/index.d.ts

@@ -7,6 +7,7 @@ export type * from "./exploration-types.js";
 export { TERMINAL_RUN_EVENT_TYPES } from "./run-types.js";
 export type * from "./run-types.js";
 export type * from "./schedule-types.js";
+export type * from "./citation-types.js";
 export { VARY_AXES } from "./composition-types.js";
 export type * from "./composition-types.js";
 export type * from "./slot-pool-types.js";
@@ -18,7 +19,9 @@ export { MATERIALGRAPH_PROBLEM_EXTENSIONS, MaterialGraphError, } from "./errors.
 export type { MaterialGraphErrorInit, MaterialGraphErrorKind, MaterialGraphRequestMetadata, ProblemDetail, RateLimit, SanitizedErrorValue, SanitizedIssue, SimpleErrorBody, } from "./errors.js";
 export type * from "./types.js";
 export type * from "./search-collapse-types.js";
+export type * from "./search-card-types.js";
 export type * from "./match-types.js";
+export type * from "./identify-types.js";
 export type * from "./browse-types.js";
 export type * from "./catalogue-types.js";
 export type * from "./by-colour-types.js";
@@ -36,10 +39,17 @@ 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 "./render-assets-types.js";
 export type * from "./material-block-types.js";
 export type * from "./schema-resource-types.js";
+export type * from "./taxonomy-coverage-types.js";
+export type * from "./schedule-reference-types.js";
+export type * from "./substitute-types.js";
 export type * from "./search-refinement-types.js";
 export type * from "./search-window-types.js";
+export type * from "./attribution-types.js";
 export { CERTIFICATION_PROGRAMME_ATTRIBUTE_ID } from "./spec-types.js";
 export type * from "./spec-types.js";
 export { certificationProgramme, certificationProgrammeCriterion, hasSpec, specCriterion, specRangeCriterion, specTerm, } from "./specifications.js";
+export type { SamplizePublicationSource, SamplizeLrvObservation, SamplizeDemand, SamplizeCollectionMembership, SamplizeCatalogueOptions, SamplizeCataloguePage, SamplizeCatalogueProduct, SamplizeHexObservation, } from "./samplize-catalogue-types.js";
+export type { PaletteCompleteInput, PaletteCompleteResponse, PaletteDiscoverInput, PaletteDiscoverResponse, } from "./palette-completion-types.js";

package/json-value-types.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A JSON value, recursively — exactly what survives a `jsonb` round-trip
+ * unchanged. Used where a payload's SHAPE belongs to its producer but its values
+ * must still be JSON: `Date`, `bigint`, `undefined`, and functions are not.
+ */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};

package/json-value-types.js

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

package/match-stream-types.d.ts

@@ -1,3 +1,4 @@
+import type { ResponseAttribution } from "./attribution-types.js";
 import type { MatchCategoryInference, MatchColourReading } from "./match-types.js";
 /**
  * The Material Match PROGRESS-STREAM contracts — the wire vocabulary of
@@ -179,6 +180,18 @@ export type MatchSenseCheckVerdict = (typeof MATCH_SENSE_CHECK_VERDICTS)[number]
 export declare const MATCH_OUTCOMES: readonly ["matched", "no_surfaces"];
 export type MatchOutcome = (typeof MATCH_OUTCOMES)[number];
 export interface MatchWorkflowResult {
+    /**
+     * Result attribution (MG-1131) — `responseId` (the same value as the run's
+     * `X-Request-Id` header), `basis: "match"`, and `issuedAt`. Every item in
+     * `results` and in each `surfaces[].results` carries a matching `resultId`.
+     *
+     * A surface's hits arrive twice — on its own `surface` frame and again here —
+     * and both times with the SAME `resultId`, so a consumer that stored the
+     * first recognises the second rather than double-counting it.
+     *
+     * ABSENT only from a response produced by a server predating MG-1131.
+     */
+    attribution?: ResponseAttribution;
     imageType: MatchImageType;
     /** How the run ended. Absent means `matched`. */
     outcome?: MatchOutcome;

package/match-types.d.ts

@@ -1,3 +1,5 @@
+import type { ResponseAttribution } from "./attribution-types.js";
+import type { CorpusScope } from "./corpus-scope-types.js";
 /**
  * @module sdk/match-types
  * @description The buffered Material Match request and response, hand-mirrored
@@ -36,6 +38,15 @@ export interface MatchColourReading {
     measurable: boolean;
 }
 export interface MatchResponse {
+    /**
+     * Result attribution (MG-1131). `basis` is always `"match"` here — this route
+     * has no `mode`, so this is the field that lets a Match outcome be grouped
+     * alongside a `search()` one. Store it beside the query and each item's
+     * `resultId` beside the outcome.
+     *
+     * ABSENT only from a response produced by a server predating MG-1131.
+     */
+    attribution?: ResponseAttribution;
     /** THIS answer, capped by `limit`. Not a total. */
     results: SearchResultItem[];
     inferredCategories: MatchCategoryInference[];
@@ -92,6 +103,8 @@ export interface MatchInput {
      */
     includeBelowFloor?: boolean;
     requestedType?: OpenEnum<"swatch" | "installation" | "flatplan">;
+    /** Corpus to retrieve candidates from, applied inside retrieval. */
+    corpusScope?: CorpusScope;
     /** 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. */

package/material-block-types.d.ts

@@ -52,6 +52,10 @@ export interface MaterialBlockProjectionField {
     value: MaterialBlockFieldValue;
     unit?: string;
     status: MaterialBlockFieldStatus;
+    /** Provenance supplied by the graph when a source-backed claim supports this field. */
+    sourceBasis?: string;
+    /** Claim confidence supplied by the graph; absence means no confidence was emitted. */
+    confidence?: number;
 }
 export interface MaterialBlockProjectionItem {
     canonicalBlockId: string;

package/material-resources-client.d.ts

@@ -3,10 +3,13 @@ import { HttpTransport } from "./http-transport.js";
 import type { VariantId } from "./identifiers.js";
 import type { MaterialAssetProjection, MaterialDocumentPage, MaterialDocumentPageOptions } from "./material-asset-types.js";
 import type { MaterialBlockProjection } from "./material-block-types.js";
+import type { MaterialRenderAssets } from "./render-assets-types.js";
 /** Read known and explicitly unobserved canonical material fields. */
 export declare function materialBlocks(transport: HttpTransport, variantId: VariantId, signal?: AbortSignal): Promise<MaterialBlockProjection>;
 /** Read only redistribution-safe images and downloads for a material. */
 export declare function materialAssets(transport: HttpTransport, variantId: VariantId, signal?: AbortSignal): Promise<MaterialAssetProjection>;
+/** Read the accepted render-ready appearance projection, or an explicit unavailable reason. */
+export declare function materialRenderAssets(transport: HttpTransport, variantId: VariantId, signal?: AbortSignal): Promise<MaterialRenderAssets>;
 /**
  * Read the owning Product's URL-deduplicated document page. Variant declarations
  * retain exact attribution; consumers inspect `appliesToRequestedVariant`

package/material-resources-client.js

@@ -9,6 +9,10 @@ export function materialBlocks(transport, variantId, signal) {
 export function materialAssets(transport, variantId, signal) {
     return transport.requestJson(resolveOperation("list_material_assets"), { signal, pathParams: { variantId } });
 }
+/** Read the accepted render-ready appearance projection, or an explicit unavailable reason. */
+export function materialRenderAssets(transport, variantId, signal) {
+    return transport.requestJson(resolveOperation("get_material_render_assets"), { signal, pathParams: { variantId } });
+}
 /**
  * Read the owning Product's URL-deduplicated document page. Variant declarations
  * retain exact attribution; consumers inspect `appliesToRequestedVariant`

package/material-types.d.ts

@@ -57,6 +57,8 @@ export interface MaterialSuccessor {
  * successor record — read the detail projection for that.
  */
 export interface MaterialTile {
+    /** Accepted sampleability fact. Absent means unknown, never false. */
+    sampleable?: boolean;
     /** Opaque — round-trip verbatim into every other material read. */
     variantId: VariantId;
     brand: string;
@@ -87,6 +89,27 @@ export interface MaterialTile {
 export interface MaterialFacet {
     attributeId: string;
     term: string;
+    /**
+     * Whether this value identifies the variant or specifies its performance /
+     * composition. Present on current responses; optional for captured older
+     * payloads. Only `specification` facets are valid inputs to `bySpec`.
+     */
+    role?: "identity" | "specification";
+}
+/** A retained product-type proposal. It is review evidence, never a category. */
+export interface ProposedProductType {
+    id: string;
+    displayName: string;
+    confidence: number | null;
+    /** Canonical source URL when the proposal retained one; null when it did not. */
+    sourceUrl: string | null;
+    isPrimary: boolean;
+    scope: "variant" | "product";
+}
+/** Accepted display categories remain separate from this review-state receipt. */
+export interface ProductTypeReceipt {
+    state: "accepted" | "proposed" | "unknown";
+    proposedProductTypes: ProposedProductType[];
 }
 /**
  * One dimensional configuration of a material. Numeric fields are millimetres
@@ -132,6 +155,7 @@ export interface MaterialDetail extends MaterialTile {
     sourceStatus?: "provisional";
     installationImageUrl: string | null;
     displayCategory: string | null;
+    productTypeReceipt: ProductTypeReceipt;
     categoryPath: string[];
     /** Durable state of image-colour extraction and its variant projection. */
     colourEvidence: {

package/operations.d.ts

@@ -1,5 +1,5 @@
 export declare const MATERIALGRAPH_API_VERSION = "0.7.0";
-declare const OPERATION_DEFINITIONS: readonly [readonly ["catalogs", "GET", "/api/v1/catalogs", "list_catalog_documents"], readonly ["catalogPages", "GET", "/api/v1/catalogs/{catalogId}/pages", "list_catalog_pages"], readonly ["catalogPageRepresentation", "GET", "/api/v1/catalog-pages/{pageId}/representation", "get_catalog_page_representation"], readonly ["catalogReferences", "GET", "/api/v1/catalogs/{catalogId}/references", "list_catalog_product_references"], readonly ["search", "POST", "/api/v1/search", "search_materials_post"], readonly ["planQuery", "POST", "/api/v1/search/plan", "plan_material_query"], 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 ["catalogueReferences", "POST", "/api/v1/catalogues/references", "get_catalogue_references_batch"], readonly ["catalogueCollections", "GET", "/api/v1/catalogues/collections", "list_catalogue_channel_collections"], readonly ["catalogueDocumentAccess", "GET", "/api/v1/catalogues/documents/{documentId}", "get_catalogue_document_access"], 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 ["materialDocuments", "GET", "/api/v1/materials/{variantId}/documents", "list_material_documents"], readonly ["exploration.operators", "GET", "/api/v1/materials/{variantId}/operators", "list_material_operators"], readonly ["exploration.candidates", "POST", "/api/v1/materials/{variantId}/candidates", "read_material_candidates"], 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 ["applicability", "GET", "/api/v1/applicability", "get_applicability"], 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 ["sourceMaterialComments", "GET", "/api/v1/source-material/{batchId}/sources/{sourceId}/comments", "list_source_material_comments"], readonly ["sourceMaterialComments", "POST", "/api/v1/source-material/{batchId}/sources/{sourceId}/comments", "post_source_material_comment"], 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 ["slotPools", "POST", "/api/v1/schemes/pools", "slot_pools"], 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 ["colours.complete", "POST", "/api/v1/colours/palettes/complete", "complete_interior_palette"], readonly ["colours.discover", "GET", "/api/v1/colours/palettes", "discover_interior_palettes"], readonly ["samplizeColorVecCache", "GET", "/api/v1/catalogues/samplize/colorvec", "samplize_colorvec_cache"], readonly ["samplizeCatalogueSearch", "POST", "/api/v1/catalogues/samplize/search", "samplize_catalogue_search"], readonly ["scheduleReferences.list", "GET", "/api/v1/schedules/{scheduleId}/references", "list_schedule_reference_feedback"], readonly ["scheduleReferences.put", "PUT", "/api/v1/schedules/{scheduleId}/references/{referenceId}", "put_schedule_reference_feedback"], readonly ["catalogs", "GET", "/api/v1/catalogs", "list_catalog_documents"], readonly ["catalogPages", "GET", "/api/v1/catalogs/{catalogId}/pages", "list_catalog_pages"], readonly ["catalogPageRepresentation", "GET", "/api/v1/catalog-pages/{pageId}/representation", "get_catalog_page_representation"], readonly ["catalogReferences", "GET", "/api/v1/catalogs/{catalogId}/references", "list_catalog_product_references"], readonly ["search", "POST", "/api/v1/search", "search_materials_post"], readonly ["identify", "POST", "/api/v1/identify", "retrieval.identify"], readonly ["planQuery", "POST", "/api/v1/search/plan", "plan_material_query"], readonly ["samplizeCatalogue", "GET", "/api/v1/catalogues/samplize/products", "samplize_catalogue_products"], 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 ["catalogueReferences", "POST", "/api/v1/catalogues/references", "get_catalogue_references_batch"], readonly ["catalogueCollections", "GET", "/api/v1/catalogues/collections", "list_catalogue_channel_collections"], readonly ["catalogueDocumentAccess", "GET", "/api/v1/catalogues/documents/{documentId}", "get_catalogue_document_access"], 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 ["materialRenderAssets", "GET", "/api/v1/materials/{variantId}/render-assets", "get_material_render_assets"], readonly ["materialDocuments", "GET", "/api/v1/materials/{variantId}/documents", "list_material_documents"], readonly ["exploration.operators", "GET", "/api/v1/materials/{variantId}/operators", "list_material_operators"], readonly ["exploration.candidates", "POST", "/api/v1/materials/{variantId}/candidates", "read_material_candidates"], 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 ["findSubstitutes", "POST", "/api/v1/materials/{variantId}/substitutes", "find_material_substitutes"], readonly ["associatedFinishes", "GET", "/api/v1/associated/finishes", "list_associated_finishes"], readonly ["associatedProducts", "GET", "/api/v1/associated/products", "list_associated_products"], readonly ["applicability", "GET", "/api/v1/applicability", "get_applicability"], 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 ["productTypeCoverage", "GET", "/api/v1/taxonomy/coverage", "get_product_type_status_coverage"], 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 ["sourceMaterialComments.list", "GET", "/api/v1/source-material/{batchId}/sources/{sourceId}/comments", "list_source_material_comments"], readonly ["sourceMaterialComments.post", "POST", "/api/v1/source-material/{batchId}/sources/{sourceId}/comments", "post_source_material_comment"], 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 ["citation", "GET", "/api/v1/citations/{citationId}", "get_verdict_citation"], 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 ["slotPools", "POST", "/api/v1/schemes/pools", "slot_pools"], 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];