@instruments/materialgraph 0.2.0 → 0.3.0

package/runs.js

@@ -8,6 +8,7 @@
 import { MaterialGraphError } from "./errors.js";
 import { HttpTransport } from "./http-transport.js";
 import { findSdkOperation, operationPath } from "./operations.js";
+import { checkSourceMaterialBatchDetail } from "./source-material-validation.js";
 import { readSseFrames } from "./sse.js";
 import { TERMINAL_RUN_EVENT_TYPES, } from "./run-types.js";
 function runOperation(operationId) {
@@ -66,6 +67,25 @@ export async function uploadSourceMaterial(transport, input, signal) {
     });
     return parsed;
 }
+/**
+ * Read back one uploaded batch (`GET /api/v1/source-material/{batchId}`): every
+ * file with a fetchable `url`, and every analysis computed over its bytes
+ * inlined as `analyses` — always an array, `[]` when nothing has been computed.
+ *
+ * A batch you do not own is indistinguishable from one that does not exist:
+ * both raise a 404, never a 403, so batch ids cannot be probed for existence.
+ *
+ * The body is VALIDATED, not trusted: `checkSourceMaterialBatchDetail` mirrors
+ * the server's Zod contract so a malformed response fails here with a path into
+ * the payload rather than as an undefined three frames away in caller code.
+ */
+export async function getSourceMaterialBatch(transport, batchId, signal) {
+    const body = await transport.requestJson(runOperation("get_source_material_batch"), {
+        pathParams: { batchId },
+        signal,
+    });
+    return checkSourceMaterialBatchDetail(body, batchId);
+}
 /** List invocable agents, workflows, and tools (`GET /api/v1/capabilities`). */
 export function capabilities(transport, signal) {
     return transport.requestJson(runOperation("list_public_capabilities"), {
@@ -86,10 +106,61 @@ export function getRun(transport, runId, signal) {
         signal,
     });
 }
-/** Resume a suspended Run (`POST /api/v1/runs/{runId}/resume`). */
-export function resumeRun(transport, runId, resumeData, signal) {
+/**
+ * Export a completed compose Run's scheme as a finish schedule — one row per
+ * slot, every attribute value carrying its source and verification state
+ * (`GET /api/v1/runs/{runId}/schedule`).
+ *
+ * The `.xlsx` form of the same export is deliberately NOT an SDK method: this
+ * transport parses every response as text/JSON and has no binary read path, so
+ * a bytes-returning method would mean a second transport surface for one file.
+ * Fetch `GET /api/v1/runs/{runId}/schedule.xlsx` directly with the same bearer
+ * key when you want the workbook.
+ */
+export function getRunSchedule(transport, runId, options = {}) {
+    return transport.requestJson(runOperation("get_run_finish_schedule"), {
+        pathParams: { runId },
+        ...(options.schemeId ? { query: { schemeId: options.schemeId } } : {}),
+        ...(options.signal ? { signal: options.signal } : {}),
+    });
+}
+/**
+ * Normalise `resumeRun`'s overloaded third argument.
+ *
+ * A bare `AbortSignal` stays supported because it is the published shape:
+ * reordering that parameter would break any consumer passing it positionally,
+ * and this ships with no version bump.
+ *
+ * Discriminated on `instanceof AbortSignal`, NOT on the presence of `stepId`.
+ * `{ signal }` with no `stepId` is a perfectly valid options object, and a
+ * key-presence test would misread it as a signal and silently drop the abort.
+ */
+function resumeOptions(value) {
+    if (value === undefined)
+        return {};
+    return value instanceof AbortSignal ? { signal: value } : value;
+}
+/**
+ * Resume a suspended Run (`POST /api/v1/runs/{runId}/resume`).
+ *
+ * The third argument takes either an `AbortSignal` (legacy) or
+ * {@link ResumeRunOptions}.
+ *
+ * `stepId` is forwarded whenever it is PRESENT — `!== undefined`, not truthy.
+ * An empty string is a present-but-malformed value and must reach the server
+ * so its schema rejects it; treating it as absent would silently downgrade a
+ * guarded resume into an unguarded one, which is the exact failure this guard
+ * exists to prevent.
+ *
+ * Omitting it sends a body byte-identical to what this sent before. Note the
+ * wire cannot distinguish `{ stepId: undefined }` from no key at all —
+ * `JSON.stringify` drops both — so the distinction here is construction
+ * intent, kept so the serialised body is provably unchanged for old callers.
+ */
+export function resumeRun(transport, runId, resumeData, signalOrOptions) {
+    const { stepId, signal } = resumeOptions(signalOrOptions);
     return transport.requestJson(runOperation("resume_public_run"), {
-        body: { resumeData },
+        body: { resumeData, ...(stepId !== undefined ? { stepId } : {}) },
         pathParams: { runId },
         signal,
     });
@@ -127,46 +198,14 @@ function decodeRunEvent(data) {
  * 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 body = await transport.openStream(runOperation("list_public_run_events"), {
+        pathParams: { runId },
+        ...(options.after === undefined ? {} : { query: { after: options.after } }),
+        ...(options.signal ? { signal: options.signal } : {}),
+        accept: "text/event-stream",
+        subject: "run-event stream",
+    });
+    for await (const frame of readSseFrames(body, options.signal)) {
         const event = decodeRunEvent(frame.data);
         if (event)
             yield event;

package/schedule-types.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Finish-schedule wire types (MG-616) — the hand-mirror of
+ * `@materialgraph/products/schemes/finish-schedule`. Kept in their own module
+ * rather than `types.ts`, which sits at its source-size baseline.
+ *
+ * A finish schedule is a completed compose scheme rendered as ONE ROW PER SLOT:
+ * the shape a specifier issues. The contract that makes it trustworthy is that
+ * every row carries the IDENTICAL, fixed column set, and every attribute cell
+ * states its own verification alongside its value. An unknown is an explicit
+ * `missing` cell with a null value — never a blank that reads as complete.
+ */
+/** One schedule column: the attribute and its header text. */
+export interface FinishScheduleColumn {
+    attributeId: string;
+    /** The registry presentation label. */
+    label: string;
+}
+/**
+ * The six verification states a schedule cell can report, mirroring the shared
+ * verdict contract. On this public surface a `proposed` (pending-review) value
+ * is projected to `missing`, so it can never be told apart from a value that
+ * never existed.
+ */
+export type FinishScheduleCellState = "matched" | "deviated" | "failed" | "unverified" | "missing" | "not_evaluated";
+/**
+ * One attribute cell of one row: the value AND how far it can be trusted.
+ *
+ * Columns the Run's criteria evaluated carry the real verdict state. Columns
+ * backfilled from the catalogue (nothing in the brief asked about them) only
+ * ever read `matched` or `missing`: they assert presence-with-trust, not that
+ * the brief was met.
+ */
+export interface FinishScheduleCell {
+    attributeId: string;
+    label: string;
+    /** The display value, or null when unknown. */
+    value: string | null;
+    state: FinishScheduleCellState;
+    confidence: number | null;
+    sourceBasis: string | null;
+}
+/** The rolled-up grade for one row, from its evaluated criterion cells only. */
+export type FinishScheduleGrade = "meets_all" | "close" | "hard_no";
+/** One row: one slot, one specified material, fully graded. */
+export interface FinishScheduleRow {
+    slotId: string;
+    slotName: string;
+    /** The space NAME, or null for a spaceless slot. */
+    space: string | null;
+    element: string | null;
+    /** True when the designer pinned this pick rather than the engine choosing it. */
+    anchored: boolean;
+    brand: string;
+    product: string;
+    variant: string;
+    variantId: string;
+    /** Relative path to the public material record (`/materials/{variantId}`). */
+    recordUrl: string;
+    imageUrl: string | null;
+    hex: string | null;
+    /** Always the full, identically-ordered column set. */
+    attributes: FinishScheduleCell[];
+    fitNotes: string[];
+    grade: FinishScheduleGrade;
+}
+/** A whole composed scheme as an issuable finish schedule. */
+export interface FinishSchedule {
+    runId: string;
+    schemeId: string;
+    title: string;
+    /** The compose contract version stamped on the Run, or `"unknown"`. */
+    composeVersion: string;
+    /** ISO timestamp the export was compiled at. */
+    generatedAt: string;
+    /** The stable column order every row's `attributes` array follows. */
+    columns: FinishScheduleColumn[];
+    rows: FinishScheduleRow[];
+}
+/** `GET /api/v1/runs/{runId}/schedule`. */
+export interface FinishScheduleResponse {
+    schedule: FinishSchedule;
+}
+/** Options for {@link getRunSchedule}. */
+export interface GetRunScheduleOptions {
+    /** Which composed scheme to export; defaults to the Run's first scheme. */
+    schemeId?: string;
+    signal?: AbortSignal;
+}

package/schedule-types.js

@@ -0,0 +1,12 @@
+/**
+ * Finish-schedule wire types (MG-616) — the hand-mirror of
+ * `@materialgraph/products/schemes/finish-schedule`. Kept in their own module
+ * rather than `types.ts`, which sits at its source-size baseline.
+ *
+ * A finish schedule is a completed compose scheme rendered as ONE ROW PER SLOT:
+ * the shape a specifier issues. The contract that makes it trustworthy is that
+ * every row carries the IDENTICAL, fixed column set, and every attribute cell
+ * states its own verification alongside its value. An unknown is an explicit
+ * `missing` cell with a null value — never a blank that reads as complete.
+ */
+export {};

package/search-refinement-types.d.ts

@@ -13,12 +13,25 @@ import type { SearchInput } from "./types.js";
  * supported for the virtual programme attribute. The typed `spec-types` mirror
  * and the `specifications` builders produce values assignable to this type.
  */
+/**
+ * Optional per-filter TRUST bar the matching value must clear. `minConfidence` is
+ * an explicit confidence floor; `sourceBasis` demands an EXACT source basis (closed
+ * enum — an unknown basis is rejected); `meetsRequirement` folds the attribute's
+ * registry confidence requirement server-side.
+ */
+export interface SearchFilterTrust {
+    minConfidence?: number;
+    sourceBasis?: "catalog_feed" | "declared" | "derived" | "tested";
+    meetsRequirement?: true;
+}
 export type SearchFilter = {
     attributeId: string;
     term: string;
+    trust?: SearchFilterTrust;
 } | {
     attributeId: string;
     hasValue: true;
+    trust?: SearchFilterTrust;
 };
 /** One structured refinement returned with a search response. */
 export interface SearchSuggestion {

package/search-result-validation.d.ts

@@ -0,0 +1,27 @@
+import { type ValidationFailure } from "./validation.js";
+/** `verdictStateSchema` — the six live cell states. */
+export declare const VERDICT_STATES: readonly ["matched", "deviated", "failed", "unverified", "missing", "not_evaluated"];
+/** `attributeVerdictSchema.strength`. */
+export declare const VERDICT_STRENGTHS: readonly ["required", "preferred"];
+/** `verdictBaselineSchema` discriminant — the four arms of what a cell was judged against. */
+export declare const VERDICT_BASELINE_KINDS: readonly ["term", "presence", "seed", "image"];
+/** The `image` baseline arm's own `source` enum. */
+export declare const VERDICT_IMAGE_SOURCES: readonly ["variant", "vector"];
+/** `verdictDeviationSchema.direction`. */
+export declare const VERDICT_DEVIATION_DIRECTIONS: readonly ["above", "below", "other"];
+/** `verdictTrustGapSchema` — why a real value did not clear the trust bar. */
+export declare const VERDICT_TRUST_GAPS: readonly ["below_confidence", "basis_unmet", "proposed"];
+/** `verdictGradeSchema` — the rolled-up card grade. */
+export declare const VERDICT_GRADES: readonly ["meets_all", "close", "hard_no"];
+/** `visualMeaningSchema.basis` — where a meaning came from. */
+export declare const VISUAL_MEANING_BASES: readonly ["canonical_attribute", "image_colour_analysis"];
+/**
+ * Prove one wire value is a {@link SearchResultItem}, raising through `fail` at
+ * the first field that does not match `searchResultItemSchema`. Checks the shape
+ * only — unknown keys ride through untouched, per the SDK's pass-through
+ * contract (nothing on the emit path parses, so stripping would invent a
+ * normalisation the wire never had).
+ */
+export declare function checkSearchResultItem(value: unknown, what: string, fail: ValidationFailure): void;
+/** Prove every entry of a `results[]` array is a {@link SearchResultItem}. */
+export declare function checkSearchResultItems(items: readonly unknown[], what: string, fail: ValidationFailure): void;

package/search-result-validation.js

@@ -0,0 +1,174 @@
+import { requireArray, requireBoolean, requireEnum, requireNonEmptyString, requireNonEmptyStringArray, requireNullableBoundedNumber, requireNullableEnum, requireNullableNonEmptyString, requireNullableNumber, requireNullableString, requireNumber, requireOptionalBoolean, requireOptionalNumber, requireOptionalString, requireRecord, requireString, requireIntegerAtLeast, } from "./validation.js";
+// ── Closed enum members (canonical `z.enum` mirrors) ─────────────────────────
+/** `verdictStateSchema` — the six live cell states. */
+export const VERDICT_STATES = [
+    "matched",
+    "deviated",
+    "failed",
+    "unverified",
+    "missing",
+    "not_evaluated",
+];
+/** `attributeVerdictSchema.strength`. */
+export const VERDICT_STRENGTHS = ["required", "preferred"];
+/** `verdictBaselineSchema` discriminant — the four arms of what a cell was judged against. */
+export const VERDICT_BASELINE_KINDS = ["term", "presence", "seed", "image"];
+/** The `image` baseline arm's own `source` enum. */
+export const VERDICT_IMAGE_SOURCES = ["variant", "vector"];
+/** `verdictDeviationSchema.direction`. */
+export const VERDICT_DEVIATION_DIRECTIONS = ["above", "below", "other"];
+/** `verdictTrustGapSchema` — why a real value did not clear the trust bar. */
+export const VERDICT_TRUST_GAPS = ["below_confidence", "basis_unmet", "proposed"];
+/** `verdictGradeSchema` — the rolled-up card grade. */
+export const VERDICT_GRADES = ["meets_all", "close", "hard_no"];
+/** `visualMeaningSchema.basis` — where a meaning came from. */
+export const VISUAL_MEANING_BASES = ["canonical_attribute", "image_colour_analysis"];
+// ── Leaf checks ──────────────────────────────────────────────────────────────
+/** `palette[]` — `{ hex, proportion, name: string.nullable().optional() }`. */
+function checkPaletteSwatch(value, what, fail) {
+    const record = requireRecord(value, what, fail);
+    requireString(record.hex, `${what}.hex`, fail);
+    requireNumber(record.proportion, `${what}.proportion`, fail);
+    // `.nullable().optional()` — absent OR null OR a string.
+    if (record.name !== undefined)
+        requireNullableString(record.name, `${what}.name`, fail);
+}
+/** `colourMeta` — three independently optional strings. */
+function checkColourMeta(value, what, fail) {
+    const record = requireRecord(value, what, fail);
+    requireOptionalString(record.mood, `${what}.mood`, fail);
+    requireOptionalString(record.dominantFamily, `${what}.dominantFamily`, fail);
+    requireOptionalString(record.dominantHex, `${what}.dominantHex`, fail);
+}
+/** `searchResultSignalsSchema` — five nullable numbers, all required keys. */
+function checkSignals(value, what, fail) {
+    const record = requireRecord(value, what, fail);
+    for (const signal of ["image", "category", "colour", "lexical", "text"]) {
+        requireNullableNumber(record[signal], `${what}.${signal}`, fail);
+    }
+}
+/** `visualMeaningSchema` — note the NON-EMPTY `values` array and the closed `basis`. */
+function checkVisualMeaning(value, what, fail) {
+    const record = requireRecord(value, what, fail);
+    requireString(record.id, `${what}.id`, fail);
+    requireString(record.label, `${what}.label`, fail);
+    requireNonEmptyStringArray(record.values, `${what}.values`, fail);
+    requireEnum(record.basis, VISUAL_MEANING_BASES, `${what}.basis`, fail);
+    requireOptionalNumber(record.confidence, `${what}.confidence`, fail);
+    requireOptionalString(record.sourceBasis, `${what}.sourceBasis`, fail);
+    requireOptionalString(record.version, `${what}.version`, fail);
+    requireOptionalString(record.appliedAt, `${what}.appliedAt`, fail);
+}
+// ── Verdict subtree ──────────────────────────────────────────────────────────
+/**
+ * `verdictBaselineSchema` — a discriminated union on `kind`. An unknown
+ * discriminant is rejected, exactly as `z.discriminatedUnion` rejects it, and
+ * each arm carries only the fields it needs.
+ */
+function checkVerdictBaseline(value, what, fail) {
+    const record = requireRecord(value, what, fail);
+    const kind = requireEnum(record.kind, VERDICT_BASELINE_KINDS, `${what}.kind`, fail);
+    switch (kind) {
+        case "term":
+            requireNonEmptyString(record.term, `${what}.term`, fail);
+            return;
+        case "presence":
+            return;
+        case "seed":
+            requireNonEmptyString(record.variantId, `${what}.variantId`, fail);
+            return;
+        default:
+            // `image` — the like-this-picture arm.
+            requireEnum(record.source, VERDICT_IMAGE_SOURCES, `${what}.source`, fail);
+            requireNullableNonEmptyString(record.variantId, `${what}.variantId`, fail);
+    }
+}
+/** `verdictDeviationSchema` — a named near-miss. */
+function checkVerdictDeviation(value, what, fail) {
+    const record = requireRecord(value, what, fail);
+    requireEnum(record.direction, VERDICT_DEVIATION_DIRECTIONS, `${what}.direction`, fail);
+    requireNullableNumber(record.delta, `${what}.delta`, fail);
+    requireNullableString(record.unit, `${what}.unit`, fail);
+    requireNonEmptyString(record.label, `${what}.label`, fail);
+}
+/**
+ * `attributeVerdictSchema` — nine fields plus the TWO cross-field invariants its
+ * `.superRefine()` enforces. Those are relational rather than field-wise, which
+ * is no obstacle to a hand-rolled validator: they are two conditionals, and the
+ * schema's own doc calls them out as the reason a malformed cell can never reach
+ * a consumer.
+ */
+function checkAttributeVerdict(value, what, fail) {
+    const record = requireRecord(value, what, fail);
+    requireNonEmptyString(record.attributeId, `${what}.attributeId`, fail);
+    const state = requireEnum(record.state, VERDICT_STATES, `${what}.state`, fail);
+    requireEnum(record.strength, VERDICT_STRENGTHS, `${what}.strength`, fail);
+    checkVerdictBaseline(record.baseline, `${what}.baseline`, fail);
+    requireNullableString(record.value, `${what}.value`, fail);
+    requireNullableBoundedNumber(record.confidence, `${what}.confidence`, fail, 0, 1);
+    requireNullableString(record.sourceBasis, `${what}.sourceBasis`, fail);
+    const deviation = record.deviation;
+    if (deviation !== null)
+        checkVerdictDeviation(deviation, `${what}.deviation`, fail);
+    const trustGap = requireNullableEnum(record.trustGap, VERDICT_TRUST_GAPS, `${what}.trustGap`, fail);
+    // superRefine invariant 1 — a deviation only describes a `deviated` cell.
+    if (deviation !== null && state !== "deviated") {
+        throw fail(`${what}.deviation is set on a cell whose state is "${state}", not "deviated"`);
+    }
+    // superRefine invariant 2 — a trust gap only explains an `unverified` cell.
+    if (trustGap !== null && state !== "unverified") {
+        throw fail(`${what}.trustGap is set on a cell whose state is "${state}", not "unverified"`);
+    }
+}
+/** `candidateVerdictSchema` — the whole report card. */
+function checkCandidateVerdict(value, what, fail) {
+    const record = requireRecord(value, what, fail);
+    const cells = requireArray(record.cells, `${what}.cells`, fail);
+    cells.forEach((cell, index) => checkAttributeVerdict(cell, `${what}.cells[${index}]`, fail));
+    requireEnum(record.grade, VERDICT_GRADES, `${what}.grade`, fail);
+    requireNullableBoundedNumber(record.minConfidence, `${what}.minConfidence`, fail, 0, 1);
+}
+// ── The item ─────────────────────────────────────────────────────────────────
+/**
+ * Prove one wire value is a {@link SearchResultItem}, raising through `fail` at
+ * the first field that does not match `searchResultItemSchema`. Checks the shape
+ * only — unknown keys ride through untouched, per the SDK's pass-through
+ * contract (nothing on the emit path parses, so stripping would invent a
+ * normalisation the wire never had).
+ */
+export function checkSearchResultItem(value, what, fail) {
+    const record = requireRecord(value, what, fail);
+    requireString(record.variantId, `${what}.variantId`, fail);
+    requireString(record.brand, `${what}.brand`, fail);
+    requireString(record.product, `${what}.product`, fail);
+    requireNullableString(record.brandSlug, `${what}.brandSlug`, fail);
+    requireNullableString(record.productId, `${what}.productId`, fail);
+    requireNullableString(record.color, `${what}.color`, fail);
+    requireNullableString(record.variantName, `${what}.variantName`, fail);
+    requireNullableString(record.imageUrl, `${what}.imageUrl`, fail);
+    requireBoolean(record.hasImage, `${what}.hasImage`, fail);
+    requireNumber(record.score, `${what}.score`, fail);
+    const palette = requireArray(record.palette, `${what}.palette`, fail);
+    palette.forEach((swatch, index) => checkPaletteSwatch(swatch, `${what}.palette[${index}]`, fail));
+    if (record.colourMeta !== undefined) {
+        checkColourMeta(record.colourMeta, `${what}.colourMeta`, fail);
+    }
+    if (record.signals !== undefined)
+        checkSignals(record.signals, `${what}.signals`, fail);
+    requireOptionalBoolean(record.retired, `${what}.retired`, fail);
+    requireOptionalBoolean(record.belowFloor, `${what}.belowFloor`, fail);
+    if (record.siblingCount !== undefined) {
+        requireIntegerAtLeast(record.siblingCount, `${what}.siblingCount`, fail, 1);
+    }
+    if (record.visualMeanings !== undefined) {
+        const meanings = requireArray(record.visualMeanings, `${what}.visualMeanings`, fail);
+        meanings.forEach((meaning, index) => checkVisualMeaning(meaning, `${what}.visualMeanings[${index}]`, fail));
+    }
+    if (record.verdict !== undefined) {
+        checkCandidateVerdict(record.verdict, `${what}.verdict`, fail);
+    }
+}
+/** Prove every entry of a `results[]` array is a {@link SearchResultItem}. */
+export function checkSearchResultItems(items, what, fail) {
+    items.forEach((item, index) => checkSearchResultItem(item, `${what}[${index}]`, fail));
+}

package/source-material-validation.d.ts

@@ -0,0 +1,3 @@
+import type { SourceMaterialBatchDetail } from "./run-types.js";
+/** Validate a batch-detail body, returning it typed, or throw explaining why. */
+export declare function checkSourceMaterialBatchDetail(value: unknown, batchId: string): SourceMaterialBatchDetail;

package/source-material-validation.js

@@ -0,0 +1,109 @@
+/**
+ * The runtime validator for `GET /api/v1/source-material/{batchId}` — the
+ * hand-rolled, zero-runtime-dependency mirror of
+ * `sourceMaterialBatchDetailSchema` and its transitive closure
+ * (`sourceMaterialBatchDetailFileSchema`, `sourceImageAnalysisSchema`,
+ * `sourceImageAnalysisResultSchema`) in
+ * `packages/sources/src/source-material/contract.ts`.
+ *
+ * WHY IT EXISTS. `contract-parity.test.ts` proves the SDK's STATIC types match
+ * the canonical schemas; that is a compile-time proof about shapes and validates
+ * nothing at run time. This is the run-time half, and it must ACCEPT and REJECT
+ * exactly what the schema does — pinned by `source-material-parity.test.ts`.
+ *
+ * TWO CONTRACT PROPERTIES IT ENFORCES, both easy to lose in a refactor:
+ *   1. `analyses` is REQUIRED and an array on every file. `[]` means "nothing
+ *      computed yet"; an absent field is a broken response, not an empty one.
+ *      Preprocessing is manual today and automatic later — only the trigger
+ *      changes, never this contract.
+ *   2. `result` is a JSON record all the way down (`z.json()`), not `unknown`.
+ *      See `requireJsonValue` for why the schema is that strict and why this
+ *      mirror cannot actually fire over the wire.
+ *
+ * ENUMS ARE CLOSED here, matching the canonical `z.enum(…)` members, while the
+ * published types are `OpenEnum` so a newer server value keeps type-checking.
+ * The validator follows the SCHEMA: the type stays wider than what is proven,
+ * which is imprecise but never a lie — the same choice
+ * `search-result-validation.ts` makes for `basis`.
+ *
+ * Package-internal (not re-exported from `index.ts`): a published symbol is a
+ * permanent contract, and promoting it later is additive.
+ */
+import { MaterialGraphError } from "./errors.js";
+import { requireArray, requireEnum, requireSafeInteger, requireJsonRecord, requireNonEmptyString, requireRecord, requireString, } from "./validation.js";
+/** `sourceImageAnalysisKindSchema` members, verbatim. */
+const ANALYSIS_KINDS = ["scene_match"];
+/** `sourceImageAnalysisStatusSchema` members, verbatim. */
+const ANALYSIS_STATUSES = ["ok", "failed"];
+/** `sourceMaterialRoleSchema` members, verbatim. */
+const SOURCE_ROLES = [
+    "brief",
+    "reference_image",
+    "document",
+    "document_image",
+    "inspiration_image",
+    "unclassified",
+];
+function detailFailure(batchId) {
+    return (reason) => MaterialGraphError.unexpected(`GET /api/v1/source-material/${batchId} returned a malformed body: ${reason}`);
+}
+function checkAnalysis(value, what, fail) {
+    const record = requireRecord(value, what, fail);
+    // `model` and `analysedAt` ARE `.min(1)` canonically — fields this endpoint
+    // introduces, where an empty value is meaningless and `model` already cannot
+    // be written empty. Parity here is achieved by the schema being strict, never
+    // by this mirror freelancing past it.
+    return {
+        kind: requireEnum(record.kind, ANALYSIS_KINDS, `${what}.kind`, fail),
+        model: requireNonEmptyString(record.model, `${what}.model`, fail),
+        status: requireEnum(record.status, ANALYSIS_STATUSES, `${what}.status`, fail),
+        result: requireJsonRecord(record.result, `${what}.result`, fail),
+        analysedAt: requireNonEmptyString(record.analysedAt, `${what}.analysedAt`, fail),
+    };
+}
+function checkFile(value, what, fail) {
+    const record = requireRecord(value, what, fail);
+    // NOT `requireDefaultedArray`: the schema has no `.default([])`, so an absent
+    // `analyses` is a malformed body rather than an empty one. Keeping that
+    // distinction is the whole point of the always-an-array contract.
+    const analyses = requireArray(record.analyses, `${what}.analyses`, fail);
+    // `requireString`, NOT `requireNonEmptyString`, for the fields this endpoint
+    // INHERITS from the shared source-material contract (`sourceId`, `sha256`,
+    // `url` — plus `batchId`/`createdAt` below). Those are plain `z.string()`
+    // there and shared with the upload path; a client that rejected `""` would
+    // refuse a response the server can legitimately produce, and tightening them
+    // is a change to a contract this endpoint does not own.
+    return {
+        sourceId: requireString(record.sourceId, `${what}.sourceId`, fail),
+        role: requireEnum(record.role, SOURCE_ROLES, `${what}.role`, fail),
+        filename: requireString(record.filename, `${what}.filename`, fail),
+        mediaType: requireString(record.mediaType, `${what}.mediaType`, fail),
+        sha256: requireString(record.sha256, `${what}.sha256`, fail),
+        // `requireSafeInteger`, NOT `requireIntegerAtLeast(…, 0)`. Canonically these
+        // are a bare `z.number().int()` on the INHERITED
+        // `sourceMaterialFileReceiptSchema`, which carries no lower bound — so a
+        // negative is accepted there and must be accepted here.
+        //
+        // A negative `bytes` is nonsense and a negative `pages` more so, and this is
+        // still not the place to say so: a client validator holding an opinion the
+        // contract does not is how the two drift, and how a response the server may
+        // legitimately produce starts throwing at the boundary. Tightening those
+        // fields is a canonical change to a schema shared with the upload path, and
+        // belongs in its own ticket with this mirror following after.
+        bytes: requireSafeInteger(record.bytes, `${what}.bytes`, fail),
+        pages: record.pages === null ? null : requireSafeInteger(record.pages, `${what}.pages`, fail),
+        url: requireString(record.url, `${what}.url`, fail),
+        analyses: analyses.map((analysis, index) => checkAnalysis(analysis, `${what}.analyses[${index}]`, fail)),
+    };
+}
+/** Validate a batch-detail body, returning it typed, or throw explaining why. */
+export function checkSourceMaterialBatchDetail(value, batchId) {
+    const fail = detailFailure(batchId);
+    const record = requireRecord(value, "body", fail);
+    const sources = requireArray(record.sources, "body.sources", fail);
+    return {
+        batchId: requireString(record.batchId, "body.batchId", fail),
+        createdAt: requireString(record.createdAt, "body.createdAt", fail),
+        sources: sources.map((file, index) => checkFile(file, `body.sources[${index}]`, fail)),
+    };
+}

package/spec-types.d.ts

@@ -30,6 +30,10 @@
  * 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.
  *
+ * The `term` may be a display name or alias ("GREENGUARD Gold", "LEED"), resolved
+ * server-side to its canonical programme token, or a canonical token directly
+ * (e.g. `greenguard_certificate`, `has_greenguard_gold_certification`).
+ *
  * @example
  * // "find a GREENGUARD-certified alternative"
  * client.search({

package/spec-types.js

@@ -30,6 +30,10 @@
  * 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.
  *
+ * The `term` may be a display name or alias ("GREENGUARD Gold", "LEED"), resolved
+ * server-side to its canonical programme token, or a canonical token directly
+ * (e.g. `greenguard_certificate`, `has_greenguard_gold_certification`).
+ *
  * @example
  * // "find a GREENGUARD-certified alternative"
  * client.search({

package/specifications.d.ts

@@ -38,6 +38,11 @@ export declare function hasSpec(attributeId: string): SpecPresenceFilter;
  * virtual attribute so a programme matches wherever it landed at ingest
  * (compliance / sustainability / material-health / VOC buckets).
  *
+ * The value may be a display name or alias ("GREENGUARD Gold", "LEED") — the
+ * server resolves it to its canonical programme token before matching — or a
+ * canonical token directly (e.g. `greenguard_certificate`,
+ * `has_greenguard_gold_certification`).
+ *
  * @example
  * // "find a GREENGUARD-certified alternative"
  * client.search({ similarTo: { variantId: seed }, filters: [certificationProgramme("GREENGUARD Gold")] });
@@ -56,6 +61,10 @@ export declare function specCriterion(attributeId: string, value: string): strin
  * An `attribute:value` criterion string for `bySpec` that filters by
  * certification PROGRAMME across all four certification buckets.
  *
+ * The value may be a display name or alias ("GREENGUARD Gold", "LEED"), resolved
+ * server-side to its canonical programme token, or a canonical token directly
+ * (e.g. `greenguard_certificate`, `has_greenguard_gold_certification`).
+ *
  * @example
  * // every brand's GREENGUARD-Gold materials
  * client.bySpec([certificationProgrammeCriterion("GREENGUARD Gold")]);