@instruments/materialgraph 0.9.1 → 0.11.0

package/client.d.ts

@@ -1,25 +1,31 @@
-import { type RateLimit } from "./errors.js";
 import type { MaterialGraphClientOptions } from "./client-config.js";
+import { type RateLimit } from "./errors.js";
 export * from "./client-config.js";
 import { type BrowseNamespace } from "./client-browse.js";
+import { type ExplorationNamespace } from "./client-exploration.js";
 export type { BrowseNamespace } from "./client-browse.js";
-import type { CapabilityManifestResponse, CreatePublicRunRequest, CreatePublicRunResponse, DrainRunEventsOptions, ListRunsOptions, PublicRunListResponse, PublicRunResponse, ResumeRunOptions, RunEvent, SourceMaterialBatchDetail, SourceMaterialBatchReceipt, StreamRunEventsOptions, UploadSourceMaterialInput } from "./run-types.js";
-import type { FinishScheduleResponse, GetRunScheduleOptions } from "./schedule-types.js";
-import type { MatchStreamEvent } from "./match-stream-types.js";
-import type { AppendProjectEventRequest, CreateProjectRequest, ProjectEventReceipt, ProjectListResponse, ProjectState } from "./project-types.js";
-import type { VarySchemesRequest, VarySchemesResponse } from "./composition-types.js";
-import { CodesClient } from "./codes-client.js";
-import { ColoursClient } from "./colours-client.js";
-import type { CodeAdvisoryInput, CodeAdvisoryResponse } from "./codes-types.js";
+export type { ExplorationNamespace } from "./client-exploration.js";
+import { type SourceMaterialCommentsNamespace } from "./client-source-material-comments.js";
+export type { SourceMaterialCommentsNamespace } from "./client-source-material-comments.js";
 import type { AssociatedOptions } from "./association-types.js";
 import type { BrandCatalogListPage, BrandsOptions } from "./brand-types.js";
+import type { ByColourParams, ByColourResponse } from "./by-colour-types.js";
+import { CodesClient } from "./codes-client.js";
+import type { CodeAdvisoryInput, CodeAdvisoryResponse } from "./codes-types.js";
+import { ColoursClient } from "./colours-client.js";
+import type { VarySchemesRequest, VarySchemesResponse } from "./composition-types.js";
+import type { BatchId, ProjectId, RunId, VariantId } from "./identifiers.js";
+import type { MatchStreamEvent } from "./match-stream-types.js";
+import type { MatchInput, MatchResponse } from "./match-types.js";
 import type { MaterialAssetProjection } from "./material-asset-types.js";
 import type { MaterialBlockProjection } from "./material-block-types.js";
+import type { AppendProjectEventRequest, CreateProjectRequest, ProjectEventReceipt, ProjectListResponse, ProjectState } from "./project-types.js";
+import { resolvePhrasesRequest as resolvePhrases } from "./resolve-client.js";
+import type { CapabilityManifestResponse, CreatePublicRunRequest, CreatePublicRunResponse, DrainRunEventsOptions, ListRunsOptions, PublicRunListResponse, PublicRunResponse, ResumeRunOptions, RunEvent, SourceMaterialBatchDetail, SourceMaterialBatchReceipt, StreamRunEventsOptions, UploadSourceMaterialInput } from "./run-types.js";
+import type { FinishScheduleResponse, GetRunScheduleOptions } from "./schedule-types.js";
 import type { SchemaResource, SchemaResourceResponse } from "./schema-resource-types.js";
-import type { BatchId, ProjectId, RunId, VariantId } from "./identifiers.js";
-import type { ByColourParams, ByColourResponse } from "./by-colour-types.js";
+import type { SlotPoolsRequest, SlotPoolsResponse } from "./slot-pool-types.js";
 import type { ApplicableSpecsResponse, BrandOptions, BrandProfileResponse, BySpecOptions, BySpecResponse, ColourFacetsResponse, CoordinateInput, CoordinateResponse, DemandBatchInput, DemandBatchResponse, DemandParams, DemandResponse, ExtractPaletteInput, ExtractPaletteResponse, GlossaryTermResponse, MaterialResponse, MaterialsBatchDetailResponse, MaterialsBatchGetOptions, MaterialsBatchOptions, MaterialsBatchTileResponse, PairingsOptions, PairingsResponse, ResolveAttributeOptions, ResolveAttributeResponse, ResolveAttributeValueOptions, ResolveAttributeValueResponse, ResolveColourResponse, SearchGetParams, SearchInput, SearchResponse, SiblingsResponse, SpecFacetsDistributionResponse, SpecFacetsListResponse, SuggestColourResponse, SuggestOptions, SuggestResponse, TaxonomyResponse, VocabularySearchOptions, WhoamiResponse } from "./types.js";
