@instruments/materialgraph 0.2.0 → 0.4.0

package/match-stream.js

@@ -0,0 +1,280 @@
+/**
+ * The Material Match PROGRESS STREAM — the streaming twin of the buffered
+ * `match()` read. `POST /api/v1/search/match` with `Accept:
+ * application/x-ndjson` runs classify → decompose → one match per surface and
+ * emits an event per line as each surface resolves, so a `/match` UI can fill in
+ * progressively instead of showing a spinner until the whole run lands.
+ *
+ * FAIL-FAST BY CONTRACT. Every non-blank line is validated before it is yielded;
+ * a line that is not JSON, is not an object, carries an unknown `type`, an
+ * out-of-range number, a value outside a closed enum, or a field of the wrong
+ * kind raises a {@link MaterialGraphError} rather than being skipped. A stream
+ * that ends without a `complete` or an `error` event was truncated, and raises
+ * too — a short run and a dropped connection must never look alike. There is no
+ * retry or reconnect.
+ *
+ * HEARTBEATS ARE NOT PROGRESS. A scene match goes quiet for long stretches
+ * between surfaces, and proxies kill idle connections, so the server sends a
+ * payload-free `{ type: "heartbeat" }` when the stream has been silent. It is
+ * yielded like any other event — the connection being alive is worth knowing —
+ * but it carries nothing and marks no state change: never advance a step, reset
+ * a no-progress watchdog, or count anything on one. It is not terminal, and none
+ * arrives after `complete` or `error`.
+ *
+ * ACCEPTANCE PARITY WITH THE CANONICAL SCHEMA. The SDK cannot import
+ * `matchStreamEventSchema` at runtime (it publishes with zero dependencies), so
+ * this validator mirrors it by hand and `contract-parity.test.ts` proves the two
+ * ACCEPT and REJECT the same frames — with the enum members derived from the
+ * canonical schemas, so a server-side addition fails that test.
+ *
+ * OUTPUT IS PASS-THROUGH, NOT `parse` OUTPUT — a deliberate divergence. Zod
+ * objects strip unknown keys, so `matchStreamEventSchema.parse(frame)` DROPS any
+ * field the schema does not name. This reader keeps the frame as sent. Three
+ * reasons:
+ *  1. Nothing on the emit path parses. The route stringifies the workflow's own
+ *     objects (`createMatchNdjsonStream`), so `parse` output is not what the wire
+ *     carries; reshaping to match it would invent a normalisation that never
+ *     happened.
+ *  2. Stripping needs the COMPLETE key inventory of `searchResultItemSchema`,
+ *     whose closure reaches `candidateVerdictSchema` in `@materialgraph/contracts`
+ *     — a recursive hand-mirror that would have to stay in step forever, and a
+ *     wider surface than the validation it would serve.
+ *  3. An additive server field then reaches consumers without an SDK release,
+ *     which matters while new EVENT types still require one (MG-658).
+ * The ONE exception is `.default([])`: an omitted `results` / `inferredCategories`
+ * is FILLED to `[]`, because {@link MatchSurfaceResult} types both as always
+ * present and the SDK must not hand back a type it has falsified.
+ *
+ * VALIDATION DEPTH — FULL. The frame envelope, every closed enum, every bounded
+ * number, every non-negative integer in a `surface` event's `totals`, every
+ * optional string, `MatchCategoryInference` items, and every
+ * `SearchResultItem` in `results[]` are checked exhaustively. Item validation is
+ * the shared `checkSearchResultItem` (`search-result-validation.ts`), which
+ * mirrors `searchResultItemSchema` and its whole closure down to
+ * `candidateVerdictSchema` — including both of its `.superRefine()` cross-field
+ * invariants.
+ */
+import { MaterialGraphError } from "./errors.js";
+import { findSdkOperation } from "./operations.js";
+import { MATCH_IMAGE_TYPES, MATCH_MATERIAL_FUNCTIONS, MATCH_STREAM_EVENT_TYPES, MATCH_SURFACE_STATUSES, MATCH_WORKFLOW_STEPS, } from "./match-stream-types.js";
+import { readNdjsonLines } from "./ndjson.js";
+import { checkSearchResultItems } from "./search-result-validation.js";
+import { requireArray, requireBoundedNumber, requireDefaultedArray, requireEnum, requireIntegerAtLeast, requireNumber, requireOptionalString, requireRecord, requireString, } from "./validation.js";
+/** The NDJSON media type the Match route negotiates the scene workflow on. */
+const MATCH_STREAM_ACCEPT = "application/x-ndjson";
+/** How much of an offending frame a diagnostic quotes (crops can be megabytes). */
+const MAX_FRAME_PREVIEW = 200;
+const BOUNDING_BOX_CORNERS = Object.freeze(["x0", "y0", "x1", "y1"]);
+function operation(operationId) {
+    const found = findSdkOperation(operationId);
+    if (!found)
+        throw MaterialGraphError.unexpected(`Unknown SDK operation: ${operationId}`);
+    return found;
+}
+/**
+ * The failure shape every check in this module raises: one message naming the
+ * offending path and quoting a bounded slice of the frame.
+ */
+function frameFailure(line) {
+    const preview = line.length > MAX_FRAME_PREVIEW ? `${line.slice(0, MAX_FRAME_PREVIEW)}…` : line;
+    return (reason) => MaterialGraphError.unexpected(`MaterialGraph match stream sent a malformed NDJSON frame: ${reason}. Frame: ${preview}`);
+}
+/** Check one `MatchCategoryInference` item. */
+function checkCategoryInference(value, what, fail) {
+    const record = requireRecord(value, what, fail);
+    requireString(record.productTypeId, `${what}.productTypeId`, fail);
+    requireString(record.displayName, `${what}.displayName`, fail);
+    requireNumber(record.boost, `${what}.boost`, fail);
+}
+function checkCategoryInferences(items, what, fail) {
+    items.forEach((item, index) => checkCategoryInference(item, `${what}[${index}]`, fail));
+}
+/** Check one detected surface — identity, function, confidence, and its box. */
+function checkDetectedSurface(value, what, fail) {
+    const record = requireRecord(value, what, fail);
+    requireString(record.id, `${what}.id`, fail);
+    requireString(record.label, `${what}.label`, fail);
+    requireEnum(record.materialFunction, MATCH_MATERIAL_FUNCTIONS, `${what}.materialFunction`, fail);
+    requireOptionalString(record.categoryHint, `${what}.categoryHint`, fail);
+    requireOptionalString(record.description, `${what}.description`, fail);
+    requireOptionalString(record.cropDataUri, `${what}.cropDataUri`, fail);
+    requireBoundedNumber(record.confidence, `${what}.confidence`, fail, 0, 1);
+    const box = requireRecord(record.boundingBox, `${what}.boundingBox`, fail);
+    for (const corner of BOUNDING_BOX_CORNERS) {
+        requireNumber(box[corner], `${what}.boundingBox.${corner}`, fail);
+    }
+}
+/**
+ * Check one surface's matching state and fill the canonical `.default([])`
+ * arrays, so a consumer never meets `undefined` where the type promises an array.
+ */
+function readSurfaceResult(value, what, fail) {
+    const record = requireRecord(value, what, fail);
+    checkDetectedSurface(record.surface, `${what}.surface`, fail);
+    requireEnum(record.status, MATCH_SURFACE_STATUSES, `${what}.status`, fail);
+    requireOptionalString(record.error, `${what}.error`, fail);
+    const results = requireDefaultedArray(record.results, `${what}.results`, fail);
+    checkSearchResultItems(results, `${what}.results`, fail);
+    const inferredCategories = requireDefaultedArray(record.inferredCategories, `${what}.inferredCategories`, fail);
+    checkCategoryInferences(inferredCategories, `${what}.inferredCategories`, fail);
+    return { ...record, results, inferredCategories };
+}
+/**
+ * `matchRunTotalsSchema` — four non-negative integers plus the TWO cross-field
+ * invariants its `.superRefine()` enforces. Relational rather than field-wise,
+ * which is no obstacle here: they are two comparisons, and without them a frame
+ * claiming "7 of 2 surfaces done" would reach a consumer that trusted the tally.
+ *
+ * `matchesSoFar` is deliberately unbounded against the surface counts — one
+ * surface can carry many results and another none, so no ratio is principled.
+ */
+function checkRunTotals(value, what, fail) {
+    const record = requireRecord(value, what, fail);
+    const detected = requireIntegerAtLeast(record.surfacesDetected, `${what}.surfacesDetected`, fail, 0);
+    const resolved = requireIntegerAtLeast(record.surfacesResolved, `${what}.surfacesResolved`, fail, 0);
+    const failed = requireIntegerAtLeast(record.surfacesFailed, `${what}.surfacesFailed`, fail, 0);
+    requireIntegerAtLeast(record.matchesSoFar, `${what}.matchesSoFar`, fail, 0);
+    // superRefine invariant 1 — a failed surface is also a resolved one.
+    if (failed > resolved) {
+        throw fail(`${what}.surfacesFailed (${failed}) exceeds ${what}.surfacesResolved (${resolved}) — a failed surface is also a resolved one`);
+    }
+    // superRefine invariant 2 — a run cannot resolve more surfaces than it found.
+    if (resolved > detected) {
+        throw fail(`${what}.surfacesResolved (${resolved}) exceeds ${what}.surfacesDetected (${detected}) — a run cannot resolve more surfaces than it found`);
+    }
+}
+/** Check the terminal workflow result — image type, surfaces, optional roll-ups. */
+function readWorkflowResult(value, what, fail) {
+    const record = requireRecord(value, what, fail);
+    requireEnum(record.imageType, MATCH_IMAGE_TYPES, `${what}.imageType`, fail);
+    const surfaces = requireArray(record.surfaces, `${what}.surfaces`, fail).map((surface, index) => readSurfaceResult(surface, `${what}.surfaces[${index}]`, fail));
+    // These two are `.optional()` on the workflow result, NOT `.default([])`:
+    // absent stays absent, matching the swatch path that skips decompose.
+    if (record.results !== undefined) {
+        checkSearchResultItems(requireArray(record.results, `${what}.results`, fail), `${what}.results`, fail);
+    }
+    if (record.inferredCategories !== undefined) {
+        checkCategoryInferences(requireArray(record.inferredCategories, `${what}.inferredCategories`, fail), `${what}.inferredCategories`, fail);
+    }
+    return { ...record, surfaces };
+}
+/**
+ * Validate one frame against the canonical contract and apply the schema's
+ * `.default([])` fills, returning the event as a plain record. Unknown keys ride
+ * through untouched — see the pass-through note in the module header.
+ */
+function readFrame(value, fail) {
+    const record = requireRecord(value, "the frame", fail);
+    const type = requireString(record.type, "`type`", fail);
+    switch (type) {
+        case "step":
+            requireEnum(record.step, MATCH_WORKFLOW_STEPS, "`step`", fail);
+            requireString(record.message, "`message`", fail);
+            return record;
+        case "classified":
+            requireEnum(record.imageType, MATCH_IMAGE_TYPES, "`imageType`", fail);
+            return record;
+        case "surfaces": {
+            const surfaces = requireArray(record.surfaces, "`surfaces`", fail);
+            surfaces.forEach((surface, index) => checkDetectedSurface(surface, `surfaces[${index}]`, fail));
+            return record;
+        }
+        case "surface": {
+            // Payload before tally, so a malformed surface reports itself rather than
+            // being masked by whatever the totals looked like.
+            const surface = readSurfaceResult(record.surface, "`surface`", fail);
+            checkRunTotals(record.totals, "`totals`", fail);
+            return { ...record, surface };
+        }
+        case "heartbeat":
+            // Payload-free by contract — there is nothing else to check.
+            return record;
+        case "complete":
+            return { ...record, result: readWorkflowResult(record.result, "`result`", fail) };
+        case "error":
+            requireString(record.message, "`message`", fail);
+            return record;
+        default:
+            throw fail(`\`type\` is not a known Match stream event (${type})`);
+    }
+}
+/**
+ * The single narrowing boundary of this module. {@link readFrame} has already
+ * proven every field the union's shape depends on; re-checking the discriminant
+ * here keeps the assertion from being vacuous.
+ */
+function assertMatchStreamEvent(frame, fail) {
+    const record = requireRecord(frame, "the frame", fail);
+    requireEnum(record.type, MATCH_STREAM_EVENT_TYPES, "`type`", fail);
+}
+/**
+ * Decode one NDJSON line into a validated {@link MatchStreamEvent}, raising a
+ * {@link MaterialGraphError} on anything the contract does not allow. Exported
+ * for `contract-parity.test.ts`, which re-checks it against the real Zod schema;
+ * it is not part of the published surface.
+ */
+export function decodeMatchStreamEvent(line) {
+    const fail = frameFailure(line);
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch (cause) {
+        throw fail(`it is not valid JSON (${String(cause)})`);
+    }
+    const frame = readFrame(parsed, fail);
+    assertMatchStreamEvent(frame, fail);
+    return frame;
+}
+function isTerminal(event) {
+    return event.type === "complete" || event.type === "error";
+}
+/**
+ * Stream Match progress as an async iterator. Iterates until the run reaches a
+ * `complete` or an `error` event, and raises if the connection ends before one
+ * arrives.
+ *
+ * `signal` genuinely cancels: it is linked to the AbortController that owns the
+ * in-flight request, so aborting (or simply `break`ing out of the loop) tears
+ * down the HTTP connection rather than merely stopping the yields. A
+ * caller-requested abort ends the iteration CLEANLY — the caller already knows
+ * it cancelled, so the truncated-stream error is not raised for it.
+ */
+export async function* matchStream(transport, input, signal) {
+    if (signal?.aborted === true)
+        return;
+    // Our own controller, so abandoning the iterator cancels the request too.
+    const controller = new AbortController();
+    const forwardAbort = () => controller.abort();
+    signal?.addEventListener("abort", forwardAbort, { once: true });
+    try {
+        let body;
+        try {
+            body = await transport.openStream(operation("match_material"), {
+                body: input,
+                signal: controller.signal,
+                accept: MATCH_STREAM_ACCEPT,
+                subject: "match stream",
+            });
+        }
+        catch (error) {
+            // Cancelled before the response headers landed — the caller's own stop.
+            if (controller.signal.aborted)
+                return;
+            throw error;
+        }
+        for await (const line of readNdjsonLines(body, controller.signal)) {
+            const event = decodeMatchStreamEvent(line);
+            yield event;
+            if (isTerminal(event))
+                return;
+        }
+        if (!controller.signal.aborted) {
+            throw MaterialGraphError.unexpected("MaterialGraph match stream ended without a `complete` or `error` event — the connection was truncated");
+        }
+    }
+    finally {
+        signal?.removeEventListener("abort", forwardAbort);
+        controller.abort();
+    }
+}

package/material-asset-types.d.ts

@@ -1,6 +1,6 @@
 import type { OpenEnum } from "./types.js";
 export type MaterialAssetVisualRole = OpenEnum<"grid" | "detail" | "scene" | "swatch" | "technical" | "unknown">;
-export type MaterialAssetStatus = OpenEnum<"downloaded" | "linked_not_downloaded" | "failed">;
+export type MaterialAssetStatus = OpenEnum<"downloaded" | "linked_not_downloaded" | "failed" | "retired_placeholder">;
 export interface MaterialAssetProjectionImage {
     key: string;
     ordinal: number;

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 ["suggest", "GET", "/api/v1/search/suggest", "search_suggest"], 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,8 +22,11 @@ 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"],
+    ["suggest", "GET", "/api/v1/search/suggest", "search_suggest"],
     ["resolveAttribute", "GET", "/api/v1/catalog/attributes/resolve", "catalog_resolve_attribute"],
     [
         "resolveAttributeValue",
@@ -50,9 +53,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 +68,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.4.0",
   "type": "module",
   "exports": {
     ".": {