@instruments/materialgraph 0.1.0 → 0.2.0

package/run-events.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Typed payloads for the composition Run event family — the friction fix flagged
+ * by the MG-443 walk. These narrow the loose {@link RunEvent.payloadJson} so
+ * consumers (the Box console) can render phase progress, the parsed programme,
+ * and the criteria-correction UI without re-typing each payload at the call
+ * site.
+ *
+ * Both wire generations are covered: the CURRENT `composition.*` strings the
+ * server emits today, and the LEGACY `material-box.*` strings kept for read-side
+ * dual-read compatibility. Shapes mirror
+ * `packages/mastra/src/workflow/composition/events.ts` and the
+ * `reviewCriteriaSuspendPayloadSchema` in `@materialgraph/products` — expressed
+ * as standalone TS types (no cross-package import; the SDK is publishable).
+ */
+import type { OpenEnum } from "./types.js";
+import type { RunEvent } from "./run-types.js";
+export declare const COMPOSITION_PHASE_EVENT_TYPES: readonly ["composition.phase", "material-box.phase"];
+export declare const COMPOSITION_PROGRAMME_EVENT_TYPES: readonly ["composition.programme", "material-box.brief"];
+export declare const COMPOSITION_REVIEW_CRITERIA_EVENT_TYPES: readonly ["composition.review-criteria", "material-box.review-criteria"];
+export type CompositionPhaseEventType = (typeof COMPOSITION_PHASE_EVENT_TYPES)[number];
+export type CompositionProgrammeEventType = (typeof COMPOSITION_PROGRAMME_EVENT_TYPES)[number];
+export type CompositionReviewCriteriaEventType = (typeof COMPOSITION_REVIEW_CRITERIA_EVENT_TYPES)[number];
+/** Payload of a `composition.phase` / `material-box.phase` progress event. */
+export interface CompositionPhasePayload {
+    workflow: OpenEnum<"parse-material-brief" | "compose-material-schemes">;
+    phase: string;
+    label: string;
+    state: OpenEnum<"started" | "completed" | "failed">;
+    /** Additive narration (file names, error messages); absent on older events. */
+    detail?: string;
+    /** Additive tallies (slot/candidate/scheme counts); absent on older events. */
+    counts?: Record<string, number>;
+}
+/**
+ * Payload of a `composition.programme` / `material-box.brief` event. The current
+ * generation carries `programme`; the legacy generation carried `brief`. Both
+ * are read structurally (the parsed programme document).
+ */
+export interface CompositionProgrammePayload {
+    programme?: unknown;
+    brief?: unknown;
+}
+/** One unresolved brief phrase offered for human correction at the review step. */
+export interface CompositionReviewCriteriaSuggestion {
+    attributeId: string;
+    name: string;
+    term?: string;
+    score: number;
+}
+export interface CompositionReviewCriteriaUnresolved {
+    slotId: string;
+    raw: string;
+    suggestions: CompositionReviewCriteriaSuggestion[];
+}
+/**
+ * Payload of a `composition.review-criteria` / `material-box.review-criteria`
+ * suspend event — the correction grammar the Box review step renders.
+ */
+export interface CompositionReviewCriteriaPayload {
+    unresolved: CompositionReviewCriteriaUnresolved[];
+}
+export interface CompositionPhaseEvent extends RunEvent {
+    type: CompositionPhaseEventType;
+    payloadJson: CompositionPhasePayload;
+}
+export interface CompositionProgrammeEvent extends RunEvent {
+    type: CompositionProgrammeEventType;
+    payloadJson: CompositionProgrammePayload;
+}
+export interface CompositionReviewCriteriaEvent extends RunEvent {
+    type: CompositionReviewCriteriaEventType;
+    payloadJson: CompositionReviewCriteriaPayload;
+}
+/** The discriminated union of all composition Run events. */
+export type CompositionEvent = CompositionPhaseEvent | CompositionProgrammeEvent | CompositionReviewCriteriaEvent;
+/**
+ * Narrow a {@link RunEvent} to the composition family by its `type`, returning
+ * `null` for lifecycle events (`queued`, `running`, `succeeded`, …) and any
+ * unknown type. Narrowing is by the discriminating `type` only — payloads are
+ * trusted structurally per the tolerant-parsing contract, never re-validated.
+ */
+export declare function parseRunEvent(event: RunEvent): CompositionEvent | null;