-import type { MatchInput, MatchResponse } from "./match-types.js";
 /**
  * The MaterialGraph client — every lens on the graph, on one object.
  *
@@ -60,14 +66,21 @@ export declare class MaterialGraphClient {
     #private;
     readonly baseUrl: string;
     /**
-     * THE QUESTION: "show me everything, ordered lightest / most vivid / most
-     * muted." Pure colour scalars — no query, no relevance. `browse({ sort })` is
-     * one page; `browse.pages({ sort })` walks them all, and only the walk can
-     * support a corpus claim.
+     * THE QUESTION: "show me everything in this category / this brand, in a plain
+     * order." No query, no relevance, no ranking. `browse(params)` is one page;
+     * `browse.pages(params)` walks them all.
+     *
+     * `sort` is optional (`name` A→Z by default, `recent` for newest first, plus
+     * the five colour ramps), `types`/`brands`/`corpusScope` narrow it, and
+     * `count: true` returns the total so a listing can say how many things it is
+     * listing without walking every page. `results.length` remains a PAGE.
      *
      * Instead use {@link MaterialGraphClient.byColour} for materials NEAR a colour,
      * {@link MaterialGraphClient.search} when there is anything to rank against,
      * and `colours.profiles()` for a category's palette rather than its members.
+     *
+     * @example A category listing that can state its own size
+     * const page = await client.browse({ types: "tile_surfaces", count: true });
      */
     readonly browse: BrowseNamespace;
     /**
@@ -93,6 +106,14 @@ export declare class MaterialGraphClient {
      * likeness, never a declared colour specification.
      */
     readonly colours: ColoursClient;
+    /** Discover honest graph questions, then traverse one explicit operator. */
+    readonly exploration: ExplorationNamespace;
+    /**
+     * THE QUESTION: "what did people say about this uploaded file, and record what
+     * they said." Names on these remarks are REPORTED, never verified — see
+     * {@link SourceMaterialCommentsNamespace}.
+     */
+    readonly sourceMaterialComments: SourceMaterialCommentsNamespace;
     constructor(options: MaterialGraphClientOptions);
     get lastRateLimit(): RateLimit | null;
     /**
@@ -172,8 +193,7 @@ export declare class MaterialGraphClient {
      * {@link MaterialGraphClient.browse} to walk by lightness/vividness, and
      * {@link MaterialGraphClient.search} when colour is one signal among many.
      * Report matches as visual likeness, never a stated colour specification.
-     * `family` gates the answer to ONE colorscope colour family when nearness
-     * alone crosses a hue boundary; a gated page can be shorter than `limit`.
+     * `family` gates to ONE colorscope family (a gated page can be short); `brand` gates to named brands — one brand's nearest colour to another's.
      */
     byColour(params: ByColourParams, signal?: AbortSignal): Promise<ByColourResponse>;
     /**
@@ -326,33 +346,29 @@ export declare class MaterialGraphClient {
     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>;
-    /** "I have words — what do they mean in YOUR vocabulary?" — see {@link resolvePhrasesRequest}. */
-    resolve(phrases: string[], signal?: AbortSignal): Promise<import("./resolve-types.js").ResolveResponse>;
+    /** "I have words — what do they mean, and what stands behind them?" — see {@link resolvePhrases}. */
+    resolve(phrases: string[], scope?: Parameters<typeof resolvePhrases>[2]): Promise<import("./resolve-types.js").ResolveResponse>;
     /**
      * THE QUESTION: "which materials, from ANYONE, are ASTM E84 Class A AND
-     * GREENGUARD-certified?" — hard specifications, no ranking, every brand at once
-     * whatever each called the value in source.
+     * GREENGUARD-certified?" — hard specifications, no ranking, every brand at
+     * once whatever each called the value in source. The value-anchored,
+     * spec-only primitive (GET `/api/v1/search/specifications`).
      *
      * Instead use `search({ filters })` when the spec merely GATES a ranked
      * question, `codes.advisory()` when the real question is what a space demands,
-     * and {@link MaterialGraphClient.specificationFacets} first if you do not know
-     * the canonical tokens. Guessing one no longer returns a silently empty
-     * answer: an unresolvable criterion means the query NEVER RAN, and the
-     * response says so — read {@link BySpecResponse.unresolvedCriteria} before
-     * treating an empty `matches` as "nothing qualifies".
-     *
-     * A PAGE, NOT A CORPUS, unusually so: `totalMatches` is the size of the
-     * returned sample under `limit`, not a corpus count. See {@link BySpecResponse}.
-     *
-     * Find materials by canonical specification across every brand — the
-     * value-anchored, spec-only primitive (GET `/api/v1/search/specifications`).
-     * Each `spec` is an `attribute:value` criterion; a variant must satisfy ALL of
-     * them, and each match carries per-criterion trust (`confidence` +
-     * `sourceBasis`). Answers "which materials, from anyone, are ASTM E84 Class A
-     * AND GREENGUARD-certified?" Build the strings with `specCriterion` /
-     * `certificationProgrammeCriterion` (e.g.
-     * `certificationProgrammeCriterion("GREENGUARD Gold")`); discover the queryable
-     * vocabulary with {@link specificationFacets} and {@link attributeValues}.
+     * and {@link specificationFacets} first if you do not know the canonical
+     * tokens. Guessing one no longer returns a silently empty answer: an
+     * unresolvable criterion means the query NEVER RAN and the response says so —
+     * read {@link BySpecResponse.unresolvedCriteria} before treating an empty
+     * `matches` as "nothing qualifies". A PAGE, NOT A CORPUS, unusually so:
+     * `totalMatches` is the returned sample's size under `limit`, not a corpus
+     * count. Each `spec` is an `attribute:value` criterion built with
+     * `specCriterion` / `certificationProgrammeCriterion`; a variant must satisfy
+     * ALL of them, and each match carries per-criterion trust (`confidence` +
+     * `sourceBasis`). NUMBER-valued specs take BOUNDS, not values — pass
+     * `options.ranges` built with `specRangeCriterion("light_reflectance_value",
+     * { min: 60 })`; bounds are inclusive, at least one is required, and a
+     * non-numeric stored value is excluded rather than read as zero.
      */
     bySpec(spec: string | string[], options?: BySpecOptions, signal?: AbortSignal): Promise<BySpecResponse>;
     /**
@@ -368,17 +384,7 @@ export declare class MaterialGraphClient {
      * and `mg:admin` unlocks extra evidence fields.
      */
     whoami(signal?: AbortSignal): Promise<WhoamiResponse>;
