@instruments/materialgraph 0.18.0 → 0.20.0

package/association-types.d.ts

@@ -11,6 +11,7 @@
  * Present them as separate sections, and never describe a pairing as available.
  */
 import type { Cursor, VariantId } from "./identifiers.js";
+import type { ProductTypeReceipt } from "./material-types.js";
 /**
  * Why an association is believed.
  *
@@ -42,8 +43,16 @@ export interface DeclaredAssociation {
     brand: string;
     product: string;
     variantName: string | null;
+    /** The role played by this endpoint of the declared edge. */
+    role: "finish" | "product";
+    /** The directed relationship asserted by the manufacturer. */
+    relation: "applicable_finish";
+    /** Accepted sampleability when known; absent means unknown. */
+    sampleable?: boolean;
     /** Canonical thumbnail; null when the variant has no eligible image. */
     imageUrl: string | null;
+    /** Review receipt; proposed types are never accepted categories. */
+    productTypeReceipt: ProductTypeReceipt;
     declared: DeclaredProvenance;
 }
 /**
@@ -77,12 +86,13 @@ export interface AssociatedOptions {
      */
     limit?: number;
     /**
-     * Orderability scope. `material_bank` returns only associations pointing at a
-     * variant carrying a Material Bank SKU — the ones a caller can actually
-     * order. Today every visible variant carries one, so this currently removes
-     * nothing; it tracks orderability rather than a snapshot of it.
+     * Source identity scope. `material_bank` returns associations pointing at a
+     * variant carrying a Material Bank SKU. A SKU alone does not establish current
+     * sampleability; use `sampleableOnly` for an accepted availability fact.
      */
     corpus?: "all" | "material_bank";
+    /** Return only associations whose effective sampleability is true. */
+    sampleableOnly?: boolean;
     /**
      * The previous response's `nextCursor`, passed back verbatim. A cursor is
      * bound to its subject, direction and corpus — replaying it against a
@@ -134,6 +144,21 @@ export interface ApplicabilitySourceEntry {
     factRevisions: string[];
     /** Active facts from this source only. */
     facts: ApplicabilityFact[];
