@instruments/materialgraph 0.26.0 → 0.27.0

package/client.js

@@ -1,23 +1,22 @@
 import * as assoc from "./associations-client.js";
-import { brandColourDeck, brandProfile, listBrands } from "./brands-client.js";
+import { listBrands } from "./brands-client.js";
 import { CatalogueClient } from "./catalogue-client.js";
-import { browseQuery, createBrowseNamespace } from "./client-browse.js";
-import { DEFAULT_BASE_URL, MAX_BATCH_IDS } from "./client-config.js";
-import { createExplorationNamespace } from "./client-exploration.js";
+import { CategoriesClient } from "./categories-client.js";
+import { DEFAULT_BASE_URL } from "./client-config.js";
 import { createSourceMaterialCommentsNamespace } from "./client-source-material-comments.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 { 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 { 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 { cancelRun, capabilities as capabilitiesRun, createRun, drainRunEvents, getRun, getSourceMaterialBatch as getSourceMaterialBatchCall, listRuns, resumeRun, streamRunEvents, uploadSourceMaterial, } from "./runs.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";
@@ -31,13 +30,13 @@ export * from "./client-config.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,30 +58,26 @@ export * from "./client-config.js";
 export class MaterialGraphClient extends CatalogueClient {
     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.
+     * 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()`).
      *
-     * `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 });
+     * 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.
@@ -92,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
@@ -120,7 +114,9 @@ export class MaterialGraphClient extends CatalogueClient {
         super(transport);
         this.#transport = transport;
         this.baseUrl = transport.baseUrl;
-        this.browse = createBrowseNamespace(async (params, signal) => await 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: async (operationId, query, signal) => await this.#get(operationId, query, signal),
             post: async (operationId, body, signal) => await this.#post(operationId, body, signal),
@@ -129,7 +125,6 @@ export class MaterialGraphClient extends CatalogueClient {
             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() {
@@ -149,21 +144,6 @@ export class MaterialGraphClient extends CatalogueClient {
             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`.
-     */
     async search(input, signal) {
         return await this.#post("search_materials_post", input, signal);
     }
@@ -171,12 +151,6 @@ export class MaterialGraphClient extends CatalogueClient {
     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`.
-     */
     async searchGet(params, signal) {
         return await this.#get("search_materials_get", { ...params }, signal);
     }
@@ -229,7 +203,7 @@ 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.
@@ -249,6 +223,7 @@ export class MaterialGraphClient extends CatalogueClient {
             maxColourDistance: params.maxColourDistance,
             order: params.order,
             q: params.q,
+            variantId: params.variantId,
         }, signal);
     }
     // ── Materials ──────────────────────────────────────────────────────────────
@@ -257,35 +232,34 @@ 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.
      */
-    async material(variantId, options, signal) {
-        return await this.#get("get_material", options?.includeSiblings ? { include: "siblings" } : undefined, signal, { variantId });
-    }
-    /**
-     * THE QUESTION: "what other colourways and finishes does this product come in?"
-     * — the SAME product, different variants.
-     *
-     * Instead use {@link MaterialGraphClient.pairings} for a DIFFERENT product that
-     * goes with this one, and `search({ similarTo })` for one that LOOKS like it.
-     */
-    async siblings(variantId, signal) {
-        return await this.#get("get_material_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);
     }
-    async materialAssets(variantId, signal) {
-        return await materialAssetsCall(this.#transport, variantId, signal);
+    /**
+     * THE QUESTION: "which product types can composition be answered for yet?"
+     *
+     * 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.
+     */
+    async compositionReport(signal) {
+        return await compositionReportCall(this.#transport, signal);
     }
-    async materialRenderAssets(variantId, signal) {
-        return await materialRenderAssetsCall(this.#transport, variantId, signal);
+    async listVariantAssets(variantId, options, signal) {
+        return await listVariantAssetsCall(this.#transport, variantId, options, signal);
     }
     async materialDocuments(variantId, options, signal) {
         return await materialDocumentsCall(this.#transport, variantId, options, signal);
@@ -294,8 +268,7 @@ export class MaterialGraphClient extends CatalogueClient {
      * 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.
      */
     async schema(resource, signal) {
         return await this.#get(SCHEMA_RESOURCE_OPERATION_IDS[resource], undefined, signal);
@@ -305,9 +278,9 @@ export class MaterialGraphClient extends CatalogueClient {
      * 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
@@ -319,10 +292,6 @@ export class MaterialGraphClient extends CatalogueClient {
             variantId,
         });
     }
-    /** Find bounded, exact-spec substitutes for one opaque variant id. */
-    async findSubstitutes(variantId, options = {}, signal) {
-        return await this.#post("find_material_substitutes", options, signal, { variantId });
-    }
     /** "What finishes does the manufacturer declare for THIS product?" — {@link declaredFinishes}. */
     async associatedFinishes(variantId, options, signal) {
         return await assoc.declaredFinishes(this.#transport, variantId, options, signal);
@@ -334,29 +303,50 @@ export class MaterialGraphClient extends CatalogueClient {
     async applicability(options, signal) {
         return await assoc.applicability(this.#transport, options, signal);
     }
-    async 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 await this.#post("get_materials_batch_post", {
-            idKind: options?.idKind ?? "variantId",
-            ids,
-            view: options?.view ?? "tile",
-        }, signal);
-    }
-    async 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 await this.#get("get_materials_batch_get", {
-            idKind: options?.idKind ?? "variantId",
-            ids: ids.join(","),
-            view: options?.view ?? "tile",
+    /**
+     * 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. */
-    async colourFacets(signal) {
-        return await 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. */
     async resolveColour(name, signal, options) {
@@ -371,13 +361,17 @@ export class MaterialGraphClient extends CatalogueClient {
         return await suggestCall(this.#transport, q, options, signal);
     }
     // ── Catalog ──────────────────────────────────────────────────────────────────
-    /** Resolve free text to a canonical attribute id. */
-    async resolveAttribute(q, options, signal) {
-        return await resolveAttributeCall(this.#transport, q, options, signal);
-    }
-    /** Resolve a value under a canonical attribute id; inspect `recommendedAction` for ambiguity. */
-    async resolveAttributeValue(attributeId, query, options, signal) {
-        return await resolveAttributeValueCall(this.#transport, attributeId, query, options, signal);
+    /**
+     * 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.
+     */
+    async listAttributes(options, signal) {
+        return await listAttributesCall(this.#transport, options, signal);
     }
     /** "Is this phrase an attribute or a value?" — see {@link searchVocabularyRequest}. */
     async searchVocabulary(query, options, signal) {
@@ -387,45 +381,16 @@ export class MaterialGraphClient extends CatalogueClient {
     async resolve(phrases, scope) {
         return await 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.
-     */
-    async bySpec(spec, options, signal) {
-        return await this.#get("catalog_by_spec", {
-            spec: Array.isArray(spec) ? spec : [spec],
-            ...(options?.ranges?.length ? { specRange: options.ranges } : {}),
-            limit: options?.limit,
-        }, 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.
-     */
-    async taxonomy(signal) {
-        return await this.#get("get_category_taxonomy", undefined, signal);
-    }
+    // 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
@@ -513,13 +478,12 @@ export class MaterialGraphClient extends CatalogueClient {
     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
@@ -528,58 +492,19 @@ 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.
      */
     async specificationFacets(signal) {
         return await 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.
-     */
-    async attributeValues(attributeId, signal) {
-        return await 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}.
-     */
-    async applicableSpecs(key, signal) {
-        return await 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.
-     */
-    async glossary(term, signal) {
-        return await this.#get("explain_material_term", undefined, signal, { term });
-    }
     // ── Brands ───────────────────────────────────────────────────────────────────
     /** "Whose catalogs are in here, and how big is each?" — {@link listBrands}. */
     async brands(options = {}, signal) {
         return await listBrands(this.#transport, options, signal);
     }
-    /** "Who is this brand, and what do they claim?" — {@link brandProfile}. */
-    async brand(brandSlug, options, signal) {
-        return await brandProfile(this.#transport, brandSlug, options, signal);
-    }
-    /** "This maker's whole range, the way a fan deck reads" — {@link brandColourDeck}. */
-    async brandColourDeck(brandSlug, signal) {
-        return await brandColourDeck(this.#transport, brandSlug, signal);
-    }
     // ── Runs (the hosted agentic surface) ────────────────────────────────────────
     /**
      * Upload one atomic source-material batch (POST `/api/v1/source-material`,
@@ -601,22 +526,11 @@ export class MaterialGraphClient extends CatalogueClient {
     async sourceMaterialBatch(batchId, signal) {
         return await 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.
-     */
-    async capabilities(signal) {
-        return await capabilitiesRun(this.#transport, 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.
      */
     async createRun(body, signal) {
@@ -625,54 +539,15 @@ export class MaterialGraphClient extends CatalogueClient {
     /**
      * 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.
      */
     async run(runId, signal) {
         return await 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.
-     */
-    async listRuns(options) {
-        return await listRuns(this.#transport, options);
-    }
     /** Follow a verdict cell's citation handle to its canonical claim source. */
     async citation(citationId, signal) {
         return await 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).
-     */
-    async resumeRun(runId, resumeData, signalOrOptions) {
-        return await 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.
-     */
-    async cancelRun(runId, signal) {
-        return await cancelRun(this.#transport, runId, signal);
-    }
-    /** Option B from a composed Run, along one axis. See {@link varySchemeCall}. */
-    async varyScheme(body, signal) {
-        return await varySchemeCall(this.#transport, body, signal);
-    }
-    /** Ranked candidate pools for up to 24 slots. See {@link slotPoolsCall}. */
-    async slotPools(body, signal) {
-        return await slotPoolsCall(this.#transport, body, signal);
-    }
     /**
      * Stream ordered Run events as an async iterator (GET
      * `/api/v1/runs/{runId}/events`, SSE). Iterates until the stream ends or the

package/codes-types.d.ts

@@ -14,6 +14,7 @@
  * model code as adopted, never a legal determination.
  */
 import type { VariantId } from "./identifiers.js";
+import type { FilterGroups } from "./list-variants-types.js";
 import type { OpenEnum } from "./types.js";
 /**
  * A code context: the space the registry is queried for.
@@ -292,6 +293,14 @@ export type CodeRequirementListing = {
     /** One readable line, e.g. `"Class A or better · ASTM E84 / UL 723"`. */
     label: string;
 };
+/** Why one requirement the context imposes could not become a `list_variants` filter predicate. */
+export type CodeSpecFilterUnexpressible = {
+    requirementId: string;
+    dimension: OpenEnum<"fire" | "floor" | "slip" | "decorative">;
+    reason: OpenEnum<"no_matchable_tokens" | "unsupported_scale" | "no_floor">;
+    /** One readable line naming why, e.g. `"Scale ... has no ordinal definition..."`. */
+    detail: string;
+};
 /**
  * The `GET /api/v1/codes/requirements` envelope. An empty `requirements` array
  * means the registry holds nothing for this context — it is not a pass.
@@ -300,5 +309,17 @@ export type CodeRequirementsResponse = {
     jurisdiction: CodeJurisdictionSummary;
     context: ResolvedCodeContext;
     requirements: CodeRequirementListing[];
+    /**
+     * The same requirements as a ready-to-use `list_variants` `filters` group
+     * (MG-2222, `{terms, numbers, presence}`) — pass it straight through as
+     * `listVariants({ filters })`.
+     * `null` when nothing here is filterable; read `specFilterUnexpressible`
+     * for why, not an empty `requirements` list.
+     */
+    specFilter: FilterGroups | null;
+    /** The dimensions `specFilter` actually narrows on — a subset of `requirements`' dimensions. */
+    specFilterApplied: OpenEnum<"fire" | "floor" | "slip" | "decorative">[];
+    /** Requirements that could not be turned into a filter predicate, and why. */
+    specFilterUnexpressible: CodeSpecFilterUnexpressible[];
     caveat: string;
 };