-    /**
-     * THE QUESTION: "here is my whole scheme so far — what completes it?" The
-     * multi-seed form of {@link MaterialGraphClient.pairings}: lift is summed across
-     * seeds, so a companion suiting one pick ranks below one suiting several.
-     * Instead use `pairings` for a single material and `colours.palette()` when the
-     * scheme is COLOURS rather than materials. Check `unresolved` before presenting.
-     *
-     * Coordinate a palette of already-chosen materials (POST
-     * `/api/v1/pairings/coordinate`). Returns demand-lift-ranked companions with
-     * colour swatches and an annotate-only `colourFit` (never reorders in v1).
-     */
+    /** What completes a scheme already part-chosen. See {@link coordinateCall}. */
     coordinate(input: CoordinateInput, signal?: AbortSignal): Promise<CoordinateResponse>;
     /**
      * THE QUESTION: "how much is this material actually specified, and what gets
@@ -479,21 +485,12 @@ export declare class MaterialGraphClient {
      * {@link MaterialGraphClient.attributeValues} for the values it takes.
      */
     glossary(term: string, signal?: AbortSignal): Promise<GlossaryTermResponse>;
-    /**
-     * THE QUESTION: "whose catalogs are in here, and how big is each?" The SDK's
-     * one OFFSET-paginated surface: read `meta.total` for the collection size and
-     * `meta.hasMore` to keep walking. Instead use {@link MaterialGraphClient.brand}
-     * for one brand's profile and trade signals.
-     */
+    /** "Whose catalogs are in here, and how big is each?" — {@link listBrands}. */
     brands(options?: BrandsOptions, signal?: AbortSignal): Promise<BrandCatalogListPage>;
-    /**
-     * THE QUESTION: "who is this brand, and what do they claim?" — profile plus the
-     * trade/spec signals ON RECORD. `trade` is keyed by attribute id and an ABSENT
-     * key means no value is held — never infer `false`. Instead use
-     * {@link MaterialGraphClient.search} to find their materials; this describes the
-     * company, not the catalog.
-     */
+    /** "Who is this brand, and what do they claim?" — {@link brandProfile}. */
     brand(brandSlug: string, options?: BrandOptions, signal?: AbortSignal): Promise<BrandProfileResponse>;
