@instruments/materialgraph 0.2.0 → 0.3.0

package/material-block-types.d.ts

@@ -1,6 +1,27 @@
 import type { OpenEnum } from "./types.js";
-export type MaterialBlockStatus = OpenEnum<"populated" | "partial" | "pending" | "not_applicable">;
-export type MaterialBlockFieldStatus = OpenEnum<"verified" | "partial" | "missing" | "not_applicable">;
+/**
+ * Coverage status, shared by blocks and fields.
+ *
+ * `verified` — determined. For a field a value is known, INCLUDING `false`, `0`
+ * and `[]`, which are answers meaning "we looked and there is none". For a
+ * block, every field is determined.
+ * `partial` — determined for some fields but not all.
+ * `missing` — not determined yet. The work queue, and the only status that
+ * appears in `missingAttributeIds`.
+ * `not_applicable` — cannot apply to this product type. Never work, never a gap.
+ *
+ * BREAKING in this release: blocks previously reported `populated`/`pending`
+ * while fields reported `verified`/`missing` — two spellings of one concept
+ * that disagreed with each other on the same variant. Map `populated ->
+ * verified` and `pending -> missing`. Both types are retained as aliases so
+ * existing code keeps compiling; they now describe the same set.
+ *
+ * The authoritative list is served at runtime by
+ * `get-schema { kind: "coverageStatuses" }`.
+ */
+export type MaterialCoverageStatus = OpenEnum<"verified" | "partial" | "missing" | "not_applicable">;
+export type MaterialBlockStatus = MaterialCoverageStatus;
+export type MaterialBlockFieldStatus = MaterialCoverageStatus;
 export type MaterialBlockFieldValue = string | number | boolean | unknown[] | Record<string, unknown> | null;
 export interface MaterialBlockProjectionField {
     attributeId: string;

package/material-types.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Hand-mirrored wire types for the material projections — the grid-card tile,
+ * the detail record, and the availability/successor block they carry.
+ *
+ * Extracted from `./types.ts` (which re-exports everything here) so that module
+ * stays within the repository's source-size budget. Same contract, same
+ * tolerant-parsing rules: response enums are OPEN, so `MaterialAvailability` is
+ * widened — a new server state still type-checks.
+ */
+import type { ImageSource, MaterialColour, OpenEnum, PaletteSwatch } from "./types.js";
+/**
+ * Whether a material can still be bought.
+ *
+ *  - `available` — listed in the catalog of record.
+ *  - `discontinued` — WITHDRAWN from that catalog. This is the source's own
+ *    listing state, not a reviewed manufacturer-discontinuation claim; do not
+ *    present it as the manufacturer having discontinued the product.
+ *  - `superseded` — a reviewed product relationship names a successor and the
+ *    material is no longer listed. See `MaterialDetail.supersededBy`.
+ *  - `unknown` — never checked. A real answer, not an error.
+ */
+export type MaterialAvailability = OpenEnum<"available" | "discontinued" | "superseded" | "unknown">;
+/**
+ * The variant a reviewed product relationship names as replacing another.
+ * `availability` is the successor's OWN state, resolved ONE HOP only — a
+ * successor that has itself been superseded reports `discontinued`/`unknown`
+ * here; follow `variantId` for the next link in the chain.
+ */
+export interface MaterialSuccessor {
+    variantId: string;
+    brandSlug: string;
+    productId: string;
+    brand: string;
+    product: string;
+    variant: string;
+    color: string | null;
+    availability: MaterialAvailability;
+}
+/**
+ * The grid-card projection of a material. Tiles carry `availability` but not the
+ * successor record — read the detail projection for that.
+ */
+export interface MaterialTile {
+    variantId: string;
+    brand: string;
+    product: string;
+    variantName: string | null;
+    imageUrl: string | null;
+    imageSource: ImageSource | null;
+    category: string | null;
+    colour: MaterialColour;
+    availability: MaterialAvailability;
+}
+/** A canonical attribute/term pair carried on a detail record. */
+export interface MaterialFacet {
+    attributeId: string;
+    term: string;
+}
+/**
+ * One dimensional configuration of a material. Numeric fields are millimetres
+ * (mass in kilograms); string fields are the source's own descriptors. The
+ * index signature preserves the corpus's long tail of rarer keys.
+ */
+export interface DimensionEntry {
+    label?: string;
+    tile_size?: string;
+    measurement_basis?: string;
+    width_mm?: number;
+    length_mm?: number;
+    height_mm?: number;
+    depth_mm?: number;
+    thickness_mm?: number;
+    diameter_mm?: number;
+    visible_projection_mm?: number;
+    weight_kg?: number;
+    [key: string]: unknown;
+}
+/** The record projection of a material — the tile plus detail-only fields. */
+export interface MaterialDetail extends MaterialTile {
+    brandSlug: string;
+    productId: string;
+    color: string | null;
+    materialBankId: string | null;
+    installationImageUrl: string | null;
+    displayCategory: string | null;
+    categoryPath: string[];
+    palette: PaletteSwatch[];
+    facets: MaterialFacet[];
+    dimensions: DimensionEntry[] | null;
+    /** The declared successor, or null when no reviewed relationship names one. */
+    supersededBy: MaterialSuccessor | null;
+}

package/material-types.js

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

package/ndjson.d.ts

@@ -0,0 +1,46 @@
+/**
+ * A minimal, dependency-free NDJSON (newline-delimited JSON) line reader — the
+ * primitive behind {@link MaterialGraphClient.matchStream}. Hand-rolled so the
+ * SDK stays zero-runtime-dep and works unchanged inside Node route handlers,
+ * where `fetch` yields a byte `ReadableStream`.
+ *
+ * Deliberately a SIBLING of `sse.ts`, not a reuse of it. NDJSON and SSE agree on
+ * nothing but "text arrives in chunks": SSE frames are `field: value` lines
+ * terminated by a BLANK line, with comment lines and multi-line `data:`
+ * accumulation, whereas an NDJSON frame is exactly one line of JSON. Feeding
+ * NDJSON through the SSE tokenizer would read `{"type":"step",…}` as a field
+ * named `{"type"` and silently discard every frame. The two also want OPPOSITE
+ * end-of-stream policies: SSE dispatches a trailing partial frame as valid,
+ * while a truncated NDJSON line must surface as an error (enforced by the
+ * caller, which parses whatever `flush` returns rather than dropping it).
+ *
+ * Line endings: the reader splits on `\n` only, per the NDJSON contract. A `\r`
+ * left by a CRLF-normalising proxy stays as trailing whitespace on the line,
+ * which `JSON.parse` ignores.
+ */
+/**
+ * A push-based NDJSON line assembler. Feed it decoded text with {@link push};
+ * it returns the lines that text COMPLETED, terminators removed. Any partial
+ * trailing line is held in an internal buffer until a later chunk terminates it,
+ * or until {@link flush} surrenders it at end of stream.
+ */
+export declare class NdjsonDecoder {
+    #private;
+    /** Absorb one decoded chunk and return the lines it completed, in order. */
+    push(text: string): string[];
+    /**
+     * Surrender the unterminated remainder at end of stream — a well-formed
+     * NDJSON stream's final line need not carry a trailing newline. The remainder
+     * is RETURNED, never dropped: a truncated frame is the caller's error to
+     * raise, not this decoder's fragment to discard.
+     */
+    flush(): string[];
+}
+/**
+ * Iterate the NDJSON lines of a byte stream. Only lines with non-whitespace
+ * content are yielded — a blank separator line carries no frame and must never
+ * reach `JSON.parse`, where it would become an empty object. Stops cleanly when
+ * the stream ends or `signal` aborts (mid-read abort rejections are swallowed
+ * once the signal is set).
+ */
+export declare function readNdjsonLines(body: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<string, void, unknown>;

package/ndjson.js

@@ -0,0 +1,103 @@
+/**
+ * A minimal, dependency-free NDJSON (newline-delimited JSON) line reader — the
+ * primitive behind {@link MaterialGraphClient.matchStream}. Hand-rolled so the
+ * SDK stays zero-runtime-dep and works unchanged inside Node route handlers,
+ * where `fetch` yields a byte `ReadableStream`.
+ *
+ * Deliberately a SIBLING of `sse.ts`, not a reuse of it. NDJSON and SSE agree on
+ * nothing but "text arrives in chunks": SSE frames are `field: value` lines
+ * terminated by a BLANK line, with comment lines and multi-line `data:`
+ * accumulation, whereas an NDJSON frame is exactly one line of JSON. Feeding
+ * NDJSON through the SSE tokenizer would read `{"type":"step",…}` as a field
+ * named `{"type"` and silently discard every frame. The two also want OPPOSITE
+ * end-of-stream policies: SSE dispatches a trailing partial frame as valid,
+ * while a truncated NDJSON line must surface as an error (enforced by the
+ * caller, which parses whatever `flush` returns rather than dropping it).
+ *
+ * Line endings: the reader splits on `\n` only, per the NDJSON contract. A `\r`
+ * left by a CRLF-normalising proxy stays as trailing whitespace on the line,
+ * which `JSON.parse` ignores.
+ */
+/**
+ * A push-based NDJSON line assembler. Feed it decoded text with {@link push};
+ * it returns the lines that text COMPLETED, terminators removed. Any partial
+ * trailing line is held in an internal buffer until a later chunk terminates it,
+ * or until {@link flush} surrenders it at end of stream.
+ */
+export class NdjsonDecoder {
+    #buffer = "";
+    /** Absorb one decoded chunk and return the lines it completed, in order. */
+    push(text) {
+        this.#buffer += text;
+        const lines = [];
+        for (;;) {
+            const index = this.#buffer.indexOf("\n");
+            if (index === -1)
+                break;
+            lines.push(this.#buffer.slice(0, index));
+            this.#buffer = this.#buffer.slice(index + 1);
+        }
+        return lines;
+    }
+    /**
+     * Surrender the unterminated remainder at end of stream — a well-formed
+     * NDJSON stream's final line need not carry a trailing newline. The remainder
+     * is RETURNED, never dropped: a truncated frame is the caller's error to
+     * raise, not this decoder's fragment to discard.
+     */
+    flush() {
+        if (this.#buffer.length === 0)
+            return [];
+        const remainder = this.#buffer;
+        this.#buffer = "";
+        return [remainder];
+    }
+}
+/**
+ * Iterate the NDJSON lines of a byte stream. Only lines with non-whitespace
+ * content are yielded — a blank separator line carries no frame and must never
+ * reach `JSON.parse`, where it would become an empty object. Stops cleanly when
+ * the stream ends or `signal` aborts (mid-read abort rejections are swallowed
+ * once the signal is set).
+ */
+export async function* readNdjsonLines(body, signal) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    const ndjson = new NdjsonDecoder();
+    try {
+        for (;;) {
+            if (signal?.aborted)
+                return;
+            let result;
+            try {
+                result = await reader.read();
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    return;
+                throw error;
+            }
+            if (result.done) {
+                // `decode()` with no argument flushes any dangling multi-byte sequence.
+                for (const line of ndjson.push(decoder.decode())) {
+                    if (line.trim().length > 0)
+                        yield line;
+                }
+                for (const line of ndjson.flush()) {
+                    if (line.trim().length > 0)
+                        yield line;
+                }
+                return;
+            }
+            for (const line of ndjson.push(decoder.decode(result.value, { stream: true }))) {
+                if (signal?.aborted)
+                    return;
+                if (line.trim().length > 0)
+                    yield line;
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}

package/operations.d.ts

@@ -1,5 +1,5 @@
 export declare const MATERIALGRAPH_API_VERSION = "0.7.0";
-declare const OPERATION_DEFINITIONS: readonly [readonly ["search", "POST", "/api/v1/search", "search_materials_post"], readonly ["searchGet", "GET", "/api/v1/search", "search_materials_get"], readonly ["match", "POST", "/api/v1/search/match", "match_material"], readonly ["byColour", "GET", "/api/v1/search/colours", "search_by_colour"], readonly ["material", "GET", "/api/v1/materials/{variantId}", "get_material"], readonly ["siblings", "GET", "/api/v1/materials/{variantId}/siblings", "get_material_siblings"], readonly ["materialBlocks", "GET", "/api/v1/materials/{variantId}/blocks", "list_material_blocks"], readonly ["materialAssets", "GET", "/api/v1/materials/{variantId}/assets", "list_material_assets"], readonly ["schema", "GET", "/api/v1/schema/blocks", "list_schema_blocks"], readonly ["schema", "GET", "/api/v1/schema/attributes", "list_schema_attributes"], readonly ["schema", "GET", "/api/v1/schema/verticals", "list_schema_verticals"], readonly ["schema", "GET", "/api/v1/schema/product-types", "list_schema_product_types"], readonly ["schema", "GET", "/api/v1/schema/units", "list_schema_units"], readonly ["schema", "GET", "/api/v1/schema/value-dictionaries", "list_schema_value_dictionaries"], readonly ["schema", "GET", "/api/v1/schema/source-requirements", "list_schema_source_requirements"], readonly ["schema", "GET", "/api/v1/schema/product-type-templates", "list_schema_product_type_templates"], readonly ["schema", "GET", "/api/v1/schema/mappings", "list_schema_mappings"], readonly ["pairings", "GET", "/api/v1/materials/{variantId}/pairings", "get_material_pairings"], readonly ["materials", "POST", "/api/v1/materials/batch", "get_materials_batch_post"], readonly ["materialsCached", "GET", "/api/v1/materials/batch", "get_materials_batch_get"], readonly ["browse", "GET", "/api/v1/search/browse", "search_browse_by_colour"], readonly ["colourFacets", "GET", "/api/v1/colours/facets", "get_colour_facets"], readonly ["resolveColour", "GET", "/api/v1/search/colours/resolve", "resolve_colour_name"], readonly ["suggestColour", "GET", "/api/v1/search/colours/suggest", "suggest_colour_names"], readonly ["resolveAttribute", "GET", "/api/v1/catalog/attributes/resolve", "catalog_resolve_attribute"], readonly ["resolveAttributeValue", "GET", "/api/v1/catalog/attributes/{attributeId}/values/resolve", "catalog_resolve_value"], readonly ["searchVocabulary", "GET", "/api/v1/catalog/vocabulary/search", "catalog_vocabulary_search"], readonly ["bySpec", "GET", "/api/v1/search/specifications", "catalog_by_spec"], readonly ["taxonomy", "GET", "/api/v1/taxonomy/categories", "get_category_taxonomy"], readonly ["whoami", "GET", "/api/v1/whoami", "whoami"], readonly ["coordinate", "POST", "/api/v1/pairings/coordinate", "coordinate_materials"], readonly ["demand", "GET", "/api/v1/demand", "get_material_demand"], readonly ["extractPalette", "POST", "/api/v1/search/palettes/extract", "extract_image_palette"], readonly ["specificationFacets", "GET", "/api/v1/catalog/specifications/facets", "list_spec_facets"], readonly ["attributeValues", "GET", "/api/v1/catalog/attributes/{attributeId}/values", "list_attribute_values"], readonly ["applicableSpecs", "GET", "/api/v1/taxonomy/categories/{key}/specs", "get_applicable_specs"], readonly ["glossary", "GET", "/api/v1/glossary/{term}", "explain_material_term"], readonly ["brands", "GET", "/api/v1/brands", "list_brands"], readonly ["brand", "GET", "/api/v1/brands/{brandSlug}", "get_brand_profile"], readonly ["uploadSourceMaterial", "POST", "/api/v1/source-material", "upload_source_material"], readonly ["capabilities", "GET", "/api/v1/capabilities", "list_public_capabilities"], readonly ["createRun", "POST", "/api/v1/runs", "create_public_run"], readonly ["run", "GET", "/api/v1/runs/{runId}", "get_public_run"], readonly ["streamRunEvents", "GET", "/api/v1/runs/{runId}/events", "list_public_run_events"], readonly ["resumeRun", "POST", "/api/v1/runs/{runId}/resume", "resume_public_run"], readonly ["cancelRun", "POST", "/api/v1/runs/{runId}/cancel", "cancel_public_run"], readonly ["varyScheme", "POST", "/api/v1/schemes/vary", "vary_schemes"], readonly ["createProject", "POST", "/api/v1/projects", "create_box_project"], readonly ["listProjects", "GET", "/api/v1/projects", "list_box_projects"], readonly ["getProject", "GET", "/api/v1/projects/{projectId}", "get_box_project"], readonly ["appendProjectEvent", "POST", "/api/v1/projects/{projectId}/events", "append_box_project_event"], readonly ["demandBatch", "POST", "/api/v1/demand/batch", "get_demand_batch"], readonly ["codeAdvisory", "POST", "/api/v1/codes/advisory", "resolveCodeAdvisory"]];
+declare const OPERATION_DEFINITIONS: readonly [readonly ["search", "POST", "/api/v1/search", "search_materials_post"], readonly ["searchGet", "GET", "/api/v1/search", "search_materials_get"], readonly ["match", "POST", "/api/v1/search/match", "match_material"], readonly ["byColour", "GET", "/api/v1/search/colours", "search_by_colour"], readonly ["material", "GET", "/api/v1/materials/{variantId}", "get_material"], readonly ["siblings", "GET", "/api/v1/materials/{variantId}/siblings", "get_material_siblings"], readonly ["materialBlocks", "GET", "/api/v1/materials/{variantId}/blocks", "list_material_blocks"], readonly ["materialAssets", "GET", "/api/v1/materials/{variantId}/assets", "list_material_assets"], readonly ["schema", "GET", "/api/v1/schema/blocks", "list_schema_blocks"], readonly ["schema", "GET", "/api/v1/schema/attributes", "list_schema_attributes"], readonly ["schema", "GET", "/api/v1/schema/verticals", "list_schema_verticals"], readonly ["schema", "GET", "/api/v1/schema/product-types", "list_schema_product_types"], readonly ["schema", "GET", "/api/v1/schema/units", "list_schema_units"], readonly ["schema", "GET", "/api/v1/schema/value-dictionaries", "list_schema_value_dictionaries"], readonly ["schema", "GET", "/api/v1/schema/source-requirements", "list_schema_source_requirements"], readonly ["schema", "GET", "/api/v1/schema/product-type-templates", "list_schema_product_type_templates"], readonly ["schema", "GET", "/api/v1/schema/mappings", "list_schema_mappings"], readonly ["pairings", "GET", "/api/v1/materials/{variantId}/pairings", "get_material_pairings"], readonly ["materials", "POST", "/api/v1/materials/batch", "get_materials_batch_post"], readonly ["materialsCached", "GET", "/api/v1/materials/batch", "get_materials_batch_get"], readonly ["browse", "GET", "/api/v1/search/browse", "search_browse_by_colour"], readonly ["colourFacets", "GET", "/api/v1/colours/facets", "get_colour_facets"], readonly ["colours.profiles", "GET", "/api/v1/colours/profiles", "get_category_colour_profiles"], readonly ["colours.stats", "GET", "/api/v1/colours/stats", "get_colour_stats"], readonly ["resolveColour", "GET", "/api/v1/search/colours/resolve", "resolve_colour_name"], readonly ["suggestColour", "GET", "/api/v1/search/colours/suggest", "suggest_colour_names"], readonly ["resolveAttribute", "GET", "/api/v1/catalog/attributes/resolve", "catalog_resolve_attribute"], readonly ["resolveAttributeValue", "GET", "/api/v1/catalog/attributes/{attributeId}/values/resolve", "catalog_resolve_value"], readonly ["searchVocabulary", "GET", "/api/v1/catalog/vocabulary/search", "catalog_vocabulary_search"], readonly ["bySpec", "GET", "/api/v1/search/specifications", "catalog_by_spec"], readonly ["taxonomy", "GET", "/api/v1/taxonomy/categories", "get_category_taxonomy"], readonly ["whoami", "GET", "/api/v1/whoami", "whoami"], readonly ["coordinate", "POST", "/api/v1/pairings/coordinate", "coordinate_materials"], readonly ["demand", "GET", "/api/v1/demand", "get_material_demand"], readonly ["extractPalette", "POST", "/api/v1/search/palettes/extract", "extract_image_palette"], readonly ["specificationFacets", "GET", "/api/v1/catalog/specifications/facets", "list_spec_facets"], readonly ["attributeValues", "GET", "/api/v1/catalog/attributes/{attributeId}/values", "list_attribute_values"], readonly ["applicableSpecs", "GET", "/api/v1/taxonomy/categories/{key}/specs", "get_applicable_specs"], readonly ["glossary", "GET", "/api/v1/glossary/{term}", "explain_material_term"], readonly ["brands", "GET", "/api/v1/brands", "list_brands"], readonly ["brand", "GET", "/api/v1/brands/{brandSlug}", "get_brand_profile"], readonly ["uploadSourceMaterial", "POST", "/api/v1/source-material", "upload_source_material"], readonly ["sourceMaterialBatch", "GET", "/api/v1/source-material/{batchId}", "get_source_material_batch"], readonly ["capabilities", "GET", "/api/v1/capabilities", "list_public_capabilities"], readonly ["createRun", "POST", "/api/v1/runs", "create_public_run"], readonly ["run", "GET", "/api/v1/runs/{runId}", "get_public_run"], readonly ["runSchedule", "GET", "/api/v1/runs/{runId}/schedule", "get_run_finish_schedule"], readonly ["streamRunEvents", "GET", "/api/v1/runs/{runId}/events", "list_public_run_events"], readonly ["resumeRun", "POST", "/api/v1/runs/{runId}/resume", "resume_public_run"], readonly ["cancelRun", "POST", "/api/v1/runs/{runId}/cancel", "cancel_public_run"], readonly ["varyScheme", "POST", "/api/v1/schemes/vary", "vary_schemes"], readonly ["createProject", "POST", "/api/v1/projects", "create_box_project"], readonly ["listProjects", "GET", "/api/v1/projects", "list_box_projects"], readonly ["getProject", "GET", "/api/v1/projects/{projectId}", "get_box_project"], readonly ["appendProjectEvent", "POST", "/api/v1/projects/{projectId}/events", "append_box_project_event"], readonly ["demandBatch", "POST", "/api/v1/demand/batch", "get_demand_batch"], readonly ["codeAdvisory", "POST", "/api/v1/codes/advisory", "resolveCodeAdvisory"], readonly ["codes.context", "GET", "/api/v1/codes/context", "list_code_context"], readonly ["codes.requirements", "GET", "/api/v1/codes/requirements", "list_code_requirements"]];
 export type SdkOperationId = (typeof OPERATION_DEFINITIONS)[number][3];
 export type SdkOperation = Readonly<{
     clientMethod: (typeof OPERATION_DEFINITIONS)[number][0];

package/operations.js

@@ -22,6 +22,8 @@ const OPERATION_DEFINITIONS = [
     ["materialsCached", "GET", "/api/v1/materials/batch", "get_materials_batch_get"],
     ["browse", "GET", "/api/v1/search/browse", "search_browse_by_colour"],
     ["colourFacets", "GET", "/api/v1/colours/facets", "get_colour_facets"],
+    ["colours.profiles", "GET", "/api/v1/colours/profiles", "get_category_colour_profiles"],
+    ["colours.stats", "GET", "/api/v1/colours/stats", "get_colour_stats"],
     ["resolveColour", "GET", "/api/v1/search/colours/resolve", "resolve_colour_name"],
     ["suggestColour", "GET", "/api/v1/search/colours/suggest", "suggest_colour_names"],
     ["resolveAttribute", "GET", "/api/v1/catalog/attributes/resolve", "catalog_resolve_attribute"],
@@ -50,9 +52,11 @@ const OPERATION_DEFINITIONS = [
     ["brands", "GET", "/api/v1/brands", "list_brands"],
     ["brand", "GET", "/api/v1/brands/{brandSlug}", "get_brand_profile"],
     ["uploadSourceMaterial", "POST", "/api/v1/source-material", "upload_source_material"],
+    ["sourceMaterialBatch", "GET", "/api/v1/source-material/{batchId}", "get_source_material_batch"],
     ["capabilities", "GET", "/api/v1/capabilities", "list_public_capabilities"],
     ["createRun", "POST", "/api/v1/runs", "create_public_run"],
     ["run", "GET", "/api/v1/runs/{runId}", "get_public_run"],
+    ["runSchedule", "GET", "/api/v1/runs/{runId}/schedule", "get_run_finish_schedule"],
     ["streamRunEvents", "GET", "/api/v1/runs/{runId}/events", "list_public_run_events"],
     ["resumeRun", "POST", "/api/v1/runs/{runId}/resume", "resume_public_run"],
     ["cancelRun", "POST", "/api/v1/runs/{runId}/cancel", "cancel_public_run"],
@@ -63,6 +67,8 @@ const OPERATION_DEFINITIONS = [
     ["appendProjectEvent", "POST", "/api/v1/projects/{projectId}/events", "append_box_project_event"],
     ["demandBatch", "POST", "/api/v1/demand/batch", "get_demand_batch"],
     ["codeAdvisory", "POST", "/api/v1/codes/advisory", "resolveCodeAdvisory"],
+    ["codes.context", "GET", "/api/v1/codes/context", "list_code_context"],
+    ["codes.requirements", "GET", "/api/v1/codes/requirements", "list_code_requirements"],
 ];
 export const SDK_OPERATIONS = Object.freeze(OPERATION_DEFINITIONS.map(([clientMethod, method, path, operationId]) => Object.freeze({ clientMethod, method, path, operationId })));
 /** Look up a registered operation by its OpenAPI `operationId`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instruments/materialgraph",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "exports": {
     ".": {

package/run-types.d.ts

@@ -10,7 +10,7 @@
  * so a new server value still type-checks, and objects are read structurally —
  * unknown keys pass through untouched.
  */
-import type { OpenEnum } from "./types.js";
+import type { JsonValue, OpenEnum } from "./types.js";
 /**
  * A file to upload. Two forms so the SDK is ergonomic on BOTH Node route
  * handlers and modern runtimes: pass a platform `Blob`/`File` directly, or the
@@ -74,6 +74,58 @@ export interface SourceMaterialBatchReceipt {
     batchId: string;
     sources: SourceMaterialReceiptFile[];
 }
+/**
+ * One analysis computed over an uploaded image's bytes.
+ *
+ * Analyses are CONTENT-ADDRESSED: keyed by the file's SHA-256, not by the
+ * upload or the uploading key. Re-uploading an image someone has already
+ * analysed therefore returns that analysis immediately, with no work. That
+ * sharing is by design and discloses nothing — you only ever see analyses of
+ * images you hold yourself.
+ */
+export interface SourceImageAnalysis {
+    /** The kind of read. {@link OpenEnum} keeps a newer server value type-checking. */
+    kind: OpenEnum<"scene_match">;
+    /** The model version that produced {@link SourceImageAnalysis.result}. */
+    model: string;
+    /**
+     * `failed` analyses are RETURNED, not hidden — so "we looked and it did not
+     * work" is distinguishable from "nobody has looked yet", which is an empty
+     * {@link SourceMaterialBatchFile.analyses}.
+     */
+    status: OpenEnum<"ok" | "failed">;
+    /**
+     * The payload verbatim, or the failure record when `status` is `failed`. For
+     * `scene_match`: the detected regions with their candidate variant ids and
+     * scores. The interior shape belongs to the producing model and may gain
+     * fields, so it is typed as JSON rather than pinned here.
+     */
+    result: Record<string, JsonValue>;
+    /** ISO-8601 timestamp of the most recent analysis. */
+    analysedAt: string;
+}
+/** One file as `GET /api/v1/source-material/{batchId}` returns it. */
+export interface SourceMaterialBatchFile extends SourceMaterialReceiptFile {
+    /** Fetchable URL for the stored bytes. */
+    url: string;
+    /**
+     * ALWAYS an array. `[]` means nothing has been computed yet — never a missing
+     * field. Preprocessing is triggered manually today; when it becomes automatic
+     * only the trigger changes and this contract does not.
+     */
+    analyses: SourceImageAnalysis[];
+}
+/**
+ * The `200` body of `GET /api/v1/source-material/{batchId}` — the batch, every
+ * file it holds, and the analyses computed over each file's bytes.
+ */
+export interface SourceMaterialBatchDetail {
+    /** The stored batch id (`smb_…`). */
+    batchId: string;
+    /** ISO-8601 timestamp of the upload. */
+    createdAt: string;
+    sources: SourceMaterialBatchFile[];
+}
 export type CapabilityKind = OpenEnum<"agent" | "tool" | "workflow">;
 export type CapabilityExposure = OpenEnum<"public" | "partner" | "internal">;
 export type CapabilityScope = OpenEnum<"mg:read" | "mg:write" | "mg:ingest" | "mg:admin">;
@@ -200,3 +252,15 @@ export interface DrainRunEventsOptions {
     /** Stop collecting after this many milliseconds even without a terminal event. */
     deadlineMs: number;
 }
+/** Options for {@link MaterialGraphClient.resumeRun}. */
+export interface ResumeRunOptions {
+    /**
+     * The step the caller believes is suspended. When it mismatches the run
+     * doc's live `suspensionStepId` the API answers RFC-7807 409 (MG-608) —
+     * which is what stops a stale client resuming a step the run has already
+     * moved past. Omitted, the resume is unguarded, exactly as before.
+     */
+    stepId?: string;
+    /** Abort the request. */
+    signal?: AbortSignal;
+}

package/runs.d.ts

@@ -1,5 +1,6 @@
 import { HttpTransport } from "./http-transport.js";
-import { type CapabilityManifestResponse, type CreatePublicRunRequest, type CreatePublicRunResponse, type DrainRunEventsOptions, type PublicRunResponse, type RunEvent, type SourceMaterialBatchReceipt, type StreamRunEventsOptions, type UploadSourceMaterialInput } from "./run-types.js";
+import type { FinishScheduleResponse, GetRunScheduleOptions } from "./schedule-types.js";
+import { type CapabilityManifestResponse, type CreatePublicRunRequest, type CreatePublicRunResponse, type DrainRunEventsOptions, type PublicRunResponse, type ResumeRunOptions, type RunEvent, type SourceMaterialBatchDetail, type SourceMaterialBatchReceipt, type StreamRunEventsOptions, type UploadSourceMaterialInput } from "./run-types.js";
 /**
  * Upload one atomic source-material batch (`POST /api/v1/source-material`).
  * Accepts the pile-of-files shape (`{ files }` → repeatable `files` field) or
@@ -7,14 +8,55 @@ import { type CapabilityManifestResponse, type CreatePublicRunRequest, type Crea
  * fields). Both wire to multipart the server accepts.
  */
 export declare function uploadSourceMaterial(transport: HttpTransport, input: UploadSourceMaterialInput, signal?: AbortSignal): Promise<SourceMaterialBatchReceipt>;
+/**
+ * Read back one uploaded batch (`GET /api/v1/source-material/{batchId}`): every
+ * file with a fetchable `url`, and every analysis computed over its bytes
+ * inlined as `analyses` — always an array, `[]` when nothing has been computed.
+ *
+ * A batch you do not own is indistinguishable from one that does not exist:
+ * both raise a 404, never a 403, so batch ids cannot be probed for existence.
+ *
+ * The body is VALIDATED, not trusted: `checkSourceMaterialBatchDetail` mirrors
+ * the server's Zod contract so a malformed response fails here with a path into
+ * the payload rather than as an undefined three frames away in caller code.
+ */
+export declare function getSourceMaterialBatch(transport: HttpTransport, batchId: string, signal?: AbortSignal): Promise<SourceMaterialBatchDetail>;
 /** List invocable agents, workflows, and tools (`GET /api/v1/capabilities`). */
 export declare function capabilities(transport: HttpTransport, signal?: AbortSignal): Promise<CapabilityManifestResponse>;
 /** Start an asynchronous capability Run (`POST /api/v1/runs`). */
 export declare function createRun(transport: HttpTransport, body: CreatePublicRunRequest, signal?: AbortSignal): Promise<CreatePublicRunResponse>;
 /** Get a Run's current state (`GET /api/v1/runs/{runId}`). */
 export declare function getRun(transport: HttpTransport, runId: string, signal?: AbortSignal): Promise<PublicRunResponse>;
-/** Resume a suspended Run (`POST /api/v1/runs/{runId}/resume`). */
-export declare function resumeRun(transport: HttpTransport, 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`).
+ *
+ * The `.xlsx` form of the same export is deliberately NOT an SDK method: this
+ * transport parses every response as text/JSON and has no binary read path, so
+ * a bytes-returning method would mean a second transport surface for one file.
+ * Fetch `GET /api/v1/runs/{runId}/schedule.xlsx` directly with the same bearer
+ * key when you want the workbook.
+ */
+export declare function getRunSchedule(transport: HttpTransport, runId: string, options?: GetRunScheduleOptions): Promise<FinishScheduleResponse>;
+/**
+ * Resume a suspended Run (`POST /api/v1/runs/{runId}/resume`).
+ *
+ * The third argument takes either an `AbortSignal` (legacy) or
+ * {@link ResumeRunOptions}.
+ *
+ * `stepId` is forwarded whenever it is PRESENT — `!== undefined`, not truthy.
+ * An empty string is a present-but-malformed value and must reach the server
+ * so its schema rejects it; treating it as absent would silently downgrade a
+ * guarded resume into an unguarded one, which is the exact failure this guard
+ * exists to prevent.
+ *
+ * Omitting it sends a body byte-identical to what this sent before. Note the
+ * wire cannot distinguish `{ stepId: undefined }` from no key at all —
+ * `JSON.stringify` drops both — so the distinction here is construction
+ * intent, kept so the serialised body is provably unchanged for old callers.
+ */
+export declare function resumeRun(transport: HttpTransport, runId: string, resumeData: unknown, signalOrOptions?: AbortSignal | ResumeRunOptions): Promise<PublicRunResponse>;
 /** Request durable Run cancellation (`POST /api/v1/runs/{runId}/cancel`). */
 export declare function cancelRun(transport: HttpTransport, runId: string, signal?: AbortSignal): Promise<PublicRunResponse>;
 /**