package/run-events.js

@@ -0,0 +1,29 @@
+// ── Wire event-type strings (both generations) ───────────────────────────────
+export const COMPOSITION_PHASE_EVENT_TYPES = ["composition.phase", "material-box.phase"];
+export const COMPOSITION_PROGRAMME_EVENT_TYPES = [
+    "composition.programme",
+    "material-box.brief",
+];
+export const COMPOSITION_REVIEW_CRITERIA_EVENT_TYPES = [
+    "composition.review-criteria",
+    "material-box.review-criteria",
+];
+const includesType = (types, type) => types.includes(type);
+/**
+ * Narrow a {@link RunEvent} to the composition family by its `type`, returning
+ * `null` for lifecycle events (`queued`, `running`, `succeeded`, …) and any
+ * unknown type. Narrowing is by the discriminating `type` only — payloads are
+ * trusted structurally per the tolerant-parsing contract, never re-validated.
+ */
+export function parseRunEvent(event) {
+    if (includesType(COMPOSITION_PHASE_EVENT_TYPES, event.type)) {
+        return event;
+    }
+    if (includesType(COMPOSITION_PROGRAMME_EVENT_TYPES, event.type)) {
+        return event;
+    }
+    if (includesType(COMPOSITION_REVIEW_CRITERIA_EVENT_TYPES, event.type)) {
+        return event;
+    }
+    return null;
+}

