@instruments/materialgraph 0.2.0 → 0.4.0

package/by-spec-types.d.ts

@@ -0,0 +1,73 @@
+export interface BySpecMatchedCell {
+    attributeId: string;
+    confidence: number | null;
+    sourceBasis: string | null;
+}
+/** The six states a verdict cell can report; open per the response-enum policy. */
+export type BySpecVerdictState = "matched" | "deviated" | "failed" | "unverified" | "missing" | "not_evaluated";
+/**
+ * One cell of a match's report card — how a single requested criterion scored.
+ * Hand-mirrors the `AttributeVerdict` contract from `@materialgraph/contracts`;
+ * the OpenAPI `CatalogBySpecResponse` schema is the source of truth on the wire.
+ */
+export interface BySpecVerdictCell {
+    attributeId: string;
+    state: BySpecVerdictState;
+    strength: "required" | "preferred";
+    baseline: {
+        kind: "term";
+        term: string;
+    } | {
+        kind: "presence";
+    } | {
+        kind: "seed";
+        variantId: string;
+    } | {
+        kind: "image";
+        source: "variant" | "vector";
+        variantId: string | null;
+    };
+    value: string | null;
+    deviation: {
+        direction: "above" | "below" | "other";
+        delta: number | null;
+        unit: string | null;
+        label: string;
+    } | null;
+    confidence: number | null;
+    sourceBasis: string | null;
+    trustGap: "below_confidence" | "basis_unmet" | "proposed" | null;
+}
+/** A match's full report card: every cell, the rolled-up grade, weakest confidence. */
+export interface BySpecVerdict {
+    cells: BySpecVerdictCell[];
+    grade: "meets_all" | "close" | "hard_no";
+    minConfidence: number | null;
+}
+/**
+ * The verdict a materials-search hit carries (MG-625). It IS the shared
+ * {@link BySpecVerdict} shape — the single CandidateVerdict mirror — aliased here
+ * so search-surface code can name it for what it is rather than duplicating it.
+ */
+export type MaterialVerdict = BySpecVerdict;
+export interface BySpecMatch {
+    variantId: string;
+    brand: string;
+    product: string;
+    variant: string;
+    color: string | null;
+    imageUrl: string | null;
+    hex: string | null;
+    matched: BySpecMatchedCell[];
+    minConfidence: number | null;
+    verdict: BySpecVerdict;
+}
+export interface BySpecResponse {
+    criteria: Array<{
+        attribute: string;
+        value: string;
+    }>;
+    totalMatches: number;
+    brandsSpanned: number;
+    matches: BySpecMatch[];
+}

package/by-spec-types.js

@@ -0,0 +1,7 @@
+// ── Catalog / spec — find-by-spec wire types ─────────────────────────────────
+//
+// Hand-maintained mirror of the `CatalogBySpecResponse` OpenAPI schema (the
+// source of truth on the wire); the `sdk-openapi-parity` test gates this against
+// the generated spec. Split out of `types.ts` to keep that file under its growth
+// baseline; re-exported from `types.ts` so importers see no change.
+export {};

