@instruments/materialgraph 0.2.0 → 0.3.0

package/http-transport.d.ts

@@ -2,8 +2,9 @@
  * The shared low-level HTTP transport for {@link MaterialGraphClient}. It owns
  * URL building, the bearer header, rate-limit capture, response reading, and the
  * one error-mapping path — so the JSON read surface (`client.ts`), the multipart
- * upload, and the SSE stream (`runs.ts`) all fail identically. Retry-free by
- * design; a single failure surfaces as one {@link MaterialGraphError}.
+ * upload, the SSE stream (`runs.ts`), and the NDJSON Match stream
+ * (`match-stream.ts`) all fail identically. Retry-free by design; a single
+ * failure surfaces as one {@link MaterialGraphError}.
  */
 import { type RateLimit } from "./errors.js";
 import { type SdkOperation } from "./operations.js";
@@ -15,6 +16,12 @@ export interface RequestOptions {
     signal?: AbortSignal;
     pathParams?: Readonly<Record<string, string>>;
 }
+export interface StreamRequestOptions extends RequestOptions {
+    /** The streaming media type to negotiate (`text/event-stream`, `application/x-ndjson`). */
+    accept: string;
+    /** Names this stream in the "returned no body" diagnostic, e.g. `"match stream"`. */
+    subject: string;
+}
 /** A read, status-checked HTTP response with its parsed body. */
 export interface SentResponse {
     response: Response;
@@ -51,6 +58,16 @@ export declare class HttpTransport {
      * it consumes the whole body via `response.text()`.
      */
     send(input: SendInput): Promise<SentResponse>;
+    /**
+     * Open a streaming operation and hand back its UNREAD byte body — the one
+     * entry point for every long-lived read (SSE run events, NDJSON Match
+     * progress). Everything up to the first byte behaves exactly like
+     * {@link send}: same URL building, same bearer header, same rate-limit
+     * capture, same {@link MaterialGraphError} mapping for a transport failure or
+     * a non-2xx (whose short error body IS read, since it is not a stream).
+     * Framing and cancellation belong to the caller.
+     */
+    openStream(sdkOperation: SdkOperation, options: StreamRequestOptions): Promise<ReadableStream<Uint8Array>>;
     /** Execute a registered JSON operation and return its typed body. */
     requestJson<T>(sdkOperation: SdkOperation, options?: RequestOptions): Promise<T>;
 }

package/http-transport.js

@@ -2,8 +2,9 @@
  * The shared low-level HTTP transport for {@link MaterialGraphClient}. It owns
  * URL building, the bearer header, rate-limit capture, response reading, and the
  * one error-mapping path — so the JSON read surface (`client.ts`), the multipart
- * upload, and the SSE stream (`runs.ts`) all fail identically. Retry-free by
- * design; a single failure surfaces as one {@link MaterialGraphError}.
+ * upload, the SSE stream (`runs.ts`), and the NDJSON Match stream
+ * (`match-stream.ts`) all fail identically. Retry-free by design; a single
+ * failure surfaces as one {@link MaterialGraphError}.
  */
 import { MaterialGraphError } from "./errors.js";
 import { operationPath } from "./operations.js";
@@ -115,6 +116,75 @@ export class HttpTransport {
         }
         return { response, text, parsed };
     }
