@instruments/materialgraph 0.25.0 → 0.27.0

package/client.d.ts

@@ -1,36 +1,31 @@
-import { CatalogueClient } from "./catalogue-client.js";
-import type { MaterialGraphClientOptions } from "./client-config.js";
-import { type RateLimit } from "./errors.js";
-import { ScheduleReferencesClient } from "./schedule-references-client.js";
-export * from "./client-config.js";
-import { type BrowseNamespace } from "./client-browse.js";
-import { type ExplorationNamespace } from "./client-exploration.js";
-export type { BrowseNamespace } from "./client-browse.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 { ApplicabilityOptions, AssociatedOptions } from "./association-types.js";
 import type { BrandsOptions } from "./brand-types.js";
 import type { ByColourParams, ByColourResponse } from "./by-colour-types.js";
+import { CatalogueClient } from "./catalogue-client.js";
+import { CategoriesClient } from "./categories-client.js";
 import type { ResolvedVerdictCitation } from "./citation-types.js";
+import type { MaterialGraphClientOptions } from "./client-config.js";
+import type { SourceMaterialCommentsNamespace } from "./client-source-material-comments.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 { RateLimit } from "./errors.js";
+import type { BatchId, RunId, VariantId } from "./identifiers.js";
+import type { ListVariantFacetsInput, ListVariantFacetsOutput } from "./list-variant-facets-types.js";
+import type { ListVariantsInput, ListVariantsOutput } from "./list-variants-types.js";
 import type { MatchStreamEvent } from "./match-stream-types.js";
-import type { MatchInput, MatchResponse } from "./match-types.js";
-import type { MaterialDocumentPageOptions } from "./material-asset-types.js";
+import type { MatchAnswer, MatchInput } from "./match-types.js";
+import type { ListVariantAssetsOptions, MaterialDocumentPageOptions, VariantAssetPage } from "./material-asset-types.js";
+import type { CompositionCorpusSummary } from "./material-composition-types.js";
 import type { MaterialQueryPlan } from "./material-query-plan-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 { CreatePublicRunRequest, CreatePublicRunResponse, DrainRunEventsOptions, PublicRunResponse, RunEvent, SourceMaterialBatchDetail, SourceMaterialBatchReceipt, StreamRunEventsOptions, UploadSourceMaterialInput } from "./run-types.js";
 import type { SchemaResource, SchemaResourceResponse } from "./schema-resource-types.js";
-import type { SlotPoolsRequest, SlotPoolsResponse } from "./slot-pool-types.js";
-import type { FindSubstitutesOptions, FindSubstitutesResponse } from "./substitute-types.js";
+import type { CardProjectionRequest, SearchCardResponse } from "./search-card-types.js";
 import type { ProductTypeCoverageOptions, ProductTypeStatusCoverage } from "./taxonomy-coverage-types.js";