+    /** "This maker's whole range, the way a fan deck reads" — {@link brandColourDeck}. */
+    brandColourDeck(brandSlug: string, signal?: AbortSignal): Promise<import("./fan-deck-types.js").BrandFanDeck>;
     /**
      * Upload one atomic source-material batch (POST `/api/v1/source-material`,
      * multipart). Pass a heterogeneous pile via `{ files }` (any mix of PDF,
@@ -566,14 +563,10 @@ export declare class MaterialGraphClient {
      * Poll {@link MaterialGraphClient.run} for the terminal state.
      */
     cancelRun(runId: RunId, signal?: AbortSignal): Promise<PublicRunResponse>;
-    /**
-     * Derive an "option B" scheme from a succeeded compose Run along one
-     * constraint axis (POST `/api/v1/schemes/vary`). Deterministic and
-     * synchronous — the response IS the hydrated scheme (no Run envelope), stamped
-     * with axis + source provenance whose `notes` are the variation's receipts.
-     * Requires the `mg:read` scope.
-     */
+    /** Option B from a composed Run, along one axis. See {@link varySchemeCall}. */
     varyScheme(body: VarySchemesRequest, signal?: AbortSignal): Promise<VarySchemesResponse>;
+    /** Ranked candidate pools for up to 24 slots. See {@link slotPoolsCall}. */
+    slotPools(body: SlotPoolsRequest, signal?: AbortSignal): Promise<SlotPoolsResponse>;
     /**
      * Stream ordered Run events as an async iterator (GET
      * `/api/v1/runs/{runId}/events`, SSE). Iterates until the stream ends or the

package/client.js

@@ -1,20 +1,25 @@
+import { DEFAULT_BASE_URL, MAX_BATCH_IDS } from "./client-config.js";
 import { MaterialGraphError } from "./errors.js";
 import { HttpTransport } from "./http-transport.js";
 // Aliased to `operation` — the local name every call site here already used.
-import { resolveOperation as operation } from "./operations.js";
+import { resolveOperation as operation, } from "./operations.js";
 import { cancelRun, capabilities as capabilitiesRun, createRun, drainRunEvents, getRun, getRunSchedule, getSourceMaterialBatch as getSourceMaterialBatchCall, listRuns, resumeRun, streamRunEvents, uploadSourceMaterial, } from "./runs.js";
-import { DEFAULT_BASE_URL, MAX_BATCH_IDS } from "./client-config.js";
 // Re-exported whole so `index.ts` and every existing importer keep their path.
 export * from "./client-config.js";
-import { browseQuery, createBrowseNamespace } from "./client-browse.js";
-import { suggestQuery } from "./suggest-types.js";
-import { matchStream as matchStreamCall } from "./match-stream.js";
-import { appendProjectEvent as appendProjectEventCall, createProject as createProjectCall, getProject as getProjectCall, listProjects as listProjectsCall, } from "./projects.js";
+import { browseQuery, createBrowseNamespace, } from "./client-browse.js";
+import { createExplorationNamespace, } from "./client-exploration.js";
+import { createSourceMaterialCommentsNamespace, } from "./client-source-material-comments.js";
+import { declaredFinishes, declaredProducts } from "./associations-client.js";
+import { brandColourDeck, brandProfile, listBrands } from "./brands-client.js";
 import { CodesClient } from "./codes-client.js";
 import { ColoursClient } from "./colours-client.js";
-import { resolvePhrasesRequest, searchVocabularyRequest } from "./resolve-client.js";
-import { declaredFinishes, declaredProducts } from "./associations-client.js";
+import { slotPools as slotPoolsCall, varyScheme as varySchemeCall, } from "./composition-client.js";
+import { coordinate as coordinateCall } from "./coordinate-client.js";
+import { matchStream as matchStreamCall } from "./match-stream.js";
+import { appendProjectEvent as appendProjectEventCall, createProject as createProjectCall, getProject as getProjectCall, listProjects as listProjectsCall, } from "./projects.js";
+import { resolvePhrasesRequest as resolvePhrases, searchVocabularyRequest, } from "./resolve-client.js";
 import { SCHEMA_RESOURCE_OPERATION_IDS } from "./schema-resource-types.js";
+import { suggestQuery } from "./suggest-types.js";
 /**
  * The MaterialGraph client — every lens on the graph, on one object.
  *
@@ -54,14 +59,21 @@ import { SCHEMA_RESOURCE_OPERATION_IDS } from "./schema-resource-types.js";
 export class MaterialGraphClient {
     baseUrl;
     /**
-     * THE QUESTION: "show me everything, ordered lightest / most vivid / most
-     * muted." Pure colour scalars — no query, no relevance. `browse({ sort })` is
-     * one page; `browse.pages({ sort })` walks them all, and only the walk can
-     * support a corpus claim.
+     * THE QUESTION: "show me everything in this category / this brand, in a plain
+     * order." No query, no relevance, no ranking. `browse(params)` is one page;
+     * `browse.pages(params)` walks them all.
+     *
+     * `sort` is optional (`name` A→Z by default, `recent` for newest first, plus
+     * the five colour ramps), `types`/`brands`/`corpusScope` narrow it, and
+     * `count: true` returns the total so a listing can say how many things it is
+     * listing without walking every page. `results.length` remains a PAGE.
      *
      * Instead use {@link MaterialGraphClient.byColour} for materials NEAR a colour,
      * {@link MaterialGraphClient.search} when there is anything to rank against,
      * and `colours.profiles()` for a category's palette rather than its members.
+     *
+     * @example A category listing that can state its own size
+     * const page = await client.browse({ types: "tile_surfaces", count: true });
      */
     browse;
     /**
@@ -87,6 +99,14 @@ export class MaterialGraphClient {
      * likeness, never a declared colour specification.
      */
     colours;
