@instruments/materialgraph 0.30.0 → 0.32.0

package/match-stream-types.js

@@ -1,65 +0,0 @@
-/** How the workflow classified the uploaded image. */
-export const MATCH_IMAGE_TYPES = [
-    "swatch",
-    "installation",
-    "flatplan",
-];
-/** Why a Match run ended on an `error` frame (MG-730). */
-export const MATCH_ERROR_REASONS = ["upstream_unavailable", "failed"];
-/** 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.
- *
- * `colour_fallback` (appended, additive): the surface completed, but through
- * the colour lane — its visible sample was too small to read texture, so the
- * results match the region's palette, scoped to the detected category. Such a
- * surface carries a `note` saying so and no `senseCheck` verdicts (there is no
- * texture to verify).
- */
-export const MATCH_SURFACE_STATUSES = [
-    "pending",
-    "matching",
-    "complete",
-    "error",
-    "colour_fallback",
-];
-/** 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",
-];
-export const MATCH_SENSE_CHECK_VERDICTS = [
-    "confirmed",
-    "rejected",
-    "abstained",
-];
-/** The terminal Match workflow result — every surface in its final state. */
-/**
- * How a Match run ended. `no_surfaces` means the detector worked and found no
- * material in the photo — a finding, not a failure. Branch on this rather than
- * on an error message. Absent means `matched`.
- */
-export const MATCH_OUTCOMES = ["matched", "no_surfaces"];

package/match-stream.d.ts

@@ -1,22 +0,0 @@
-import type { HttpTransport } from "./http-transport.js";
-import type { MatchStreamEvent } from "./match-stream-types.js";
-import type { MatchInput } from "./match-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 const 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

@@ -1,308 +0,0 @@
-/**
- * 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`
- *     — a 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.
- */
-import { MaterialGraphError } from "./errors.js";
-import { MATCH_ERROR_REASONS, 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 { findSdkOperation } from "./operations.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",
-]);
-const 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.
- */
-const 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. */
-const 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);
-};
-const checkCategoryInferences = (items, what, fail) => {
-    items.forEach((item, index) => {
-        checkCategoryInference(item, `${what}[${index}]`, fail);
-    });
-};
-/** Check one detected surface — identity, function, confidence, and its box. */
-const 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.
- */
-const 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, inferredCategories, results };
-};
-/**
- * `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.
- */
-const 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. */
-const 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.
- */
-const 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);
-            if (record.reason !== undefined) {
-                requireEnum(record.reason, MATCH_ERROR_REASONS, "`reason`", fail);
-            }
-            if (record.retriable !== undefined &&
-                typeof record.retriable !== "boolean") {
-                throw fail("`retriable` must be a boolean");
-            }
-            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.
- */
-const 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 const 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;
-};
-const isTerminal = (event) => 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"), {
-                accept: MATCH_STREAM_ACCEPT,
-                body: input,
-                signal: controller.signal,
-                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/match-types.d.ts

