@instruments/materialgraph 0.1.0 → 0.3.0

package/match-stream-types.d.ts

@@ -0,0 +1,150 @@
+/**
+ * The Material Match PROGRESS-STREAM contracts — the wire vocabulary of
+ * {@link MaterialGraphClient.matchStream} (`POST /api/v1/search/match` under
+ * `Accept: application/x-ndjson`). One JSON object per line; the run ends on a
+ * `complete` or an `error` event.
+ *
+ * These shapes are HAND-MIRRORED from `matchStreamEventSchema` in
+ * `@materialgraph/products` — the SDK publishes with zero runtime dependencies,
+ * so it cannot import the Zod schema itself. `contract-parity.test.ts` re-checks
+ * the mirror against the real schema, deriving the enum members FROM the
+ * canonical schemas so a server-side addition fails that test rather than
+ * silently widening the client.
+ *
+ * Every enum here is CLOSED, exactly as the canonical `z.enum(…)` members are.
+ * The value lists are exported so a consumer can build an exhaustive switch or a
+ * UI legend from the same source the validator uses.
+ */
+import type { MatchCategoryInference, SearchResultItem } from "./types.js";
+/** How the workflow classified the uploaded image. */
+export declare const MATCH_IMAGE_TYPES: readonly ["swatch", "installation", "flatplan"];
+export type MatchImageType = (typeof MATCH_IMAGE_TYPES)[number];
+/** What a detected surface is FOR — the element the material would serve. */
+export declare const MATCH_MATERIAL_FUNCTIONS: readonly ["flooring", "wall_surface", "ceiling", "partition", "upholstery", "millwork", "countertop", "accent", "sample"];
+export type MatchMaterialFunction = (typeof MATCH_MATERIAL_FUNCTIONS)[number];
+/** The workflow's coarse progress phase, narrated by a `step` event. */
+export declare const MATCH_WORKFLOW_STEPS: readonly ["classifying", "decomposing", "matching", "complete"];
+export type MatchWorkflowStep = (typeof MATCH_WORKFLOW_STEPS)[number];
+/** Where one surface stands in the run. */
+export declare const MATCH_SURFACE_STATUSES: readonly ["pending", "matching", "complete", "error"];
+export type MatchSurfaceStatus = (typeof MATCH_SURFACE_STATUSES)[number];
+/** Every frame type the stream can carry — the union's discriminant values. */
+export declare const MATCH_STREAM_EVENT_TYPES: readonly ["step", "classified", "surfaces", "surface", "heartbeat", "complete", "error"];
+export type MatchStreamEventType = (typeof MATCH_STREAM_EVENT_TYPES)[number];
+/** Where a surface sits in the image, in Gemini-style 0–1000 image space. */
+export interface MatchBoundingBox {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+}
+/** One surface the decompose step found in the image. */
+export interface MatchDetectedSurface {
+    id: string;
+    label: string;
+    materialFunction: MatchMaterialFunction;
+    /** The detector's catalog category answer, when it named one. */
+    categoryHint?: string;
+    /** Detector confidence, always within [0, 1]. */
+    confidence: number;
+    description?: string;
+    boundingBox: MatchBoundingBox;
+    /** JPEG data-URI crop used for Match retrieval — the thumbnail to show. */
+    cropDataUri?: string;
+}
+/**
+ * One surface's matching state and its ranked results. The same `surface.id`
+ * arrives repeatedly as the run progresses (`matching` → `complete` / `error`);
+ * render by replacing on id rather than appending.
+ *
+ * `results` and `inferredCategories` are always present on a yielded event: the
+ * canonical schema defaults each to `[]`, and the reader fills them when the
+ * server omits them, so neither ever arrives as `undefined`.
+ */
+export interface MatchSurfaceResult {
+    surface: MatchDetectedSurface;
+    status: MatchSurfaceStatus;
+    results: SearchResultItem[];
+    inferredCategories: MatchCategoryInference[];
+    /** Present only on `status: "error"` — why this one surface failed. */
+    error?: string;
+}
+/** The terminal Match workflow result — every surface in its final state. */
+export interface MatchWorkflowResult {
+    imageType: MatchImageType;
+    surfaces: MatchSurfaceResult[];
+    /** Present for swatch / single-surface runs that skip decompose. */
+    results?: SearchResultItem[];
+    inferredCategories?: MatchCategoryInference[];
+    /**
+     * How the run ended, counted rather than inferred. `surfacesFailed > 0` with
+     * no results is a broken run; zero failures with no results is a genuine
+     * "nothing above the floor". Do not fold `surfaces[]` to tell those apart.
+     */
+    totals: MatchRunTotals;
+}
+/** Progress narration for the phase the workflow just entered. */
+export interface MatchStreamStepEvent {
+    type: "step";
+    step: MatchWorkflowStep;
+    message: string;
+}
+/** The image type the classify step settled on. */
+export interface MatchStreamClassifiedEvent {
+    type: "classified";
+    imageType: MatchImageType;
+}
+/** Every surface the decompose step found, before any of them has matched. */
+export interface MatchStreamSurfacesEvent {
+    type: "surfaces";
+    surfaces: MatchDetectedSurface[];
+}
+/**
+ * The run's tally at the moment a `surface` event was emitted, so a consumer
+ * reads the server's arithmetic rather than reimplementing it.
+ *
+ * A FAILED surface is the case this exists to settle: failing is a way of
+ * RESOLVING. An errored surface counts in `surfacesResolved` (it will never be
+ * reported again), counts again in `surfacesFailed`, and adds nothing to
+ * `matchesSoFar`. `surfacesResolved === surfacesDetected` is therefore the
+ * correct "the run is done" test, and never stalls at 3/4 on a failure.
+ */
+export interface MatchRunTotals {
+    /** Surfaces the decompose step found. The denominator; fixed for the run. */
+    surfacesDetected: number;
+    /** Surfaces that reached a terminal state — `complete` OR `error`. */
+    surfacesResolved: number;
+    /** Of those resolved, how many ended in `error`. Always ≤ `surfacesResolved`. */
+    surfacesFailed: number;
+    /** Result items accumulated across every surface resolved so far. */
+    matchesSoFar: number;
+}
+/** One surface's state changed — the frame that makes Match progressive. */
+export interface MatchStreamSurfaceEvent {
+    type: "surface";
+    surface: MatchSurfaceResult;
+    /** The run's tally as of this frame. Always present on a `surface` event. */
+    totals: MatchRunTotals;
+}
+/**
+ * CONNECTION LIVENESS ONLY — never progress. Proxies and load balancers kill
+ * idle connections, so the server sends this when the stream has been quiet, and
+ * a client can tell a slow run from a dropped one. It carries no payload, and no
+ * consumer should treat it as a state change: do not advance a step, reset a
+ * no-progress watchdog, or count it towards anything.
+ */
+export interface MatchStreamHeartbeatEvent {
+    type: "heartbeat";
+}
+/** Terminal: the whole run finished and carries its assembled result. */
+export interface MatchStreamCompleteEvent {
+    type: "complete";
+    result: MatchWorkflowResult;
+}
+/** Terminal: the run failed as a whole (a single surface failing is not this). */
+export interface MatchStreamErrorEvent {
+    type: "error";
+    message: string;
+}
+/** One frame of the Match progress stream, discriminated by `type`. */
+export type MatchStreamEvent = MatchStreamStepEvent | MatchStreamClassifiedEvent | MatchStreamSurfacesEvent | MatchStreamSurfaceEvent | MatchStreamHeartbeatEvent | MatchStreamCompleteEvent | MatchStreamErrorEvent;