package/client-browse.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The `browse` namespace's implementation — the paged colour-ordered walk of the
+ * corpus behind `client.browse(...)` and `client.browse.pages(...)`.
+ *
+ * Lifted out of `client.ts` for the repository's source-file size budget. These
+ * were already private implementations behind a public namespace, so nothing
+ * about the client's surface changes: `client.browse` is still a callable with a
+ * `.pages()` generator, and the class still owns the transport. What moved is
+ * the pagination LOOP, which is the only real logic here and the only part worth
+ * testing on its own.
+ */
+import type { BrowseParams, BrowseResponse } from "./types.js";
+/** `client.browse(...)` — callable for one page, `.pages()` for the whole walk. */
+export interface BrowseNamespace {
+    (params: BrowseParams, signal?: AbortSignal): Promise<BrowseResponse>;
+    pages(params: BrowseParams, signal?: AbortSignal): AsyncGenerator<BrowseResponse, void, unknown>;
+}
+/** Fetch one page. The client supplies this, so the transport stays private. */
+export type BrowsePageFetcher = (params: BrowseParams, signal?: AbortSignal) => Promise<BrowseResponse>;
+/**
+ * The query string for one browse page — the four params the route reads, named
+ * here so the client method and the pagination loop cannot disagree about them.
+ */
+export declare function browseQuery(params: BrowseParams): {
+    sort: BrowseParams["sort"];
+    cursor: BrowseParams["cursor"];
+    limit: BrowseParams["limit"];
+    types: BrowseParams["types"];
+};
+/**
+ * Walk every page from `params.cursor` onward.
+ *
+ * Stops on the first page that reports no next cursor OR comes back empty. Both
+ * conditions matter: a server that keeps handing out a cursor for an exhausted
+ * scan would otherwise spin here forever, and an infinite generator is a hang,
+ * not an error anyone can see.
+ */
+export declare function browsePages(fetchPage: BrowsePageFetcher, params: BrowseParams, signal?: AbortSignal): AsyncGenerator<BrowseResponse, void, unknown>;
+/**
+ * Build the callable-with-`.pages()` object the client exposes as `browse`.
+ *
+ * @example
+ * const page = await client.browse({ sort: "lightest" });
+ * for await (const page of client.browse.pages({ sort: "lightest" })) { … }
+ */
+export declare function createBrowseNamespace(fetchPage: BrowsePageFetcher): BrowseNamespace;

package/client-browse.js

@@ -0,0 +1,42 @@
+/**
+ * The query string for one browse page — the four params the route reads, named
+ * here so the client method and the pagination loop cannot disagree about them.
+ */
+export function browseQuery(params) {
+    return {
+        sort: params.sort,
+        cursor: params.cursor,
+        limit: params.limit,
+        types: params.types,
+    };
+}
+/**
+ * Walk every page from `params.cursor` onward.
+ *
+ * Stops on the first page that reports no next cursor OR comes back empty. Both
+ * conditions matter: a server that keeps handing out a cursor for an exhausted
+ * scan would otherwise spin here forever, and an infinite generator is a hang,
+ * not an error anyone can see.
+ */
+export async function* browsePages(fetchPage, params, signal) {
+    let cursor = params.cursor;
+    for (;;) {
+        const page = await fetchPage({ ...params, cursor }, signal);
+        yield page;
+        if (page.cursor === undefined || page.results.length === 0)
+            return;
+        cursor = page.cursor;
+    }
+}
+/**
+ * Build the callable-with-`.pages()` object the client exposes as `browse`.
+ *
+ * @example
+ * const page = await client.browse({ sort: "lightest" });
+ * for await (const page of client.browse.pages({ sort: "lightest" })) { … }
+ */
+export function createBrowseNamespace(fetchPage) {
+    const browse = (params, signal) => fetchPage(params, signal);
+    browse.pages = (params, signal) => browsePages(fetchPage, params, signal);
+    return browse;
+}

package/client.d.ts

@@ -1,13 +1,19 @@
 import { type RateLimit } from "./errors.js";
-import type { CapabilityManifestResponse, CreatePublicRunRequest, CreatePublicRunResponse, DrainRunEventsOptions, PublicRunResponse, RunEvent, SourceMaterialBatchReceipt, StreamRunEventsOptions, UploadSourceMaterialInput } from "./run-types.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 { 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";
 import type { VarySchemesRequest, VarySchemesResponse } from "./composition-types.js";