+    /** Discover honest graph questions, then traverse one explicit operator. */
+    exploration;
+    /**
+     * THE QUESTION: "what did people say about this uploaded file, and record what
+     * they said." Names on these remarks are REPORTED, never verified — see
+     * {@link SourceMaterialCommentsNamespace}.
+     */
+    sourceMaterialComments;
     #transport;
     constructor(options) {
         if (!options.apiKey) {
@@ -107,15 +127,24 @@ export class MaterialGraphClient {
             get: (operationId, query, signal) => this.#get(operationId, query, signal),
             post: (operationId, body, signal) => this.#post(operationId, body, signal),
         });
+        this.exploration = createExplorationNamespace(this.#transport);
+        this.sourceMaterialComments = createSourceMaterialCommentsNamespace(this.#transport);
     }
     get lastRateLimit() {
         return this.#transport.lastRateLimit;
     }
     #get(operationId, query, signal, pathParams) {
-        return this.#transport.requestJson(operation(operationId), { query, signal, pathParams });
+        return this.#transport.requestJson(operation(operationId), {
+            query,
+            signal,
+            pathParams,
+        });
     }
     #post(operationId, body, signal) {
-        return this.#transport.requestJson(operation(operationId), { body, signal });
+        return this.#transport.requestJson(operation(operationId), {
+            body,
+            signal,
+        });
     }
     /**
      * THE QUESTION: "find me materials like this" — a RANKED answer over words, a
@@ -202,8 +231,7 @@ export class MaterialGraphClient {
      * {@link MaterialGraphClient.browse} to walk by lightness/vividness, and
      * {@link MaterialGraphClient.search} when colour is one signal among many.
      * Report matches as visual likeness, never a stated colour specification.
-     * `family` gates the answer to ONE colorscope colour family when nearness
-     * alone crosses a hue boundary; a gated page can be shorter than `limit`.
+     * `family` gates to ONE colorscope family (a gated page can be short); `brand` gates to named brands — one brand's nearest colour to another's.
      */
     byColour(params, signal) {
         return this.#get("search_by_colour", {
@@ -213,6 +241,7 @@ export class MaterialGraphClient {
             a: params.a,
             b: params.b,
             category: params.category,
+            brand: params.brand,
             family: params.family,
             limit: params.limit,
         }, signal);