package/run-types.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Hand-mirrored wire types for the MaterialGraph public Run + source-material
+ * surface (spec 0.7.0). Like {@link ./types.ts}, these interfaces carry NO
+ * runtime dependency on any `@materialgraph/*` package — they mirror the shapes
+ * in `apps/web/public/openapi.yaml` (`list_public_capabilities`,
+ * `create_public_run`, `get_public_run`, `list_public_run_events`,
+ * `resume_public_run`, `cancel_public_run`, `upload_source_material`).
+ *
+ * TOLERANT-PARSING CONTRACT: response enums are widened with {@link OpenEnum}
+ * so a new server value still type-checks, and objects are read structurally —
+ * unknown keys pass through untouched.
+ */
+import type { OpenEnum } from "./types.js";
+/**
+ * A file to upload. Two forms so the SDK is ergonomic on BOTH Node route
+ * handlers and modern runtimes: pass a platform `Blob`/`File` directly, or the
+ * bytes plus a filename. The SDK builds the multipart body internally — callers
+ * never touch `FormData` or wrestle a `string`-typed binary field.
+ */
+export type FileInput = Blob | {
+    /** Raw file bytes. */
+    data: Uint8Array | ArrayBuffer;
+    /** Filename recorded on the multipart part (drives the stored receipt filename). */
+    filename: string;
+    /** Optional MIME type; the server re-validates by magic bytes regardless. */
+    contentType?: string;
+};
+/**
+ * A heterogeneous pile of source files (multipart field `files`, repeatable):
+ * any mix of PDF, plain-text/markdown, and images (≥1, ≤16). The server
+ * classifies each file and assigns its receipt {@link SourceMaterialReceiptFile.role};
+ * the caller no longer pre-sorts a brief from its references.
+ */
+export interface UploadSourceMaterialFilesInput {
+    files: FileInput[];
+}
+/**
+ * The legacy pre-classified shape — a single PDF `brief` plus optional image
+ * `references` (multipart fields `brief` + `references`). Still accepted by the
+ * server, folded into the pile. Prefer {@link UploadSourceMaterialFilesInput}.
+ */
+export interface UploadSourceMaterialLegacyInput {
+    /** The single PDF brief for the batch (multipart field `brief`). */
+    brief: FileInput;
+    /** Up to 12 reference images (multipart field `references`, repeatable). */
+    references?: FileInput[];
+}
+/**
+ * Input for {@link MaterialGraphClient.uploadSourceMaterial} — either the
+ * pile-of-files shape or the legacy brief+references shape.
+ */
+export type UploadSourceMaterialInput = UploadSourceMaterialFilesInput | UploadSourceMaterialLegacyInput;
+/** One stored file in an upload receipt. */
+export interface SourceMaterialReceiptFile {
+    /** The stored file id (`smf_…`). */
+    sourceId: string;
+    /**
+     * The pipeline-assigned role. The vocabulary grows over time; {@link OpenEnum}
+     * keeps a newer server value type-checking. `unclassified` is a legitimate
+     * terminal value when the pipeline could not place the file.
+     */
+    role: OpenEnum<"brief" | "reference_image" | "document" | "document_image" | "inspiration_image" | "unclassified">;
+    filename: string;
+    mediaType: string;
+    /** Lowercase hex SHA-256 of the stored bytes. */
+    sha256: string;
+    bytes: number;
+    /** PDF page count; null for images. */
+    pages: number | null;
+}
+/** The `201` receipt from `POST /api/v1/source-material`. */
+export interface SourceMaterialBatchReceipt {
+    /** The stored batch id (`smb_…`). */
+    batchId: string;
+    sources: SourceMaterialReceiptFile[];
+}
+export type CapabilityKind = OpenEnum<"agent" | "tool" | "workflow">;
+export type CapabilityExposure = OpenEnum<"public" | "partner" | "internal">;
+export type CapabilityScope = OpenEnum<"mg:read" | "mg:write" | "mg:ingest" | "mg:admin">;
+export type CapabilitySideEffectClass = OpenEnum<"read_only" | "browser_local" | "external_read" | "writes_proposed" | "writes_persisted" | "planned_only">;
+export interface CapabilityRetryPolicy {
+    maxAttempts: number;
+    backoff: OpenEnum<"none" | "fixed" | "exponential">;
+}
+export interface CapabilityInvokeLink {
+    href: string;
+    method: OpenEnum<"GET" | "POST">;
+}
+/** One invocable capability from the governed public manifest. */
+export interface PublicCapabilityMetadata {
+    publicId: string;
+    runtimeId: string;
+    kind: CapabilityKind;
+    exposure: CapabilityExposure;
+    name: string;
+    description: string;
+    schemas: {
+        input: Record<string, unknown>;
+        output: Record<string, unknown>;
+    };
+    sideEffectClass: CapabilitySideEffectClass;
+    scopes: CapabilityScope[];
+    timeoutMs: number;
+    retryPolicy: CapabilityRetryPolicy;
+    tags: string[];
+    links: {
+        invoke: CapabilityInvokeLink;
+    };
+}
+/** The `GET /api/v1/capabilities` response envelope. */
+export interface CapabilityManifestResponse {
+    capabilities: PublicCapabilityMetadata[];
+}
+export type PublicRunStatus = OpenEnum<"queued" | "claimed" | "running" | "suspended" | "succeeded" | "failed" | "canceled">;
+export interface PublicRunFailure {
+    code: string;
+    message: string;
+    retryable: boolean;
+    detail?: Record<string, unknown>;
+}
+export interface PublicRunArtifactRef {
+    kind: string;
+    ref: string;
+}
+/**
+ * The caller-owned, redacted Run ledger record. Prompts, raw model messages,
+ * reasoning, credentials, provider payloads, and source-document contents are
+ * never returned — inputs and outputs are the `redacted*Json` projections.
+ */
+export interface PublicRun {
+    id: string;
+    capabilityKind: CapabilityKind;
+    capabilityId: string;
+    clientReference: string | null;
+    status: PublicRunStatus;
+    redactedInputJson: Record<string, unknown>;
+    redactedOutputJson: Record<string, unknown> | null;
+    usageJson: Record<string, unknown> | null;
+    artifactRefs: PublicRunArtifactRef[] | null;
+    failureJson: PublicRunFailure | null;
+    suspensionStepId: string | null;
+    eventCursor: number;
+    attempts: number;
+    startedAt: string | null;
+    cancellationRequestedAt: string | null;
+    completedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Body for `POST /api/v1/runs` ({@link MaterialGraphClient.createRun}). */
+export interface CreatePublicRunRequest {
+    capabilityKind: CapabilityKind;
+    capabilityId: string;
+    /** The capability input, validated server-side against its live input schema. */
+    inputJson: unknown;
+    /** Stable caller key making Run creation idempotent across retries. */
+    idempotencyKey?: string;
+    /** Free-form caller correlation reference, echoed back on the Run. */
+    clientReference?: string;
+}
+/** The `POST /api/v1/runs` response (`200` replay or `202` accepted). */
+export interface CreatePublicRunResponse {
+    accepted: boolean;
+    replayed: boolean;
+    workflowRunId: string;
+    run: PublicRun;
+}
+/** The `GET /api/v1/runs/{runId}` and resume/cancel response envelope. */
+export interface PublicRunResponse {
+    run: PublicRun;
+}
+/** Body for `POST /api/v1/runs/{runId}/resume`. */
+export interface ResumePublicRunRequest {
+    /** The resume payload, validated against the suspended step's resume schema. */
+    resumeData: unknown;
+}
+/**
+ * One redacted Run event, decoded from an SSE `data:` frame. The stream yields
+ * these in ascending {@link RunEvent.sequence} order. `payloadJson` is read
+ * structurally; use {@link parseRunEvent} to narrow the composition family.
+ */
+export interface RunEvent {
+    sequence: number;
+    type: string;
+    payloadJson: unknown;
+}
+/** Run event types that close the stream — a terminal event ends a drain. */
+export declare const TERMINAL_RUN_EVENT_TYPES: ReadonlySet<string>;
+/** Options for {@link MaterialGraphClient.streamRunEvents}. */
+export interface StreamRunEventsOptions {
+    /** Resume the stream after this sequence (exclusive). Omitted starts at 0. */
+    after?: number;
+    /** Abort the stream; iteration stops cleanly. */
+    signal?: AbortSignal;
+}
+/** Options for {@link MaterialGraphClient.drainRunEvents}. */
+export interface DrainRunEventsOptions {
+    /** Resume after this sequence (exclusive). */
+    after?: number;
+    /** Stop collecting after this many milliseconds even without a terminal event. */
+    deadlineMs: number;
+}

package/run-types.js

@@ -0,0 +1,6 @@
+/** Run event types that close the stream — a terminal event ends a drain. */
+export const TERMINAL_RUN_EVENT_TYPES = new Set([
+    "succeeded",
+    "failed",
+    "canceled",
+]);

package/runs.d.ts

@@ -0,0 +1,42 @@
+import { HttpTransport } from "./http-transport.js";
+import { type CapabilityManifestResponse, type CreatePublicRunRequest, type CreatePublicRunResponse, type DrainRunEventsOptions, type PublicRunResponse, type RunEvent, type SourceMaterialBatchReceipt, type StreamRunEventsOptions, type UploadSourceMaterialInput } from "./run-types.js";
+/**
+ * Upload one atomic source-material batch (`POST /api/v1/source-material`).
+ * Accepts the pile-of-files shape (`{ files }` → repeatable `files` field) or
+ * the legacy `{ brief, references }` shape (→ `brief` + repeatable `references`
+ * fields). Both wire to multipart the server accepts.
+ */
+export declare function uploadSourceMaterial(transport: HttpTransport, input: UploadSourceMaterialInput, signal?: AbortSignal): Promise<SourceMaterialBatchReceipt>;
+/** List invocable agents, workflows, and tools (`GET /api/v1/capabilities`). */
+export declare function capabilities(transport: HttpTransport, signal?: AbortSignal): Promise<CapabilityManifestResponse>;
+/** Start an asynchronous capability Run (`POST /api/v1/runs`). */
+export declare function createRun(transport: HttpTransport, body: CreatePublicRunRequest, signal?: AbortSignal): Promise<CreatePublicRunResponse>;
+/** Get a Run's current state (`GET /api/v1/runs/{runId}`). */
+export declare function getRun(transport: HttpTransport, runId: string, signal?: AbortSignal): Promise<PublicRunResponse>;
+/** Resume a suspended Run (`POST /api/v1/runs/{runId}/resume`). */
+export declare function resumeRun(transport: HttpTransport, runId: string, resumeData: unknown, signal?: AbortSignal): Promise<PublicRunResponse>;
+/** Request durable Run cancellation (`POST /api/v1/runs/{runId}/cancel`). */
+export declare function cancelRun(transport: HttpTransport, runId: string, signal?: AbortSignal): Promise<PublicRunResponse>;
+/**
+ * Stream ordered Run events as an async iterator (`GET
+ * /api/v1/runs/{runId}/events`, SSE). Iterates until the stream ends or
+ * `signal` aborts. One connection is bounded server-side (~25s or a terminal
+ * event); pass `after` to resume from the last observed sequence.
+ */
+export declare function streamRunEvents(transport: HttpTransport, runId: string, options?: StreamRunEventsOptions): AsyncGenerator<RunEvent, void, unknown>;
+/**
+ * Collect Run events until a terminal event, the deadline, or the stream ends —
+ * the bounded events-log pattern the console uses. A single pass over
+ * {@link streamRunEvents}; the deadline is enforced by aborting the stream.
+ *
+ * The deadline abort is this drain's OWN, expected termination — not a failure.
+ * Where it lands decides how {@link streamRunEvents} surfaces it: mid-read it
+ * ends the iterator cleanly, but while the underlying `fetch` is still pending —
+ * the common case for a poll whose upstream has flushed no bytes yet (no new
+ * events after the cursor, so no immediate SSE frame) — it rejects with an
+ * `aborted` {@link MaterialGraphError}. Both mean the same thing here, so the
+ * self-inflicted abort is swallowed and the collected events returned. Any other
+ * failure (a real 4xx/5xx or transport error) still propagates, keeping the
+ * fail-fast surface for genuine upstream problems.
+ */
+export declare function drainRunEvents(transport: HttpTransport, runId: string, options: DrainRunEventsOptions): Promise<RunEvent[]>;

package/runs.js

@@ -0,0 +1,214 @@
+/**
+ * The Run + source-material namespace — the agentic half of the SDK. These
+ * functions take the shared {@link HttpTransport} and speak the hosted Run
+ * lifecycle: upload source material, list capabilities, create/read/resume/
+ * cancel Runs, and stream (or drain) their events. Box's proxy routes are thin
+ * wrappers over exactly these calls.
+ */
+import { MaterialGraphError } from "./errors.js";
+import { HttpTransport } from "./http-transport.js";
+import { findSdkOperation, operationPath } from "./operations.js";
+import { readSseFrames } from "./sse.js";
+import { TERMINAL_RUN_EVENT_TYPES, } from "./run-types.js";
+function runOperation(operationId) {
+    const match = findSdkOperation(operationId);
+    if (!match)
+        throw MaterialGraphError.unexpected(`Unknown SDK operation: ${operationId}`);
+    return match;
+}
+/** Build a `Blob` from raw bytes, normalising to an ArrayBuffer-backed view. */
+function bytesToBlob(input) {
+    const type = input.contentType ? { type: input.contentType } : {};
+    if (input.data instanceof ArrayBuffer)
+        return new Blob([input.data], type);
+    // A Uint8Array may be SharedArrayBuffer-backed; copy into a fresh view so the
+    // Blob part is unambiguously ArrayBuffer-backed (no cast needed).
+    const copy = new Uint8Array(input.data.byteLength);
+    copy.set(input.data);
+    return new Blob([copy], type);
+}
+/** Append one file to the multipart body, from either input form. */
+function appendFile(form, field, input) {
+    if (input instanceof Blob) {
+        if (input instanceof File)
+            form.append(field, input, input.name);
+        else
+            form.append(field, input);
+        return;
+    }
+    form.append(field, bytesToBlob(input), input.filename);
+}
+/**
+ * Upload one atomic source-material batch (`POST /api/v1/source-material`).
+ * Accepts the pile-of-files shape (`{ files }` → repeatable `files` field) or
+ * the legacy `{ brief, references }` shape (→ `brief` + repeatable `references`
+ * fields). Both wire to multipart the server accepts.
+ */
+export async function uploadSourceMaterial(transport, input, signal) {
+    const form = new FormData();
+    if ("files" in input) {
+        for (const file of input.files)
+            appendFile(form, "files", file);
+    }
+    else {
+        appendFile(form, "brief", input.brief);
+        for (const reference of input.references ?? [])
+            appendFile(form, "references", reference);
+    }
+    const url = transport.buildUrl(operationPath(runOperation("upload_source_material")));
+    // No Content-Type header: fetch sets multipart/form-data with the boundary.
+    const { parsed } = await transport.send({
+        method: "POST",
+        url,
+        headers: transport.authHeaders(),
+        body: form,
+        signal,
+    });
+    return parsed;
+}
+/** List invocable agents, workflows, and tools (`GET /api/v1/capabilities`). */
+export function capabilities(transport, signal) {
+    return transport.requestJson(runOperation("list_public_capabilities"), {
+        signal,
+    });
+}
+/** Start an asynchronous capability Run (`POST /api/v1/runs`). */
+export function createRun(transport, body, signal) {
+    return transport.requestJson(runOperation("create_public_run"), {
+        body,
+        signal,
+    });
+}
+/** Get a Run's current state (`GET /api/v1/runs/{runId}`). */
+export function getRun(transport, runId, signal) {
+    return transport.requestJson(runOperation("get_public_run"), {
+        pathParams: { runId },
+        signal,
+    });
+}
+/** Resume a suspended Run (`POST /api/v1/runs/{runId}/resume`). */
+export function resumeRun(transport, runId, resumeData, signal) {
+    return transport.requestJson(runOperation("resume_public_run"), {
+        body: { resumeData },
+        pathParams: { runId },
+        signal,
+    });
+}
+/** Request durable Run cancellation (`POST /api/v1/runs/{runId}/cancel`). */
+export function cancelRun(transport, runId, signal) {
+    return transport.requestJson(runOperation("cancel_public_run"), {
+        body: {},
+        pathParams: { runId },
+        signal,
+    });
+}
+/** Decode one SSE `data:` frame into a {@link RunEvent}, or `null` when unusable. */
+function decodeRunEvent(data) {
+    if (data.length === 0)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(data);
+    }
+    catch (cause) {
+        throw MaterialGraphError.unexpected(`MaterialGraph run-event stream sent an unparseable data frame: ${String(cause)}`);
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return null;
+    const record = parsed;
+    if (typeof record.sequence !== "number" || typeof record.type !== "string")
+        return null;
+    return parsed;
+}
+/**
+ * Stream ordered Run events as an async iterator (`GET
+ * /api/v1/runs/{runId}/events`, SSE). Iterates until the stream ends or
+ * `signal` aborts. One connection is bounded server-side (~25s or a terminal
+ * event); pass `after` to resume from the last observed sequence.
+ */
+export async function* streamRunEvents(transport, runId, options = {}) {
+    const operation = runOperation("list_public_run_events");
+    const url = transport.buildUrl(operationPath(operation, { runId }), options.after === undefined ? undefined : { after: options.after });
+    const requestUrl = new URL(url);
+    const metadata = { method: "GET", origin: requestUrl.origin, path: requestUrl.pathname };
+    let response;
+    try {
+        response = await transport.fetch(url, {
+            method: "GET",
+            headers: transport.authHeaders({ Accept: "text/event-stream" }),
+            signal: options.signal,
+        });
+    }
+    catch (cause) {
+        throw MaterialGraphError.fromTransport({ ...metadata, cause, callerSignal: options.signal });
+    }
+    if (!response.ok) {
+        const text = await response.text().catch(() => "");
+        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: transport.lastRateLimit,
+            apiKey: transport.apiKey,
+            queryValues: [...requestUrl.searchParams.values()],
+        });
+    }
+    if (response.body === null) {
+        throw MaterialGraphError.unexpected("MaterialGraph run-event stream returned no body");
+    }
+    for await (const frame of readSseFrames(response.body, options.signal)) {
+        const event = decodeRunEvent(frame.data);
+        if (event)
+            yield event;
+    }
+}
+/**
+ * Collect Run events until a terminal event, the deadline, or the stream ends —
+ * the bounded events-log pattern the console uses. A single pass over
+ * {@link streamRunEvents}; the deadline is enforced by aborting the stream.
+ *
+ * The deadline abort is this drain's OWN, expected termination — not a failure.
+ * Where it lands decides how {@link streamRunEvents} surfaces it: mid-read it
+ * ends the iterator cleanly, but while the underlying `fetch` is still pending —
+ * the common case for a poll whose upstream has flushed no bytes yet (no new
+ * events after the cursor, so no immediate SSE frame) — it rejects with an
+ * `aborted` {@link MaterialGraphError}. Both mean the same thing here, so the
+ * self-inflicted abort is swallowed and the collected events returned. Any other
+ * failure (a real 4xx/5xx or transport error) still propagates, keeping the
+ * fail-fast surface for genuine upstream problems.
+ */
+export async function drainRunEvents(transport, runId, options) {
+    const collected = [];
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.deadlineMs);
+    try {
+        for await (const event of streamRunEvents(transport, runId, {
+            after: options.after,
+            signal: controller.signal,
+        })) {
+            collected.push(event);
+            if (TERMINAL_RUN_EVENT_TYPES.has(event.type))
+                break;
+        }
+    }
+    catch (error) {
+        const causedByDeadline = controller.signal.aborted && error instanceof MaterialGraphError && error.kind === "aborted";
+        if (!causedByDeadline)
+            throw error;
+    }
+    finally {
+        clearTimeout(timer);
+        controller.abort();
+    }
+    return collected;
+}