-import type { ApplicableSpecsResponse, BrandOptions, BySpecOptions, BySpecResponse, ColourFacetsResponse, CoordinateInput, CoordinateResponse, DemandBatchInput, DemandBatchResponse, DemandParams, DemandResponse, ExtractPaletteInput, ExtractPaletteResponse, GlossaryTermResponse, MaterialResponse, MaterialsBatchDetailResponse, MaterialsBatchGetOptions, MaterialsBatchOptions, MaterialsBatchTileResponse, PairingsOptions, PairingsResponse, ResolveAttributeOptions, ResolveAttributeResponse, ResolveAttributeValueOptions, ResolveAttributeValueResponse, ResolveColourOptions, ResolveColourResponse, SearchGetParams, SearchInput, SearchResponse, SiblingsResponse, SpecFacetsDistributionResponse, SpecFacetsListResponse, SuggestColourResponse, SuggestOptions, SuggestResponse, TaxonomyResponse, VocabularySearchOptions, WhoamiResponse } from "./types.js";
+import type { CoordinateInput, CoordinateResponse, DemandBatchInput, DemandBatchResponse, DemandParams, DemandResponse, ExtractPaletteInput, ExtractPaletteResponse, ListAttributesOptions, ListAttributesResult, MaterialResponse, PairingsOptions, PairingsResponse, ResolveColourOptions, ResolveColourResponse, SearchGetParams, SearchInput, SearchResponse, SpecFacetsListResponse, SuggestColourResponse, SuggestOptions, SuggestResponse, VocabularySearchOptions, WhoamiResponse } from "./types.js";
+export * from "./client-config.js";
+export type { SourceMaterialCommentsNamespace } from "./client-source-material-comments.js";
 /**
  * The MaterialGraph client — every lens on the graph, on one object.
  *
@@ -41,13 +36,13 @@ import type { ApplicableSpecsResponse, BrandOptions, BySpecOptions, BySpecRespon
  * | --- | --- |
  * | "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` |
  *
@@ -68,33 +63,28 @@ import type { ApplicableSpecsResponse, BrandOptions, BySpecOptions, BySpecRespon
  */
 export declare class MaterialGraphClient extends CatalogueClient {
     #private;
-    readonly scheduleReferences: ScheduleReferencesClient;
     readonly baseUrl: string;
     /**
-     * THE QUESTION: "show me everything in this category / this brand, in a plain
-     * 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.
+     * 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()`).
      *
-     * 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.
      */
-    readonly browse: BrowseNamespace;
+    readonly categories: CategoriesClient;
     /**
      * 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.
@@ -104,15 +94,14 @@ export declare 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.
      */
     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
@@ -122,29 +111,36 @@ export declare class MaterialGraphClient extends CatalogueClient {
     constructor(options: MaterialGraphClientOptions);
     get lastRateLimit(): RateLimit | null;
     /**
-     * THE QUESTION: "find me materials like this" — a RANKED answer over words, a
-     * seed image, colours and a mood, optionally gated by hard specs.
+     * THE QUESTION: "find me materials like this": one search over the words, or
+     * a seed or query image, optionally gated by a category, hard attribute
+     * filters and a corpus scope (ADR 0031).
      *
-     * Instead use {@link MaterialGraphClient.bySpec} when the spec IS the question
+     * Instead use {@link MaterialGraphClient.listVariants} 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`.
+     * The full POST search primitive. `input.filters` are hard token sets on
+     * the search index, run in the same query; they change no ordering. Build
+     * them with `certificationProgramme`, `specTerm`, or `hasSpec`. Weights,
+     * mood, colours, sort and preferences are gone, and the server refuses them
+     * by name.
      */
+    search(input: SearchInput & CardProjectionRequest, signal?: AbortSignal): Promise<SearchCardResponse>;
     search(input: SearchInput, signal?: AbortSignal): Promise<SearchResponse>;
     /** Whole materials ask → inspectable meanings and complete safe search requests. */
     planQuery(query: string, signal?: AbortSignal): Promise<MaterialQueryPlan>;
     /**
      * 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`.
+     * transport: a cacheable, link-shareable GET for queries that must survive in
+     * a URL. `category`, `filters` and image bytes have no query-string form, so
+     * anything using those must go through `search`.
      */
+    searchGet(params: SearchGetParams & {
+        view: "card";
+    }, signal?: AbortSignal): Promise<SearchCardResponse>;
     searchGet(params: SearchGetParams, signal?: AbortSignal): Promise<SearchResponse>;
     /**
      * THE QUESTION: "what materials are in this PHOTO?" — Material Match classifies
@@ -159,7 +155,7 @@ export declare class MaterialGraphClient extends CatalogueClient {
      * `droppedBelowFloor` before reporting an empty result: "nothing was good
      * enough" and "nothing was found" are different answers.
      */
-    match(input: MatchInput, signal?: AbortSignal): Promise<MatchResponse>;
+    match(input: MatchInput, signal?: AbortSignal): Promise<MatchAnswer>;
     /**
      * Material Match as a PROGRESSIVE stream — the same POST
      * `/api/v1/search/match` endpoint negotiated with `Accept:
@@ -191,7 +187,7 @@ export declare 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.
@@ -202,35 +198,33 @@ export declare 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: VariantId, options?: {
-        includeSiblings?: boolean;
-    }, signal?: AbortSignal): Promise<MaterialResponse>;
+    material(variantId: VariantId, signal?: AbortSignal): Promise<MaterialResponse>;
+    materialBlocks(variantId: VariantId, signal?: AbortSignal): Promise<import("./material-block-types.js").MaterialBlockProjection>;
     /**
-     * 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: VariantId, signal?: AbortSignal): Promise<SiblingsResponse>;
-    materialBlocks(variantId: VariantId, signal?: AbortSignal): Promise<import("./material-block-types.js").MaterialBlockProjection>;
-    materialAssets(variantId: VariantId, signal?: AbortSignal): Promise<import("./material-asset-types.js").MaterialAssetProjection>;
-    materialRenderAssets(variantId: VariantId, signal?: AbortSignal): Promise<import("./render-assets-types.js").MaterialRenderAssets>;
+    compositionReport(signal?: AbortSignal): Promise<CompositionCorpusSummary>;
+    listVariantAssets(variantId: VariantId, options?: ListVariantAssetsOptions, signal?: AbortSignal): Promise<VariantAssetPage>;
     materialDocuments(variantId: VariantId, options?: MaterialDocumentPageOptions, signal?: AbortSignal): Promise<import("./material-asset-types.js").MaterialDocumentPage>;
     /**
      * THE QUESTION: "what does the schema DEFINE?" — the governed static registry.
      *
      * 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<K extends SchemaResource>(resource: K, signal?: AbortSignal): Promise<SchemaResourceResponse<K>>;
     /**
@@ -238,9 +232,9 @@ export declare 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
@@ -248,45 +242,37 @@ export declare class MaterialGraphClient extends CatalogueClient {
      * you how much of the rail is real order evidence.
      */
     pairings(variantId: VariantId, options?: PairingsOptions, signal?: AbortSignal): Promise<PairingsResponse>;
-    /** Find bounded, exact-spec substitutes for one opaque variant id. */
-    findSubstitutes(variantId: VariantId, options?: FindSubstitutesOptions, signal?: AbortSignal): Promise<FindSubstitutesResponse>;
     /** "What finishes does the manufacturer declare for THIS product?" — {@link declaredFinishes}. */
     associatedFinishes(variantId: VariantId, options?: AssociatedOptions, signal?: AbortSignal): Promise<import("./association-types.js").DeclaredAssociationsResponse>;
     /** "What products does the manufacturer declare THIS finish for?" — {@link declaredProducts}. */
     associatedProducts(variantId: VariantId, options?: AssociatedOptions, signal?: AbortSignal): Promise<import("./association-types.js").DeclaredAssociationsResponse>;
     applicability(options: ApplicabilityOptions, signal?: AbortSignal): Promise<import("./association-types.js").ApplicabilityResponse>;
     /**
-     * THE QUESTION: "hydrate these ids I already hold" (POST
-     * `/api/v1/materials/batch`, ≤ 100 ids) — never a discovery call. Throws
-     * client-side above {@link MAX_BATCH_IDS}. The response is NOT positional:
-     * match on `variantId` and read `missingIds` rather than comparing lengths.
-     * {@link MaterialGraphClient.materialsCached} is the CDN-friendly GET form.
+     * 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.
      *
-     * @param ids Opaque tokens, passed back verbatim.
+     * `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.
      */
-    materials(ids: VariantId[], options: {
-        view: "detail";
-        idKind?: MaterialsBatchOptions["idKind"];
-    }, signal?: AbortSignal): Promise<MaterialsBatchDetailResponse>;
-    materials(ids: VariantId[], options?: {
-        view?: "tile";
-        idKind?: MaterialsBatchOptions["idKind"];
-    }, signal?: AbortSignal): Promise<MaterialsBatchTileResponse>;
+    listVariants(input: ListVariantsInput, signal?: AbortSignal): Promise<ListVariantsOutput>;
     /**
-     * Cacheable GET form of the batch read (GET `/api/v1/materials/batch`,
-     * `Cache-Control: public, max-age=300`). Same response as {@link materials};
-     * prefer this for repeatable, cache-friendly id sets. Also ≤ 100 ids.
+     * 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.
      */
-    materialsCached(ids: VariantId[], options: {
-        view: "detail";
-        idKind?: MaterialsBatchGetOptions["idKind"];
-    }, signal?: AbortSignal): Promise<MaterialsBatchDetailResponse>;
-    materialsCached(ids: VariantId[], options?: {
-        view?: "tile";
-        idKind?: MaterialsBatchGetOptions["idKind"];
-    }, signal?: AbortSignal): Promise<MaterialsBatchTileResponse>;
-    /** Vocabulary families and counts; use `colours.profiles()` for a material palette. */
-    colourFacets(signal?: AbortSignal): Promise<ColourFacetsResponse>;
+    listVariantFacets(input: ListVariantFacetsInput, signal?: AbortSignal): Promise<ListVariantFacetsOutput>;
     /** Resolve a colour name to its hex, and the named paint's catalogue variant. */
     resolveColour(name: string, signal?: AbortSignal, options?: ResolveColourOptions): Promise<ResolveColourResponse>;
     /** Ranked colour-name typeahead (GET `/api/v1/search/colours/suggest`). */
@@ -295,44 +281,20 @@ export declare class MaterialGraphClient extends CatalogueClient {
     }, signal?: AbortSignal): Promise<SuggestColourResponse>;
     /** Entity typeahead. Navigate using the selected `refId`; use `search()` for materials. */
     suggest(q: string, options?: SuggestOptions, signal?: AbortSignal): Promise<SuggestResponse>;
-    /** Resolve free text to a canonical attribute id. */
-    resolveAttribute(q: string, options?: ResolveAttributeOptions, signal?: AbortSignal): Promise<ResolveAttributeResponse>;
-    /** Resolve a value under a canonical attribute id; inspect `recommendedAction` for ambiguity. */
-    resolveAttributeValue(attributeId: string, query: string, options?: ResolveAttributeValueOptions, signal?: AbortSignal): Promise<ResolveAttributeValueResponse>;
+    /**
+     * 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.
+     */
+    listAttributes(options?: ListAttributesOptions, signal?: AbortSignal): Promise<ListAttributesResult>;
     /** "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, 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. 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.
-     */
-    bySpec(spec: string | string[], options?: BySpecOptions, signal?: AbortSignal): Promise<BySpecResponse>;
-    /**
-     * 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?: AbortSignal): Promise<TaxonomyResponse>;
     /**
      * Exact current primary-type status counts by retained source category path.
      * `comparisonThreshold` is a reporting cutoff only: it never promotes a
@@ -406,9 +368,8 @@ export declare class MaterialGraphClient extends CatalogueClient {
     /**
      * 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
@@ -417,41 +378,14 @@ export declare 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?: AbortSignal): Promise<SpecFacetsListResponse>;
-    /**
-     * 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: string, signal?: AbortSignal): Promise<SpecFacetsDistributionResponse>;
-    /**
-     * 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: string, signal?: AbortSignal): Promise<ApplicableSpecsResponse>;
-    /**
-     * 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: string, signal?: AbortSignal): Promise<GlossaryTermResponse>;
     /** "Whose catalogs are in here, and how big is each?" — {@link listBrands}. */
     brands(options?: BrandsOptions, signal?: AbortSignal): Promise<import("./brand-types.js").BrandCatalogListPage>;
-    /** "Who is this brand, and what do they claim?" — {@link brandProfile}. */
-    brand(brandSlug: string, options?: BrandOptions, signal?: AbortSignal): Promise<import("./types.js").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,
@@ -468,96 +402,28 @@ export declare class MaterialGraphClient extends CatalogueClient {
      * exist. Requires the `mg:compose` scope.
      */
     sourceMaterialBatch(batchId: BatchId, signal?: AbortSignal): Promise<SourceMaterialBatchDetail>;
-    /**
-     * 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?: AbortSignal): Promise<CapabilityManifestResponse>;
     /**
      * 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: CreatePublicRunRequest, signal?: AbortSignal): Promise<CreatePublicRunResponse>;
     /**
      * 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: RunId, signal?: AbortSignal): Promise<PublicRunResponse>;
-    /**
-     * 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?: ListRunsOptions): Promise<PublicRunListResponse>;
-    /**
-     * 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: RunId, options?: GetRunScheduleOptions): Promise<FinishScheduleResponse>;
     /** Follow a verdict cell's citation handle to its canonical claim source. */
     citation(citationId: string, signal?: AbortSignal): Promise<ResolvedVerdictCitation>;
-    /**
-     * Resume a suspended Run (POST `/api/v1/runs/{runId}/resume`).
-     *
-     * 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: RunId, resumeData: unknown, signalOrOptions?: AbortSignal | ResumeRunOptions): Promise<PublicRunResponse>;
-    /**
-     * 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: RunId, signal?: AbortSignal): Promise<PublicRunResponse>;
-    /** 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
      * signal aborts; pass `after` to resume from the last observed sequence.
      */
     streamRunEvents(runId: RunId, options?: StreamRunEventsOptions): AsyncGenerator<RunEvent>;
-    /**
-     * 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?: CreateProjectRequest, signal?: AbortSignal): Promise<ProjectState>;
-    /**
-     * 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: ProjectId, signal?: AbortSignal): Promise<ProjectState>;
-    /**
-     * Append one event to a project's append-only process trail (POST
-     * `/api/v1/projects/{projectId}/events`). Requires the `mg:ingest` scope.
-     */
-    appendProjectEvent(projectId: ProjectId, body: AppendProjectEventRequest, signal?: AbortSignal): Promise<ProjectEventReceipt>;
-    /**
-     * THE QUESTION: "what Boxes do I have?" Scoped to the authenticated principal —
-     * another key's projects are invisible, not forbidden.
-     */
-    listProjects(signal?: AbortSignal): Promise<ProjectListResponse>;
     /**
      * Collect Run events until a terminal event, the deadline, or the stream ends
      * — the bounded events-log pattern (a single pass over {@link streamRunEvents}).