package/match-stream-types.js

@@ -0,0 +1,28 @@
+/** How the workflow classified the uploaded image. */
+export const MATCH_IMAGE_TYPES = ["swatch", "installation", "flatplan"];
+/** What a detected surface is FOR — the element the material would serve. */
+export const MATCH_MATERIAL_FUNCTIONS = [
+    "flooring",
+    "wall_surface",
+    "ceiling",
+    "partition",
+    "upholstery",
+    "millwork",
+    "countertop",
+    "accent",
+    "sample",
+];
+/** The workflow's coarse progress phase, narrated by a `step` event. */
+export const MATCH_WORKFLOW_STEPS = ["classifying", "decomposing", "matching", "complete"];
+/** Where one surface stands in the run. */
+export const MATCH_SURFACE_STATUSES = ["pending", "matching", "complete", "error"];
+/** Every frame type the stream can carry — the union's discriminant values. */
+export const MATCH_STREAM_EVENT_TYPES = [
+    "step",
+    "classified",
+    "surfaces",
+    "surface",
+    "heartbeat",
+    "complete",
+    "error",
+];

package/match-stream.d.ts

@@ -0,0 +1,22 @@
+import type { HttpTransport } from "./http-transport.js";
+import { type MatchStreamEvent } from "./match-stream-types.js";
+import type { MatchInput } from "./types.js";
+/**
+ * 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 declare function decodeMatchStreamEvent(line: string): MatchStreamEvent;
+/**
+ * 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 declare function matchStream(transport: HttpTransport, input: MatchInput, signal?: AbortSignal): AsyncGenerator<MatchStreamEvent, void, unknown>;

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-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>;