@instruments/materialgraph 0.7.0 → 0.8.0

package/association-types.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Wire types for the DECLARED FF&E association reads
+ * (`GET /api/v1/associated/finishes`, `GET /api/v1/associated/products`).
+ *
+ * THE AUTHORITY ON "THE MANUFACTURER SAID SO". Every other relationship lens in
+ * this SDK is inference: `pairings` reads order and board activity, `search
+ * ({ similarTo })` reads appearance. These two reads are the only ones carrying
+ * a compatibility the manufacturer themselves enumerated — this fabric is
+ * genuinely available on this chair — and the shapes deliberately share no field
+ * with {@link PairingItem}, so the two can never be concatenated into one list.
+ * Present them as separate sections, and never describe a pairing as available.
+ */
+import type { Cursor, VariantId } from "./identifiers.js";
+/**
+ * Why an association is believed.
+ *
+ * Every field is ALWAYS present. `confidence` is a FIXED convention value (0.9)
+ * that the ingest writes on every manufacturer-declared edge — it is not a
+ * measurement, it does not vary between edges, and it must never be shown as a
+ * score or used to rank. Declared associations carry no ranking at all: that is
+ * the point of them.
+ */
+export interface DeclaredProvenance {
+    /** The stored convention value (0.9 today). Never a per-edge measurement. */
+    confidence: number;
+    /** The manufacturer enumerated this association in their own catalog data. */
+    basis: "manufacturer_declared";
+    /** The provenance recorded on the edge — the manufacturer catalog feed. */
+    source: "warehouse";
+}
+/** The material the question was asked about, resolved to its identity. */
+export interface DeclaredAssociationSubject {
+    variantId: VariantId;
+    brand: string;
+    product: string;
+    /** The variant's own name; null when it is unnamed. */
+    variantName: string | null;
+}
+/** One declared association, plus why it is believed. */
+export interface DeclaredAssociation {
+    variantId: VariantId;
+    brand: string;
+    product: string;
+    variantName: string | null;
+    /** Canonical thumbnail; null when the variant has no eligible image. */
+    imageUrl: string | null;
+    declared: DeclaredProvenance;
+}
+/**
+ * One page of declared associations.
+ *
+ * READ `totalAssociations`, NOT `associations.length`, when rendering a count
+ * like "Compatible Finishes (128)": the array is one page (up to 48), the total
+ * is the whole set for this subject, direction and corpus. A page is not a
+ * corpus — walk `nextCursor` before making any claim about the full set.
+ */
+export interface DeclaredAssociationsResponse {
+    subject: DeclaredAssociationSubject;
+    /**
+     * Constant discriminator. Its presence is how a caller tells a declared fact
+     * from the inferred `/pairings` rail — check it before merging anything.
+     */
+    kind: "declared_association";
+    associations: DeclaredAssociation[];
+    /** The TRUE count for this subject, direction and corpus. Not the page size. */
+    totalAssociations: number;
+    /** How many associations this page carries. */
+    returnedCount: number;
+    /** Present only when another page exists; pass back verbatim as `cursor`. */
+    nextCursor?: Cursor;
+}
+/** Options for a declared-association read. */
+export interface AssociatedOptions {
+    /**
+     * Page size, 1–48 inclusive (default 24). The server rejects (400), not
+     * clamps, values outside this range.
+     */
+    limit?: number;
+    /**
+     * Orderability scope. `material_bank` returns only associations pointing at a
+     * variant carrying a Material Bank SKU — the ones a caller can actually
+     * order. Today every visible variant carries one, so this currently removes
+     * nothing; it tracks orderability rather than a snapshot of it.
+     */
+    corpus?: "all" | "material_bank";
+    /**
+     * The previous response's `nextCursor`, passed back verbatim. A cursor is
+     * bound to its subject, direction and corpus — replaying it against a
+     * different one is a 400, never a silently different page.
+     */
+    cursor?: Cursor;
+}

package/association-types.js