@@ -1,138 +0,0 @@
-import type { ResponseAttribution } from "./attribution-types.js";
-import type { CorpusScope } from "./corpus-scope-types.js";
-/**
- * @module sdk/match-types
- * @description The buffered Material Match request and response, hand-mirrored
- * from the server's Zod contracts.
- *
- * Split out of `types.ts` — which is at the repository's source-size limit —
- * along its natural seam: everything a caller of `client.match()` needs, and
- * nothing else. The STREAMING contracts live in `match-stream-types.ts`.
- */
-import type { MatchWorkflowResult } from "./match-stream-types.js";
-import type { SearchFilter } from "./search-refinement-types.js";
-import type { OpenEnum, PaletteSwatch, SearchResultItem } from "./types.js";
-/** An inferred product-type category from the query image, with its boost. */
-export type MatchCategoryInference = {
-    productTypeId: string;
-    displayName: string;
-    boost: number;
-};
-/**
- * The Material Match response (non-streaming form).
- *
- * `poolSize` is the candidate pool the floor was applied to, NOT a corpus total
- * and NOT "how many materials look like this". An empty `results` with
- * `droppedBelowFloor > 0` means "candidates existed and none was good enough" —
- * a different answer from `poolSize: 0`, which means the image found nothing to
- * search against at all.
- */
-/**
- * One candidate's colour reading against the query crop. `measurable: false`
- * means the material carries no palette on record — UNKNOWN, never "no colour"
- * and never "the wrong colour".
- */
-export type MatchColourReading = {
-    variantId: string;
-    colourDistance: number | null;
-    colourBand: string | null;
-    measurable: boolean;
-};
-export type MatchResponse = {
-    /**
-     * Result attribution (MG-1131). `basis` is always `"match"` here — this route
-     * has no `mode`, so this is the field that lets a Match outcome be grouped
-     * alongside a `search()` one. Store it beside the query and each item's
-     * `resultId` beside the outcome.
-     *
-     * ABSENT only from a response produced by a server predating MG-1131.
-     */
-    attribution?: ResponseAttribution;
-    /** THIS answer, capped by `limit`. Not a total. */
-    results: SearchResultItem[];
-    inferredCategories: MatchCategoryInference[];
-    qualityFloor: number;
-    poolSize: number;
-    droppedBelowFloor: number;
-    droppedAsDuplicateProduct: number;
-    /**
-     * The closest candidate the quality floor REJECTED, in the same [0,1] unit as
-     * `qualityFloor`. This is what turns "no matches" into "the closest thing in
-     * the catalogue read 0.48 against a 0.55 bar" — the one number that separates
-     * an engine that failed from a corpus that does not hold the material. Absent
-     * when nothing was rejected; null when the rejects carried no readable signal.
-     */
-    bestRejected?: number | null;
-    /** The maximum score achievable under the weights this query ran — `score`'s denominator. */
-    maxScore: number;
-    /**
-     * Per-candidate colour readings against the query crop, in `results` order.
-     * `null` means the colour stage DID NOT RUN (no image bytes, or it was turned
-     * off) — never "no colour".
-     */
-    colour?: MatchColourReading[] | null;
-    /** The query crop's own extracted palette — what the colour stage compared against. */
-    segmentPalette?: PaletteSwatch[] | null;
-    note?: string;
-};
-/**
- * What a BUFFERED `match()` actually answers with, either shape.
- *
- * An IMAGE input (`imageBase64` or `imageUrl`) runs the same workflow the
- * stream lane runs — image kind first, then the swatch shortcut or the scene
- * route — and answers in {@link MatchWorkflowResult}. A `vector` input has no
- * bytes to read a kind from and keeps the thin {@link MatchResponse} leaf.
- * The server declares exactly this as an `anyOf` of the two.
- *
- * TELL THEM APART BY A FIELD THAT ONLY ONE HAS, never by what you sent:
- * `imageType` is required on the workflow shape and absent from the leaf, and
- * `qualityFloor` is required on the leaf and absent from the workflow shape.
- *
- * ```ts
- * const answer = await client.match({ imageBase64 });
- * if ("imageType" in answer) {
- *   for (const surface of answer.surfaces) render(surface);
- * } else {
- *   report(answer.qualityFloor, answer.droppedBelowFloor);
- * }
- * ```
- */
-export type MatchAnswer = MatchResponse | MatchWorkflowResult;
-/** The Material Match request body — exactly one of `imageBase64`, `imageUrl`, `vector`. */
-export type MatchInput = {
-    imageBase64?: string;
-    imageUrl?: string;
-    vector?: string;
-    limit?: number;
-    qualityFloor?: number;
-    categoryTopK?: number;
-    categoryMinBoost?: number;
-    detectionLabel?: string;
-    /**
-     * The detector's fuller reading of the surface — a SENTENCE, where
-     * `detectionLabel` is a phrase. Fused WITH the image into ONE multimodal
-     * query vector and preferred over the label when both are present.
-     *
-     * Distinct from `detectionLabel`, which also buys the category scope: a
-     * request can narrow the scope by label and steer retrieval by description in
-     * the same call.
-     */
-    detectionDescription?: string;
-    materialFunction?: string;
-    detectionCategory?: string;
-    /**
-     * Opt-in: also return quality-floor rejects, flagged `belowFloor: true` and
-     * appended after the kept results. Absent/false = default behaviour;
-     * `droppedBelowFloor` is unchanged.
-     */
-    includeBelowFloor?: boolean;
-    requestedType?: OpenEnum<"swatch" | "installation" | "flatplan">;
-    /** Corpus to retrieve candidates from, applied inside retrieval. */
-    corpusScope?: CorpusScope;
-    /** Hard spec gates forwarded verbatim to the inner search — term match or presence, each with an optional trust bar. */
-    filters?: SearchFilter[];
-    /** Soft criteria (rank-never-exclude). A miss demotes within the page but never removes a hit. */
-    preferences?: SearchFilter[];
-    /** Opt in to seed-relative verdict cells; inert unless the inner search carries a variant seed. */
-    verdicts?: boolean;
-};

package/match-types.js

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