+import { CodesClient } from "./codes-client.js";
+import { ColoursClient } from "./colours-client.js";
 import type { CodeAdvisoryInput, CodeAdvisoryResponse } from "./codes-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 { ApplicableSpecsResponse, BrandOptions, BrandProfileResponse, ByColourParams, ByColourResponse, BrowseParams, BrowseResponse, 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, TaxonomyResponse, VocabularySearchOptions, VocabularySearchResponse, WhoamiResponse } from "./types.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 {
@@ -18,14 +24,21 @@ export interface MaterialGraphClientOptions {
     /** Inject a custom `fetch` (tests, proxies). Defaults to the global `fetch`. */
     fetch?: typeof fetch;
 }
-export interface BrowseNamespace {
-    (params: BrowseParams, signal?: AbortSignal): Promise<BrowseResponse>;
-    pages(params: BrowseParams, signal?: AbortSignal): AsyncGenerator<BrowseResponse, void, unknown>;
-}
 export declare class MaterialGraphClient {
     #private;
     readonly baseUrl: string;
     readonly browse: BrowseNamespace;
+    /**
+     * The advisory building-code surface: `codes.context()` to discover the
+     * vocabulary, `codes.requirements()` to state a space, `codes.advisory()` to
+     * badge candidates against it.
+     */
+    readonly codes: CodesClient;
+    /**
+     * The colour AGGREGATE surface: `colours.profiles()` for a category palette,
+     * `colours.stats()` for corpus colour coverage.
+     */
+    readonly colours: ColoursClient;
     constructor(options: MaterialGraphClientOptions);
     get lastRateLimit(): RateLimit | null;
     /**
@@ -42,6 +55,30 @@ export declare class MaterialGraphClient {
     search(input: SearchInput, signal?: AbortSignal): Promise<SearchResponse>;
     searchGet(params: SearchGetParams, signal?: AbortSignal): Promise<SearchResponse>;
     match(input: MatchInput, signal?: AbortSignal): Promise<MatchResponse>;
+    /**
+     * Material Match as a PROGRESSIVE stream — the same POST
+     * `/api/v1/search/match` endpoint negotiated with `Accept:
+     * application/x-ndjson`, which runs the scene workflow (classify → decompose →
+     * one match per surface) and emits an event as each surface resolves. Use this
+     * wherever the user watches a photo come apart; use {@link match} when you only
+     * want the finished answer.
+     *
+     * Iterate it directly — the request opens on the first `next()`:
+     *
+     * ```ts
+     * for await (const event of client.matchStream({ imageBase64 })) {
+     *   if (event.type === "surface") render(event.surface);
+     * }
+     * ```
+     *
+     * Every frame is validated before it is yielded, and the iterator ends only on
+     * a `complete` or `error` event — a truncated connection raises rather than
+     * passing for a short run. `signal` cancels the in-flight request itself, as
+     * does breaking out of the loop; a cancelled stream ends without raising.
+     * Requires an image (`imageBase64` or `imageUrl`); a `vector` input is
+     * buffered-only.
+     */
+    matchStream(input: MatchInput, signal?: AbortSignal): AsyncGenerator<MatchStreamEvent, void, unknown>;
     byColour(params: ByColourParams, signal?: AbortSignal): Promise<ByColourResponse>;
     /** Get a single material's detail record (GET `/api/v1/materials/{variantId}`). */
     material(variantId: string, options?: {
@@ -91,6 +128,18 @@ export declare class MaterialGraphClient {
     suggestColour(q: string, options?: {
         limit?: number;
     }, signal?: AbortSignal): Promise<SuggestColourResponse>;
+    /**
+     * Entity typeahead across products, brands and categories
+     * (GET `/api/v1/search/suggest`). Built for per-keystroke use: one indexed
+     * lookup, no embedding call and no model. Every suggestion carries the
+     * `refId` it resolves to — a product id, a brand slug, or a product-type key
+     * — so selecting one should navigate to that entity rather than re-running
+     * `label` as a search.
+     *
+     * @example
+     * const { suggestions } = await client.suggest("carr", { kind: "product" });
+     */
+    suggest(q: string, options?: SuggestOptions, signal?: AbortSignal): Promise<SuggestResponse>;
     /** Resolve a free-text spec phrase to canonical attribute ids (GET `/api/v1/catalog/attributes/resolve`). */
     resolveAttribute(q: string, options?: ResolveAttributeOptions, signal?: AbortSignal): Promise<ResolveAttributeResponse>;
     /** Resolve a value phrase against one canonical attribute's dictionary. */
@@ -146,26 +195,9 @@ export declare class MaterialGraphClient {
      */
     demandBatch(input: DemandBatchInput, signal?: AbortSignal): Promise<DemandBatchResponse>;
     /**
-     * Badge a set of materials against the advisory building-code registry for one
-     * (jurisdiction, occupancy, space, sprinklered) context (POST
-     * `/api/v1/codes/advisory`, ≤ 48 ids). Every applicable requirement is badged
-     * `meets` / `shortfall` / `unknown` from the material's accepted fire and
-     * slip-resistance facts, in input order. ADVISORY ONLY — every verdict and the
-     * envelope carry the AHJ caveat; this is model code as adopted, never a legal
-     * determination.
-     *
-     * @example
-     * // Badge this scheme's picks for a Texas hospitality fire-code review.
-     * const advisory = await mg.codeAdvisory({
-     *   variantIds: scheme.picks.map((p) => p.variantId),
-     *   jurisdictionId: "us-tx",
-     *   occupancyGroup: "A-2", // assembly — restaurant / bar
-     *   spaceType: "corridor",
-     *   sprinklered: true,
-     * });
-     * const shortfalls = advisory.results.filter((r) =>
-     *   r.requirements.some((req) => req.verdict === "shortfall"),
-     * );
+     * 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.
      */
     codeAdvisory(input: CodeAdvisoryInput, signal?: AbortSignal): Promise<CodeAdvisoryResponse>;
     /** Extract a named colour palette from an uploaded image (POST `/api/v1/search/palettes/extract`). */
@@ -206,14 +238,37 @@ export declare class MaterialGraphClient {
      * `{ brief, references }` shape. Requires the `mg:ingest` scope.
      */
     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: string, signal?: AbortSignal): Promise<SourceMaterialBatchDetail>;
     /** List invocable agents, workflows, and tools (GET `/api/v1/capabilities`). */
     capabilities(signal?: AbortSignal): Promise<CapabilityManifestResponse>;
     /** Start an asynchronous capability Run (POST `/api/v1/runs`). */
     createRun(body: CreatePublicRunRequest, signal?: AbortSignal): Promise<CreatePublicRunResponse>;
     /** Get a Run's current state (GET `/api/v1/runs/{runId}`). */
     run(runId: string, signal?: AbortSignal): Promise<PublicRunResponse>;
-    /** Resume a suspended Run (POST `/api/v1/runs/{runId}/resume`). */
-    resumeRun(runId: string, resumeData: unknown, signal?: AbortSignal): Promise<PublicRunResponse>;
+    /**
+     * Export a completed compose Run's scheme as a finish schedule — one row per
+     * slot, every attribute value carrying its source and verification state
+     * (GET `/api/v1/runs/{runId}/schedule`). Unknown values are explicit
+     * `missing` cells, never blanks. The `.xlsx` form is a direct-URL download:
+     * `GET /api/v1/runs/{runId}/schedule.xlsx` with the same bearer key.
+     */
+    runSchedule(runId: string, options?: GetRunScheduleOptions): Promise<FinishScheduleResponse>;
+    /**
+     * Resume a suspended Run (POST `/api/v1/runs/{runId}/resume`).
+     *
+     * The third argument accepts either an `AbortSignal` (the published form) or
+     * {@link ResumeRunOptions}, whose `stepId` guards against resuming a step the
+     * run has already moved past — the API answers 409 on a mismatch (MG-608).
+     */
+    resumeRun(runId: string, resumeData: unknown, signalOrOptions?: AbortSignal | ResumeRunOptions): Promise<PublicRunResponse>;
     /** Request durable Run cancellation (POST `/api/v1/runs/{runId}/cancel`). */
     cancelRun(runId: string, signal?: AbortSignal): Promise<PublicRunResponse>;
     /**

package/client.js

@@ -1,8 +1,13 @@
 import { MaterialGraphError } from "./errors.js";
 import { HttpTransport } from "./http-transport.js";
 import { findSdkOperation } from "./operations.js";
-import { cancelRun, capabilities as capabilitiesRun, createRun, drainRunEvents, getRun, resumeRun, streamRunEvents, uploadSourceMaterial, } from "./runs.js";
+import { cancelRun, capabilities as capabilitiesRun, createRun, drainRunEvents, getRun, getRunSchedule, getSourceMaterialBatch as getSourceMaterialBatchCall, resumeRun, streamRunEvents, uploadSourceMaterial, } from "./runs.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 = {
@@ -26,6 +31,17 @@ function operation(operationId) {
 export class MaterialGraphClient {
     baseUrl;
     browse;
+    /**
+     * The advisory building-code surface: `codes.context()` to discover the
+     * vocabulary, `codes.requirements()` to state a space, `codes.advisory()` to
+     * badge candidates against it.
+     */
+    codes;
+    /**
+     * The colour AGGREGATE surface: `colours.profiles()` for a category palette,
+     * `colours.stats()` for corpus colour coverage.
+     */
+    colours;
     #transport;
     constructor(options) {
         if (!options.apiKey) {
@@ -37,9 +53,14 @@ export class MaterialGraphClient {
             fetch: options.fetch ?? globalThis.fetch,
         });
         this.baseUrl = this.#transport.baseUrl;
-        const browse = (params, signal) => this.#browsePage(params, signal);
-        browse.pages = (params, signal) => this.#browsePages(params, signal);
-        this.browse = browse;
+        this.browse = createBrowseNamespace((params, signal) => this.#get("search_browse_by_colour", browseQuery(params), signal));
+        this.codes = new CodesClient({
+            get: (operationId, query, signal) => this.#get(operationId, query, signal),
+            post: (operationId, body, signal) => this.#post(operationId, body, signal),
+        });
+        this.colours = new ColoursClient({
+            get: (operationId, query, signal) => this.#get(operationId, query, signal),
+        });
     }
     get lastRateLimit() {
         return this.#transport.lastRateLimit;
@@ -70,6 +91,32 @@ export class MaterialGraphClient {
     match(input, signal) {
         return this.#post("match_material", input, signal);
     }
+    /**
+     * Material Match as a PROGRESSIVE stream — the same POST
+     * `/api/v1/search/match` endpoint negotiated with `Accept:
+     * application/x-ndjson`, which runs the scene workflow (classify → decompose →
+     * one match per surface) and emits an event as each surface resolves. Use this
+     * wherever the user watches a photo come apart; use {@link match} when you only
+     * want the finished answer.
+     *
+     * Iterate it directly — the request opens on the first `next()`:
+     *
+     * ```ts
+     * for await (const event of client.matchStream({ imageBase64 })) {
+     *   if (event.type === "surface") render(event.surface);
+     * }
+     * ```
+     *
+     * Every frame is validated before it is yielded, and the iterator ends only on
+     * a `complete` or `error` event — a truncated connection raises rather than
+     * passing for a short run. `signal` cancels the in-flight request itself, as
+     * does breaking out of the loop; a cancelled stream ends without raising.
+     * Requires an image (`imageBase64` or `imageUrl`); a `vector` input is
+     * buffered-only.
+     */
+    matchStream(input, signal) {
+        return matchStreamCall(this.#transport, input, signal);
+    }
     byColour(params, signal) {
         return this.#get("search_by_colour", {
             hex: params.hex,
@@ -126,25 +173,6 @@ export class MaterialGraphClient {
             idKind: options?.idKind ?? "variantId",
         }, signal);
     }
-    // ── Browse (private impls behind the `browse` namespace) ─────────────────────
-    #browsePage(params, signal) {
-        return this.#get("search_browse_by_colour", {
-            sort: params.sort,
-            cursor: params.cursor,
-            limit: params.limit,
-            types: params.types,
-        }, signal);
-    }
-    async *#browsePages(params, signal) {
-        let cursor = params.cursor;
-        for (;;) {
-            const page = await this.#browsePage({ ...params, cursor }, signal);
-            yield page;
-            if (page.cursor === undefined || page.results.length === 0)
-                return;
-            cursor = page.cursor;
-        }
-    }
     // ── Colour helpers ───────────────────────────────────────────────────────────
     /** The three canonical colour vocabularies with live counts (GET `/api/v1/colours/facets`). */
     colourFacets(signal) {
@@ -158,6 +186,20 @@ export class MaterialGraphClient {
     suggestColour(q, options, signal) {
         return this.#get("suggest_colour_names", { q, limit: options?.limit }, signal);
     }
+    /**
+     * Entity typeahead across products, brands and categories
+     * (GET `/api/v1/search/suggest`). Built for per-keystroke use: one indexed
+     * lookup, no embedding call and no model. Every suggestion carries the
+     * `refId` it resolves to — a product id, a brand slug, or a product-type key
+     * — so selecting one should navigate to that entity rather than re-running
+     * `label` as a search.
+     *
+     * @example
+     * const { suggestions } = await client.suggest("carr", { kind: "product" });
+     */
+    suggest(q, options, signal) {
+        return this.#get("search_suggest", suggestQuery(q, options), signal);
+    }
     // ── Catalog ──────────────────────────────────────────────────────────────────
     /** Resolve a free-text spec phrase to canonical attribute ids (GET `/api/v1/catalog/attributes/resolve`). */
     resolveAttribute(q, options, signal) {
@@ -235,29 +277,12 @@ export class MaterialGraphClient {
     }
     // ── Codes (advisory building-code compliance) ────────────────────────────────
     /**
-     * Badge a set of materials against the advisory building-code registry for one
-     * (jurisdiction, occupancy, space, sprinklered) context (POST
-     * `/api/v1/codes/advisory`, ≤ 48 ids). Every applicable requirement is badged
-     * `meets` / `shortfall` / `unknown` from the material's accepted fire and
-     * slip-resistance facts, in input order. ADVISORY ONLY — every verdict and the
-     * envelope carry the AHJ caveat; this is model code as adopted, never a legal
-     * determination.
-     *
-     * @example
-     * // Badge this scheme's picks for a Texas hospitality fire-code review.
-     * const advisory = await mg.codeAdvisory({
-     *   variantIds: scheme.picks.map((p) => p.variantId),
-     *   jurisdictionId: "us-tx",
-     *   occupancyGroup: "A-2", // assembly — restaurant / bar
-     *   spaceType: "corridor",
-     *   sprinklered: true,
-     * });
-     * const shortfalls = advisory.results.filter((r) =>
-     *   r.requirements.some((req) => req.verdict === "shortfall"),
-     * );
+     * 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.
      */
     codeAdvisory(input, signal) {
-        return this.#post("resolveCodeAdvisory", input, signal);
+        return this.codes.advisory(input, signal);
     }
     // ── Colour helpers (extract) ─────────────────────────────────────────────────
     /** Extract a named colour palette from an uploaded image (POST `/api/v1/search/palettes/extract`). */
@@ -321,6 +346,17 @@ export class MaterialGraphClient {
     uploadSourceMaterial(input, signal) {
         return uploadSourceMaterial(this.#transport, input, signal);
     }
+    /**
+     * 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, signal) {
+        return getSourceMaterialBatchCall(this.#transport, batchId, signal);
+    }
     /** List invocable agents, workflows, and tools (GET `/api/v1/capabilities`). */
     capabilities(signal) {
         return capabilitiesRun(this.#transport, signal);
@@ -333,9 +369,25 @@ export class MaterialGraphClient {
     run(runId, signal) {
         return getRun(this.#transport, runId, signal);
     }
-    /** Resume a suspended Run (POST `/api/v1/runs/{runId}/resume`). */
-    resumeRun(runId, resumeData, signal) {
-        return resumeRun(this.#transport, runId, resumeData, signal);
+    /**
+     * Export a completed compose Run's scheme as a finish schedule — one row per
+     * slot, every attribute value carrying its source and verification state
+     * (GET `/api/v1/runs/{runId}/schedule`). Unknown values are explicit
+     * `missing` cells, never blanks. The `.xlsx` form is a direct-URL download:
+     * `GET /api/v1/runs/{runId}/schedule.xlsx` with the same bearer key.
+     */
+    runSchedule(runId, options) {
+        return getRunSchedule(this.#transport, runId, options);
+    }
+    /**
+     * Resume a suspended Run (POST `/api/v1/runs/{runId}/resume`).
+     *
+     * The third argument accepts either an `AbortSignal` (the published form) or
+     * {@link ResumeRunOptions}, whose `stepId` guards against resuming a step the
+     * run has already moved past — the API answers 409 on a mismatch (MG-608).
+     */
+    resumeRun(runId, resumeData, signalOrOptions) {
+        return resumeRun(this.#transport, runId, resumeData, signalOrOptions);
     }
     /** Request durable Run cancellation (POST `/api/v1/runs/{runId}/cancel`). */
     cancelRun(runId, signal) {

package/codes-client.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The advisory building-code surface, namespaced as `mg.codes`.
+ *
+ * Three calls that are one workflow — discover the vocabulary, state the space,
+ * then badge candidates against it — so they live together rather than as three
+ * flat methods on an already-large client facade. `mg.browse` set the precedent
+ * for a namespace when a capability is a small family rather than a single verb.
+ *
+ * The namespace holds no transport of its own: the client hands it bound
+ * `get`/`post` callbacks, so auth, rate-limit accounting and error shaping stay
+ * in exactly one place.
+ *
+ * ADVISORY ONLY: every verdict and every envelope carries the AHJ caveat — this
+ * is model code as adopted, never a legal determination.
+ */
+import type { CodeAdvisoryInput, CodeAdvisoryResponse, CodeContextRequest, CodeContextResponse, CodeRequirementsResponse } from "./codes-types.js";
+import type { QueryParams } from "./http-transport.js";
+import type { SdkOperationId } from "./operations.js";
+/** The client's own request primitives, handed down so this file owns no transport. */
+export interface CodesTransport {
+    get<T>(operationId: SdkOperationId, query?: QueryParams, signal?: AbortSignal): Promise<T>;
+    post<T>(operationId: SdkOperationId, body: unknown, signal?: AbortSignal): Promise<T>;
+}
+export declare class CodesClient {
+    #private;
+    constructor(transport: CodesTransport);
+    /**
+     * The vocabulary for stating a code context (GET `/api/v1/codes/context`):
+     * seeded jurisdictions and their coverage tier, the occupancy groups the
+     * registry keys on, finish locations, dimensions, classification scales with
+     * classes ordered best-first, and which `ms_room` term correlates to which
+     * regulatory axes.
+     *
+     * Start here — every value the other two calls accept is listed in this one
+     * response, so nothing need be hardcoded. A correlation the registry refuses to
+     * make comes back `null`, never a guess.
+     *
+     * @example
+     * const vocab = await mg.codes.context();
+     * const texas = vocab.jurisdictions.find((j) => j.id === "us-tx");
+     * // `model_baseline` means unamended model IBC stood in for this AHJ's own table.
+     * console.log(texas?.coverage, texas?.adoptionNote);
+     */
+    context(signal?: AbortSignal): Promise<CodeContextResponse>;
+    /**
+     * What a space demands, before any candidate exists (GET
+     * `/api/v1/codes/requirements`). State the space by explicit axes, or by a
+     * `roomType` the axes are correlated from.
+     *
+     * An empty `requirements` array means nothing in the registry applies to this
+     * context. It is NOT a pass.
+     *
+     * @example
+     * const { requirements } = await mg.codes.requirements({
+     *   jurisdictionId: "us-tx",
+     *   occupancyGroup: "A-2", // or: roomType: "hotel_room" to correlate the axes
+     *   spaceType: "corridors",
+     *   sprinklered: true,
+     * });
+     * requirements.map((r) => `${r.dimension}: ${r.label} (${r.section})`);
+     */
+    requirements(input: CodeContextRequest, signal?: AbortSignal): Promise<CodeRequirementsResponse>;
+    /**
+     * Badge materials against the advisory building-code registry for one context
+     * (POST `/api/v1/codes/advisory`, ≤ 100 ids). Each applicable requirement is
+     * badged `meets` / `shortfall` / `unknown` from the material's accepted fire
+     * and slip facts, in input order; each material also carries a rolled-up
+     * `summary`, and `resolvedContext` reports the axes actually used.
+     *
+     * @example
+     * const advisory = await mg.codes.advisory({
+     *   variantIds: scheme.picks.map((p) => p.variantId),
+     *   jurisdictionId: "us-tx",
+     *   occupancyGroup: "A-2", // or: roomType: "hotel_room" to correlate the axes
+     *   spaceType: "corridors", // corridors | exit_stairs_passageways | rooms_enclosed_spaces
+     *   sprinklered: true,
+     * });
+     * // `unverified` means no comparable rating is on file — common, never a pass.
+     * const blocked = advisory.results.filter((r) => r.summary?.status === "shortfall");
+     */
+    advisory(input: CodeAdvisoryInput, signal?: AbortSignal): Promise<CodeAdvisoryResponse>;
+}