@@ -307,7 +336,11 @@ export class MaterialGraphClient {
         if (ids.length > MAX_BATCH_IDS) {
             throw MaterialGraphError.unexpected(`MaterialGraphClient.materials(): at most ${MAX_BATCH_IDS} ids per call, received ${ids.length}. Split into multiple batches.`);
         }
-        return this.#post("get_materials_batch_post", { ids, view: options?.view ?? "tile", idKind: options?.idKind ?? "variantId" }, signal);
+        return this.#post("get_materials_batch_post", {
+            ids,
+            view: options?.view ?? "tile",
+            idKind: options?.idKind ?? "variantId",
+        }, signal);
     }
     materialsCached(ids, options, signal) {
         if (ids.length > MAX_BATCH_IDS) {
@@ -388,38 +421,38 @@ export class MaterialGraphClient {
     searchVocabulary(query, options, signal) {
         return searchVocabularyRequest(this.#transport, query, options, signal);
     }
-    /** "I have words — what do they mean in YOUR vocabulary?" — see {@link resolvePhrasesRequest}. */
-    resolve(phrases, signal) {
-        return resolvePhrasesRequest(this.#transport, phrases, signal);
+    /** "I have words — what do they mean, and what stands behind them?" — see {@link resolvePhrases}. */
+    resolve(phrases, scope) {
+        return resolvePhrases(this.#transport, phrases, scope);
     }
     /**
      * THE QUESTION: "which materials, from ANYONE, are ASTM E84 Class A AND
-     * GREENGUARD-certified?" — hard specifications, no ranking, every brand at once
-     * whatever each called the value in source.
+     * GREENGUARD-certified?" — hard specifications, no ranking, every brand at
+     * once whatever each called the value in source. The value-anchored,
+     * spec-only primitive (GET `/api/v1/search/specifications`).
      *
      * Instead use `search({ filters })` when the spec merely GATES a ranked
      * question, `codes.advisory()` when the real question is what a space demands,
-     * and {@link MaterialGraphClient.specificationFacets} first if you do not know
-     * the canonical tokens. Guessing one no longer returns a silently empty
-     * answer: an unresolvable criterion means the query NEVER RAN, and the
-     * response says so — read {@link BySpecResponse.unresolvedCriteria} before
-     * treating an empty `matches` as "nothing qualifies".
-     *
-     * A PAGE, NOT A CORPUS, unusually so: `totalMatches` is the size of the
-     * returned sample under `limit`, not a corpus count. See {@link BySpecResponse}.
-     *
-     * Find materials by canonical specification across every brand — the
-     * value-anchored, spec-only primitive (GET `/api/v1/search/specifications`).
-     * Each `spec` is an `attribute:value` criterion; a variant must satisfy ALL of
-     * them, and each match carries per-criterion trust (`confidence` +
-     * `sourceBasis`). Answers "which materials, from anyone, are ASTM E84 Class A
-     * AND GREENGUARD-certified?" Build the strings with `specCriterion` /
-     * `certificationProgrammeCriterion` (e.g.
-     * `certificationProgrammeCriterion("GREENGUARD Gold")`); discover the queryable
-     * vocabulary with {@link specificationFacets} and {@link attributeValues}.
+     * and {@link specificationFacets} first if you do not know the canonical
+     * tokens. Guessing one no longer returns a silently empty answer: an
+     * unresolvable criterion means the query NEVER RAN and the response says so —
+     * read {@link BySpecResponse.unresolvedCriteria} before treating an empty
+     * `matches` as "nothing qualifies". A PAGE, NOT A CORPUS, unusually so:
+     * `totalMatches` is the returned sample's size under `limit`, not a corpus
+     * count. Each `spec` is an `attribute:value` criterion built with
+     * `specCriterion` / `certificationProgrammeCriterion`; a variant must satisfy
+     * ALL of them, and each match carries per-criterion trust (`confidence` +
+     * `sourceBasis`). NUMBER-valued specs take BOUNDS, not values — pass
+     * `options.ranges` built with `specRangeCriterion("light_reflectance_value",
+     * { min: 60 })`; bounds are inclusive, at least one is required, and a
+     * non-numeric stored value is excluded rather than read as zero.
      */
     bySpec(spec, options, signal) {
-        return this.#get("catalog_by_spec", { spec: Array.isArray(spec) ? spec : [spec], limit: options?.limit }, signal);
+        return this.#get("catalog_by_spec", {
+            spec: Array.isArray(spec) ? spec : [spec],
+            ...(options?.ranges?.length ? { specRange: options.ranges } : {}),
+            limit: options?.limit,
+        }, signal);
     }
     // ── Taxonomy + meta ──────────────────────────────────────────────────────────
     /**
@@ -440,19 +473,9 @@ export class MaterialGraphClient {
         return this.#get("whoami", undefined, signal);
     }
     // ── Pairings / demand ────────────────────────────────────────────────────────
-    /**
-     * THE QUESTION: "here is my whole scheme so far — what completes it?" The
-     * multi-seed form of {@link MaterialGraphClient.pairings}: lift is summed across
-     * seeds, so a companion suiting one pick ranks below one suiting several.
-     * Instead use `pairings` for a single material and `colours.palette()` when the
-     * scheme is COLOURS rather than materials. Check `unresolved` before presenting.
-     *
-     * Coordinate a palette of already-chosen materials (POST
-     * `/api/v1/pairings/coordinate`). Returns demand-lift-ranked companions with
-     * colour swatches and an annotate-only `colourFit` (never reorders in v1).
-     */
+    /** What completes a scheme already part-chosen. See {@link coordinateCall}. */
     coordinate(input, signal) {
-        return this.#post("coordinate_materials", input, signal);
+        return coordinateCall(this.#transport, input, signal);
     }
     /**
      * THE QUESTION: "how much is this material actually specified, and what gets
@@ -575,26 +598,17 @@ export class MaterialGraphClient {
         return this.#get("explain_material_term", undefined, signal, { term });
     }
     // ── Brands ───────────────────────────────────────────────────────────────────
-    /**
-     * THE QUESTION: "whose catalogs are in here, and how big is each?" The SDK's
-     * one OFFSET-paginated surface: read `meta.total` for the collection size and
-     * `meta.hasMore` to keep walking. Instead use {@link MaterialGraphClient.brand}
-     * for one brand's profile and trade signals.
-     */
+    /** "Whose catalogs are in here, and how big is each?" — {@link listBrands}. */
     brands(options = {}, signal) {
-        return this.#get("list_brands", { q: options.q, limit: options.limit, offset: options.offset }, signal);
+        return listBrands(this.#transport, options, signal);
     }
-    /**
-     * THE QUESTION: "who is this brand, and what do they claim?" — profile plus the
-     * trade/spec signals ON RECORD. `trade` is keyed by attribute id and an ABSENT
-     * key means no value is held — never infer `false`. Instead use
-     * {@link MaterialGraphClient.search} to find their materials; this describes the
-     * company, not the catalog.
-     */
+    /** "Who is this brand, and what do they claim?" — {@link brandProfile}. */
     brand(brandSlug, options, signal) {
-        return this.#get("get_brand_profile", { q: options?.q }, signal, {
-            brandSlug,
-        });
+        return brandProfile(this.#transport, brandSlug, options, signal);
+    }
+    /** "This maker's whole range, the way a fan deck reads" — {@link brandColourDeck}. */
+    brandColourDeck(brandSlug, signal) {
+        return brandColourDeck(this.#transport, brandSlug, signal);
     }
     // ── Runs (the hosted agentic surface) ────────────────────────────────────────
     /**
@@ -687,15 +701,13 @@ export class MaterialGraphClient {
     cancelRun(runId, signal) {
         return cancelRun(this.#transport, runId, signal);
     }
-    /**
-     * Derive an "option B" scheme from a succeeded compose Run along one
-     * constraint axis (POST `/api/v1/schemes/vary`). Deterministic and
-     * synchronous — the response IS the hydrated scheme (no Run envelope), stamped
-     * with axis + source provenance whose `notes` are the variation's receipts.
-     * Requires the `mg:read` scope.
-     */
+    /** Option B from a composed Run, along one axis. See {@link varySchemeCall}. */
     varyScheme(body, signal) {
-        return this.#post("vary_schemes", body, signal);
+        return varySchemeCall(this.#transport, body, signal);
+    }
+    /** Ranked candidate pools for up to 24 slots. See {@link slotPoolsCall}. */
+    slotPools(body, signal) {
+        return slotPoolsCall(this.#transport, body, signal);
     }
     /**
      * Stream ordered Run events as an async iterator (GET

package/colour-aggregate-types.d.ts

@@ -88,6 +88,43 @@ export interface ColourStatsGroup {
     productTypes: number;
     variants: number;
 }
+/**
+ * One cell of the brand x category x colour-family matrix — the shape that
+ * answers questions no single dimension can, such as "how many whites does
+ * Benjamin Moore offer in paint".
+ */
+export interface ColourStatsRow {
+    /** Opaque brand id — the join key for brand reads. Never parse it. */
+    brandId: string;
+    brandSlug: string;
+    brandName: string;
+    /**
+     * Product-type key. NULL means these variants carry NO accepted primary
+     * product type — a real population, kept so the matrix sums to the corpus,
+     * not an error and not a residual bucket.
+     */
+    categoryKey: string | null;
+    family: string;
+    /**
+     * Distinct variants at this (brand, category, family) carrying an ACCEPTED
+     * `colour_family`. Not every variant of the brand.
+     */
+    variants: number;
+}
+/** How to narrow the matrix. Passing ANY of these asks for `rows`. */
+export interface ColourStatsParams {
+    /** `"brand,category"` — ask for the whole matrix, unscoped. */
+    groupBy?: string;
+    brandId?: string;
+    brandSlug?: string;
+    /**
+     * A product-type key, or the literal `"null"` for the unclassified
+     * population. Omitting it means every category — a different question.
+     */
+    categoryKey?: string;
+    family?: string;
+    limit?: number;
+}
 /** Where each section came from, how fresh it is, and what it does NOT answer. */
 export interface ColourStatsBasis {
     corpus: string;
@@ -95,11 +132,32 @@ export interface ColourStatsBasis {
     groups: string;
     groupsRefreshedAt: string | null;
     groupsVariantCount: number;
+    /**
+     * Where `rows` came from, its freshness, and what it EXCLUDES — present only
+     * when `rows` is. Read it: the matrix deliberately omits Samplize, which is a
+     * sampling channel printing other manufacturers' colours rather than a maker.
+     */
+    rows?: string;
     omissions: string[];
 }
 export interface ColourStatsResponse {
     corpus: ColourStatsCorpus;
     families: ColourStatsFamily[];
     groups: ColourStatsGroup[];
+    /**
+     * The brand x category x colour-family matrix. Present ONLY when you asked
+     * for it; ABSENT means nobody asked, never that the matrix is empty.
+     *
+     * `families` above is NOT scoped by the same parameters and stays
+     * platform-wide under all of them. Scoped counts live here.
+     */
+    rows?: ColourStatsRow[];
+    /**
+     * Rows matching your query BEFORE the response cap — the honest total.
+     * A shortfall against `rows.length` means `rows` is a prefix.
+     */
+    rowsMatched?: number;
+    /** TRUE when the matrix exceeded the cap and `rows` is a prefix. */
+    rowsTruncated?: boolean;
     basis: ColourStatsBasis;
 }

package/colours-client.d.ts

@@ -32,7 +32,7 @@
  * FROM PRODUCT IMAGERY, not declared by the manufacturer. Report visual
  * likeness, never a stated colour specification.
  */
-import type { CategoryColourProfilesResponse, ColourProfilesParams, ColourStatsResponse } from "./colour-aggregate-types.js";
+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 { SearchGradientInput, SearchGradientResponse, SearchPaletteInput, SearchPaletteResponse } from "./palette-search-types.js";
@@ -87,8 +87,14 @@ export declare class ColoursClient {
      * coverage per product-type group. `basis` states the source and freshness of
      * each section plus `basis.omissions` — what this call deliberately does not
      * answer, listed rather than silently absent.
+     *
+     * Pass `{ groupBy: "brand,category" }` for the whole brand x category x
+     * family matrix in one call, or a `brandSlug`/`categoryKey` scope for a slice
+     * of it — either way it arrives as `rows`, each row carrying `brandId` and
+     * `brandSlug` to join on. Without any of those parameters the payload is the
+     * platform-wide one and `rows` is absent. `families` is never scoped by them.
      */
-    stats(signal?: AbortSignal): Promise<ColourStatsResponse>;
+    stats(params?: ColourStatsParams, signal?: AbortSignal): Promise<ColourStatsResponse>;
     /**
      * THE QUESTION: "what goes with this WHOLE PALETTE?" — N colours at once, at
      * stated proportions, not one colour repeated (POST `/api/v1/search/palettes`).

package/colours-client.js

@@ -53,9 +53,22 @@ export class ColoursClient {
      * coverage per product-type group. `basis` states the source and freshness of
      * each section plus `basis.omissions` — what this call deliberately does not
      * answer, listed rather than silently absent.
+     *
+     * Pass `{ groupBy: "brand,category" }` for the whole brand x category x
+     * family matrix in one call, or a `brandSlug`/`categoryKey` scope for a slice
+     * of it — either way it arrives as `rows`, each row carrying `brandId` and
+     * `brandSlug` to join on. Without any of those parameters the payload is the
+     * platform-wide one and `rows` is absent. `families` is never scoped by them.
      */
-    stats(signal) {
-        return this.#transport.get("get_colour_stats", undefined, signal);
+    stats(params = {}, signal) {
+        return this.#transport.get("get_colour_stats", {
+            groupBy: params.groupBy,
+            brandId: params.brandId,
+            brandSlug: params.brandSlug,
+            categoryKey: params.categoryKey,
+            family: params.family,
+            limit: params.limit,
+        }, signal);
     }
     /**
      * THE QUESTION: "what goes with this WHOLE PALETTE?" — N colours at once, at