@instruments/materialgraph 0.19.0 → 0.20.0

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/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 {

package/catalogue-client.d.ts

@@ -1,11 +1,62 @@
 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>;
     /**

package/catalogue-client.js

@@ -5,6 +5,18 @@ 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 });

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/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

@@ -19,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";
@@ -45,7 +47,9 @@ 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/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,4 @@
+import type { ResponseAttribution } from "./attribution-types.js";
 import type { CorpusScope } from "./corpus-scope-types.js";
 /**
  * @module sdk/match-types
@@ -37,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[];

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/operations.d.ts

@@ -1,5 +1,5 @@
 export declare const MATERIALGRAPH_API_VERSION = "0.7.0";
-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"]];
+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];

package/operations.js

@@ -1,6 +1,30 @@
 import { MaterialGraphError } from "./errors.js";
 export const MATERIALGRAPH_API_VERSION = "0.7.0";
 const OPERATION_DEFINITIONS = [
+    [
+        "colours.complete",
+        "POST",
+        "/api/v1/colours/palettes/complete",
+        "complete_interior_palette",
+    ],
+    [
+        "colours.discover",
+        "GET",
+        "/api/v1/colours/palettes",
+        "discover_interior_palettes",
+    ],
+    [
+        "samplizeColorVecCache",
+        "GET",
+        "/api/v1/catalogues/samplize/colorvec",
+        "samplize_colorvec_cache",
+    ],
+    [
+        "samplizeCatalogueSearch",
+        "POST",
+        "/api/v1/catalogues/samplize/search",
+        "samplize_catalogue_search",
+    ],
     [
         "scheduleReferences.list",
         "GET",
@@ -33,6 +57,7 @@ const OPERATION_DEFINITIONS = [
         "list_catalog_product_references",
     ],
     ["search", "POST", "/api/v1/search", "search_materials_post"],
+    ["identify", "POST", "/api/v1/identify", "retrieval.identify"],
     ["planQuery", "POST", "/api/v1/search/plan", "plan_material_query"],
     [
         "samplizeCatalogue",
@@ -270,13 +295,13 @@ const OPERATION_DEFINITIONS = [
         "get_source_material_batch",
     ],
     [
-        "sourceMaterialComments",
+        "sourceMaterialComments.list",
         "GET",
         "/api/v1/source-material/{batchId}/sources/{sourceId}/comments",
         "list_source_material_comments",
     ],
     [
-        "sourceMaterialComments",
+        "sourceMaterialComments.post",
         "POST",
         "/api/v1/source-material/{batchId}/sources/{sourceId}/comments",
         "post_source_material_comment",

package/package.json

@@ -1,13 +1,20 @@
 {
   "name": "@instruments/materialgraph",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "type": "module",
   "exports": {
     ".": {
       "types": "./index.d.ts",
       "import": "./index.js"
+    },
+    "./samplize-colorvec": {
+      "types": "./samplize-colorvec.d.ts",
+      "import": "./samplize-colorvec.js"
     }
   },
+  "dependencies": {
+    "@instruments/colorscope": "7.6.0"
+  },
   "license": "Proprietary",
   "engines": {
     "node": ">=24.0.0"

package/palette-completion-types.d.ts

@@ -0,0 +1,115 @@
+/** Public wire types; the SDK does not load the producer corpus. */
+export type CompositionalRole = "Foundation" | "Supporting" | "Accent";
+export interface RetainedColor {
+    readonly id: string;
+    readonly hex: string;
+    readonly role?: CompositionalRole;
+    readonly paintVariantId?: string;
+}
+export interface CompletionRequest {
+    readonly inputs: readonly RetainedColor[];
+    readonly maxDistance?: number;
+    readonly limit?: number;
+    readonly white?: "published" | "perceptual";
+    readonly memberCount?: number;
+    readonly excludeHexes?: readonly string[];
+}
+export interface CompletionAssignment {
+    readonly input: RetainedColor;
+    readonly referenceIndex: number;
+    readonly referenceHex: string;
+    readonly distance: number;
+}
+export interface CompletionMember {
+    readonly hex: string;
+    readonly referenceHex: string;
+    readonly referenceIndex: number;
+    readonly inputIds: readonly string[];
+    readonly role: CompositionalRole;
+    readonly proportion: number;
+    readonly sourceRole: string | null;
+    readonly sourceRelation: string | null;
+}
+export interface PaletteCompletion {
+    readonly uses?: readonly {
+        readonly inputId: string;
+        readonly role: CompositionalRole;
+        readonly proportions: readonly number[];
+    }[];
+    readonly id: string;
+    readonly reference: {
+        readonly anchorIndex?: number | null;
+        readonly libraryId: string;
+        readonly paletteId: string;
+        readonly name: string | null;
+        readonly maker: string | null;
+        readonly intent: "joint" | "alternatives";
+        readonly provenance: "authored" | "derived" | "generated";
+    };
+    readonly assignments: readonly CompletionAssignment[];
+    readonly members: readonly CompletionMember[];
+    readonly evidenceBasis: "published-composition" | "published-pair" | "nearby-adaptation";
+    readonly proportionBasis: "sourced" | "proposed";
+    readonly worstDistance: number;
+    readonly totalDistance: number;
+}
+export type PaletteCompleteInput = CompletionRequest & {
+    sourceVersion: string;
+};
+export interface PaletteDiscoverInput {
+    sourceVersion: string;
+    character?: "warm" | "cool" | "very-light" | "light" | "dark" | "muted" | "soft" | "vivid";
+    moreLike?: string;
+    cursor?: string;
+    limit?: number;
+}
+export interface MaterializedPalette {
+    completion: PaletteCompletion;
+    samples: Array<{
+        retainedPaint?: {
+            variantId: string;
+            name: string;
+            maker: string;
+        };
+        referenceIndex: number;
+        inputIds: readonly string[];
+        hex: string;
+        product: {
+            variantId: string;
+            productId: string;
+            hex: string;
+            name: string;
+            brand: {
+                slug: string;
+                name: string;
+            };
+        } | null;
+        status: string;
+        distance: number | null;
+        units: "oklab-euclidean";
+    }>;
+}
+interface PaletteVersions {
+    sourceVersion: string;
+    corpusVersion: string;
+    algorithmVersion: string;
+    transport: "colorscope-package";
+}
+export interface PaletteCompleteResponse extends PaletteVersions {
+    results: MaterializedPalette[];
+    coverage: {
+        status: string;
+        supported: number;
+    };
+    tolerance: {
+        bound: number;
+        units: string;
+        policy: string;
+    };
+}
+export interface PaletteDiscoverResponse extends PaletteVersions {
+    results: MaterializedPalette[];
+    total: number;
+    nextCursor: string | null;
+}
+export {};

package/palette-completion-types.js

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

package/samplize-colorvec.d.ts

@@ -0,0 +1,70 @@
+export declare const SAMPLIZE_COLORVEC_RANKING_VERSION = "solid-colorvec-cosine-v2";
+export declare const SAMPLIZE_COLORVEC_EMBEDDING_VERSION = "oklch-anchor-quantiles-v12";
+export interface SamplizeColorVecPaint {
+    variantId: string;
+    hex: string;
+    brand: string;
+    oklab: {
+        L: number;
+        a: number;
+        b: number;
+    };
+    family: string;
+    lightness: string;
+    intensity: string;
+    vector: number[] | string;
+}
+export interface SamplizeColorVecCache {
+    sourceVersion: string;
+    dictionaryVersion: string;
+    embeddingVersion: string;
+    rankingVersion: string;
+    generatedAt: string;
+    paints: SamplizeColorVecPaint[];
+}
+export interface SamplizeColorVecInput {
+    hex?: string;
+    reference?: string;
+    palette?: Array<{
+        hex: string;
+        proportion: number;
+    }>;
+    direction?: "similar" | "lighter" | "darker" | "muted";
+    brand?: string[];
+    family?: string[];
+    lightness?: string[];
+    intensity?: string[];
+    lightnessMin?: number;
+    lightnessMax?: number;
+    temperatureMin?: number;
+    temperatureMax?: number;
+    limit?: number;
+}
+export declare const samplizeSolidColorVector: (hex: string) => number[];
+/** Canonical constraints are shared by full-cache similarity and constrained text retrieval. */
+export declare function selectSamplizeEligiblePaints<T extends Omit<SamplizeColorVecPaint, "vector">>(paints: T[], input: SamplizeColorVecInput): {
+    reference: T | undefined;
+    eligible: T[];
+    counts: Record<"brand" | "family" | "intensity" | "lightness", Record<string, number>>;
+};
+/** Official portable MG ranking over its complete versioned sampling-channel projection. */
+export declare function createSamplizeColorVecIndex(cache: SamplizeColorVecCache): {
+    search(input: SamplizeColorVecInput): {
+        ids: string[];
+        groups: {
+            hex: string;
+            proportion: number;
+            quota: number;
+            ids: string[];
+            shortfall: number;
+        }[];
+        limited: boolean;
+        eligibleCount: number;
+        counts: Record<"brand" | "family" | "intensity" | "lightness", Record<string, number>>;
+        sourceVersion: string;
+        dictionaryVersion: string;
+        embeddingVersion: string;
+        rankingVersion: string;
+        countBasis: "complete-catalogue";
+    };
+};

package/samplize-colorvec.js

@@ -0,0 +1,167 @@
+import { EMBEDDING_VERSION, EMBEDDING_VECTOR_SIZE, embeddingCosineSimilarity, paletteToEmbedding, } from "@instruments/colorscope/embedding";
+export const SAMPLIZE_COLORVEC_RANKING_VERSION = "solid-colorvec-cosine-v2";
+export const SAMPLIZE_COLORVEC_EMBEDDING_VERSION = EMBEDDING_VERSION;
+const decodeVector = (encoded) => {
+    const bytes = Uint8Array.from(atob(encoded), (c) => c.charCodeAt(0));
+    if (bytes.length !== EMBEDDING_VECTOR_SIZE * 4)
+        throw new Error("Invalid colour vector size.");
+    const view = new DataView(bytes.buffer);
+    return Array.from({ length: EMBEDDING_VECTOR_SIZE }, (_, i) => view.getFloat32(i * 4, true));
+};
+const facets = ["brand", "family", "lightness", "intensity"];
+const identityOrder = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+export const samplizeSolidColorVector = (hex) => {
+    if (!/^#[0-9a-f]{6}$/i.test(hex))
+        throw new Error("A six-digit published colour is required.");
+    return paletteToEmbedding([{ hex, proportion: 1 }], { validateOklab: true });
+};
+/** Canonical constraints are shared by full-cache similarity and constrained text retrieval. */
+export function selectSamplizeEligiblePaints(paints, input) {
+    const reference = input.reference
+        ? paints.find((p) => p.variantId === input.reference)
+        : undefined;
+    if (input.reference && !reference)
+        throw new Error("The reference is absent from this catalogue version.");
+    const low = input.lightnessMin ?? 0, high = input.lightnessMax ?? 1;
+    const cool = input.temperatureMin ?? -0.4, warm = input.temperatureMax ?? 0.4;
+    if (![low, high, cool, warm].every(Number.isFinite) ||
+        low > high ||
+        cool > warm)
+        throw new Error("Appearance ranges must be finite and ordered.");
+    const candidates = paints.filter((p) => {
+        if (!reference)
+            return true;
+        if (p.variantId === reference.variantId)
+            return false;
+        if (input.direction === "lighter")
+            return p.oklab.L > reference.oklab.L;
+        if (input.direction === "darker")
+            return p.oklab.L < reference.oklab.L;
+        if (input.direction === "muted")
+            return (Math.hypot(p.oklab.a, p.oklab.b) <
+                Math.hypot(reference.oklab.a, reference.oklab.b));
+        return true;
+    });
+    const matches = (p, omit) => p.oklab.L >= low &&
+        p.oklab.L <= high &&
+        p.oklab.b >= cool &&
+        p.oklab.b <= warm &&
+        facets.every((f) => f === omit || !input[f]?.length || input[f].includes(p[f]));
+    const counts = {
+        brand: {},
+        family: {},
+        lightness: {},
+        intensity: {},
+    };
+    for (const p of candidates)
+        for (const f of facets)
+            if (matches(p, f))
+                counts[f][p[f]] = (counts[f][p[f]] ?? 0) + 1;
+    const eligible = candidates.filter((p) => matches(p));
+    return { reference, eligible, counts };
+}
+/** Official portable MG ranking over its complete versioned sampling-channel projection. */
+export function createSamplizeColorVecIndex(cache) {
+    if (cache.embeddingVersion !== EMBEDDING_VERSION ||
+        cache.rankingVersion !== SAMPLIZE_COLORVEC_RANKING_VERSION)
+        throw new Error("The colour cache uses an incompatible embedding or ranking version. Refresh it before searching.");
+    if (!cache.sourceVersion ||
+        !cache.dictionaryVersion ||
+        !Number.isFinite(Date.parse(cache.generatedAt)))
+        throw new Error("The colour cache is missing its provenance.");
+    const paints = cache.paints.map((p) => ({
+        ...p,
+        vector: typeof p.vector === "string" ? decodeVector(p.vector) : p.vector,
+    }));
+    const identities = new Set();
+    for (const paint of paints) {
+        if (identities.has(paint.variantId) ||
+            paint.vector.length !== EMBEDDING_VECTOR_SIZE ||
+            !paint.vector.every(Number.isFinite) ||
+            ![paint.oklab.L, paint.oklab.a, paint.oklab.b].every(Number.isFinite))
+            throw new Error("The colour cache contains invalid or duplicate paint records.");
+        identities.add(paint.variantId);
+    }
+    const vectors = new Map();
+    const vectorFor = (hex) => {
+        const key = hex.toLowerCase();
+        let value = vectors.get(key);
+        if (!value) {
+            value = samplizeSolidColorVector(hex);
+            if (vectors.size >= 512)
+                vectors.delete(vectors.keys().next().value);
+            vectors.set(key, value);
+        }
+        return value;
+    };
+    return {
+        search(input) {
+            const limit = input.limit ?? 48;
+            if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+                throw new Error("Choose between 1 and 100 suggestions.");
+            const { reference, eligible, counts } = selectSamplizeEligiblePaints(paints, input);
+            const palette = (input.palette?.length
+                ? input.palette
+                : [{ hex: input.hex ?? reference?.hex ?? "", proportion: 1 }])
+                .map((p) => ({ ...p, hex: p.hex.toLowerCase() }))
+                .sort((a, b) => b.proportion - a.proportion || identityOrder(a.hex, b.hex));
+            if (palette.length > 12 ||
+                palette.some((p) => !Number.isFinite(p.proportion) ||
+                    p.proportion <= 0 ||
+                    p.proportion > 1))
+                throw new Error("Supply up to twelve positive image colour shares.");
+            const total = palette.reduce((sum, p) => sum + p.proportion, 0);
+            const buckets = palette.map((p, position) => ({
+                ...p,
+                position,
+                vector: vectorFor(p.hex),
+                quota: Math.floor((limit * p.proportion) / total),
+                remainder: ((limit * p.proportion) / total) % 1,
+                paints: [],
+            }));
+            let remaining = limit - buckets.reduce((sum, p) => sum + p.quota, 0);
+            for (const p of [...buckets].sort((a, b) => b.remainder - a.remainder || a.position - b.position))
+                if (remaining-- > 0)
+                    p.quota++;
+            for (const paint of eligible) {
+                let best = buckets[0], score = embeddingCosineSimilarity(paint.vector, best.vector);
+                for (let i = 1; i < buckets.length; i++) {
+                    const candidate = buckets[i], next = embeddingCosineSimilarity(paint.vector, candidate.vector);
+                    if (next > score) {
+                        best = candidate;
+                        score = next;
+                    }
+                }
+                best.paints.push({ id: paint.variantId, score });
+            }
+            const groups = buckets
+                .sort((a, b) => b.proportion - a.proportion || a.position - b.position)
+                .map((p) => {
+                const ids = p.paints
+                    .sort((a, b) => b.score - a.score || identityOrder(a.id, b.id))
+                    .slice(0, p.quota)
+                    .map((paint) => paint.id);
+                return {
+                    hex: p.hex,
+                    proportion: p.proportion,
+                    quota: p.quota,
+                    ids,
+                    shortfall: p.quota - ids.length,
+                };
+            });
+            const ids = groups.flatMap((p) => p.ids);
+            return {
+                ids,
+                groups,
+                limited: eligible.length > ids.length,
+                eligibleCount: eligible.length,
+                counts,
+                sourceVersion: cache.sourceVersion,
+                dictionaryVersion: cache.dictionaryVersion,
+                embeddingVersion: cache.embeddingVersion,
+                rankingVersion: cache.rankingVersion,
+                countBasis: "complete-catalogue",
+            };
+        },
+    };
+}

package/search-card-types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @module sdk/search-card-types
+ * @description The `view:"card"` search projection — the lean grid item and the
+ * envelope that carries it.
+ *
+ * Split out of `types.ts` — which is over the repository's source-size limit —
+ * along the same seam `match-types.ts` took: one view of one surface, and
+ * nothing else. The full-view item and the shared envelope stay in `types.ts`,
+ * which this module reads `SearchResponse` from.
+ */
+import type { ProductId, VariantId } from "./identifiers.js";
+import type { OpenEnum, SearchResponse } from "./types.js";
+/**
+ * The lean `view:"card"` result item — identity + name + thumbnail + score.
+ *
+ * A PROJECTION, not a smaller answer: a field the card omits (palette, verdict,
+ * signals, availability) is unread here, never known-absent. Re-read the same
+ * `variantId` at `view: "full"` or via `material()` before claiming anything the
+ * card does not carry.
+ */
+export interface SearchCardItem {
+    /** Accepted sampleability fact. Absent means unknown, never false. */
+    sampleable?: boolean;
+    /** Opaque — round-trip verbatim. */
+    variantId: VariantId;
+    productId: ProductId | null;
+    brandSlug: string | null;
+    brand: string;
+    /** Product name (the full item's `product`). */
+    name: string;
+    variantName: string | null;
+    imageUrl: string | null;
+    projectSaveCapability?: "allowed";
+    sourceStatus?: "provisional";
+    score: number;
+    /**
+     * Resolved values for the attribute ids sent in `returnAttributes`, keyed by
+     * attribute id. ABSENT entirely when `returnAttributes` was not sent.
+     *
+     * Three states, all different, and reading them as two is the mistake this
+     * shape exists to prevent: no `attributes` key means you did not ask; a key
+     * whose value is `null` means this material carries no accepted value for that
+     * attribute; anything else is what the graph holds. Values resolve with the
+     * normal variant-over-product precedence, and an array is a multi-valued
+     * attribute rather than a list of candidates.
+     */
+    attributes?: Record<string, string | string[] | null>;
+}
+/** The `view:"card"` response form — the lean grid projection of {@link SearchResponse}. */
+export interface SearchCardResponse extends Omit<SearchResponse, "view" | "results"> {
+    view: OpenEnum<"card">;
+    results: SearchCardItem[];
+}

package/search-card-types.js

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

package/substitute-types.d.ts

@@ -57,6 +57,33 @@ export interface AvailableSubstitutesResponse {
     items: SubstituteResultItem[];
     candidatePoolSize: number;
     droppedUnavailable: number;
+    /**
+     * MG-1686, MG-1783. True when the candidate read hit the bounded pool ceiling,
+     * so more materials match the signature than were ranked. A cut pool is an
+     * even SAMPLE across the id keyspace rather than its lowest window, so the
+     * ranked set is representative of the match set without being all of it —
+     * treat the items as the best of a sample, never as the best that exist. A cut
+     * pool that produced NO items answers `inconclusive` instead, so `available`
+     * with an empty `items` always means a complete search that found nothing.
+     */
+    poolTruncated: boolean;
+    supersededBy: MaterialSuccessor | null;
+    nextCursor?: string;
+}
+/**
+ * MG-1686. The search read a bounded window of the matches and nothing in it
+ * reached the page, while more matches existed past the window. It is not an
+ * answer of "nothing can replace this" — that answer is `available` with an
+ * empty `items`. `reason` names what happened and the next move; follow
+ * `nextCursor` when it is present.
+ */
+export interface InconclusiveSubstitutesResponse {
+    status: "inconclusive";
+    signatureUsed: AvailableSubstituteSignature;
+    items: [];
+    candidatePoolSize: number;
+    droppedUnavailable: number;
+    reason: string;
     supersededBy: MaterialSuccessor | null;
     nextCursor?: string;
 }
@@ -72,4 +99,4 @@ export interface InsufficientSubstitutesResponse {
     items: [];
     supersededBy: MaterialSuccessor | null;
 }
-export type FindSubstitutesResponse = AvailableSubstitutesResponse | UnsupportedSubstitutesResponse | InsufficientSubstitutesResponse;
+export type FindSubstitutesResponse = AvailableSubstitutesResponse | InconclusiveSubstitutesResponse | UnsupportedSubstitutesResponse | InsufficientSubstitutesResponse;

package/types.d.ts

@@ -1,3 +1,4 @@
+import type { ResponseAttribution } from "./attribution-types.js";
 import type { BySpecVerdict } from "./by-spec-types.js";
 /**
  * Hand-mirrored wire types for the MaterialGraph public API (spec 0.5.0).
@@ -31,6 +32,7 @@ import type { Cursor, ProductId, VariantId } from "./identifiers.js";
 import type { MaterialDetail, MaterialTile } from "./material-types.js";
 import type { QueryUnderstanding } from "./query-understanding-types.js";
 import type { CollapsedVariant, SearchAnatomyMember } from "./search-collapse-types.js";
+import type { MoodInterpretation } from "./search-mood-types.js";
 import type { SearchDisambiguation, SearchSuggestion } from "./search-refinement-types.js";
 import type { CompoundColourConstraintReceipt, CompoundFormConstraintReceipt, SearchExecutionPlan, SearchMode, SearchRefinementReceipt, SearchRerankReport, SearchResponseExplainReceipts } from "./search-response-receipt-types.js";
 import type { SearchWindowReceipt } from "./search-window-types.js";
@@ -114,6 +116,8 @@ export interface VisualMeaning {
  * `visualMeanings` is not "this material has no visual meaning".
  */
 export interface SearchResultItem {
+    /** This hit's attribution key — see {@link ResponseAttribution}. Opaque. */
+    resultId?: string;
     /** Accepted sampleability fact. Absent means unknown, never false. */
     sampleable?: boolean;
     /** Opaque — round-trip verbatim into `material()`, `pairings()`, `similarTo`. */
@@ -263,42 +267,6 @@ export interface SearchResultItem {
      */
     attributes?: Record<string, string | string[] | null>;
 }
-/**
- * The lean `view:"card"` result item — identity + name + thumbnail + score.
- *
- * A PROJECTION, not a smaller answer: a field the card omits (palette, verdict,
- * signals, availability) is unread here, never known-absent. Re-read the same
- * `variantId` at `view: "full"` or via `material()` before claiming anything the
- * card does not carry.
- */
-export interface SearchCardItem {
-    /** Accepted sampleability fact. Absent means unknown, never false. */
-    sampleable?: boolean;
-    /** Opaque — round-trip verbatim. */
-    variantId: VariantId;
-    productId: ProductId | null;
-    brandSlug: string | null;
-    brand: string;
-    /** Product name (the full item's `product`). */
-    name: string;
-    variantName: string | null;
-    imageUrl: string | null;
-    projectSaveCapability?: "allowed";
-    sourceStatus?: "provisional";
-    score: number;
-    /**
-     * Resolved values for the attribute ids sent in `returnAttributes`, keyed by
-     * attribute id. ABSENT entirely when `returnAttributes` was not sent.
-     *
-     * Three states, all different, and reading them as two is the mistake this
-     * shape exists to prevent: no `attributes` key means you did not ask; a key
-     * whose value is `null` means this material carries no accepted value for that
-     * attribute; anything else is what the graph holds. Values resolve with the
-     * normal variant-over-product precedence, and an array is a multi-valued
-     * attribute rather than a list of candidates.
-     */
-    attributes?: Record<string, string | string[] | null>;
-}
 /**
  * A feed total with its honesty basis — THE CLAIM ABOUT THE MATCH SET, which is
  * a different number from `results.length` (this page).
@@ -391,11 +359,29 @@ export interface SearchFacets {
  * wrong whenever `limit` was 24.
  */
 export interface SearchResponse extends SearchResponseExplainReceipts {
+    /** Result attribution — see {@link ResponseAttribution}. `basis` is `mode` verbatim here. */
+    attribution?: ResponseAttribution;
     view: OpenEnum<"full" | "card">;
     /** THIS PAGE. Its length is a page size, never a total. */
     results: SearchResultItem[];
     suggestions: SearchSuggestion[];
     mode: SearchMode;
+    /**
+     * Which dense text lane answered, when one did (MG-1796). `image-text` — the
+     * query carried evidence it describes appearance, so it was ranked against
+     * image vectors; `variant-text` — ranked against each variant's written
+     * portrait.
+     *
+     * ABSENT means the answer did not come from the dense text arm at all: `mode`
+     * was never `text`, or the text arm resolved without a lane. Absence is
+     * UNKNOWN and never a default of `image-text` — treating it as one asserts a
+     * dense reading of a lexical, colour or browse answer. Absent too from any
+     * response produced by a server predating MG-1793.
+     *
+     * An {@link OpenEnum} because the lane vocabulary can grow: a value you do
+     * not recognise is a lane this client predates, not a malformed response.
+     */
+    textLane?: OpenEnum<"image-text" | "variant-text">;
     maxScore: number;
     cursor?: Cursor;
     window?: SearchWindowReceipt;
@@ -432,7 +418,7 @@ export interface SearchResponse extends SearchResponseExplainReceipts {
      * Explicit standard-search mood reading; null ids mean no selected mood.
      * Absent when mood was not evaluated or an older server produced the result.
      */
-    moodInterpretation?: import("./search-mood-types.js").MoodInterpretation;
+    moodInterpretation?: MoodInterpretation;
     /**
      * Present when the query had multiple defensible readings. Says which one
      * ran, or leaves every reading non-default when the engine chose none. Every
@@ -453,11 +439,6 @@ export interface SearchResponse extends SearchResponseExplainReceipts {
     /** A `getVariantBrief` echo of the seed variant, present only in `variantId` seed mode. */
     seed?: MaterialTile | Record<string, unknown>;
 }
-/** The `view:"card"` response form — the lean grid projection of {@link SearchResponse}. */
-export interface SearchCardResponse extends Omit<SearchResponse, "view" | "results"> {
-    view: OpenEnum<"card">;
-    results: SearchCardItem[];
-}
 export type ColourDictionaryId = OpenEnum<"colour_family" | "colour_mood" | "colour_undertone">;
 export interface ColourFacetTerm {
     id: string;
@@ -606,6 +587,13 @@ export interface PairingsResponse {
      * check it before presenting the rail as demand evidence.
      */
     cospecCount: number;
+    /**
+     * Candidates dropped at hydration for violating the material contract
+     * (MG-985). Present ONLY when > 0. A non-zero count means the rail is
+     * shorter than the evidence behind it — read it before calling the rail
+     * complete.
+     */
+    skippedCandidates?: number;
     /** Present only when `order` was requested. Evidence tiers remain independent. */
     ordering?: PairingOrdering;
     /** Opaque continuation bound to the seed, filters, corpus, and order. */