@instruments/materialgraph 0.31.0 → 0.33.0

package/match-stream-types.d.ts

@@ -1,306 +0,0 @@
-import type { ResponseAttribution } from "./attribution-types.js";
-import type { MatchCategoryInference, MatchColourReading } from "./match-types.js";
-/**
- * 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 { 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];
-/** Why a Match run ended on an `error` frame (MG-730). */
-export declare const MATCH_ERROR_REASONS: readonly ["upstream_unavailable", "failed"];
-export type MatchErrorReason = (typeof MATCH_ERROR_REASONS)[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.
- *
- * `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 declare const MATCH_SURFACE_STATUSES: readonly ["pending", "matching", "complete", "error", "colour_fallback"];
-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 type MatchBoundingBox = {
-    x0: number;
-    y0: number;
-    x1: number;
-    y1: number;
-};
-/** One surface the decompose step found in the image. */
-export type 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;
-    /** The `construction_methods` dictionary term the detector's finish names. */
-    construction?: 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.
- *
- * A `complete` surface can arrive TWICE: the first frame delivers its finished
- * results as soon as they exist, and a second repeats them unchanged with the
- * verifier's per-candidate verdicts attached (`senseCheck`).
- * Replacing on id handles both; the results never change between them, so
- * nothing a user is looking at moves when the second lands.
- *
- * `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`.
- */
-/**
- * What a Match actually compared, so a consumer can tell "the catalogue holds
- * nothing close" from "everything ranked badly" (MG-1031). Without it both
- * arrive as an empty list and the difference is unrecoverable.
- *
- * UNITS: `qualityFloor` and `bestRejected` are absolute image-arm cosines in
- * [0,1] — the same unit as each result's `confidence` — so they belong on one
- * axis. `poolSize` and `droppedBelowFloor` are counts and belong on neither.
- */
-export type MatchComparison = {
-    /** Candidates retrieved before the quality floor and product dedup. */
-    poolSize: number;
-    /** How many of those the quality floor rejected. */
-    droppedBelowFloor: number;
-    /** The floor they were held to, as an absolute image cosine in [0,1]. */
-    qualityFloor: number;
-    /**
-     * The closest REJECTED candidate, same unit as `qualityFloor`. Absent when
-     * nothing was rejected, or when the rejects carried no readable signal.
-     */
-    bestRejected?: number;
-};
-export type MatchSurfaceResult = {
-    surface: MatchDetectedSurface;
-    status: MatchSurfaceStatus;
-    results: SearchResultItem[];
-    inferredCategories: MatchCategoryInference[];
-    /** What this surface compared against. Absent means the server did not report it. */
-    comparison?: MatchComparison;
-    /**
-     * When `results` is empty, WHICH STAGE is responsible. Absent when the
-     * surface returned rows, and absent on servers older than this field.
-     *
-     *  - `empty_pool` — nothing eligible was retrieved. A fact about the
-     *    catalogue under the corpus scope in force.
-     *  - `quality_floor` — candidates WERE retrieved and every one was rejected.
-     *    A fact about the engine, not the catalogue.
-     *  - `unattributed` — no comparison receipt survived to attribute from.
-     *
-     * The distinction is the point: "we found nothing you can buy" and "we found
-     * things and declined them all" are the same empty list and different
-     * findings, and only the first belongs on a "nothing available here yet"
-     * state.
-     */
-    emptyReason?: "empty_pool" | "quality_floor" | "unattributed";
-    /**
-     * The verifier's reading of each candidate, when it ran.
-     *
-     * ABSENT means the stage did not run — it is opt-out, and the swatch route
-     * never runs it — OR that it is still running, which `senseCheckPending`
-     * distinguishes. Neither is the same as every candidate abstaining, and a
-     * consumer must not conflate them.
-     *
-     * `abstained` is NOT a soft rejection: it means the candidate was not judged
-     * (no image, no answer, or the judge was unavailable). Never render an
-     * abstention as a negative signal about the material.
-     */
-    senseCheck?: MatchSenseCheckCell[];
-    /**
-     * TRUE on the interim frame that delivers finished results while the verifier
-     * is still reading them. Render the rows immediately. The follow-up frame
-     * carries the SAME rows with verdicts attached, settled once into verdict
-     * bands (confirmed → abstained → rejected, stable within each band) — the
-     * page's one settling reorder. Nothing is ever removed.
-     */
-    senseCheckPending?: boolean;
-    /**
-     * Per-candidate colour readings against this surface's own crop, when the
-     * colour re-rank ran. `results` are already ordered by the blended score when
-     * this is present; this array is the receipt for that order.
-     */
-    colour?: MatchColourReading[];
-    /** The segment's own extracted palette — what the colour stage matched against. */
-    segmentPalette?: {
-        hex: string;
-        proportion: number;
-    }[];
-    /**
-     * One sentence of provenance a consumer may render verbatim, when the server
-     * sent one — e.g. the `colour_fallback` explanation carrying the refused
-     * sample's pixel size. Absent on ordinary surfaces.
-     */
-    note?: string;
-    /** Present only on `status: "error"` — why this one surface failed. */
-    error?: string;
-};
-/** The verifier's reading of one candidate, keyed back to its variant. */
-export type MatchSenseCheckCell = {
-    variantId: string;
-    verdict: MatchSenseCheckVerdict;
-    reason: string;
-};
-export declare const MATCH_SENSE_CHECK_VERDICTS: readonly ["confirmed", "rejected", "abstained"];
-export type MatchSenseCheckVerdict = (typeof MATCH_SENSE_CHECK_VERDICTS)[number];
-/** 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 declare const MATCH_OUTCOMES: readonly ["matched", "no_surfaces"];
-export type MatchOutcome = (typeof MATCH_OUTCOMES)[number];
-export type MatchWorkflowResult = {
-    /**
-     * Result attribution (MG-1131) — `responseId` (the same value as the run's
-     * `X-Request-Id` header), `basis: "match"`, and `issuedAt`. Every item in
-     * `results` and in each `surfaces[].results` carries a matching `resultId`.
-     *
-     * A surface's hits arrive twice — on its own `surface` frame and again here —
-     * and both times with the SAME `resultId`, so a consumer that stored the
-     * first recognises the second rather than double-counting it.
-     *
-     * ABSENT only from a response produced by a server predating MG-1131.
-     */
-    attribution?: ResponseAttribution;
-    imageType: MatchImageType;
-    /** How the run ended. Absent means `matched`. */
-    outcome?: MatchOutcome;
-    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;
-    /**
-     * Whole-image palette matches, sent ONLY when an installation photo yielded
-     * no usable surfaces at all. These match the image's overall palette — they
-     * are not material identifications, and the note says so. A consumer that
-     * ignores this field sees exactly the empty run it saw before the field
-     * existed.
-     */
-    paletteMatches?: {
-        results: SearchResultItem[];
-        palette: {
-            hex: string;
-            proportion: number;
-        }[];
-        note: string;
-    };
-    /**
-     * What a SWATCH run compared against — a swatch detects no surfaces, so it has
-     * nowhere else to put this. A scene run reports per surface instead.
-     */
-    comparison?: MatchComparison;
-};
-/** Progress narration for the phase the workflow just entered. */
-export type MatchStreamStepEvent = {
-    type: "step";
-    step: MatchWorkflowStep;
-    message: string;
-};
-/** The image type the classify step settled on. */
-export type MatchStreamClassifiedEvent = {
-    type: "classified";
-    imageType: MatchImageType;
-};
-/** Every surface the decompose step found, before any of them has matched. */
-export type 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 type 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 type 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 type MatchStreamHeartbeatEvent = {
-    type: "heartbeat";
-};
-/** Terminal: the whole run finished and carries its assembled result. */
-export type MatchStreamCompleteEvent = {
-    type: "complete";
-    result: MatchWorkflowResult;
-};
-/** Terminal: the run failed as a whole (a single surface failing is not this). */
-export type MatchStreamErrorEvent = {
-    type: "error";
-    message: string;
-    /**
-     * `upstream_unavailable`: a provider (vision, embedding, vector index) could
-     * not answer, so nothing was looked at and a retry may succeed. `failed`: the
-     * run broke on something else. Absent from servers older than MG-730.
-     */
-    reason?: MatchErrorReason;
-    /** True only for `upstream_unavailable`. Absent from servers older than MG-730. */
-    retriable?: boolean;
-};
-/** 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

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