@@ -0,0 +1 @@
+export {};

package/associations-client.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The DECLARED-association lens: `GET /api/v1/associated/finishes` and
+ * `GET /api/v1/associated/products`, as thin wrappers over the shared
+ * {@link HttpTransport}. `MaterialGraphClient.associatedFinishes` /
+ * `.associatedProducts` delegate here; the contract lives in this file.
+ *
+ * DECLARED IS NOT INFERRED — the rule this whole lens exists to make
+ * unmissable. These two reads return compatibility the MANUFACTURER stated
+ * ("this fabric is available on this chair"); `pairings()` returns
+ * companionship the graph INFERRED from orders, boards and colour. The two
+ * response shapes share no field, on purpose: render them as separate
+ * sections, never concatenate them, and never describe a pairing as
+ * "available on".
+ */
+import type { AssociatedOptions, DeclaredAssociationsResponse } from "./association-types.js";
+import { HttpTransport } from "./http-transport.js";
+import type { VariantId } from "./identifiers.js";
+/**
+ * THE QUESTION: "what finishes can I get on THIS chair?" — the fabrics,
+ * leathers and surfaces the MANUFACTURER declares are available on a product
+ * variant (GET `/api/v1/associated/finishes`).
+ *
+ * Instead use `pairings()` for what merely GOES WITH something (inference from
+ * orders, boards and colour) and `siblings()` for the same product in another
+ * colourway. These are the only relationships the manufacturer themselves
+ * stated: `kind` is always `"declared_association"`, and the shape shares no
+ * field with a pairing — see the module docblock for why that matters.
+ *
+ * Every association carries `declared` in full: `basis`, `source`, and a
+ * `confidence` that is a FIXED 0.9 convention, not a measurement — never rank
+ * by it or render it as a score. Render counts from `totalAssociations` (the
+ * true total), never `associations.length` (one page, up to 48).
+ *
+ * @param variantId The PRODUCT variant. Opaque — pass back exactly what you were given.
+ */
+export declare function declaredFinishes(transport: HttpTransport, variantId: VariantId, options?: AssociatedOptions, signal?: AbortSignal): Promise<DeclaredAssociationsResponse>;
+/**
+ * THE QUESTION: "what furniture takes THIS fabric?" — the products the
+ * MANUFACTURER declares a finish variant is available on (GET
+ * `/api/v1/associated/products`).
+ *
+ * The exact reverse of {@link declaredFinishes} over one stored relationship,
+ * so the two directions can never disagree. Everything in that function's
+ * contract applies here: declared, never inferred; `declared` is always
+ * present and its `confidence` is a fixed 0.9 convention; read
+ * `totalAssociations` for a count and walk `nextCursor` before claiming
+ * anything about the whole set.
+ *
+ * @param variantId The FINISH variant. Opaque — pass back exactly what you were given.
+ */
+export declare function declaredProducts(transport: HttpTransport, variantId: VariantId, options?: AssociatedOptions, signal?: AbortSignal): Promise<DeclaredAssociationsResponse>;

package/associations-client.js

