@instruments/materialgraph 0.17.0 → 0.19.0

package/client.js

@@ -5,22 +5,24 @@ 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";
 import { createExplorationNamespace, } from "./client-exploration.js";
 import { createSourceMaterialCommentsNamespace, } from "./client-source-material-comments.js";
-import { declaredFinishes, declaredProducts } from "./associations-client.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, 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.
  *
@@ -57,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
@@ -120,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),
@@ -142,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,
         });
     }
     /**
@@ -244,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);
@@ -275,27 +282,17 @@ export class MaterialGraphClient extends CatalogueClient {
     siblings(variantId, signal) {
         return this.#get("get_material_siblings", undefined, signal, { variantId });
     }
-    /**
-     * THE QUESTION: "what do we actually KNOW about this material, and what have we
-     * simply not checked?" The only read that distinguishes a determined absence
-     * from an unasked question — every field carries a `status`, so this is the one
-     * surface entitled to back a negative ("no fire rating").
-     * {@link MaterialGraphClient.material} cannot: there an absence is merely unknown.
-     */
     materialBlocks(variantId, signal) {
-        return this.#get("list_material_blocks", undefined, signal, {
-            variantId,
-        });
+        return materialBlocksCall(this.#transport, variantId, signal);
     }
-    /**
-     * THE QUESTION: "what images and documents may I SHOW for this material?" — the
-     * redistribution-safe set (GET `/api/v1/materials/{variantId}/assets`), not
-     * every file on record.
-     */
     materialAssets(variantId, signal) {
-        return this.#get("list_material_assets", undefined, signal, {
-            variantId,
-        });
+        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);
     }
     /**
      * THE QUESTION: "what does the schema DEFINE?" — the governed static registry.
@@ -318,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) {
@@ -326,13 +323,20 @@ 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 declaredFinishes(this.#transport, variantId, options, signal);
+        return assoc.declaredFinishes(this.#transport, variantId, options, signal);
     }
     /** "What products does the manufacturer declare THIS finish for?" — {@link declaredProducts}. */
     associatedProducts(variantId, options, signal) {
-        return declaredProducts(this.#transport, variantId, options, signal);
+        return assoc.declaredProducts(this.#transport, variantId, options, signal);
+    }
+    applicability(options, signal) {
+        return assoc.applicability(this.#transport, options, signal);
     }
     materials(ids, options, signal) {
         if (ids.length > MAX_BATCH_IDS) {
@@ -354,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) {
@@ -466,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`,
@@ -685,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/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

@@ -29,19 +29,21 @@ import { type OpenEnum } from "./types.js";
  * `"all"` (and absence) is the WHOLE GRAPH — every material MaterialGraph
  * knows, orderable or not. Absence is never a narrower default.
  *
- * Three members gate on CHANNEL membership, which is what "can someone buy
- * this" means: `"materialBankNaOrderable"` (Material Bank North America),
+ * Four members gate on governed CHANNEL membership:
+ * `"materialBankNaOrderable"` (Material Bank North America),
  * `"materialBankEuOrderable"` (Material Bank Europe) and
  * `"designShopOrderable"` (DesignShop, with the products DesignShop hides from
  * browse excluded).
+ * `"materialBankNaAndCatalogue"` is a single producer-side union of Material
+ * Bank North America and governed Catalogue channel membership.
  *
  * `"materialBankOrderable"` is NOT one of them, despite the name. It selects
  * materials carrying a Material Bank identity — PROVENANCE, not a storefront —
  * and admits about 98% of the graph. Use it to exclude the crawl-sourced brands
  * that were never in the Material Bank feed; if you mean orderable, use one of
- * the three above.
+ * the channel-backed scopes above.
  */
-export type CorpusScope = OpenEnum<"all" | "designShopOrderable" | "materialBankEuOrderable" | "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/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";
@@ -36,10 +37,15 @@ 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 { 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";

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-types.d.ts

@@ -1,3 +1,4 @@
+import type { CorpusScope } from "./corpus-scope-types.js";
 /**
  * @module sdk/match-types
  * @description The buffered Material Match request and response, hand-mirrored
@@ -92,6 +93,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-asset-types.d.ts

@@ -39,10 +39,79 @@ export interface MaterialAssetProjectionDownload {
     fileExtension: string | null;
     filename: string | null;
 }
+export type MaterialDocumentStatus = OpenEnum<"downloaded" | "linked_not_downloaded" | "unavailable_source" | "dead_link" | "failed_ingest">;
+export type MaterialDocumentCoverageState = OpenEnum<"available" | "none_declared" | "not_ingested" | "unavailable_source" | "dead_link" | "failed_ingest">;
+export interface MaterialDocumentScope {
+    kind: "product" | "variant";
+    id: string;
+}
+export interface MaterialDocumentSource {
+    /** Opaque, public identifier for one source collection; never a PIM/DAM path. */
+    id: string;
+    authority: string;
+    revision: string;
+}
+export interface MaterialDocumentProjectionItem {
+    id: string;
+    scope: MaterialDocumentScope & {
+        inherited: boolean;
+    };
+    declaredScopes: MaterialDocumentScope[];
+    variantAttribution: string[];
+    /** True only for a Product declaration or this exact requested Variant. */
+    appliesToRequestedVariant: boolean;
+    /** Every exact source-grain declaration collapsed into this URL identity. */
+    declarations: Array<{
+        scope: MaterialDocumentScope;
+        source: MaterialDocumentSource;
+        status: MaterialDocumentStatus;
+        readable: boolean;
+    }>;
+    documentType: string | null;
+    originalName: string;
+    status: MaterialDocumentStatus;
+    /** Null for unavailable, dead, or failed source documents. */
+    url: string | null;
+    contentType: string | null;
+    fileExtension: string | null;
+    source: MaterialDocumentSource;
+}
+export interface MaterialDocumentCoverageSource {
+    scope: MaterialDocumentScope;
+    state: MaterialDocumentCoverageState;
+    exact: boolean;
+    declaredCount: number | null;
+    readableCount: number;
+    source: MaterialDocumentSource;
+}
+export interface MaterialDocumentCoverage {
+    productUnion: MaterialDocumentCoverageSummary;
+    requestedVariant: MaterialDocumentCoverageSummary;
+    sources: MaterialDocumentCoverageSource[];
+}
+export interface MaterialDocumentCoverageSummary {
+    state: MaterialDocumentCoverageState;
+    exact: boolean;
+    declaredCount: number | null;
+    readableCount: number;
+}
+export interface MaterialDocumentPageOptions {
+    cursor?: string;
+    limit?: number;
+}
+export interface MaterialDocumentPage {
+    variantId: VariantId;
+    documents: MaterialDocumentProjectionItem[];
+    coverage: MaterialDocumentCoverage;
+    totalDocuments: number;
+    nextCursor: string | null;
+}
 /** Tallies over what this projection returned — never a claim about the brand's own library. */
 export interface MaterialAssetProjectionSummary {
     imageCount: number;
     downloadCount: number;
+    documentCount: number;
+    readableDocumentCount: number;
     downloadedImageCount: number;
 }
 export interface MaterialAssetProjection {
@@ -50,5 +119,7 @@ export interface MaterialAssetProjection {
     variantId: VariantId;
     images: MaterialAssetProjectionImage[];
     downloads: MaterialAssetProjectionDownload[];
+    documents: MaterialDocumentProjectionItem[];
+    documentCoverage: MaterialDocumentCoverage;
     summary: MaterialAssetProjectionSummary;
 }

package/material-resources-client.d.ts

@@ -0,0 +1,18 @@
+/** Material blocks, safe assets, and technical documents over one shared transport. */
+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`
+ * before presenting a sibling Variant declaration as applicable.
+ */
+export declare function materialDocuments(transport: HttpTransport, variantId: VariantId, options?: MaterialDocumentPageOptions, signal?: AbortSignal): Promise<MaterialDocumentPage>;

package/material-resources-client.js

@@ -0,0 +1,29 @@
+/** Material blocks, safe assets, and technical documents over one shared transport. */
+import { HttpTransport } from "./http-transport.js";
+import { resolveOperation } from "./operations.js";
+/** Read known and explicitly unobserved canonical material fields. */
+export function materialBlocks(transport, variantId, signal) {
+    return transport.requestJson(resolveOperation("list_material_blocks"), { signal, pathParams: { variantId } });
+}
+/** Read only redistribution-safe images and downloads for a material. */
+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`
+ * before presenting a sibling Variant declaration as applicable.
+ */
+export function materialDocuments(transport, variantId, options, signal) {
+    return transport.requestJson(resolveOperation("list_material_documents"), {
+        query: options
+            ? { cursor: options.cursor, limit: options.limit }
+            : undefined,
+        signal,
+        pathParams: { variantId },
+    });
+}

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,7 +155,43 @@ 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: {
+        status: "no_eligible_asset";
+    } | {
+        status: "extractor_not_run";
+        origin: {
+            assetId: string;
+            method: "colorscope_primary_image";
+        };
+    } | {
+        status: "available";
+        basis: "palette" | "palette_and_dominant_oklab" | "dominant_oklab";
+        extractedAt: string;
+        extractionVersion: string | null;
+        origin: {
+            assetId: string;
+            method: "colorscope_primary_image";
+        };
+    } | {
+        status: "projection_missing";
+        extractedAt: string;
+        extractionVersion: string | null;
+        origin: {
+            assetId: string;
+            method: "colorscope_primary_image";
+        };
+    } | {
+        status: "genuinely_colourless";
+        extractedAt: string;
+        extractionVersion: string | null;
+        origin: {
+            assetId: string;
+            method: "colorscope_primary_image";
+        };
+    };
     /** Extracted from imagery — visual likeness, never a declared colour spec. */
     palette: PaletteSwatch[];
     /** What is ON RECORD. An absent attribute is unrecorded, never known-false. */

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 ["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 ["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 ["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 ["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 ["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 ["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", "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 ["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];