@instruments/materialgraph 0.29.0 → 0.30.0

package/brands-client.d.ts

@@ -5,7 +5,7 @@
  *
  * A brand is a COMPANY, not a catalogue. Every count this read returns is
  * coverage — what MaterialGraph has ingested — and never a claim about how
- * many products the maker sells.
+ * many products the brand sells.
  */
 import type { BrandCatalogListPage, BrandsOptions } from "./brand-types.js";
 import type { HttpTransport } from "./http-transport.js";

package/by-colour-types.d.ts

@@ -1,10 +1,10 @@
 /**
  * Wire types for the single-colour lane — GET `/api/v1/search/colours`.
  *
- * Kept out of `types.ts` for the same reason `palette-search-types.ts` and
- * `colour-aggregate-types.ts` are: the shared mirror is at its source-size
- * budget. Same tolerant-parsing contract as the rest of the mirror — response
- * enums are widened so a new server value still type-checks.
+ * Kept out of `types.ts` for the same reason `palette-search-types.ts` is: the
+ * shared mirror is at its source-size budget. Same tolerant-parsing contract as
+ * the rest of the mirror — response enums are widened so a new server value
+ * still type-checks.
  */
 import type { CorpusScope, CorpusScopeReceipt } from "./corpus-scope-types.js";
 import type { VariantId } from "./identifiers.js";

package/catalogue-client.d.ts

@@ -1,7 +1,7 @@
 import type { CatalogDocumentList, CatalogPageListResult, CatalogProductReferenceReadResult, CatalogueChannelCollectionsResponse, CatalogueCollectionsOptions, CatalogueDocumentAccessResult, CataloguePageRepresentationReadResult, CatalogueReferenceBatchResponse } from "./catalogue-types.js";
 import type { HttpTransport } from "./http-transport.js";
 import type { VariantId } from "./identifiers.js";
-import type { IdentifyResponse, IdentifyVariantInput } from "./identify-types.js";
+import type { ResolveVariantInput, ResolveVariantOutput } from "./resolve-variant-types.js";
 import type { SamplizeCatalogueOptions, SamplizeCataloguePage } from "./samplize-catalogue-types.js";
 import type { SamplizeColorVecCache } from "./samplize-colorvec.js";
 /** Catalogue publication operations inherited by the public SDK client. */