@@ -0,0 +1,40 @@
+import { HttpTransport } from "./http-transport.js";
+import { resolveOperation } from "./operations.js";
+/**
+ * THE QUESTION: "what finishes can I get on THIS chair?" — the fabrics,
+ * leathers and surfaces the MANUFACTURER declares are available on a product
+ * variant (GET `/api/v1/associated/finishes`).
+ *
+ * Instead use `pairings()` for what merely GOES WITH something (inference from
+ * orders, boards and colour) and `siblings()` for the same product in another
+ * colourway. These are the only relationships the manufacturer themselves
+ * stated: `kind` is always `"declared_association"`, and the shape shares no
+ * field with a pairing — see the module docblock for why that matters.
+ *
+ * Every association carries `declared` in full: `basis`, `source`, and a
+ * `confidence` that is a FIXED 0.9 convention, not a measurement — never rank
+ * by it or render it as a score. Render counts from `totalAssociations` (the
+ * true total), never `associations.length` (one page, up to 48).
+ *
+ * @param variantId The PRODUCT variant. Opaque — pass back exactly what you were given.
+ */
+export function declaredFinishes(transport, variantId, options, signal) {
+    return transport.requestJson(resolveOperation("list_associated_finishes"), { query: { variantId, ...options }, signal });
+}
+/**
+ * THE QUESTION: "what furniture takes THIS fabric?" — the products the
+ * MANUFACTURER declares a finish variant is available on (GET
+ * `/api/v1/associated/products`).
+ *
+ * The exact reverse of {@link declaredFinishes} over one stored relationship,
+ * so the two directions can never disagree. Everything in that function's
+ * contract applies here: declared, never inferred; `declared` is always
+ * present and its `confidence` is a fixed 0.9 convention; read
+ * `totalAssociations` for a count and walk `nextCursor` before claiming
+ * anything about the whole set.
+ *
+ * @param variantId The FINISH variant. Opaque — pass back exactly what you were given.
+ */
+export function declaredProducts(transport, variantId, options, signal) {
+    return transport.requestJson(resolveOperation("list_associated_products"), { query: { variantId, ...options }, signal });
+}

package/by-colour-types.d.ts

@@ -0,0 +1,119 @@
+/**
+ * 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.
+ */
+import type { VariantId } from "./identifiers.js";
+import type { OklabTriple, PaletteSwatch } from "./types.js";
+/** Coarse group + fine type of a colour match's primary product type. */
+export interface MatchCategory {
+    group: string | null;
+    type: string | null;
+}
+/**
+ * One colour-palette match.
+ *
+ * `hex`, `distance` and `closeness` are OKLab geometry over colour EXTRACTED
+ * FROM PRODUCT IMAGERY, not declared by the manufacturer. Report it as visual
+ * likeness ("reads close to this colour"), never as a stated colour
+ * specification.
+ */
+export interface ByColourMatch {
+    /** Opaque — round-trip verbatim. */
+    variantId: VariantId;
+    brand: string;
+    product: string;
+    color: string | null;
+    variantName: string | null;
+    imageUrl: string | null;
+    hex: string | null;
+    distance: number;
+    closeness: number;
+    category: MatchCategory | null;
+    oklab: OklabTriple | null;
+    /**
+     * The match's own image palette — the FULL stored palette, uncapped and in
+     * stored order, each swatch with `oklab` (see {@link ByColourSwatch}), so a
+     * card can render, sort or group colours without a second call. A one-swatch
+     * palette means the extractor found one colour (solid-colour materials are
+     * genuinely monochrome), not that the list was trimmed. ABSENT when no palette
+     * is on record: absent means unknown, NOT that the material has no colours.
+     * Like `hex`, these swatches come from product imagery, not from the
+     * manufacturer.
+     */
+    palette?: ByColourSwatch[];
+}
+/** A {@link PaletteSwatch} on the colour lane, where `oklab` is always derived. */
+export interface ByColourSwatch extends PaletteSwatch {
+    /** `hex` in OKLab — guaranteed present on this surface. */
+    oklab: OklabTriple;
+}
+/**
+ * Receipt for the `family` filter — ABSENT when none was asked for, so absence
+ * means "no gate ran", never "a gate that dropped nothing".
+ */
+export interface ColourFamilyGate {
+    /** The colorscope taxonomy family id the gate kept (normalised). */
+    family: string;
+    /** Candidates the gate examined — the retrieved pool. NOT a corpus total. */
+    considered: number;
+    /**
+     * Candidates the gate rejected — another family, or no readable hex (unknown
+     * is not membership). `considered − matches.length` is not the same number
+     * once the page is cut to `limit`; this is the gate's own cost.
+     */
+    dropped: number;
+}
+/** The `search/colours` response. */
+export interface ByColourResponse {
+    query: {
+        colours: string[];
+        categories?: string[];
+        /** Echoed `family` filter, normalised. Present only when one was applied. */
+        family?: string;
+        oklab?: OklabTriple;
+    };
+    /** `matches.length` — THIS PAGE. Not a corpus total; this surface states none. */
+    count: number;
+    matches: ByColourMatch[];
+    /**
+     * Present only when `family` was asked for. A gated page can be SHORTER than
+     * `limit` — the gate runs over a retrieved pool, not the corpus — and this is
+     * what says so in counts rather than adjectives.
+     */
+    familyGate?: ColourFamilyGate;
+}
+/** Params for `search/colours`. */
+export interface ByColourParams {
+    /** A single hex (with or without `#`). */
+    hex?: string;
+    /** A palette — repeated as one `colour` query entry each. */
+    colour?: string | string[];
+    /** OKLab triple (all-or-none). */
+    l?: number;
+    a?: number;
+    b?: number;
+    /** HARD category filter — display names or taxonomy ids (repeatable). */
+    category?: string | string[];
+    /**
+     * HARD colour-family filter — ONE colorscope taxonomy family id, from the
+     * closed 15-value vocabulary colorscope itself publishes (`white`, `cream`,
+     * `gray`, `black`, `beige`, `taupe`, `brown`, `red`, `orange`, `yellow`,
+     * `green`, `teal`, `blue`, `purple`, `pink`). Case-insensitive; anything else
+     * is a 400 listing the vocabulary.
+     *
+     * This is NOT the `colour_family` facet vocabulary from `colourFacets()`, and
+     * NOT a match's stored dominant-family term — those are colorscope's NAMING
+     * families, a different (13-term) list. The family here is assigned from the
+     * match's dominant hex by colorscope's taxonomy ownership rules.
+     *
+     * A filtered page may come back shorter than `limit`: the gate runs over a
+     * retrieved pool, and `familyGate` on the response reports that pool and the
+     * drop.
+     */
+    family?: string;
+    limit?: number;
+}