+    /** Source endpoints that could not be resolved during reconciliation. */
+    unresolved: UnresolvedApplicabilityEndpoint[];
+}
+export interface UnresolvedApplicabilityEndpoint {
+    subjectLocator: string;
+    subjectKind: "product" | "variant" | "unknown";
+    finishLocator: string;
+    finishKind: "variant" | "unknown";
+    reason: "subject_unresolved" | "finish_unresolved" | "both_unresolved" | "unsupported_subject_kind";
+    declaringBrandId: string | null;
+    source: {
+        authority: string;
+        locator: string;
+        revision: string;
+    };
 }
 /** Source-grained response; sources are never merged or given hidden precedence. */
 export interface ApplicabilityResponse {

package/attribution-types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Result attribution (MG-1131) — joining an outcome back to the ranking that
+ * produced it.
+ *
+ * When someone orders a sample days after a search, a list of SKUs cannot say
+ * which response returned it or on what basis it was ranked. Store
+ * {@link SearchResultItem.resultId} next to the order row and
+ * {@link ResponseAttribution} beside the search, and both questions become a
+ * join in your own warehouse.
+ *
+ * MaterialGraph keeps no ledger of these ids. What you store IS the record.
+ */
+/**
+ * The ranking basis, in one vocabulary across both ranked routes.
+ *
+ * The first five values are `search()`'s `mode` verbatim, and there
+ * `attribution.basis === mode` always. `"match"` is what `match()` reports;
+ * that route has no `mode`, so this is the only field its outcomes can be
+ * grouped by.
+ */
+export type AttributionBasis = "image" | "colour" | "text" | "lexical" | "entity-browse" | "match";
+/**
+ * Envelope-level attribution receipt, on every successful ranked response.
+ *
+ * Store this beside the search and each result's `resultId` beside the outcome
+ * (an order, a save, a click), and "which sample was ordered off which ranking,
+ * on what basis" becomes a join in your own warehouse.
+ *
+ * A `resultId` is `<responseId>:<rank>`, rank being 1-based within the response
+ * that returned it — unique across pages, because each page is its own
+ * response. On the Match stream lane it also carries the surface id, so a hit
+ * sent twice (on its `surface` frame and again inside `complete`) keeps one key.
+ *
+ * Both ids are OPAQUE: store them verbatim, never parse them. Group on
+ * `responseId` and `basis`.
+ *
+ * Both fields are optional in the SDK types for one reason only: a server
+ * predating MG-1131 does not send them. Every current response does.
+ */
+export interface ResponseAttribution {
+    /**
+     * This response's stable id — the same value as the `X-Request-Id` header.
+     * Opaque: store it verbatim, never parse it. Group your stored outcomes by
+     * this field to recover the response that produced them.
+     */
+    responseId: string;
+    /** How this ranking was produced. The field to group outcomes by. */
+    basis: AttributionBasis;
+    /** ISO-8601 timestamp of when the response was assembled. */
+    issuedAt: string;
+}

package/attribution-types.js

@@ -0,0 +1,13 @@
+/**
+ * Result attribution (MG-1131) — joining an outcome back to the ranking that
+ * produced it.
+ *
+ * When someone orders a sample days after a search, a list of SKUs cannot say
+ * which response returned it or on what basis it was ranked. Store
+ * {@link SearchResultItem.resultId} next to the order row and
+ * {@link ResponseAttribution} beside the search, and both questions become a
+ * join in your own warehouse.
+ *
+ * MaterialGraph keeps no ledger of these ids. What you store IS the record.
+ */
+export {};

package/browse-types.d.ts

@@ -26,6 +26,8 @@ export interface BrowseResultItem {
     productId: ProductId | null;
     color: string | null;
     variantName: string | null;
+    /** MaterialGraph record creation time, not a manufacturer release date. */
+    recordCreatedAt: string | null;
     imageUrl: string | null;
     scalars: {
         l: number | null;
@@ -165,11 +167,20 @@ export interface BrowseParams {
      */
     types?: string;
     /**
-     * Comma-separated brand slugs (`farrow-ball`) or display names
-     * (`Farrow & Ball`), case-insensitive. One brand plus a colour `sort` is that
-     * brand's fan deck. An unknown brand is a 400 naming it, never an empty page.
+     * Comma-separated canonical brand ids, exact slugs (`farrow-ball`), or exact
+     * display names (`Farrow & Ball`). Canonical ids and slugs are case-sensitive
+     * and opaque; display names are case-insensitive. One brand plus a colour `sort` is that brand's
+     * fan deck. An unknown brand is a typed 400 naming it, and an exact display
+     * name shared by multiple brands is a typed 400 with the candidates; neither
+     * becomes an empty page.
      */
     brands?: string;
+    /**
+     * Positive manufacturer declarations. accepts_finishes includes variants of
+     * product-level declarations; it does not assert variant-specific applicability.
+     * Absence means no role filter.
+     */
+    role?: "finish" | "accepts_finishes";
     /**
      * Typed attribute filters, in the SAME grammar `search` takes — a term, a
      * term SET (OR within the entry), a presence check or a numeric range, each

package/by-colour-types.d.ts

@@ -99,6 +99,15 @@ export interface ColourFamilyGate {
      * once the page is cut to `limit`; this is the gate's own cost.
      */
     dropped: number;
+    /**
+     * Rows dropped a SECOND time, after the page was hydrated with the brand's
+     * declared `colour_hex`. A paint's chip photograph and its published hex are
+     * different colours and can fall in different families, so the page is
+     * re-gated on the hex it reports — every `hex` you receive belongs to the
+     * family you asked for. Absent means hydration moved nothing across a
+     * boundary.
+     */
+    droppedOnPublishedHex?: number;
 }
 /** Receipt for the hard category gate and its treatment of unknown typing. */
 export interface ColourCategoryGate {
@@ -169,12 +178,17 @@ export interface ByColourResponse {
         colours: string[];
         categories?: string[];
         /**
-         * Echoed brand filter as resolved SLUGS — what the names you passed
-         * resolved to. Present only when a brand scope applied.
+         * Echoed brand filter as resolved SLUGS — what the canonical ids, slugs,
+         * or exact names you passed resolved to. Present only when a brand scope
+         * applied.
          */
         brands?: string[];
         /** Echoed `family` filter, normalised. Present only when one was applied. */
         family?: string;
+        /** Applied single-colour containment order. */
+        order?: "representative" | "nearest";
+        /** Applied maximum OKLab distance to each reported match hex. */
+        maxColourDistance?: number;
         oklab?: OklabTriple;
     };
     /** `matches.length` — THIS PAGE. Not a corpus total; this surface states none. */
@@ -186,6 +200,12 @@ export interface ByColourResponse {
      * what says so in counts rather than adjectives.
      */
     familyGate?: ColourFamilyGate;
+    /** Applied `maxColourDistance` threshold and its page-bounded drop count. */
+    proximityGate?: {
+        maxColourDistance: number;
+        considered: number;
+        dropped: number;
+    };
     /**
      * Present only when `category` was asked for. It states that variants without
      * an accepted primary product type were excluded by the hard gate; absence
@@ -230,8 +250,10 @@ export interface ByColourParams {
     /** HARD category filter — display names or taxonomy ids (repeatable). */
     category?: string | string[];
     /**
-     * HARD brand filter (repeatable) — a brand SLUG (`sherwin-williams`) or its
-     * display name (`Sherwin-Williams`), case-insensitive.
+     * HARD brand filter (repeatable) — a canonical brand id, exact brand SLUG
+     * (`sherwin-williams`), or exact display name (`Sherwin-Williams`). Canonical
+     * ids and slugs are case-sensitive and opaque; display names are
+     * case-insensitive.
      *
      * This is how the CROSS-BRAND question is asked: pass one brand's colour as
      * `hex` and scope to another to get that brand's nearest colours to it. It is
@@ -239,8 +261,9 @@ export interface ByColourParams {
      * filtering a returned page instead comes back short, because a
      * nearest-neighbour scan does not know to look further.
      *
-     * An unknown brand is a 400 naming it, never an empty page. Omitting it (or
-     * passing an empty list) searches every brand.
+     * An unknown brand is a typed 400 naming it, and an exact display name shared
+     * by multiple brands is a typed 400 with the candidates; neither becomes an
+     * empty page. Omitting it (or passing an empty list) searches every brand.
      */
     brand?: string | string[];
     /**
@@ -260,6 +283,10 @@ export interface ByColourParams {
      * drop.
      */
     family?: string;
+    /** Single-colour order; omitted keeps representative browsing order. */
+    order?: "representative" | "nearest";
+    /** Maximum OKLab distance to each match's reported hex. Single-colour only. */
+    maxColourDistance?: number;
     /** Narrow retrieval inside the server query; absent means the whole graph. */
     corpusScope?: CorpusScope;
     limit?: number;

package/by-spec-types.d.ts

@@ -1,4 +1,5 @@
 import type { ValueResolution } from "./catalog-discovery-types.js";
+import type { VerdictCitation } from "./citation-types.js";
 import type { VariantId } from "./identifiers.js";
 /**
  * One criterion a match satisfied, with the trust behind it.
@@ -71,6 +72,7 @@ export interface BySpecVerdictCell {
      *  - `proposed` — the value is awaiting acceptance and is not yet on record.
      */
     trustGap: "below_confidence" | "basis_unmet" | "proposed" | null;
+    citation?: VerdictCitation;
 }
 /**
  * A match's full report card: every cell, the rolled-up grade, weakest confidence.
@@ -131,6 +133,8 @@ export interface BySpecUnresolvedCriterion {
     attributeId: string;
     /** The parsed value — never overwritten by the attribute id when that id is unknown. */
     value: string;
+    /** Why pre-flight declined it; absent on responses captured before classification. */
+    reason?: "unknown_attribute_or_term" | "not_a_specification";
     /** Ranked candidates for whichever half failed. See {@link ValueResolution}. */
     resolution: ValueResolution;
 }

package/catalogue-client.d.ts

@@ -1,10 +1,64 @@
 import type { CatalogDocumentList, CatalogPageListResult, CatalogProductReferenceReadResult, CatalogueChannelCollectionsResponse, CatalogueCollectionsOptions, CatalogueDocumentAccessResult, CataloguePageRepresentationReadResult, CatalogueReferenceBatchResponse } from "./catalogue-types.js";
 import type { HttpTransport } from "./http-transport.js";
 import type { VariantId } from "./identifiers.js";
+import type { IdentifySelectedPageInput, IdentifySelectedPageResult } from "./identify-types.js";
+import type { SamplizeCatalogueOptions, SamplizeCataloguePage } from "./samplize-catalogue-types.js";
+import type { SamplizeColorVecCache } from "./samplize-colorvec.js";
 /** Catalogue publication operations inherited by the public SDK client. */
 export declare class CatalogueClient {
     #private;
     protected constructor(transport: HttpTransport);
+    /** Identify the canonical graph subject for one explicitly selected page. */
+    identify(input: IdentifySelectedPageInput, signal?: AbortSignal): Promise<IdentifySelectedPageResult>;
+    /** Complete producer-owned vectors and classifications for portable colour matching. */
+    samplizeColorVecCache(sourceVersion: string, signal?: AbortSignal): Promise<SamplizeColorVecCache>;
+    /** MG-owned full-catalogue facets and directional colour refinement before page limiting. */
+    samplizeCatalogueSearch(input: {
+        palette?: Array<{
+            hex: string;
+            proportion: number;
+        }>;
+        query?: string;
+        reference?: string;
+        direction?: "similar" | "lighter" | "darker" | "muted";
+        lightnessMin?: number;
+        lightnessMax?: number;
+        temperatureMin?: number;
+        temperatureMax?: number;
+        family?: string[];
+        lightness?: string[];
+        intensity?: string[];
+        brand?: string[];
+        sourceVersion: string;
+        limit?: number;
+    }, signal?: AbortSignal): Promise<{
+        target?: {
+            ref: string;
+            hex: string;
+            name?: string;
+            source: string;
+            confidence?: number;
+        };
+        embeddingVersion?: string;
+        rankingVersion?: string;
+        dictionaryVersion?: string;
+        eligibleCount?: number;
+        groups?: Array<{
+            hex: string;
+            proportion: number;
+            quota: number;
+            ids: string[];
+            shortfall: number;
+        }>;
+        ids: string[];
+        limited: boolean;
+        sourceVersion: string;
+        counts: Record<string, Record<string, number>>;
+        countBasis: string;
+        basis: string;
+    }>;
+    /** Complete version-pinned Samplize paint corpus; stock never limits eligibility. */
+    samplizeCatalogue(options?: SamplizeCatalogueOptions, signal?: AbortSignal): Promise<SamplizeCataloguePage>;
     /**
      * Read exact, verified brand-publication page relationships for variants.
      * Missing evidence stays explicit; this operation never guesses a page from

package/catalogue-client.js

@@ -5,6 +5,22 @@ export class CatalogueClient {
     constructor(transport) {
         this.#transport = transport;
     }
+    /** Identify the canonical graph subject for one explicitly selected page. */
+    identify(input, signal) {
+        return this.#transport.requestJson(resolveOperation("retrieval.identify"), { body: input, signal });
+    }
+    /** Complete producer-owned vectors and classifications for portable colour matching. */
+    samplizeColorVecCache(sourceVersion, signal) {
+        return this.#transport.requestJson(resolveOperation("samplize_colorvec_cache"), { query: { sourceVersion }, signal });
+    }
+    /** MG-owned full-catalogue facets and directional colour refinement before page limiting. */
+    samplizeCatalogueSearch(input, signal) {
+        return this.#transport.requestJson(resolveOperation("samplize_catalogue_search"), { body: input, signal });
+    }
+    /** Complete version-pinned Samplize paint corpus; stock never limits eligibility. */
+    samplizeCatalogue(options = {}, signal) {
+        return this.#transport.requestJson(resolveOperation("samplize_catalogue_products"), { query: { ...options }, signal });
+    }
     /**
      * Read exact, verified brand-publication page relationships for variants.
      * Missing evidence stays explicit; this operation never guesses a page from

package/catalogue-types.d.ts

@@ -2,6 +2,8 @@
 export interface CatalogueReference {
     anchor: {
         coordinateSpace: "normalized_0_1000";
+        /** Page carrying the printed code; defaults to page.documentPage. Do not draw it on another page. */
+        documentPage?: number;
         height: number;
         kind: "printed_code";
         width: number;
@@ -53,7 +55,7 @@ export interface CatalogueReference {
         brandItemCode: string;
     };
     status: "verified";
-    isPrimary: true;
+    isPrimary: boolean;
 }
 export type CatalogueReferenceResult = {
     variantId: string;

package/citation-types.d.ts

@@ -0,0 +1,34 @@
+/** Small handle carried by a verdict cell. Resolve it only when evidence is opened. */
+export interface VerdictCitation {
+    citationId: string;
+    sourceType: string;
+    count: number;
+}
+export interface ResolvedVerdictCitation {
+    citationId: string;
+    sourceType: string;
+    source: {
+        kind: "source_record" | "source_material" | "source_fact" | "url" | "asset" | "download" | "manual_note" | "agent_output";
+        /** Canonical source/fact/asset/download id, a public source URL, or the claim-source handle when no public reference is available. */
+        ref: string;
+        title?: string;
+        url?: string;
+        /** Same-origin public asset proxy path when retained bytes are available. */
+        publicPath?: string;
+        sourceId?: string;
+        sourceFactId?: string;
+        sourceAssetId?: string;
+        sourceDownloadId?: string;
+        locator?: {
+            page?: number;
+            selector?: string;
+            xPath?: string;
+            imageBox?: {
+                x: number;
+                y: number;
+                width: number;
+                height: number;
+            };
+        };
+    };
+}

package/citation-types.js

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

package/client-browse.d.ts

@@ -52,6 +52,7 @@ export declare function browseQuery(params: BrowseParams): {
     count: BrowseParams["count"];
     types: BrowseParams["types"];
     brands: BrowseParams["brands"];
+    role: BrowseParams["role"];
     filters: string[] | undefined;
     facetCounts: string | undefined;
     corpusScope: BrowseParams["corpusScope"];

package/client-browse.js

@@ -28,6 +28,7 @@ export function browseQuery(params) {
         count: params.count,
         types: params.types,
         brands: params.brands,
+        role: params.role,
         filters: params.filters?.map((entry) => JSON.stringify(entry)),
         facetCounts: params.facetCounts?.join(","),
         corpusScope: params.corpusScope,

package/client-vocabulary.d.ts

@@ -0,0 +1,10 @@
+import { HttpTransport } from "./http-transport.js";
+import type { ColourFacetsResponse, ResolveAttributeOptions, ResolveAttributeResponse, ResolveAttributeValueOptions, ResolveAttributeValueResponse, ResolveColourResponse, SuggestColourResponse, SuggestOptions, SuggestResponse } from "./types.js";
+export declare function colourFacets(transport: HttpTransport, signal?: AbortSignal): Promise<ColourFacetsResponse>;
+export declare function resolveColour(transport: HttpTransport, name: string, signal?: AbortSignal): Promise<ResolveColourResponse>;
+export declare function suggestColour(transport: HttpTransport, q: string, options?: {
+    limit?: number;
+}, signal?: AbortSignal): Promise<SuggestColourResponse>;
+export declare function suggest(transport: HttpTransport, q: string, options?: SuggestOptions, signal?: AbortSignal): Promise<SuggestResponse>;
+export declare function resolveAttribute(transport: HttpTransport, q: string, options?: ResolveAttributeOptions, signal?: AbortSignal): Promise<ResolveAttributeResponse>;
+export declare function resolveAttributeValue(transport: HttpTransport, attributeId: string, query: string, options?: ResolveAttributeValueOptions, signal?: AbortSignal): Promise<ResolveAttributeValueResponse>;

package/client-vocabulary.js

@@ -0,0 +1,32 @@
+import { HttpTransport } from "./http-transport.js";
+import { resolveOperation } from "./operations.js";
+import { suggestQuery } from "./suggest-types.js";
+export function colourFacets(transport, signal) {
+    return transport.requestJson(resolveOperation("get_colour_facets"), { signal });
+}
+export function resolveColour(transport, name, signal) {
+    return transport.requestJson(resolveOperation("resolve_colour_name"), { query: { name }, signal });
+}
+export function suggestColour(transport, q, options, signal) {
+    return transport.requestJson(resolveOperation("suggest_colour_names"), { query: { q, limit: options?.limit }, signal });
+}
+export function suggest(transport, q, options, signal) {
+    return transport.requestJson(resolveOperation("search_suggest"), { query: suggestQuery(q, options), signal });
+}
+export function resolveAttribute(transport, q, options, signal) {
+    return transport.requestJson(resolveOperation("catalog_resolve_attribute"), {
+        query: {
+            q,
+            limit: options?.limit,
+            facetableOnly: options?.facetableOnly,
+        },
+        signal,
+    });
+}
+export function resolveAttributeValue(transport, attributeId, query, options, signal) {
+    return transport.requestJson(resolveOperation("catalog_resolve_value"), {
+        query: { q: query, limit: options?.limit },
+        pathParams: { attributeId },
+        signal,
+    });
+}

package/client.d.ts

@@ -1,6 +1,7 @@
 import { CatalogueClient } from "./catalogue-client.js";
 import type { MaterialGraphClientOptions } from "./client-config.js";
 import { type RateLimit } from "./errors.js";
+import { ScheduleReferencesClient } from "./schedule-references-client.js";
 export * from "./client-config.js";
 import { type BrowseNamespace } from "./client-browse.js";
 import { type ExplorationNamespace } from "./client-exploration.js";
@@ -11,6 +12,7 @@ export type { SourceMaterialCommentsNamespace } from "./client-source-material-c
 import type { ApplicabilityOptions, AssociatedOptions } from "./association-types.js";
 import type { BrandsOptions } from "./brand-types.js";
 import type { ByColourParams, ByColourResponse } from "./by-colour-types.js";
+import type { ResolvedVerdictCitation } from "./citation-types.js";
 import { CodesClient } from "./codes-client.js";
 import type { CodeAdvisoryInput, CodeAdvisoryResponse } from "./codes-types.js";
 import { ColoursClient } from "./colours-client.js";
@@ -26,6 +28,8 @@ import type { CapabilityManifestResponse, CreatePublicRunRequest, CreatePublicRu
 import type { FinishScheduleResponse, GetRunScheduleOptions } from "./schedule-types.js";
 import type { SchemaResource, SchemaResourceResponse } from "./schema-resource-types.js";
 import type { SlotPoolsRequest, SlotPoolsResponse } from "./slot-pool-types.js";
+import type { FindSubstitutesOptions, FindSubstitutesResponse } from "./substitute-types.js";
+import type { ProductTypeCoverageOptions, ProductTypeStatusCoverage } from "./taxonomy-coverage-types.js";
 import type { ApplicableSpecsResponse, BrandOptions, BySpecOptions, BySpecResponse, ColourFacetsResponse, CoordinateInput, CoordinateResponse, DemandBatchInput, DemandBatchResponse, DemandParams, DemandResponse, ExtractPaletteInput, ExtractPaletteResponse, GlossaryTermResponse, MaterialResponse, MaterialsBatchDetailResponse, MaterialsBatchGetOptions, MaterialsBatchOptions, MaterialsBatchTileResponse, PairingsOptions, PairingsResponse, ResolveAttributeOptions, ResolveAttributeResponse, ResolveAttributeValueOptions, ResolveAttributeValueResponse, ResolveColourResponse, SearchGetParams, SearchInput, SearchResponse, SiblingsResponse, SpecFacetsDistributionResponse, SpecFacetsListResponse, SuggestColourResponse, SuggestOptions, SuggestResponse, TaxonomyResponse, VocabularySearchOptions, WhoamiResponse } from "./types.js";
 /**
  * The MaterialGraph client — every lens on the graph, on one object.
@@ -64,6 +68,7 @@ import type { ApplicableSpecsResponse, BrandOptions, BySpecOptions, BySpecRespon
  */
 export declare class MaterialGraphClient extends CatalogueClient {
     #private;
+    readonly scheduleReferences: ScheduleReferencesClient;
     readonly baseUrl: string;
     /**
      * THE QUESTION: "show me everything in this category / this brand, in a plain
@@ -218,6 +223,7 @@ export declare class MaterialGraphClient extends CatalogueClient {
     siblings(variantId: VariantId, signal?: AbortSignal): Promise<SiblingsResponse>;
     materialBlocks(variantId: VariantId, signal?: AbortSignal): Promise<import("./material-block-types.js").MaterialBlockProjection>;
     materialAssets(variantId: VariantId, signal?: AbortSignal): Promise<import("./material-asset-types.js").MaterialAssetProjection>;
+    materialRenderAssets(variantId: VariantId, signal?: AbortSignal): Promise<import("./render-assets-types.js").MaterialRenderAssets>;
     materialDocuments(variantId: VariantId, options?: MaterialDocumentPageOptions, signal?: AbortSignal): Promise<import("./material-asset-types.js").MaterialDocumentPage>;
     /**
      * THE QUESTION: "what does the schema DEFINE?" — the governed static registry.
@@ -238,10 +244,12 @@ export declare 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: VariantId, options?: PairingsOptions, signal?: AbortSignal): Promise<PairingsResponse>;
+    /** Find bounded, exact-spec substitutes for one opaque variant id. */
+    findSubstitutes(variantId: VariantId, options?: FindSubstitutesOptions, signal?: AbortSignal): Promise<FindSubstitutesResponse>;
     /** "What finishes does the manufacturer declare for THIS product?" — {@link declaredFinishes}. */
     associatedFinishes(variantId: VariantId, options?: AssociatedOptions, signal?: AbortSignal): Promise<import("./association-types.js").DeclaredAssociationsResponse>;
     /** "What products does the manufacturer declare THIS finish for?" — {@link declaredProducts}. */
@@ -277,58 +285,19 @@ export declare class MaterialGraphClient extends CatalogueClient {
         view?: "tile";
         idKind?: MaterialsBatchGetOptions["idKind"];
     }, signal?: AbortSignal): Promise<MaterialsBatchTileResponse>;
-    /**
-     * 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?: AbortSignal): Promise<ColourFacetsResponse>;
-    /**
-     * 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: string, signal?: AbortSignal): Promise<ResolveColourResponse>;
     /** Ranked colour-name typeahead (GET `/api/v1/search/colours/suggest`). */
     suggestColour(q: string, options?: {
         limit?: number;
     }, signal?: AbortSignal): Promise<SuggestColourResponse>;
-    /**
-     * 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: string, options?: SuggestOptions, signal?: AbortSignal): Promise<SuggestResponse>;
-    /**
-     * 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: string, options?: ResolveAttributeOptions, signal?: AbortSignal): Promise<ResolveAttributeResponse>;
-    /**
-     * 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: string, query: string, options?: ResolveAttributeValueOptions, signal?: AbortSignal): Promise<ResolveAttributeValueResponse>;
     /** "Is this phrase an attribute or a value?" — see {@link searchVocabularyRequest}. */
     searchVocabulary(query: string, options?: VocabularySearchOptions, signal?: AbortSignal): Promise<import("./catalog-discovery-types.js").VocabularySearchResponse>;
@@ -364,6 +333,12 @@ export declare class MaterialGraphClient extends CatalogueClient {
      * {@link MaterialGraphClient.applicableSpecs}). Discover, never hand-write.
      */
     taxonomy(signal?: AbortSignal): Promise<TaxonomyResponse>;
+    /**
+     * 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?: ProductTypeCoverageOptions, signal?: AbortSignal): Promise<ProductTypeStatusCoverage>;
     /**
      * THE QUESTION: "what is this key allowed to do?" Check `scopes` before
      * offering a capability: the write surfaces need `mg:ingest` / `mg:compose`,
@@ -535,6 +510,8 @@ export declare class MaterialGraphClient extends CatalogueClient {
      * `GET /api/v1/runs/{runId}/schedule.xlsx` with the same bearer key.
      */
     runSchedule(runId: RunId, options?: GetRunScheduleOptions): Promise<FinishScheduleResponse>;
+    /** Follow a verdict cell's citation handle to its canonical claim source. */
+    citation(citationId: string, signal?: AbortSignal): Promise<ResolvedVerdictCitation>;
     /**
      * Resume a suspended Run (POST `/api/v1/runs/{runId}/resume`).
      *