@@ -15,12 +15,12 @@ export declare class CatalogueClient {
      * when there is no page to read.
      *
      * Exact and scoreless: a sibling colourway, a similar image or a brand match
-     * alone never identifies a variant. Read `data.outcome` - `identified` names
+     * alone never identifies a variant. Read `outcome` - `identified` names
      * an exact stored variant, `placed` an exact brand with no variant match,
      * `ambiguous` carries bounded `candidates`, and `unresolved` states why,
      * never a guess. The submitted URL is never persisted.
      */
-    identify(input: IdentifyVariantInput, signal?: AbortSignal): Promise<IdentifyResponse>;
+    resolveVariant(input: ResolveVariantInput, signal?: AbortSignal): Promise<ResolveVariantOutput>;
     /** Complete producer-owned vectors and classifications for portable colour matching. */
     samplizeColorVecCache(sourceVersion: string, signal?: AbortSignal): Promise<SamplizeColorVecCache>;
     /** MG-owned full-catalogue facets and directional colour refinement before page limiting. */

package/catalogue-client.js

@@ -12,13 +12,13 @@ export class CatalogueClient {
      * when there is no page to read.
      *
      * Exact and scoreless: a sibling colourway, a similar image or a brand match
-     * alone never identifies a variant. Read `data.outcome` - `identified` names
+     * alone never identifies a variant. Read `outcome` - `identified` names
      * an exact stored variant, `placed` an exact brand with no variant match,
      * `ambiguous` carries bounded `candidates`, and `unresolved` states why,
      * never a guess. The submitted URL is never persisted.
      */
-    async identify(input, signal) {
-        return await this.#transport.requestJson(resolveOperation("retrieval.identify"), { body: input, signal });
+    async resolveVariant(input, signal) {
+        return await this.#transport.requestJson(resolveOperation("resolve_variant"), { body: input, signal });
     }
     /** Complete producer-owned vectors and classifications for portable colour matching. */
     async samplizeColorVecCache(sourceVersion, signal) {

package/catalogue-types.d.ts

@@ -65,7 +65,7 @@ export interface CatalogueReference {
 export type CatalogueReferenceAbsenceReason = 
 /**
  * The registry retains no publication for the variant's brand. It says
- * nothing about whether the maker publishes one.
+ * nothing about whether the brand publishes one.
  */
 "no_publication_on_record"
 /** The edition is known but its document is not retained. */

package/client-vocabulary.d.ts

@@ -1,8 +1,6 @@
 import type { HttpTransport } from "./http-transport.js";
-import type { ListAttributesOptions, ListAttributesResult, ResolveColourOptions, ResolveColourResponse, SuggestColourResponse, SuggestOptions, SuggestResponse } from "./types.js";
+import type { ListEnumValuesOptions, ListEnumValuesResult } from "./list-enum-values-types.js";
+import type { ListAttributesOptions, ListAttributesResult, ResolveColourOptions, ResolveColourResponse } from "./types.js";
 export declare const resolveColour: (transport: HttpTransport, name: string, signal?: AbortSignal, options?: ResolveColourOptions) => Promise<ResolveColourResponse>;
-export declare const suggestColour: (transport: HttpTransport, q: string, options?: {
-    limit?: number;
-}, signal?: AbortSignal) => Promise<SuggestColourResponse>;
-export declare const suggest: (transport: HttpTransport, q: string, options?: SuggestOptions, signal?: AbortSignal) => Promise<SuggestResponse>;
 export declare const listAttributes: (transport: HttpTransport, options?: ListAttributesOptions, signal?: AbortSignal) => Promise<ListAttributesResult>;
+export declare const listEnumValues: (transport: HttpTransport, options?: ListEnumValuesOptions, signal?: AbortSignal) => Promise<ListEnumValuesResult>;

package/client-vocabulary.js

@@ -1,11 +1,5 @@
 import { resolveOperation } from "./operations.js";
-import { suggestQuery } from "./suggest-types.js";
 export const resolveColour = async (transport, name, signal, options) => await transport.requestJson(resolveOperation("resolve_colour_name"), { query: { corpusScope: options?.corpusScope, name }, signal });
-export const suggestColour = async (transport, q, options, signal) => await transport.requestJson(resolveOperation("suggest_colour_names"), { query: { limit: options?.limit, q }, signal });
-export const suggest = async (transport, q, options, signal) => await transport.requestJson(resolveOperation("search_suggest"), {
-    query: suggestQuery(q, options),
-    signal,
-});
 /**
  * A comma list, or nothing at all for an empty one. `[].join(",")` is `""`, and
  * an absent parameter is the one honest spelling of "no restriction".
@@ -22,3 +16,12 @@ export const listAttributes = async (transport, options, signal) => await transp
     },
     signal,
 });
+export const listEnumValues = async (transport, options, signal) => await transport.requestJson(resolveOperation("catalog_list_enum_values"), {
+    query: {
+        cursor: options?.cursor,
+        dictionaryId: options?.dictionaryId,
+        limit: options?.limit,
+        query: options?.query,
+    },
+    signal,
+});

package/client.d.ts

@@ -5,26 +5,25 @@ 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 { RateLimit } from "./errors.js";
-import type { BatchId, RunId, VariantId } from "./identifiers.js";
+import type { FindVariantsByColourInput, FindVariantsByColourOutput } from "./find-variants-by-colour-types.js";
+import type { FindVariantsByVectorInput, FindVariantsByVectorOutput } from "./find-variants-by-vector-types.js";
+import type { GetVariantOptions, GetVariantOutput } from "./get-variant-types.js";
+import type { VariantId } from "./identifiers.js";
+import type { ListEnumValuesOptions, ListEnumValuesResult } from "./list-enum-values-types.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 { 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 { CreatePublicRunRequest, CreatePublicRunResponse, DrainRunEventsOptions, PublicRunResponse, RunEvent, SourceMaterialBatchDetail, SourceMaterialBatchReceipt, StreamRunEventsOptions, UploadSourceMaterialInput } from "./run-types.js";
+import type { SourceMaterialBatchReceipt, UploadSourceMaterialInput } from "./run-types.js";
 import type { SchemaResource, SchemaResourceResponse } from "./schema-resource-types.js";
 import type { CardProjectionRequest, SearchCardResponse } from "./search-card-types.js";
-import type { ProductTypeCoverageOptions, ProductTypeStatusCoverage } from "./taxonomy-coverage-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, WhoamiResponse } from "./types.js";
+import type { ExtractPaletteInput, ExtractPaletteResponse, ListAttributesOptions, ListAttributesResult, PairingsOptions, PairingsResponse, ResolveColourOptions, ResolveColourResponse, SearchGetParams, SearchInput, SearchResponse, WhoamiResponse } from "./types.js";
+import { WorkflowsClient } from "./workflows-client.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.
  *
@@ -34,16 +33,15 @@ export type { SourceMaterialCommentsNamespace } from "./client-source-material-c
  * | The question | The lens |
  * | --- | --- |
  * | "find me something like this / matching these words" | {@link MaterialGraphClient.search} |
+ * | "tell me about THIS variant" | {@link MaterialGraphClient.getVariant} |
  * | "what's IN this photo?" | {@link MaterialGraphClient.match} / {@link MaterialGraphClient.matchStream} |
  * | "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.listVariants} (same product, other colourways), {@link MaterialGraphClient.coordinate} |
+ * | "what's near this colour / this palette?" | {@link MaterialGraphClient.byColour}, `colours.palette()` |
+ * | "what goes with THIS material?" | {@link MaterialGraphClient.pairings}, {@link MaterialGraphClient.listVariants} (same product, other colourways) |
  * | "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}, `categories.list()` |
+ * | "what can I even ask for?" | {@link MaterialGraphClient.listVariantFacets}, `categories.list()` |
  * | "what is this word called here?" | {@link MaterialGraphClient.listAttributes} |
- * | "do the whole job for me, async" | {@link MaterialGraphClient.createRun} + `mg:compose` |
+ * | "do the whole job for me, async" | `workflows.start()` + `mg:compose` |
  *
  * Three structural rules that fall out of that table:
  * - **Colour is a separate lens.** {@link MaterialGraphClient.search} matches
@@ -78,35 +76,25 @@ export declare class MaterialGraphClient extends CatalogueClient {
      */
     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.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.
-     */
-    readonly codes: CodesClient;
-    /**
-     * THE QUESTION: "what colours exist here?" (`profiles`, `stats`) and "what
-     * matches this whole SET of colours?" (`palette`, `gradient`).
+     * THE QUESTION: "what colours exist here?" and "what matches this whole SET
+     * of colours?" (`palette`).
      *
      * 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
+     * not a colour specification. A brand'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;
     /**
-     * THE QUESTION: "what did people say about this uploaded file, and record what
-     * they said." Names on these remarks are REPORTED, never verified — see
-     * {@link SourceMaterialCommentsNamespace}.
+     * THE QUESTION: "do a whole job for me" — the ASYNC lens. `start()` begins a
+     * Run of one registered workflow, `run()` polls it, `streamRunEvents()` and
+     * `drainRunEvents()` follow it live. Everything else on this client answers
+     * in one round trip; a Run may suspend for human input and finish minutes
+     * later. Replaces the flat `createRun()` / `run()` family, with no shim.
      */
-    readonly sourceMaterialComments: SourceMaterialCommentsNamespace;
+    readonly workflows: WorkflowsClient;
     constructor(options: MaterialGraphClientOptions);
     get lastRateLimit(): RateLimit | null;
     /**
@@ -184,7 +172,7 @@ export declare class MaterialGraphClient extends CatalogueClient {
      * palette), ranked by OKLab closeness to colour extracted from product imagery.
      *
      * Instead use `colours.palette()` for N colours at stated proportions (a
-     * different ranking, not a wrapper), `colours.gradient()` for a transition,
+     * different ranking, not a wrapper),
      * {@link MaterialGraphClient.resolveColour} first if you hold a NAME,
      * {@link MaterialGraphClient.listVariants} to page through a category or a brand, and
      * {@link MaterialGraphClient.search} when colour is one signal among many.
@@ -193,36 +181,30 @@ export declare class MaterialGraphClient extends CatalogueClient {
      */
     byColour(params: ByColourParams, signal?: AbortSignal): Promise<ByColourResponse>;
     /**
-     * THE QUESTION: "tell me everything about THIS material" (GET
-     * `/api/v1/materials/{variantId}`).
+     * THE QUESTION: "tell me about THIS variant" (GET
+     * `/api/v1/variants/{variantId}`, `get_variant`).
      *
      * The hinge of the API: every relationship lens
-     * ({@link MaterialGraphClient.listVariants}, {@link MaterialGraphClient.pairings},
-     * {@link MaterialGraphClient.demand}, `codes.advisory()`) hangs off a
-     * `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.
+     * ({@link MaterialGraphClient.listVariants}, {@link MaterialGraphClient.pairings})
+     * hangs off a `variantId`. The answer is compact on purpose: name, code,
+     * product, brand, category, image and page. Name `attributes` and `blocks`
+     * to add their values under `specifications`; a null value is unknown, never
+     * false or zero. Instead use {@link MaterialGraphClient.listVariants} for many
+     * ids, or for the other colourways of the same product (ask `listVariants`
+     * with a `product in` filter),
+     * {@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, signal?: AbortSignal): Promise<MaterialResponse>;
+    getVariant(variantId: VariantId, options?: GetVariantOptions, signal?: AbortSignal): Promise<GetVariantOutput>;
     materialBlocks(variantId: VariantId, signal?: AbortSignal): Promise<import("./material-block-types.js").MaterialBlockProjection>;
-    /**
-     * 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.
-     */
-    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
+     * Definitions, not data: use {@link MaterialGraphClient.listVariantFacets} for
      * what the corpus actually holds.
      */
     schema<K extends SchemaResource>(resource: K, signal?: AbortSignal): Promise<SchemaResourceResponse<K>>;
@@ -230,8 +212,7 @@ export declare class MaterialGraphClient extends CatalogueClient {
      * 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.listVariants} for the same product in
+     * Instead use {@link MaterialGraphClient.listVariants} for the same product in
      * another colour, and `search({ similarTo })` for a LIKE-THIS substitute —
      * similar and complementary are opposite questions.
      *
@@ -254,10 +235,11 @@ export declare class MaterialGraphClient extends CatalogueClient {
      * 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
+     * across all three ANDed), or a category/brand listing. An explicit
      * `variant in` id that does not resolve to an eligible variant is
-     * reported in `unresolvedVariantIds`, never silently dropped from the
-     * page.
+     * reported in `unresolvedVariantIds`, or in `excludedByCorpusScope` when
+     * it names a real variant outside the materials catalogue, never silently
+     * dropped from the page.
      *
      * `filters`/`optionalFilters`/`orderBy` are sent as URL-encoded JSON;
      * `attributes`/`include` as comma-separated lists — the server validates,
@@ -272,14 +254,29 @@ export declare class MaterialGraphClient extends CatalogueClient {
      * `listVariants()` takes; the server validates both.
      */
     listVariantFacets(input: ListVariantFacetsInput, signal?: AbortSignal): Promise<ListVariantFacetsOutput>;
+    /**
+     * THE QUESTION: "which variants hold, resemble, or can be ranked by, this
+     * colour?" (POST `/api/v1/variants/by-colour`, MG-2217/MG-2230/MG-2247).
+     * One required `mode`: `contains` (a swatch for every required `colours[]`
+     * condition), `palette` (whole-palette closeness to `colours[]`, an
+     * image's extracted palette, or `targetVariantId`'s own palette) or
+     * `rerank` (reorder a held `variantIds` set by colour closeness). Use
+     * {@link MaterialGraphClient.byColour} instead for ONE colour against the
+     * search index rather than the canonical variant graph.
+     */
+    findVariantsByColour(input: FindVariantsByColourInput, signal?: AbortSignal): Promise<FindVariantsByColourOutput>;
+    /**
+     * THE QUESTION: "what looks or feels like this?" (POST
+     * `/api/v1/variants/by-vector`, MG-2231). Eligible variants ranked by
+     * semantic or visual similarity to a text description (mood words count),
+     * an image reference, or both fused into one embedding. `filters` is the
+     * same tree {@link MaterialGraphClient.listVariants} takes. `query.mode`
+     * values other than `"text"` embed through Voyage and spend the shared
+     * per-key `embed` rate budget.
+     */
+    findVariantsByVector(input: FindVariantsByVectorInput, signal?: AbortSignal): Promise<FindVariantsByVectorOutput>;
     /** 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`). */
-    suggestColour(q: string, options?: {
-        limit?: number;
-    }, signal?: AbortSignal): Promise<SuggestColourResponse>;
-    /** Entity typeahead. Navigate using the selected `refId`; use `search()` for materials. */
-    suggest(q: string, options?: SuggestOptions, signal?: AbortSignal): Promise<SuggestResponse>;
     /**
      * THE QUESTION: "which attribute means this phrase?" or "what could a
      * <category> be specified by?" (GET `/api/v1/catalog/attributes`). One page of
@@ -291,67 +288,22 @@ export declare class MaterialGraphClient extends CatalogueClient {
      */
     listAttributes(options?: ListAttributesOptions, signal?: AbortSignal): Promise<ListAttributesResult>;
     /**
-     * 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.
+     * THE QUESTION: "which value means this phrase?" or "what may this attribute
+     * be set to?" (GET `/api/v1/catalog/enum-values`). One page of a value
+     * dictionary's allowed values, browsed by `dictionaryId` (from a
+     * {@link MaterialGraphClient.listAttributes} item) or found by name, alias,
+     * misspelling or meaning across every dictionary. Pass an item's `valueId`
+     * with one of its `attributeIds` to {@link MaterialGraphClient.listVariants};
+     * an item with no `attributeIds` cannot be filtered on. Follow
+     * `pageInfo.endCursor` for the next page.
      */
-    productTypeCoverage(options?: ProductTypeCoverageOptions, signal?: AbortSignal): Promise<ProductTypeStatusCoverage>;
+    listEnumValues(options?: ListEnumValuesOptions, signal?: AbortSignal): Promise<ListEnumValuesResult>;
     /**
      * 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?: AbortSignal): Promise<WhoamiResponse>;
-    /** What completes a scheme already part-chosen. See {@link coordinateCall}. */
-    coordinate(input: CoordinateInput, signal?: AbortSignal): Promise<CoordinateResponse>;
-    /**
-     * THE QUESTION: "how much is this material actually specified, and what gets
-     * specified alongside it?" — real order behaviour, trailing 36 months.
-     *
-     * Instead use {@link MaterialGraphClient.demandBatch} for many ids (this one
-     * also resolves free text, which the batch deliberately does not) and
-     * {@link MaterialGraphClient.pairings} for a presentable rail. A null `demand`
-     * means UNREAD, never zero. Provide EXACTLY ONE of `variantId` or `material`.
-     */
-    demand(params: DemandParams, signal?: AbortSignal): Promise<DemandResponse>;
-    /**
-     * THE QUESTION: "for each of these picks I already hold, how much momentum does
-     * it have?" Enrichment, never discovery or ranking. Instead use
-     * {@link MaterialGraphClient.demand} for one material named in free text and
-     * {@link MaterialGraphClient.search} to find candidates at all. Only
-     * `state: "available"` carries numbers; the other three mean "no number", never
-     * "no demand".
-     *
-     * Enrich a bounded set of ALREADY-CHOSEN candidate ids with their real
-     * specification demand (POST `/api/v1/demand/batch`, 1–48 ids). The bounded
-     * batch complement to {@link demand}: no fuzzy resolution, ranking, or
-     * reordering — each id yields one discriminated `state` (`available` /
-     * `insufficient_data` / `no_signal` / `unknown_variant`) in input order and
-     * cardinality. This is the Desk's "show demand momentum for every pick in this
-     * scheme" read; an `mg:admin` key additionally sees per-result `evidence`.
-     *
-     * @example
-     * // Rank a shortlist by real specification momentum before locking the scheme.
-     * const { results } = await mg.demandBatch({
-     *   variantIds: scheme.picks.map((p) => p.variantId),
-     *   signal: "sampled",
-     *   context: { projectType: "hospitality" },
-     * });
-     * const rising = results.filter(
-     *   (r) => r.state === "available" && r.momentum.state === "rising",
-     * );
-     */
-    demandBatch(input: DemandBatchInput, signal?: AbortSignal): Promise<DemandBatchResponse>;
-    /**
-     * THE QUESTION: "may I put these materials in an A-2 corridor in Texas?"
-     *
-     * Badge materials against the advisory building-code registry (POST
-     * `/api/v1/codes/advisory`). Identical to {@link CodesClient.advisory}, kept
-     * flat because it shipped before the `codes` namespace existed — prefer
-     * `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: CodeAdvisoryInput, signal?: AbortSignal): Promise<CodeAdvisoryResponse>;
     /**
      * THE QUESTION: "what colours are in this image?" — the palette only, no
      * materials. The bridge from an inspiration image into the colour lens: extract
@@ -360,68 +312,15 @@ export declare class MaterialGraphClient extends CatalogueClient {
      * {@link MaterialGraphClient.match} for the MATERIALS in the photo.
      */
     extractPalette(input: ExtractPaletteInput, signal?: AbortSignal): Promise<ExtractPaletteResponse>;
-    /**
-     * 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.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
-     * have real product-graph data, each with its top canonical values and the
-     * variants/brands behind them. This is where a caller LEARNS that the data
-     * 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 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>;
     /** "Whose catalogs are in here, and how big is each?" — {@link listBrands}. */
     brands(options?: BrandsOptions, signal?: AbortSignal): Promise<import("./brand-types.js").BrandCatalogListPage>;
     /**
      * Upload one atomic source-material batch (POST `/api/v1/source-material`,
      * multipart). Pass a heterogeneous pile via `{ files }` (any mix of PDF,
-     * text/markdown, and images — the server classifies each) or the legacy
-     * `{ brief, references }` shape. Requires the `mg:ingest` scope.
+     * text/markdown, and images — the server classifies each). Requires the
+     * `mg:source` scope, which a `source`, `ingest` or `admin` key carries.
      */
     uploadSourceMaterial(input: UploadSourceMaterialInput, signal?: AbortSignal): Promise<SourceMaterialBatchReceipt>;
-    /**
-     * Read back an uploaded batch (GET `/api/v1/source-material/{batchId}`): every
-     * file with a fetchable `url` and its analyses inlined. `analyses` is always
-     * an array — `[]` means nothing has been computed yet. Analyses are shared by
-     * content hash, so re-uploading an already-analysed image returns its analysis
-     * immediately. A batch you do not own raises the same 404 as one that does not
-     * exist. Requires the `mg:compose` scope.
-     */
-    sourceMaterialBatch(batchId: BatchId, signal?: AbortSignal): Promise<SourceMaterialBatchDetail>;
-    /**
-     * 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). 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.
-     */
-    run(runId: RunId, signal?: AbortSignal): Promise<PublicRunResponse>;
     /** Follow a verdict cell's citation handle to its canonical claim source. */
     citation(citationId: string, signal?: AbortSignal): Promise<ResolvedVerdictCitation>;
-    /**
-     * 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>;
-    /**
-     * 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: RunId, options: DrainRunEventsOptions): Promise<RunEvent[]>;
 }