@instruments/materialgraph 0.25.0 → 0.27.0

package/client.js

@@ -1,28 +1,25 @@
-import { CatalogueClient } from "./catalogue-client.js";
-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 { cancelRun, capabilities as capabilitiesRun, createRun, drainRunEvents, getRun, getRunSchedule, getSourceMaterialBatch as getSourceMaterialBatchCall, listRuns, resumeRun, streamRunEvents, uploadSourceMaterial, } from "./runs.js";
-import { ScheduleReferencesClient } from "./schedule-references-client.js";
-// Re-exported whole so `index.ts` and every existing importer keep their path.
-export * from "./client-config.js";
-import { browseQuery, createBrowseNamespace, } from "./client-browse.js";
-import { createExplorationNamespace, } from "./client-exploration.js";
-import { createSourceMaterialCommentsNamespace, } from "./client-source-material-comments.js";
 import * as assoc from "./associations-client.js";
-import { brandColourDeck, brandProfile, listBrands } from "./brands-client.js";
-import { colourFacets as colourFacetsCall, resolveAttribute as resolveAttributeCall, resolveAttributeValue as resolveAttributeValueCall, resolveColour as resolveColourCall, suggest as suggestCall, suggestColour as suggestColourCall, } from "./client-vocabulary.js";
+import { listBrands } from "./brands-client.js";
+import { CatalogueClient } from "./catalogue-client.js";
+import { CategoriesClient } from "./categories-client.js";
+import { DEFAULT_BASE_URL } from "./client-config.js";
+import { createSourceMaterialCommentsNamespace } from "./client-source-material-comments.js";
+import { listAttributes as listAttributesCall, resolveColour as resolveColourCall, suggest as suggestCall, suggestColour as suggestColourCall, } from "./client-vocabulary.js";
 import { CodesClient } from "./codes-client.js";
 import { ColoursClient } from "./colours-client.js";
-import { slotPools as slotPoolsCall, varyScheme as varySchemeCall, } from "./composition-client.js";
 import { coordinate as coordinateCall } from "./coordinate-client.js";
+import { MaterialGraphError } from "./errors.js";
+import { HttpTransport } from "./http-transport.js";
 import { matchStream as matchStreamCall } from "./match-stream.js";
-import { materialAssets as materialAssetsCall, materialRenderAssets as materialRenderAssetsCall, materialBlocks as materialBlocksCall, materialDocuments as materialDocumentsCall, } from "./material-resources-client.js";
-import { appendProjectEvent as appendProjectEventCall, createProject as createProjectCall, getProject as getProjectCall, listProjects as listProjectsCall, } from "./projects.js";
+import { compositionReport as compositionReportCall } from "./material-composition-client.js";
+import { listVariantAssets as listVariantAssetsCall, materialBlocks as materialBlocksCall, materialDocuments as materialDocumentsCall, } from "./material-resources-client.js";
+// Aliased to `operation` — the local name every call site here already used.
+import { resolveOperation as operation } from "./operations.js";
 import { resolvePhrasesRequest as resolvePhrases, searchVocabularyRequest, } from "./resolve-client.js";
+import { createRun, drainRunEvents, getRun, getSourceMaterialBatch as getSourceMaterialBatchCall, streamRunEvents, uploadSourceMaterial, } from "./runs.js";
 import { SCHEMA_RESOURCE_OPERATION_IDS } from "./schema-resource-types.js";