+    /**
+     * Open a streaming operation and hand back its UNREAD byte body — the one
+     * entry point for every long-lived read (SSE run events, NDJSON Match
+     * progress). Everything up to the first byte behaves exactly like
+     * {@link send}: same URL building, same bearer header, same rate-limit
+     * capture, same {@link MaterialGraphError} mapping for a transport failure or
+     * a non-2xx (whose short error body IS read, since it is not a stream).
+     * Framing and cancellation belong to the caller.
+     */
+    async openStream(sdkOperation, options) {
+        const url = this.buildUrl(operationPath(sdkOperation, options.pathParams), options.query);
+        const requestUrl = new URL(url);
+        const metadata = {
+            method: sdkOperation.method,
+            origin: requestUrl.origin,
+            path: requestUrl.pathname,
+        };
+        const hasBody = options.body !== undefined;
+        let response;
+        try {
+            response = await this.fetch(url, {
+                method: sdkOperation.method,
+                headers: this.authHeaders({
+                    Accept: options.accept,
+                    ...(hasBody ? { "Content-Type": "application/json" } : {}),
+                }),
+                body: hasBody ? JSON.stringify(options.body) : undefined,
+                signal: options.signal,
+            });
+        }
+        catch (cause) {
+            throw MaterialGraphError.fromTransport({ ...metadata, cause, callerSignal: options.signal });
+        }
+        const rateLimit = parseRateLimit(response.headers);
+        this.#lastRateLimit = rateLimit;
+        if (!response.ok) {
+            let text = "";
+            try {
+                text = await response.text();
+            }
+            catch {
+                // The status IS the error; a body that will not read adds nothing and
+                // must not mask it. Report the failure with an empty detail instead.
+                text = "";
+            }
+            let parsed;
+            if (text.length > 0) {
+                try {
+                    parsed = JSON.parse(text);
+                }
+                catch {
+                    parsed = text;
+                }
+            }
+            throw MaterialGraphError.fromResponse({
+                ...metadata,
+                status: response.status,
+                body: parsed,
+                responseText: text,
+                rateLimit,
+                apiKey: this.apiKey,
+                queryValues: [...requestUrl.searchParams.values()],
+            });
+        }
+        if (response.body === null) {
+            throw MaterialGraphError.unexpected(`MaterialGraph ${options.subject} returned no body`);
+        }
+        return response.body;
+    }
     /** Execute a registered JSON operation and return its typed body. */
     async requestJson(sdkOperation, options = {}) {
         const url = this.buildUrl(operationPath(sdkOperation, options.pathParams), options.query);

package/index.d.ts

@@ -4,6 +4,7 @@ export { MATERIALGRAPH_API_VERSION, SDK_OPERATIONS } from "./operations.js";
 export type { SdkOperation, SdkOperationId } from "./operations.js";
 export { TERMINAL_RUN_EVENT_TYPES } from "./run-types.js";
 export type * from "./run-types.js";
+export type * from "./schedule-types.js";
 export { VARY_AXES } from "./composition-types.js";
 export type * from "./composition-types.js";
 export { PROJECT_EVENT_KINDS } from "./project-types.js";
@@ -13,7 +14,13 @@ export type * from "./run-events.js";
 export { MaterialGraphError } from "./errors.js";
 export type { MaterialGraphErrorInit, MaterialGraphErrorKind, MaterialGraphRequestMetadata, ProblemDetail, RateLimit, SanitizedErrorValue, SanitizedIssue, SimpleErrorBody, } from "./errors.js";
 export type * from "./types.js";
+export { MATCH_IMAGE_TYPES, MATCH_MATERIAL_FUNCTIONS, MATCH_STREAM_EVENT_TYPES, MATCH_SURFACE_STATUSES, MATCH_WORKFLOW_STEPS, } from "./match-stream-types.js";
+export type * from "./match-stream-types.js";
+export { CodesClient } from "./codes-client.js";
 export type * from "./codes-types.js";
+export { ColoursClient } from "./colours-client.js";
+export type { ColoursTransport } from "./colours-client.js";
+export type * from "./colour-aggregate-types.js";
 export type * from "./brand-types.js";
 export type * from "./material-asset-types.js";
 export type * from "./material-block-types.js";

package/index.js

@@ -5,5 +5,8 @@ export { VARY_AXES } from "./composition-types.js";
 export { PROJECT_EVENT_KINDS } from "./project-types.js";
 export { COMPOSITION_PHASE_EVENT_TYPES, COMPOSITION_PROGRAMME_EVENT_TYPES, COMPOSITION_REVIEW_CRITERIA_EVENT_TYPES, parseRunEvent, } from "./run-events.js";
 export { MaterialGraphError } from "./errors.js";
+export { MATCH_IMAGE_TYPES, MATCH_MATERIAL_FUNCTIONS, MATCH_STREAM_EVENT_TYPES, MATCH_SURFACE_STATUSES, MATCH_WORKFLOW_STEPS, } from "./match-stream-types.js";
+export { CodesClient } from "./codes-client.js";
+export { ColoursClient } from "./colours-client.js";
 export { CERTIFICATION_PROGRAMME_ATTRIBUTE_ID } from "./spec-types.js";
 export { certificationProgramme, certificationProgrammeCriterion, hasSpec, specCriterion, specTerm, } from "./specifications.js";

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();
+    }
+}