package/search-refinement-types.d.ts

@@ -1,6 +1,18 @@
 /** Types for structured refinements returned by MaterialGraph search. */
 import type { SearchInput } from "./types.js";
-/** A hard canonical-attribute filter accepted by the search engine. */
+/**
+ * A hard canonical-attribute filter accepted by the search engine — either a
+ * term match (`{ attributeId, term }`) or a presence check
+ * (`{ attributeId, hasValue: true }`). Applied as a restriction BEFORE ranking.
+ *
+ * The `attributeId` may be a real registry id (`"fire_classifications"`,
+ * `"environmental_product_declaration"`) OR the virtual
+ * `"certification_programme"` (see `CERTIFICATION_PROGRAMME_ATTRIBUTE_ID`),
+ * which matches a programme — GREENGUARD, FloorScore, LEED, an EPD — wherever it
+ * landed across the four certification buckets. Presence (`hasValue`) is NOT
+ * supported for the virtual programme attribute. The typed `spec-types` mirror
+ * and the `specifications` builders produce values assignable to this type.
+ */
 export type SearchFilter = {
     attributeId: string;
     term: string;

package/spec-types.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The specification surface — the typed vocabulary for asking a material
+ * "does it meet this spec?": certifications (GREENGUARD, FloorScore, Declare),
+ * VOC / emissions testing (CDPH v1.2), sustainability programmes (LEED, EPDs),
+ * and fire / abrasion / slip classifications.
+ *
+ * Every shape here is a hand-authored, zero-dependency mirror of the server's
+ * spec filter contract (`specFilterSchema` in
+ * `@materialgraph/products/search/schema`). It exists so a caller answering a
+ * question like "find me a GREENGUARD-certified alternative" or "the same fire
+ * class, but with an EPD on record" reaches for a NAMED, typed criterion instead
+ * of hand-assembling a magic `attribute:value` string.
+ *
+ * These criteria drive two operations equally:
+ * - `client.search({ filters: [...] })` — spec gates layered onto a ranked
+ *   (colour / visual / lexical) search.
+ * - `client.bySpec(...)` — the value-anchored, spec-only primitive, which takes
+ *   the same criteria as `attribute:value` strings (build them with the helpers
+ *   in `./specifications`).
+ */
+/**
+ * The virtual attribute id that matches a certification PROGRAMME wherever it
+ * landed at ingest.
+ *
+ * Certifications are not stored under one attribute: each record is an object
+ * (`{ programme, name, status, … }`) split across FOUR real object-array
+ * attributes by intent — general `certifications`,
+ * `sustainability_certifications`, `material_health_certifications`, and
+ * `voc_emissions_testing_certificate` (GREENGUARD Gold / FloorScore / CDPH land
+ * in the last). A caller shouldn't have to know which bucket a programme fell
+ * into, so this single virtual id matches the `programme` term across all four.
+ *
+ * @example
+ * // "find a GREENGUARD-certified alternative"
+ * client.search({
+ *   similarTo: { variantId: seed },
+ *   filters: [{ attributeId: CERTIFICATION_PROGRAMME_ATTRIBUTE_ID, term: "GREENGUARD Gold" }],
+ * });
+ */
+export declare const CERTIFICATION_PROGRAMME_ATTRIBUTE_ID = "certification_programme";
+/** The literal type of {@link CERTIFICATION_PROGRAMME_ATTRIBUTE_ID}. */
+export type CertificationProgrammeAttributeId = typeof CERTIFICATION_PROGRAMME_ATTRIBUTE_ID;
+/**
+ * A term-equality spec criterion: the attribute must carry this canonical value,
+ * e.g. `{ attributeId: "fire_classifications", term: "astm_e84_class_a" }`.
+ * Discover valid `attributeId`/`term` pairs via `client.specificationFacets()`
+ * and `client.attributeValues()`, or resolve free text with
+ * `client.resolveAttribute()`.
+ */
+export interface SpecTermFilter {
+    attributeId: string;
+    term: string;
+}
+/**
+ * A presence spec criterion: the attribute must have ANY accepted value —
+ * "has an EPD on record", "has a measured slip figure at all". Not supported for
+ * {@link CERTIFICATION_PROGRAMME_ATTRIBUTE_ID} (a programme is matched by name,
+ * never by bare presence).
+ */
+export interface SpecPresenceFilter {
+    attributeId: string;
+    hasValue: true;
+}
+/**
+ * A certification-programme criterion — a {@link SpecTermFilter} pinned to the
+ * virtual {@link CERTIFICATION_PROGRAMME_ATTRIBUTE_ID}. Structurally assignable
+ * to {@link SpecFilter}, so it drops straight into `search({ filters })`.
+ */
+export interface CertificationProgrammeFilter {
+    attributeId: CertificationProgrammeAttributeId;
+    term: string;
+}
+/**
+ * A hard, canonical-attribute spec criterion — either a term match or a
+ * presence check. The union the search engine applies as a restriction BEFORE
+ * ranking. Identical in shape to the SDK's `SearchFilter`.
+ */
+export type SpecFilter = SpecTermFilter | SpecPresenceFilter;