+// Re-exported whole so `index.ts` and every existing importer keep their path.
+export * from "./client-config.js";
 /**
  * The MaterialGraph client — every lens on the graph, on one object.
  *
@@ -33,13 +30,13 @@ import { SCHEMA_RESOURCE_OPERATION_IDS } from "./schema-resource-types.js";
  * | --- | --- |
  * | "find me something like this / matching these words" | {@link MaterialGraphClient.search} |
  * | "what's IN this photo?" | {@link MaterialGraphClient.match} / {@link MaterialGraphClient.matchStream} |
- * | "which materials, from anyone, meet this hard spec?" | {@link MaterialGraphClient.bySpec} |
+ * | "which materials, from anyone, meet this hard spec?" | {@link MaterialGraphClient.listVariants} |
  * | "what's near this colour / this palette / this gradient?" | {@link MaterialGraphClient.byColour}, `colours.palette()`, `colours.gradient()` |
- * | "what goes with THIS material?" | {@link MaterialGraphClient.pairings}, {@link MaterialGraphClient.siblings}, {@link MaterialGraphClient.coordinate} |
+ * | "what goes with THIS material?" | {@link MaterialGraphClient.pairings}, {@link MaterialGraphClient.listVariants} (same product, other colourways), {@link MaterialGraphClient.coordinate} |
  * | "what does the manufacturer say is AVAILABLE on this?" | {@link MaterialGraphClient.associatedFinishes}, {@link MaterialGraphClient.associatedProducts} |
  * | "how much is this specified?" | {@link MaterialGraphClient.demand}, {@link MaterialGraphClient.demandBatch} |
  * | "is this allowed in an A-2 corridor?" | `codes.*` |
- * | "what can I even ask for?" | {@link MaterialGraphClient.specificationFacets}, {@link MaterialGraphClient.attributeValues}, {@link MaterialGraphClient.taxonomy}, {@link MaterialGraphClient.colourFacets}, {@link MaterialGraphClient.glossary} |
+ * | "what can I even ask for?" | {@link MaterialGraphClient.specificationFacets}, `categories.list()` |
  * | "I have words — what do they mean in YOUR vocabulary?" | {@link MaterialGraphClient.resolve} |
  * | "do the whole job for me, async" | {@link MaterialGraphClient.createRun} + `mg:compose` |
  *
@@ -59,33 +56,28 @@ import { SCHEMA_RESOURCE_OPERATION_IDS } from "./schema-resource-types.js";
  * `./identifiers.ts`), absent is not false, and a page is not a corpus.
  */
 export class MaterialGraphClient extends CatalogueClient {
-    scheduleReferences;
     baseUrl;
     /**
-     * THE QUESTION: "show me everything in this category / this brand, in a plain
-     * 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.
+     * THE QUESTION: "what kinds of thing exist, and what are their keys?"
+     * `categories.list()` pages the tree (roots, one node's children, or a
+     * name/meaning search), and `categories.get(id)` reads one node in full:
+     * its place, the names that find it, and the canonical taxonomy concepts it
+     * relates to. The source of every category id the other lenses accept
+     * (`search({ category })`, `listVariants({ filters })`, `colours.profiles()`).
      *
-     * @example A category listing that can state its own size
-     * const page = await client.browse({ types: "tile_surfaces", count: true });
+     * A category id is a TREE KEY, never a canonical `product_category` value:
+     * the two look alike and are not interchangeable. Discover ids here, never
+     * hand-write them. Replaces the retired `taxonomy()` (MG-2226), with no
+     * shim.
      */
-    browse;
+    categories;
     /**
      * THE QUESTION: "is this material allowed HERE?" — a jurisdiction + occupancy +
      * finish location, not a property of the material alone. `codes.context()`
      * discovers the vocabulary, `codes.requirements()` states a space,
      * `codes.advisory()` badges candidates.
      *
-     * Instead use {@link MaterialGraphClient.bySpec} to find materials by a
+     * Instead use {@link MaterialGraphClient.listVariants} to find materials by a
      * classification you already know you need; codes is what tells you WHICH one
      * the space demands. ADVISORY ONLY: model code as adopted, never a
      * determination for an authority having jurisdiction.
@@ -95,15 +87,14 @@ export class MaterialGraphClient extends CatalogueClient {
      * THE QUESTION: "what colours exist here?" (`profiles`, `stats`) and "what
      * matches this whole SET of colours?" (`palette`, `gradient`).
      *
-     * Instead use {@link MaterialGraphClient.byColour} for ONE colour,
-     * {@link MaterialGraphClient.browse} to walk by a colour scalar, and
-     * {@link MaterialGraphClient.colourFacets} for the colour VOCABULARY rather
-     * than values. Colour throughout is derived from product imagery — visual
-     * likeness, never a declared colour specification.
+     * Instead use {@link MaterialGraphClient.byColour} for ONE colour and
+     * {@link MaterialGraphClient.listVariants} to page through a colour's family.
+     * Colour is usually derived from product imagery, which is visual likeness,
+     * not a colour specification. A maker's declared colour, such as a paint's
+     * published hex, wins where MaterialGraph holds one, and each value's
+     * source basis says which.
      */
     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
@@ -123,66 +114,45 @@ export class MaterialGraphClient extends CatalogueClient {
         super(transport);
         this.#transport = transport;
         this.baseUrl = transport.baseUrl;
-        this.scheduleReferences = new ScheduleReferencesClient(transport);
-        this.browse = createBrowseNamespace((params, signal) => this.#get("search_browse_by_colour", browseQuery(params), signal));
+        this.categories = new CategoriesClient({
+            get: async (operationId, query, signal, pathParams) => await this.#get(operationId, query, signal, pathParams),
+        });
         this.codes = new CodesClient({
-            get: (operationId, query, signal) => this.#get(operationId, query, signal),
-            post: (operationId, body, signal) => this.#post(operationId, body, signal),
+            get: async (operationId, query, signal) => await this.#get(operationId, query, signal),
+            post: async (operationId, body, signal) => await this.#post(operationId, body, signal),
         });
         this.colours = new ColoursClient({
-            get: (operationId, query, signal) => this.#get(operationId, query, signal),
-            post: (operationId, body, signal) => this.#post(operationId, body, signal),
+            get: async (operationId, query, signal) => await this.#get(operationId, query, signal),
+            post: async (operationId, body, signal) => await 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), {
+    async #get(operationId, query, signal, pathParams) {
+        return await this.#transport.requestJson(operation(operationId), {
+            pathParams,
             query,
             signal,
-            pathParams,
         });
     }
-    #post(operationId, body, signal, pathParams) {
-        return this.#transport.requestJson(operation(operationId), {
+    async #post(operationId, body, signal, pathParams) {
+        return await this.#transport.requestJson(operation(operationId), {
             body,
-            signal,
             pathParams,
+            signal,
         });
     }