package/by-colour-types.js

@@ -0,0 +1 @@
+export {};

package/by-spec-types.d.ts

@@ -1,3 +1,4 @@
+import type { ValueResolution } from "./catalog-discovery-types.js";
 import type { VariantId } from "./identifiers.js";
 /**
  * One criterion a match satisfied, with the trust behind it.
@@ -107,6 +108,32 @@ export interface BySpecMatch {
     minConfidence: number | null;
     verdict: BySpecVerdict;
 }
+/**
+ * One criterion the server could not resolve to canonical vocabulary, with the
+ * resolver's ranked suggestions for it.
+ *
+ * `attributeId` and `value` echo the parsed criterion, both of them, so a failed
+ * query can be restated without losing either half. (The HTTP route trims the
+ * attribute and value around the first `:` before validation.) Which HALF failed
+ * is read off `resolution.query`, the token actually resolved:
+ *
+ * - `resolution.query === attributeId` — the attribute id is unknown, and
+ *   `resolution.candidates` are ATTRIBUTE ids.
+ * - `resolution.query === value` — the attribute is known but its value is no
+ *   canonical term, and `resolution.candidates` are TERM ids, each carrying the
+ *   `dictionaryId` it came from.
+ *
+ * EVERY miss is reported, not just the first, so one round trip is enough to fix
+ * a whole spec.
+ */
+export interface BySpecUnresolvedCriterion {
+    /** The parsed attribute id, after the route's surrounding-whitespace trim. */
+    attributeId: string;
+    /** The parsed value — never overwritten by the attribute id when that id is unknown. */
+    value: string;
+    /** Ranked candidates for whichever half failed. See {@link ValueResolution}. */
+    resolution: ValueResolution;
+}
 /**
  * The find-by-spec envelope — A PAGE, AND NOTHING BUT A PAGE.
  *
@@ -116,6 +143,9 @@ export interface BySpecMatch {
  * states NO corpus total, so "N materials meet this specification" is not a
  * claim you can make from one response. Raise `limit`, or say "at least N".
  * `brandsSpanned` is likewise the brand count OF THIS SAMPLE.
+ *
+ * And check `unresolvedCriteria` BEFORE reading any of that: when it is present
+ * the numbers beside it describe a query that never ran.
  */
 export interface BySpecResponse {
     /** The criteria as parsed — check them before trusting a surprising result. */
@@ -129,4 +159,19 @@ export interface BySpecResponse {
     brandsSpanned: number;
     /** The sample, photo-first, capped by `limit`. */
     matches: BySpecMatch[];
+    /**
+     * Present ONLY when a criterion failed exact canonical-vocabulary membership —
+     * and its presence means THE QUERY WAS NEVER RUN. A pre-flight gate short-circuits
+     * before the search, so the rest of the envelope is a placeholder rather than
+     * a finding: `matches` is `[]` and `totalMatches` is `0` because nothing was
+     * searched, not because nothing qualifies. Reporting that zero as "no material
+     * meets this specification" states a fact about the corpus on the strength of
+     * a question nobody asked it.
+     *
+     * Treat these criteria as UNAPPLIED and surface them: retry with a
+     * `resolution.candidates` id (subject to `recommendedAction` — `ambiguous`
+     * means ask, not pick), or say the value could not be resolved. Absent means
+     * every criterion resolved and the query did run.
+     */
+    unresolvedCriteria?: BySpecUnresolvedCriterion[];
 }

package/catalog-discovery-types.d.ts

@@ -24,6 +24,34 @@ export interface ResolveValueCandidate {
     /** Present only for a colour_family candidate resolved via the colorscope fallback. */
     via?: OpenEnum<"colorscope">;
 }
+/**
+ * The resolver's verdict on ONE free-text token — the single shape every
+ * resolving surface speaks, so a caller learns to read it once. Returned whole
+ * by {@link MaterialGraphClient.resolveAttributeValue}, and carried per bad
+ * criterion by `bySpec`'s `unresolvedCriteria`.
+ *
+ * READ `recommendedAction`, NOT JUST `best`. `ambiguous` with a populated
+ * `candidates` list means the phrase genuinely matched several terms — taking
+ * `best` silently there is how a query ends up answering a question nobody
+ * asked. `unresolved` means no candidate cleared the resolver's confidence
+ * threshold (and may still carry weak candidates); it says nothing about how
+ * many materials would match a corrected criterion.
+ *
+ * The resolver ranks, classifies and reports; it never substitutes the nearest
+ * token for the one you asked for. `best` is populated whenever ANY candidate
+ * exists — including under an `ambiguous` or `unresolved` status — so it is a
+ * leader, not a licence.
+ *
+ * `query` is the trimmed token that was actually resolved, which is how you tell
+ * WHICH half of a failed `attribute:value` pair was the problem.
+ */
+export interface ValueResolution {
+    status: OpenEnum<"resolved" | "ambiguous" | "unresolved">;
+    query: string;
+    best: ResolveValueCandidate | null;
+    candidates: ResolveValueCandidate[];
+    recommendedAction: OpenEnum<"use_best" | "choose_from_candidates" | "ask_user" | "none_found">;
+}
 /** Response from resolving a free-text value against one attribute's dictionary. */
 export interface ResolveAttributeValueResponse {
     attribute: {
@@ -31,20 +59,8 @@ export interface ResolveAttributeValueResponse {
         name: string;
         dictionaryId: string;
     };
-    /**
-     * READ `recommendedAction`, NOT JUST `best`. `ambiguous` with a populated
-     * `candidates` list means the phrase genuinely matched several terms — taking
-     * `best` silently there is how a query ends up answering a question nobody
-     * asked. `unresolved` means the vocabulary holds nothing like it, which is not
-     * the same as the corpus holding no such materials.
-     */
-    resolution: {
-        status: OpenEnum<"resolved" | "ambiguous" | "unresolved">;
-        query: string;
-        best: ResolveValueCandidate | null;
-        candidates: ResolveValueCandidate[];
-        recommendedAction: OpenEnum<"use_best" | "choose_from_candidates" | "ask_user" | "none_found">;
-    };
+    /** The verdict on `q`. Read `recommendedAction` — see {@link ValueResolution}. */
+    resolution: ValueResolution;
 }
 /** Options for searching registry attributes and value-dictionary terms together. */
 export interface VocabularySearchOptions {

package/client-config.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Construction-time configuration for {@link MaterialGraphClient} and the two
+ * published constants callers read off it. Split out of `client.ts` so the
+ * client file carries lenses rather than setup.
+ */
+/** The hosted API origin the client talks to unless `baseUrl` overrides it. */
+export declare const DEFAULT_BASE_URL = "https://beta.materialgraph.com";
+/** The server's per-call ceiling on batch material lookups, enforced client-side. */
+export declare const MAX_BATCH_IDS = 100;
+export interface MaterialGraphClientOptions {
+    /** A `mg_read_*` API key, presented as `Authorization: Bearer <key>`. */
+    apiKey: string;
+    /** Override the API origin. Defaults to {@link DEFAULT_BASE_URL}. */
+    baseUrl?: string;
+    /** Inject a custom `fetch` (tests, proxies). Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+}

package/client-config.js

@@ -0,0 +1,9 @@
+/**
+ * Construction-time configuration for {@link MaterialGraphClient} and the two
+ * published constants callers read off it. Split out of `client.ts` so the
+ * client file carries lenses rather than setup.
+ */
+/** The hosted API origin the client talks to unless `baseUrl` overrides it. */
+export const DEFAULT_BASE_URL = "https://beta.materialgraph.com";
+/** The server's per-call ceiling on batch material lookups, enforced client-side. */
+export const MAX_BATCH_IDS = 100;

package/client.d.ts

@@ -1,7 +1,9 @@
 import { type RateLimit } from "./errors.js";
+import type { MaterialGraphClientOptions } from "./client-config.js";
+export * from "./client-config.js";
 import { type BrowseNamespace } from "./client-browse.js";
 export type { BrowseNamespace } from "./client-browse.js";
-import type { CapabilityManifestResponse, CreatePublicRunRequest, CreatePublicRunResponse, DrainRunEventsOptions, PublicRunResponse, ResumeRunOptions, RunEvent, SourceMaterialBatchDetail, SourceMaterialBatchReceipt, StreamRunEventsOptions, UploadSourceMaterialInput } from "./run-types.js";
+import type { CapabilityManifestResponse, CreatePublicRunRequest, CreatePublicRunResponse, DrainRunEventsOptions, ListRunsOptions, PublicRunListResponse, PublicRunResponse, ResumeRunOptions, RunEvent, SourceMaterialBatchDetail, SourceMaterialBatchReceipt, StreamRunEventsOptions, UploadSourceMaterialInput } from "./run-types.js";
 import type { FinishScheduleResponse, GetRunScheduleOptions } from "./schedule-types.js";
 import type { MatchStreamEvent } from "./match-stream-types.js";
 import type { AppendProjectEventRequest, CreateProjectRequest, ProjectEventReceipt, ProjectListResponse, ProjectState } from "./project-types.js";
@@ -9,22 +11,14 @@ import type { VarySchemesRequest, VarySchemesResponse } from "./composition-type
 import { CodesClient } from "./codes-client.js";
 import { ColoursClient } from "./colours-client.js";
 import type { CodeAdvisoryInput, CodeAdvisoryResponse } from "./codes-types.js";
+import type { AssociatedOptions } from "./association-types.js";
 import type { BrandCatalogListPage, BrandsOptions } from "./brand-types.js";
 import type { MaterialAssetProjection } from "./material-asset-types.js";
 import type { MaterialBlockProjection } from "./material-block-types.js";
 import type { SchemaResource, SchemaResourceResponse } from "./schema-resource-types.js";
 import type { BatchId, ProjectId, RunId, VariantId } from "./identifiers.js";
-import type { ApplicableSpecsResponse, BrandOptions, BrandProfileResponse, ByColourParams, ByColourResponse, BySpecOptions, BySpecResponse, ColourFacetsResponse, CoordinateInput, CoordinateResponse, DemandBatchInput, DemandBatchResponse, DemandParams, DemandResponse, ExtractPaletteInput, ExtractPaletteResponse, GlossaryTermResponse, MaterialResponse, MaterialsBatchDetailResponse, MaterialsBatchGetOptions, MaterialsBatchOptions, MaterialsBatchTileResponse, MatchInput, MatchResponse, PairingsOptions, PairingsResponse, ResolveAttributeOptions, ResolveAttributeResponse, ResolveAttributeValueOptions, ResolveAttributeValueResponse, ResolveColourResponse, SearchGetParams, SearchInput, SearchResponse, SiblingsResponse, SpecFacetsDistributionResponse, SpecFacetsListResponse, SuggestColourResponse, SuggestOptions, SuggestResponse, TaxonomyResponse, VocabularySearchOptions, VocabularySearchResponse, WhoamiResponse } from "./types.js";
-export declare const DEFAULT_BASE_URL = "https://beta.materialgraph.com";
-export declare const MAX_BATCH_IDS = 100;
-export interface MaterialGraphClientOptions {
-    /** A `mg_read_*` API key, presented as `Authorization: Bearer <key>`. */
-    apiKey: string;
-    /** Override the API origin. Defaults to {@link DEFAULT_BASE_URL}. */
-    baseUrl?: string;
-    /** Inject a custom `fetch` (tests, proxies). Defaults to the global `fetch`. */
-    fetch?: typeof fetch;
-}
+import type { ByColourParams, ByColourResponse } from "./by-colour-types.js";
+import type { ApplicableSpecsResponse, BrandOptions, BrandProfileResponse, BySpecOptions, BySpecResponse, ColourFacetsResponse, CoordinateInput, CoordinateResponse, DemandBatchInput, DemandBatchResponse, DemandParams, DemandResponse, ExtractPaletteInput, ExtractPaletteResponse, GlossaryTermResponse, MaterialResponse, MaterialsBatchDetailResponse, MaterialsBatchGetOptions, MaterialsBatchOptions, MaterialsBatchTileResponse, MatchInput, MatchResponse, PairingsOptions, PairingsResponse, ResolveAttributeOptions, ResolveAttributeResponse, ResolveAttributeValueOptions, ResolveAttributeValueResponse, ResolveColourResponse, SearchGetParams, SearchInput, SearchResponse, SiblingsResponse, SpecFacetsDistributionResponse, SpecFacetsListResponse, SuggestColourResponse, SuggestOptions, SuggestResponse, TaxonomyResponse, VocabularySearchOptions, WhoamiResponse } from "./types.js";
 /**
  * The MaterialGraph client — every lens on the graph, on one object.
  *
@@ -38,18 +32,25 @@ export interface MaterialGraphClientOptions {
  * | "which materials, from anyone, meet this hard spec?" | {@link MaterialGraphClient.bySpec} |
  * | "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 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} |
+ * | "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` |
  *
- * Two structural rules that fall out of that table:
+ * Three structural rules that fall out of that table:
  * - **Colour is a separate lens.** {@link MaterialGraphClient.search} matches
  *   WORDS. A colour word in `text` finds materials whose text mentions it, not
  *   materials that look it. Route visual intent to the colour lenses.
  * - **Relationships hang off a material, not off a query.** You cannot ask "what
  *   pairs with beige oak"; you resolve a material first, then ask what pairs
  *   with THAT `variantId`.
+ * - **Declared is not inferred.** `associatedFinishes()` /
+ *   `associatedProducts()` return compatibility the MANUFACTURER stated;
+ *   `pairings()` returns companionship the graph INFERRED. The response shapes
+ *   share no field, on purpose — render them as separate sections and never
+ *   concatenate them.
  *
  * And three reading rules that apply to every lens: ids are opaque (see
  * `./identifiers.ts`), absent is not false, and a page is not a corpus.
@@ -170,6 +171,8 @@ export declare class MaterialGraphClient {
      * {@link MaterialGraphClient.browse} to walk by lightness/vividness, and
      * {@link MaterialGraphClient.search} when colour is one signal among many.
      * Report matches as visual likeness, never a stated colour specification.
+     * `family` gates the answer to ONE colorscope colour family when nearness
+     * alone crosses a hue boundary; a gated page can be shorter than `limit`.
      */
     byColour(params: ByColourParams, signal?: AbortSignal): Promise<ByColourResponse>;
     /**
@@ -233,6 +236,10 @@ export declare class MaterialGraphClient {
      * you how much of the rail is real order evidence.
      */
     pairings(variantId: VariantId, options?: PairingsOptions, signal?: AbortSignal): Promise<PairingsResponse>;
+    /** "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>;
     /**
      * THE QUESTION: "hydrate these ids I already hold" (POST
      * `/api/v1/materials/batch`, ≤ 100 ids) — never a discovery call. Throws
@@ -316,15 +323,10 @@ export declare class MaterialGraphClient {
      * not invent it.
      */
     resolveAttributeValue(attributeId: string, query: string, options?: ResolveAttributeValueOptions, signal?: AbortSignal): Promise<ResolveAttributeValueResponse>;
-    /**
-     * THE QUESTION: "is 'FloorScore' an attribute or a value, and what is it called
-     * here?" The catch-all when you do not know which half of an `attribute:value`
-     * pair a phrase belongs to. Instead use
-     * {@link MaterialGraphClient.resolveAttribute} /
-     * {@link MaterialGraphClient.resolveAttributeValue} once you do, and
-     * {@link MaterialGraphClient.glossary} to EXPLAIN a term rather than find it.
-     */
-    searchVocabulary(query: string, options?: VocabularySearchOptions, signal?: AbortSignal): Promise<VocabularySearchResponse>;
+    /** "Is this phrase an attribute or a value?" — see {@link searchVocabularyRequest}. */
+    searchVocabulary(query: string, options?: VocabularySearchOptions, signal?: AbortSignal): Promise<import("./catalog-discovery-types.js").VocabularySearchResponse>;
+    /** "I have words — what do they mean in YOUR vocabulary?" — see {@link resolvePhrasesRequest}. */
+    resolve(phrases: string[], signal?: AbortSignal): Promise<import("./resolve-types.js").ResolveResponse>;
     /**
      * THE QUESTION: "which materials, from ANYONE, are ASTM E84 Class A AND
      * GREENGUARD-certified?" — hard specifications, no ranking, every brand at once
@@ -333,7 +335,10 @@ export declare class MaterialGraphClient {
      * Instead use `search({ filters })` when the spec merely GATES a ranked
      * question, `codes.advisory()` when the real question is what a space demands,
      * and {@link MaterialGraphClient.specificationFacets} first if you do not know
-     * the canonical tokens — guessing one returns an honest, empty answer.
+     * the canonical tokens. Guessing one no longer returns a silently empty
+     * answer: an unresolvable criterion means the query NEVER RAN, and the
+     * response says so — read {@link BySpecResponse.unresolvedCriteria} before
+     * treating an empty `matches` as "nothing qualifies".
      *
      * A PAGE, NOT A CORPUS, unusually so: `totalMatches` is the size of the
      * returned sample under `limit`, not a corpus count. See {@link BySpecResponse}.
@@ -528,6 +533,16 @@ export declare class MaterialGraphClient {
      * asking you something (see {@link MaterialGraphClient.resumeRun}).
      */
     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