@instruments/materialgraph 0.7.1 → 0.9.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,139 @@
+/**
+ * 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;
+}
+/**
+ * Receipt for the colour-identity collapse that turns a variant-grain ranking
+ * into a page of TILES — one per (brand, product, dominant hex), one per stored
+ * photograph. The live endpoint always sends it; it is optional here only so
+ * responses captured before the collapse existed still type-check.
+ */
+export interface ColourCollapse {
+    /** Ranked rows the collapse examined — this page's pool, never a corpus total. */
+    considered: number;
+    /** Rows dropped for repeating a better-ranked row's brand, product and hex. */
+    droppedByIdentity: number;
+    /** Rows dropped for resolving to a better-ranked row's stored photograph. */
+    droppedBySharedImage: 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;
+    /**
+     * What the colour-identity collapse cost this page. Matches are TILES: a page
+     * can be SHORTER than `limit` when the pool collapsed harder than the
+     * overfetch allowed, and this says so in counts rather than adjectives.
+     */
+    collapse?: ColourCollapse;
+}
+/** 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/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,15 @@ 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, PairingsOptions, PairingsResponse, ResolveAttributeOptions, ResolveAttributeResponse, ResolveAttributeValueOptions, ResolveAttributeValueResponse, ResolveColourResponse, SearchGetParams, SearchInput, SearchResponse, SiblingsResponse, SpecFacetsDistributionResponse, SpecFacetsListResponse, SuggestColourResponse, SuggestOptions, SuggestResponse, TaxonomyResponse, VocabularySearchOptions, WhoamiResponse } from "./types.js";
+import type { MatchInput, MatchResponse } from "./match-types.js";
 /**
  * The MaterialGraph client — every lens on the graph, on one object.
  *
@@ -38,18 +33,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 +172,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 +237,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 +324,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
@@ -531,6 +534,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

package/client.js

@@ -1,33 +1,20 @@
 import { MaterialGraphError } from "./errors.js";
 import { HttpTransport } from "./http-transport.js";
-import { findSdkOperation } from "./operations.js";
-import { cancelRun, capabilities as capabilitiesRun, createRun, drainRunEvents, getRun, getRunSchedule, getSourceMaterialBatch as getSourceMaterialBatchCall, resumeRun, streamRunEvents, uploadSourceMaterial, } from "./runs.js";
+// Aliased to `operation` — the local name every call site here already used.
+import { resolveOperation as operation } from "./operations.js";
+import { cancelRun, capabilities as capabilitiesRun, createRun, drainRunEvents, getRun, getRunSchedule, getSourceMaterialBatch as getSourceMaterialBatchCall, listRuns, resumeRun, streamRunEvents, uploadSourceMaterial, } from "./runs.js";
+import { DEFAULT_BASE_URL, MAX_BATCH_IDS } from "./client-config.js";
+// Re-exported whole so `index.ts` and every existing importer keep their path.
+export * from "./client-config.js";
 import { browseQuery, createBrowseNamespace } from "./client-browse.js";
 import { suggestQuery } from "./suggest-types.js";
 import { matchStream as matchStreamCall } from "./match-stream.js";
 import { appendProjectEvent as appendProjectEventCall, createProject as createProjectCall, getProject as getProjectCall, listProjects as listProjectsCall, } from "./projects.js";
 import { CodesClient } from "./codes-client.js";
 import { ColoursClient } from "./colours-client.js";
-export const DEFAULT_BASE_URL = "https://beta.materialgraph.com";
-export const MAX_BATCH_IDS = 100;
-const SCHEMA_RESOURCE_OPERATION_IDS = {
-    blocks: "list_schema_blocks",
-    attributes: "list_schema_attributes",
-    verticals: "list_schema_verticals",
-    productTypes: "list_schema_product_types",
-    units: "list_schema_units",
-    valueDictionaries: "list_schema_value_dictionaries",
-    sourceRequirements: "list_schema_source_requirements",
-    productTypeTemplates: "list_schema_product_type_templates",
-    mappings: "list_schema_mappings",
-};
-function operation(operationId) {
-    const match = findSdkOperation(operationId);
-    if (!match) {
-        throw MaterialGraphError.unexpected(`Unknown SDK operation: ${operationId}`);
-    }
-    return match;
-}
+import { resolvePhrasesRequest, searchVocabularyRequest } from "./resolve-client.js";
+import { declaredFinishes, declaredProducts } from "./associations-client.js";
+import { SCHEMA_RESOURCE_OPERATION_IDS } from "./schema-resource-types.js";
 /**
  * The MaterialGraph client — every lens on the graph, on one object.
  *
@@ -41,18 +28,25 @@ function operation(operationId) {
  * | "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.
@@ -208,6 +202,8 @@ export 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, signal) {
         return this.#get("search_by_colour", {
@@ -217,6 +213,7 @@ export class MaterialGraphClient {
             a: params.a,
             b: params.b,
             category: params.category,
+            family: params.family,
             limit: params.limit,
         }, signal);
     }
@@ -298,6 +295,14 @@ export class MaterialGraphClient {
             variantId,
         });
     }
+    /** "What finishes does the manufacturer declare for THIS product?" — {@link declaredFinishes}. */
+    associatedFinishes(variantId, options, signal) {
+        return declaredFinishes(this.#transport, variantId, options, signal);
+    }
+    /** "What products does the manufacturer declare THIS finish for?" — {@link declaredProducts}. */
+    associatedProducts(variantId, options, signal) {
+        return declaredProducts(this.#transport, variantId, options, signal);
+    }
     materials(ids, options, signal) {
         if (ids.length > MAX_BATCH_IDS) {
             throw MaterialGraphError.unexpected(`MaterialGraphClient.materials(): at most ${MAX_BATCH_IDS} ids per call, received ${ids.length}. Split into multiple batches.`);
@@ -379,16 +384,13 @@ export class MaterialGraphClient {
     resolveAttributeValue(attributeId, query, options, signal) {
         return this.#get("catalog_resolve_value", { q: query, limit: options?.limit }, signal, { attributeId });
     }
-    /**
-     * 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.
-     */
+    /** "Is this phrase an attribute or a value?" — see {@link searchVocabularyRequest}. */
     searchVocabulary(query, options, signal) {
-        return this.#get("catalog_vocabulary_search", { q: query, limit: options?.limit, kind: options?.kind }, signal);
+        return searchVocabularyRequest(this.#transport, query, options, signal);
+    }
+    /** "I have words — what do they mean in YOUR vocabulary?" — see {@link resolvePhrasesRequest}. */
+    resolve(phrases, signal) {
+        return resolvePhrasesRequest(this.#transport, phrases, signal);
     }
     /**
      * THE QUESTION: "which materials, from ANYONE, are ASTM E84 Class A AND
@@ -645,6 +647,18 @@ export class MaterialGraphClient {
     run(runId, signal) {
         return getRun(this.#transport, runId, signal);
     }
+    /**
+     * THE QUESTION: "which Runs are mine?" — your own Runs, newest first, paged
+     * (GET `/api/v1/runs`). This is how a client that lost a Run id finds its work
+     * again: `{ status: "suspended" }` returns the Runs still waiting on an
+     * answer, whose ids you can then feed to {@link MaterialGraphClient.resumeRun}.
+     *
+     * Only your own Runs are ever returned. Page by following `nextCursor` until
+     * it is ABSENT — a full page is not the signal to stop.
+     */
+    listRuns(options) {
+        return listRuns(this.#transport, options);
+    }
     /**
      * Export a completed compose Run's scheme as a finish schedule — one row per
      * slot, every attribute value carrying its source and verification state