-    /**
-     * THE QUESTION: "find me materials like this" — a RANKED answer over words, a
-     * seed image, colours and a mood, optionally gated by hard specs.
-     *
-     * Instead use {@link MaterialGraphClient.bySpec} when the spec IS the question
-     * (ranking would be noise), {@link MaterialGraphClient.byColour} /
-     * `colours.palette()` for visual colour intent (`text` matches WORDS — "sage
-     * green" finds materials that SAY sage, not ones that look it),
-     * {@link MaterialGraphClient.match} for a photo, {@link MaterialGraphClient.pairings}
-     * for what goes WITH something, {@link MaterialGraphClient.suggest} for typeahead.
-     *
-     * The full POST search primitive. `input.filters` layers typed hard
-     * specification gates onto ranked colour/visual/lexical/seed search. Build
-     * them with `certificationProgramme`, `specTerm`, or `hasSpec`.
-     */
-    search(input, signal) {
-        return this.#post("search_materials_post", input, signal);
+    async search(input, signal) {
+        return await this.#post("search_materials_post", input, signal);
     }
     /** Whole materials ask → inspectable meanings and complete safe search requests. */
-    planQuery(query, signal) {
-        return this.#post("plan_material_query", { query }, signal);
+    async planQuery(query, signal) {
+        return await this.#post("plan_material_query", { query }, signal);
     }
-    /**
-     * The same question as {@link MaterialGraphClient.search}; the difference is
-     * transport — a cacheable, link-shareable GET for queries that must survive in
-     * a URL. `filters`, `preferences`, `verdicts`, image bytes and `weights` have
-     * no query-string form, so anything using those must go through `search`.
-     */
-    searchGet(params, signal) {
-        return this.#get("search_materials_get", { ...params }, signal);
+    async searchGet(params, signal) {
+        return await this.#get("search_materials_get", { ...params }, signal);
     }
     /**
      * THE QUESTION: "what materials are in this PHOTO?" — Material Match classifies
@@ -197,8 +167,8 @@ export class MaterialGraphClient extends CatalogueClient {
      * `droppedBelowFloor` before reporting an empty result: "nothing was good
      * enough" and "nothing was found" are different answers.
      */
-    match(input, signal) {
-        return this.#post("match_material", input, signal);
+    async match(input, signal) {
+        return await this.#post("match_material", input, signal);
     }
     /**
      * Material Match as a PROGRESSIVE stream — the same POST
@@ -233,26 +203,27 @@ export class MaterialGraphClient extends CatalogueClient {
      * Instead use `colours.palette()` for N colours at stated proportions (a
      * different ranking, not a wrapper), `colours.gradient()` for a transition,
      * {@link MaterialGraphClient.resolveColour} first if you hold a NAME,
-     * {@link MaterialGraphClient.browse} to walk by lightness/vividness, and
+     * {@link MaterialGraphClient.listVariants} to page through a category or a brand, and
      * {@link MaterialGraphClient.search} when colour is one signal among many.
      * Report matches as visual likeness, never a stated colour specification.
      * `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", {
-            q: params.q,
-            hex: params.hex,
-            colour: params.colour,
-            l: params.l,
+    async byColour(params, signal) {
+        return await this.#get("search_by_colour", {
             a: params.a,
             b: params.b,
-            category: params.category,
             brand: params.brand,
-            family: params.family,
-            order: params.order,
-            maxColourDistance: params.maxColourDistance,
+            category: params.category,
+            colour: params.colour,
             corpusScope: params.corpusScope,
+            family: params.family,
+            hex: params.hex,
+            l: params.l,
             limit: params.limit,
+            maxColourDistance: params.maxColourDistance,
+            order: params.order,
+            q: params.q,
+            variantId: params.variantId,
         }, signal);
     }
     // ── Materials ──────────────────────────────────────────────────────────────
@@ -261,195 +232,185 @@ export class MaterialGraphClient extends CatalogueClient {
      * `/api/v1/materials/{variantId}`).
      *
      * The hinge of the API: every relationship lens
-     * ({@link MaterialGraphClient.siblings}, {@link MaterialGraphClient.pairings},
+     * ({@link MaterialGraphClient.listVariants}, {@link MaterialGraphClient.pairings},
      * {@link MaterialGraphClient.demand}, `codes.advisory()`) hangs off a
-     * `variantId`. Instead use {@link MaterialGraphClient.materials} for many ids,
-     * {@link MaterialGraphClient.materialBlocks} to tell "no value" from "not
-     * checked", {@link MaterialGraphClient.search} when you have no id yet.
+     * `variantId`. Instead use {@link MaterialGraphClient.listVariants} for many
+     * ids, or for the other colourways of the same product (MG-2222 retired
+     * this route's `?include=siblings`; ask `listVariants` with a `product in`
+     * filter instead), {@link MaterialGraphClient.materialBlocks} to tell "no
+     * value" from "not checked", {@link MaterialGraphClient.search} when you
+     * have no id yet.
      *
      * @param variantId Opaque — pass back exactly what you were given.
      */
-    material(variantId, options, signal) {
-        return this.#get("get_material", options?.includeSiblings ? { include: "siblings" } : undefined, signal, { variantId });
+    async material(variantId, signal) {
+        return await this.#get("get_material", undefined, signal, { variantId });
+    }
+    async materialBlocks(variantId, signal) {
+        return await materialBlocksCall(this.#transport, variantId, signal);
     }
     /**
-     * THE QUESTION: "what other colourways and finishes does this product come in?"
-     * — the SAME product, different variants.
+     * THE QUESTION: "which product types can composition be answered for yet?"
      *
-     * Instead use {@link MaterialGraphClient.pairings} for a DIFFERENT product that
-     * goes with this one, and `search({ similarTo })` for one that LOOKS like it.
+     * Coverage per product type, in Live SKUs as well as tuples. Read the SKU
+     * figure: one tuple can carry a hundred thousand SKUs or one.
      */
-    siblings(variantId, signal) {
-        return this.#get("get_material_siblings", undefined, signal, { variantId });
+    async compositionReport(signal) {
+        return await compositionReportCall(this.#transport, signal);
     }
-    materialBlocks(variantId, signal) {
-        return materialBlocksCall(this.#transport, variantId, signal);
+    async listVariantAssets(variantId, options, signal) {
+        return await listVariantAssetsCall(this.#transport, variantId, options, signal);
     }
-    materialAssets(variantId, signal) {
-        return materialAssetsCall(this.#transport, variantId, signal);
-    }
-    materialRenderAssets(variantId, signal) {
-        return materialRenderAssetsCall(this.#transport, variantId, signal);
-    }
-    materialDocuments(variantId, options, signal) {
-        return materialDocumentsCall(this.#transport, variantId, options, signal);
+    async materialDocuments(variantId, options, signal) {
+        return await materialDocumentsCall(this.#transport, variantId, options, signal);
     }
     /**
      * THE QUESTION: "what does the schema DEFINE?" — the governed static registry.
      *
      * Definitions, not data: use {@link MaterialGraphClient.specificationFacets} for
-     * what the corpus actually holds and {@link MaterialGraphClient.glossary} to
-     * explain one term.
+     * what the corpus actually holds.
      */
-    schema(resource, signal) {
-        return this.#get(SCHEMA_RESOURCE_OPERATION_IDS[resource], undefined, signal);
+    async schema(resource, signal) {
+        return await this.#get(SCHEMA_RESOURCE_OPERATION_IDS[resource], undefined, signal);
     }
     /**
      * THE QUESTION: "what goes WITH this material?" — the companionship rail, hung
      * off one resolved material (GET `/api/v1/materials/{variantId}/pairings`).
      *
      * Instead use {@link MaterialGraphClient.coordinate} for a whole palette of
-     * picks, {@link MaterialGraphClient.siblings} for the same product in another
-     * colour, and `search({ similarTo })` for a LIKE-THIS substitute — similar and
-     * complementary are opposite questions.
+     * picks, {@link MaterialGraphClient.listVariants} for the same product in
+     * another colour, and `search({ similarTo })` for a LIKE-THIS substitute —
+     * similar and complementary are opposite questions.
      *
      * READ `item.source` BEFORE PHRASING: the rail mixes three tiers of evidence —
      * `cospec` (real orders), `considered` (board activity), `colour` (palette
      * look-alike). Only `cospec` supports "sampled together". `cospecCount` tells
      * you how much of the rail is real order evidence.
      */
-    pairings(variantId, options, signal) {
-        return this.#get("get_material_pairings", { ...options }, signal, {
+    async pairings(variantId, options, signal) {
+        return await this.#get("get_material_pairings", { ...options }, signal, {
             variantId,
         });
     }
-    /** Find bounded, exact-spec substitutes for one opaque variant id. */
-    findSubstitutes(variantId, options = {}, signal) {
-        return this.#post("find_material_substitutes", options, signal, { variantId });
-    }
     /** "What finishes does the manufacturer declare for THIS product?" — {@link declaredFinishes}. */
-    associatedFinishes(variantId, options, signal) {
-        return assoc.declaredFinishes(this.#transport, variantId, options, signal);
+    async associatedFinishes(variantId, options, signal) {
+        return await assoc.declaredFinishes(this.#transport, variantId, options, signal);
     }
     /** "What products does the manufacturer declare THIS finish for?" — {@link declaredProducts}. */
-    associatedProducts(variantId, options, signal) {
-        return assoc.declaredProducts(this.#transport, variantId, options, signal);
-    }
-    applicability(options, signal) {
-        return assoc.applicability(this.#transport, options, signal);
-    }
-    materials(ids, options, signal) {
-        if (ids.length > MAX_BATCH_IDS) {
-            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);
-    }
-    materialsCached(ids, options, signal) {
-        if (ids.length > MAX_BATCH_IDS) {
-            throw MaterialGraphError.unexpected(`MaterialGraphClient.materialsCached(): at most ${MAX_BATCH_IDS} ids per call, received ${ids.length}. Split into multiple batches.`);
-        }
-        return this.#get("get_materials_batch_get", {
-            ids: ids.join(","),
-            view: options?.view ?? "tile",
-            idKind: options?.idKind ?? "variantId",
+    async associatedProducts(variantId, options, signal) {
+        return await assoc.declaredProducts(this.#transport, variantId, options, signal);
+    }
+    async applicability(options, signal) {
+        return await assoc.applicability(this.#transport, options, signal);
+    }
+    /**
+     * THE QUESTION: "eligible variants matching these hard filters, ranked and
+     * cursor-paged" (GET `/api/v1/variants`, MG-2222) — the one read behind
+     * `list_variants`, hydrating ids you already hold (`{terms: [{field:
+     * "variant", op: "in", values: [...]}]}`, up to 100), the other colourways
+     * of a product (`{terms: [{field: "product", op: "in", values:
+     * [productId]}, {field: "variant", op: "not_in", values: [variantId]}]}` —
+     * `filters` is kind-grouped, `{terms, numbers, presence}`, every condition
+     * across all three ANDed), or a category/maker listing. An explicit
+     * `variant in` id that does not resolve to an eligible variant is
+     * reported in `unresolvedVariantIds`, never silently dropped from the
+     * page.
+     *
+     * `filters`/`optionalFilters`/`orderBy` are sent as URL-encoded JSON;
+     * `attributes`/`include` as comma-separated lists — the server validates,
+     * this method does not duplicate that check.
+     */
+    async listVariants(input, signal) {
+        return await this.#get("list_variants", {
+            attributes: input.attributes?.length
+                ? input.attributes.join(",")
+                : undefined,
+            cursor: input.cursor,
+            filters: input.filters ? JSON.stringify(input.filters) : undefined,
+            include: input.include?.length ? input.include.join(",") : undefined,
+            limit: input.limit,
+            name: input.name,
+            optionalFilters: input.optionalFilters
+                ? JSON.stringify(input.optionalFilters)
+                : undefined,
+            orderBy: input.orderBy?.length
+                ? JSON.stringify(input.orderBy)
+                : undefined,
         }, signal);
     }
-    /** Vocabulary families and counts; use `colours.profiles()` for a material palette. */
-    colourFacets(signal) {
-        return colourFacetsCall(this.#transport, signal);
+    /**
+     * THE QUESTION: "which values do the variants matching these filters carry,
+     * and how many of each" (POST `/api/v1/variants/facets`, MG-2294) — the
+     * options and counts a filter UI shows beside a {@link
+     * MaterialGraphClient.listVariants} page. `filters` is the same tree
+     * `listVariants()` takes; the server validates both.
+     */
+    async listVariantFacets(input, signal) {
+        return await this.#post("list_variant_facets", input, signal);
     }
     /** Resolve a colour name to its hex, and the named paint's catalogue variant. */
-    resolveColour(name, signal, options) {
-        return resolveColourCall(this.#transport, name, signal, options);
+    async resolveColour(name, signal, options) {
+        return await resolveColourCall(this.#transport, name, signal, options);
     }
     /** Ranked colour-name typeahead (GET `/api/v1/search/colours/suggest`). */
-    suggestColour(q, options, signal) {
-        return suggestColourCall(this.#transport, q, options, signal);
+    async suggestColour(q, options, signal) {
+        return await suggestColourCall(this.#transport, q, options, signal);
     }
     /** Entity typeahead. Navigate using the selected `refId`; use `search()` for materials. */
-    suggest(q, options, signal) {
-        return suggestCall(this.#transport, q, options, signal);
+    async suggest(q, options, signal) {
+        return await suggestCall(this.#transport, q, options, signal);
     }
     // ── Catalog ──────────────────────────────────────────────────────────────────
-    /** Resolve free text to a canonical attribute id. */
-    resolveAttribute(q, options, signal) {
-        return resolveAttributeCall(this.#transport, q, options, signal);
-    }
-    /** Resolve a value under a canonical attribute id; inspect `recommendedAction` for ambiguity. */
-    resolveAttributeValue(attributeId, query, options, signal) {
-        return resolveAttributeValueCall(this.#transport, attributeId, query, options, signal);
-    }
-    /** "Is this phrase an attribute or a value?" — see {@link searchVocabularyRequest}. */
-    searchVocabulary(query, options, signal) {
-        return searchVocabularyRequest(this.#transport, query, options, 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. 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 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.
+     * THE QUESTION: "which attribute means this phrase?" or "what could a
+     * <category> be specified by?" (GET `/api/v1/catalog/attributes`). One page of
+     * attribute definitions, browsed or found by id, name, misspelling or
+     * meaning, scoped by `categoryIds`, `blockIds` and `filterableOnly`. Pass an
+     * item's `id` with one of its `filterOps` to
+     * {@link MaterialGraphClient.listVariants}; follow `pageInfo.endCursor` for
+     * the next page.
      */
-    bySpec(spec, options, signal) {
-        return this.#get("catalog_by_spec", {
-            spec: Array.isArray(spec) ? spec : [spec],
-            ...(options?.ranges?.length ? { specRange: options.ranges } : {}),
-            limit: options?.limit,
-        }, signal);
+    async listAttributes(options, signal) {
+        return await listAttributesCall(this.#transport, options, signal);
     }
-    // ── Taxonomy + meta ──────────────────────────────────────────────────────────
-    /**
-     * THE QUESTION: "what kinds of thing exist, and what are their canonical keys?"
-     * The source of every `categoryKey` / product-type id the other lenses accept
-     * (`search({ category })`, `colours.profiles()`,
-     * {@link MaterialGraphClient.applicableSpecs}). Discover, never hand-write.
-     */
-    taxonomy(signal) {
-        return this.#get("get_category_taxonomy", undefined, signal);
+    /** "Is this phrase an attribute or a value?" — see {@link searchVocabularyRequest}. */
+    async searchVocabulary(query, options, signal) {
+        return await searchVocabularyRequest(this.#transport, query, options, signal);
     }
+    /** "I have words — what do they mean, and what stands behind them?" — see {@link resolvePhrases}. */
+    async resolve(phrases, scope) {
+        return await resolvePhrases(this.#transport, phrases, scope);
+    }
+    // Hard-specification search (formerly `bySpec()`, GET
+    // `/api/v1/search/specifications`) moved to {@link MaterialGraphClient.listVariants}
+    // (MG-2222): each `attribute:value` criterion is one `filters` condition —
+    // `{field: attributeId, op: "in", values: [...]}` in `filters.terms` for a
+    // term, `{field: attributeId, op: "gte"/"lte"/etc, value}` in
+    // `filters.numbers` for a number — and every condition across the
+    // kind-grouped `filters` object must match. Use `codes.advisory()` when
+    // the real question is what a space demands, and {@link specificationFacets}
+    // first if you do not know the canonical tokens.
+    // ── Coverage + meta ──────────────────────────────────────────────────────────
     /**
      * Exact current primary-type status counts by retained source category path.
      * `comparisonThreshold` is a reporting cutoff only: it never promotes a
      * proposal into an accepted category.
      */
-    productTypeCoverage(options, signal) {
-        return this.#get("get_product_type_status_coverage", options, signal);
+    async productTypeCoverage(options, signal) {
+        return await this.#get("get_product_type_status_coverage", options, signal);
     }
     /**
      * THE QUESTION: "what is this key allowed to do?" Check `scopes` before
      * offering a capability: the write surfaces need `mg:ingest` / `mg:compose`,
      * and `mg:admin` unlocks extra evidence fields.
      */
-    whoami(signal) {
-        return this.#get("whoami", undefined, signal);
+    async whoami(signal) {
+        return await this.#get("whoami", undefined, signal);
     }
     // ── Pairings / demand ────────────────────────────────────────────────────────
     /** What completes a scheme already part-chosen. See {@link coordinateCall}. */
-    coordinate(input, signal) {
-        return coordinateCall(this.#transport, input, signal);
+    async coordinate(input, signal) {
+        return await coordinateCall(this.#transport, input, signal);
     }
     /**
      * THE QUESTION: "how much is this material actually specified, and what gets
@@ -460,8 +421,8 @@ export class MaterialGraphClient extends CatalogueClient {
      * {@link MaterialGraphClient.pairings} for a presentable rail. A null `demand`
      * means UNREAD, never zero. Provide EXACTLY ONE of `variantId` or `material`.
      */
-    demand(params, signal) {
-        return this.#get("get_material_demand", { variantId: params.variantId, material: params.material }, signal);
+    async demand(params, signal) {
+        return await this.#get("get_material_demand", { material: params.material, variantId: params.variantId }, signal);
     }
     /**
      * THE QUESTION: "for each of these picks I already hold, how much momentum does
@@ -490,8 +451,8 @@ export class MaterialGraphClient extends CatalogueClient {
      *   (r) => r.state === "available" && r.momentum.state === "rising",
      * );
      */
-    demandBatch(input, signal) {
-        return this.#post("get_demand_batch", input, signal);
+    async demandBatch(input, signal) {
+        return await this.#post("get_demand_batch", input, signal);
     }
     // ── Codes (advisory building-code compliance) ────────────────────────────────
     /**
@@ -503,8 +464,8 @@ export class MaterialGraphClient extends CatalogueClient {
      * `mg.codes.advisory()` in new code, and start at `mg.codes.context()` to
      * discover every accepted context value. `unverified` is not a pass.
      */
-    codeAdvisory(input, signal) {
-        return this.codes.advisory(input, signal);
+    async codeAdvisory(input, signal) {
+        return await this.codes.advisory(input, signal);
     }
     // ── Colour helpers (extract) ─────────────────────────────────────────────────
     /**
@@ -514,16 +475,15 @@ export class MaterialGraphClient extends CatalogueClient {
      * {@link MaterialGraphClient.byColour}. Instead use
      * {@link MaterialGraphClient.match} for the MATERIALS in the photo.
      */
-    extractPalette(input, signal) {
-        return this.#post("extract_image_palette", input, signal);
+    async extractPalette(input, signal) {
+        return await this.#post("extract_image_palette", input, signal);
     }
-    // ── Catalog (facets / applicable specs / glossary) ───────────────────────────
+    // ── Catalog (facets / glossary) ─────────────────────────────────────────────
     /**
      * THE QUESTION: "what can I even filter on, and what values does the corpus
      * actually hold?" The start of every spec-driven workflow. Instead use
-     * {@link MaterialGraphClient.attributeValues} for ONE attribute's distribution,
-     * {@link MaterialGraphClient.applicableSpecs} for what a product type COULD
-     * carry, {@link MaterialGraphClient.schema} for the definition.
+     * {@link MaterialGraphClient.listAttributes} with `categoryIds` for what a
+     * product type COULD carry, {@link MaterialGraphClient.schema} for the definition.
      *
      * Discover the live specification vocabulary (GET
      * `/api/v1/catalog/specifications/facets`) — the facetable spec attributes that
@@ -532,57 +492,18 @@ export class MaterialGraphClient extends CatalogueClient {
      * exists: LEED, GREENGUARD, ASTM E84 Class A, FloorScore, EPDs all surface here
      * with counts. Includes the virtual `certification_programme` facet (its values
      * are programme names). Learn an `attribute:value` here, then reuse it as a
-     * {@link bySpec} criterion or a {@link search} `filters` entry. NOTE: continuous
+     * {@link MaterialGraphClient.listVariants} filter leaf or a {@link search}
+     * `filters` entry. NOTE: continuous
      * numeric specs (e.g. `slip_resistance_dcof`, a 0–1 DCOF range) are NOT
      * token-facetable and do not appear here — read those per-attribute.
      */
-    specificationFacets(signal) {
-        return this.#get("list_spec_facets", undefined, signal);
-    }
-    /**
-     * List the live value distribution for ONE canonical attribute (GET
-     * `/api/v1/catalog/attributes/{attributeId}/values`), ordered by cross-brand
-     * reach with variant + brand counts. The drill-in companion to
-     * {@link specificationFacets} — e.g. every certification programme on record,
-     * or every fire classification and how many variants carry each.
-     */
-    attributeValues(attributeId, signal) {
-        return this.#get("list_attribute_values", undefined, signal, {
-            attributeId,
-        });
-    }
-    /**
-     * THE QUESTION: "what specs COULD a material of this type carry?" — the
-     * template, not the data. Use it to know which absences are meaningful; instead
-     * use {@link MaterialGraphClient.specificationFacets} for what the corpus holds
-     * and {@link MaterialGraphClient.materialBlocks} for one material.
-     *
-     * @param key A canonical taxonomy key from {@link MaterialGraphClient.taxonomy}.
-     */
-    applicableSpecs(key, signal) {
-        return this.#get("get_applicable_specs", undefined, signal, { key });
-    }
-    /**
-     * THE QUESTION: "what does 'DCOF' MEAN?" — one term explained, for a human.
-     * Explanation, not retrieval: instead use
-     * {@link MaterialGraphClient.searchVocabulary} to FIND a token and
-     * {@link MaterialGraphClient.attributeValues} for the values it takes.
-     */
-    glossary(term, signal) {
-        return this.#get("explain_material_term", undefined, signal, { term });
+    async specificationFacets(signal) {
+        return await this.#get("list_spec_facets", undefined, signal);
     }
     // ── Brands ───────────────────────────────────────────────────────────────────
     /** "Whose catalogs are in here, and how big is each?" — {@link listBrands}. */
-    brands(options = {}, signal) {
-        return listBrands(this.#transport, options, signal);
-    }
-    /** "Who is this brand, and what do they claim?" — {@link brandProfile}. */
-    brand(brandSlug, options, signal) {
-        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);
+    async brands(options = {}, signal) {
+        return await listBrands(this.#transport, options, signal);
     }
     // ── Runs (the hosted agentic surface) ────────────────────────────────────────
     /**
@@ -591,8 +512,8 @@ export class MaterialGraphClient extends CatalogueClient {
      * text/markdown, and images — the server classifies each) or the legacy
      * `{ brief, references }` shape. Requires the `mg:ingest` scope.
      */
-    uploadSourceMaterial(input, signal) {
-        return uploadSourceMaterial(this.#transport, input, signal);
+    async uploadSourceMaterial(input, signal) {
+        return await uploadSourceMaterial(this.#transport, input, signal);
     }
     /**
      * Read back an uploaded batch (GET `/api/v1/source-material/{batchId}`): every
@@ -602,90 +523,30 @@ export class MaterialGraphClient extends CatalogueClient {
      * immediately. A batch you do not own raises the same 404 as one that does not
      * exist. Requires the `mg:compose` scope.
      */
-    sourceMaterialBatch(batchId, signal) {
-        return getSourceMaterialBatchCall(this.#transport, batchId, signal);
-    }
-    /**
-     * THE QUESTION: "what can the hosted agentic surface be asked to DO?" Start
-     * here before {@link MaterialGraphClient.createRun}: each capability carries its
-     * live input/output schemas, scopes and side-effect class, so nothing about a
-     * Run need be hardcoded.
-     */
-    capabilities(signal) {
-        return capabilitiesRun(this.#transport, signal);
+    async sourceMaterialBatch(batchId, signal) {
+        return await getSourceMaterialBatchCall(this.#transport, batchId, signal);
     }
     /**
      * THE QUESTION: "do a whole job for me" — the ASYNC lens. Everything else here
      * answers in one round trip; a Run may suspend for human input and finish
      * minutes later. Follow with {@link MaterialGraphClient.streamRunEvents} (live)
-     * or {@link MaterialGraphClient.run} (poll); resume via
-     * {@link MaterialGraphClient.resumeRun}; pick the capability from
-     * {@link MaterialGraphClient.capabilities}. Pass `idempotencyKey` so a retry
+     * or {@link MaterialGraphClient.run} (poll). Pass `idempotencyKey` so a retry
      * replays rather than duplicates.
      */
-    createRun(body, signal) {
-        return createRun(this.#transport, body, signal);
+    async createRun(body, signal) {
+        return await createRun(this.#transport, body, signal);
     }
     /**
      * THE QUESTION: "where has this Run got to?" — the caller-owned, redacted
      * ledger record. Polling; prefer {@link MaterialGraphClient.streamRunEvents}
-     * when a human is waiting. `suspended` is not a failure — it means the Run is
-     * asking you something (see {@link MaterialGraphClient.resumeRun}).
+     * when a human is waiting.
      */
-    run(runId, signal) {
-        return getRun(this.#transport, runId, signal);
-    }
-    /**
-     * THE QUESTION: "which Runs are mine?" — your own Runs, newest first, paged
-     * (GET `/api/v1/runs`). This is how a client that lost a Run id finds its work
-     * again: `{ status: "suspended" }` returns the Runs still waiting on an
-     * answer, whose ids you can then feed to {@link MaterialGraphClient.resumeRun}.
-     *
-     * Only your own Runs are ever returned. Page by following `nextCursor` until
-     * it is ABSENT — a full page is not the signal to stop.
-     */
-    listRuns(options) {
-        return listRuns(this.#transport, options);
-    }
-    /**
-     * Export a completed compose Run's scheme as a finish schedule — one row per
-     * slot, every attribute value carrying its source and verification state
-     * (GET `/api/v1/runs/{runId}/schedule`). Unknown values are explicit
-     * `missing` cells, never blanks. The `.xlsx` form is a direct-URL download:
-     * `GET /api/v1/runs/{runId}/schedule.xlsx` with the same bearer key.
-     */
-    runSchedule(runId, options) {
-        return getRunSchedule(this.#transport, runId, options);
+    async run(runId, signal) {
+        return await getRun(this.#transport, runId, signal);
     }
     /** Follow a verdict cell's citation handle to its canonical claim source. */
-    citation(citationId, signal) {
-        return this.#get("get_verdict_citation", undefined, signal, { citationId });
-    }
-    /**
-     * Resume a suspended Run (POST `/api/v1/runs/{runId}/resume`).
-     *
-     * The third argument accepts either an `AbortSignal` (the published form) or
-     * {@link ResumeRunOptions}, whose `stepId` guards against resuming a step the
-     * run has already moved past — the API answers 409 on a mismatch (MG-608).
-     */
-    resumeRun(runId, resumeData, signalOrOptions) {
-        return resumeRun(this.#transport, runId, resumeData, signalOrOptions);
-    }
-    /**
-     * THE QUESTION: "stop this Run." Requests DURABLE cancellation — the Run
-     * acknowledges and unwinds; the call returning does not mean it has stopped.
-     * Poll {@link MaterialGraphClient.run} for the terminal state.
-     */
-    cancelRun(runId, signal) {
-        return cancelRun(this.#transport, runId, signal);
-    }
-    /** Option B from a composed Run, along one axis. See {@link varySchemeCall}. */
-    varyScheme(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);
+    async citation(citationId, signal) {
+        return await this.#get("get_verdict_citation", undefined, signal, { citationId });
     }
     /**
      * Stream ordered Run events as an async iterator (GET
@@ -695,42 +556,11 @@ export class MaterialGraphClient extends CatalogueClient {
     streamRunEvents(runId, options) {
         return streamRunEvents(this.#transport, runId, options);
     }
-    // ── Projects (the persistent Material Box entity) ────────────────────────────
-    /**
-     * Create a persistent project owned by the caller (POST `/api/v1/projects`).
-     * Returns the freshly assembled state (an empty event log). Requires the
-     * `mg:ingest` scope.
-     */
-    createProject(body = {}, signal) {
-        return createProjectCall(this.#transport, body, signal);
-    }
-    /**
-     * THE QUESTION: "what has happened on this project?" — the append-only event log
-     * FOLDED into a read model, plus the raw `events`. Read the folded collections;
-     * the log is there for audit.
-     */
-    getProject(projectId, signal) {
-        return getProjectCall(this.#transport, projectId, signal);
-    }
-    /**
-     * Append one event to a project's append-only process trail (POST
-     * `/api/v1/projects/{projectId}/events`). Requires the `mg:ingest` scope.
-     */
-    appendProjectEvent(projectId, body, signal) {
-        return appendProjectEventCall(this.#transport, projectId, body, signal);
-    }
-    /**
-     * THE QUESTION: "what Boxes do I have?" Scoped to the authenticated principal —
-     * another key's projects are invisible, not forbidden.
-     */
-    listProjects(signal) {
-        return listProjectsCall(this.#transport, signal);
-    }
     /**
      * Collect Run events until a terminal event, the deadline, or the stream ends
      * — the bounded events-log pattern (a single pass over {@link streamRunEvents}).
      */
-    drainRunEvents(runId, options) {
-        return drainRunEvents(this.#transport, runId, options);
+    async drainRunEvents(runId, options) {
+        return await drainRunEvents(this.#transport, runId, options);
     }
 }