@instruments/materialgraph 0.1.0 → 0.3.0

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

@@ -1,12 +1,37 @@
 /** 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.
+ */
+/**
+ * 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

@@ -0,0 +1,82 @@
+/**
+ * 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.
+ *
+ * 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({
+ *   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;

package/spec-types.js

@@ -0,0 +1,44 @@
+/**
+ * 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.
+ *
+ * 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({
+ *   similarTo: { variantId: seed },
+ *   filters: [{ attributeId: CERTIFICATION_PROGRAMME_ATTRIBUTE_ID, term: "GREENGUARD Gold" }],
+ * });
+ */
+export const CERTIFICATION_PROGRAMME_ATTRIBUTE_ID = "certification_programme";

package/specifications.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Zero-dependency builders for the specification surface. Turn a plain-language
+ * spec intent into a typed criterion the SDK's two spec operations accept:
+ *
+ * - `search({ filters })` takes {@link SpecFilter} objects — a spec gate layered
+ *   onto a ranked (colour / visual / lexical) search. Build them with
+ *   {@link specTerm}, {@link hasSpec}, and {@link certificationProgramme}.
+ * - `bySpec(specs)` takes `attribute:value` strings — the value-anchored,
+ *   spec-only primitive. Build them with {@link specCriterion} and
+ *   {@link certificationProgrammeCriterion}.
+ *
+ * The point of these helpers: Desk (and any spec-driven caller) never has to
+ * remember that a certification programme lives under a VIRTUAL attribute, nor
+ * hand-format the `attribute:value` string the `bySpec` route splits on its
+ * first `:`.
+ */
+import { type CertificationProgrammeFilter, type SpecPresenceFilter, type SpecTermFilter } from "./spec-types.js";
+/**
+ * A term-equality criterion for `search({ filters })` — the attribute must
+ * carry this canonical value.
+ *
+ * @example
+ * // "same fire class as the seed"
+ * client.search({ similarTo: { variantId }, filters: [specTerm("fire_classifications", "astm_e84_class_a")] });
+ */
+export declare function specTerm(attributeId: string, term: string): SpecTermFilter;
+/**
+ * A presence criterion for `search({ filters })` — the attribute must have ANY
+ * accepted value.
+ *
+ * @example
+ * // "…and it must have an EPD on record"
+ * client.search({ similarTo: { variantId }, filters: [hasSpec("environmental_product_declaration")] });
+ */
+export declare function hasSpec(attributeId: string): SpecPresenceFilter;
+/**
+ * A certification-programme criterion for `search({ filters })`, pinned to the
+ * 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")] });
+ */
+export declare function certificationProgramme(programme: string): CertificationProgrammeFilter;
+/**
+ * An `attribute:value` criterion string for `bySpec`. The `bySpec` route splits
+ * on the FIRST `:`, so a value may itself contain colons; the attribute id may
+ * not.
+ *
+ * @example
+ * client.bySpec([specCriterion("primary_material", "textile"), specCriterion("fire_classifications", "astm_e84_class_a")]);
+ */
+export declare function specCriterion(attributeId: string, value: string): string;
+/**
+ * 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")]);
+ */
+export declare function certificationProgrammeCriterion(programme: string): string;