@instruments/materialgraph 0.25.0 → 0.27.0

package/search-response-types.d.ts

@@ -1,6 +1,6 @@
 import type { SearchData } from "./types.js";
 /** Canonical Search wire response. Raw SDK methods preserve this envelope. */
-export interface SearchResponse {
+export type SearchResponse = {
     data: SearchData;
     meta: {
         operationId: "search_materials_post" | "search_materials_get";
@@ -8,4 +8,4 @@ export interface SearchResponse {
     };
     links: Record<string, never>;
     warnings: never[];
-}
+};

package/search-result-validation.d.ts

@@ -1,20 +1,4 @@
-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"];
+import type { ValidationFailure } from "./validation.js";
 /**
  * Prove one wire value is a {@link SearchResultItem}, raising through `fail` at
  * the first field that does not match `searchResultItemSchema`. Checks the shape
@@ -22,6 +6,6 @@ export declare const VISUAL_MEANING_BASES: readonly ["canonical_attribute", "ima
  * 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;
+export declare const 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;
+export declare const checkSearchResultItems: (items: readonly unknown[], what: string, fail: ValidationFailure) => void;

package/search-result-validation.js

@@ -1,178 +1,46 @@
-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",
-];
+/**
+ * The one runtime validator for a {@link SearchResultItem} on the wire — the
+ * hand-rolled, zero-runtime-dependency mirror of `searchResultItemSchema`
+ * (`packages/products/src/search/search-result-schema.ts`) and its full
+ * transitive closure, including `searchResultSignalsSchema`.
+ *
+ * WHY THIS EXISTS SEPARATELY FROM THE TYPE MIRROR. `contract-parity.test.ts`
+ * proves the SDK's STATIC types match the canonical schemas. That is a
+ * compile-time proof about shapes; it validates nothing at run time. A malformed
+ * result item arriving over a stream was caught by neither, so the Match reader
+ * now checks every item through here.
+ *
+ * ONE HOME. This module is the single implementation — no copy lives inside
+ * `match-stream.ts`. It is package-internal (not re-exported from `index.ts`)
+ * because a published symbol is a permanent contract, and nothing outside the
+ * SDK needs to call it yet; promoting it later is additive.
+ *
+ * ENUMS ARE CLOSED, matching the canonical `z.enum(…)` members.
+ */
+import { requireArray, requireBoolean, requireEnum, requireNullableNumber, requireNullableString, requireNumber, requireOptionalBoolean, requireOptionalString, requireRecord, requireString, } from "./validation.js";
 // ── Leaf checks ──────────────────────────────────────────────────────────────
 /** `palette[]` — `{ hex, proportion, name: string.nullable().optional() }`. */
-function checkPaletteSwatch(value, what, fail) {
+const 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)
+    if (record.name !== undefined) {
         requireNullableString(record.name, `${what}.name`, fail);
-}
-/**
- * `variants[]` — one entry of a product-collapsed result's ranked variant list
- * (`collapsedVariantSchema`). A SLIM projection, not a nested result item: the
- * checks here are the whole shape.
- */
-function checkCollapsedVariant(value, what, fail) {
-    const record = requireRecord(value, what, fail);
-    requireString(record.variantId, `${what}.variantId`, fail);
-    requireNullableString(record.variantName, `${what}.variantName`, fail);
-    requireNullableString(record.color, `${what}.color`, fail);
-    // `.optional()`, NOT nullable: the emit path omits the key when no palette is
-    // on record rather than sending null.
-    requireOptionalString(record.hex, `${what}.hex`, fail);
-    requireNullableString(record.imageUrl, `${what}.imageUrl`, fail);
-    requireOptionalString(record.materialBankId, `${what}.materialBankId`, fail);
-    requireNumber(record.score, `${what}.score`, fail);
-}
+    }
+};
 /** `colourMeta` — three independently optional strings. */
-function checkColourMeta(value, what, fail) {
+const 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 required scores plus additive portrait. */
-function checkSignals(value, what, fail) {
-    const record = requireRecord(value, what, fail);
-    if (record.portrait !== undefined) {
-        requireNullableNumber(record.portrait, `${what}.portrait`, 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);
-    if (record.citation !== undefined) {
-        const citation = requireRecord(record.citation, `${what}.citation`, fail);
-        requireNonEmptyString(citation.citationId, `${what}.citation.citationId`, fail);
-        requireNonEmptyString(citation.sourceType, `${what}.citation.sourceType`, fail);
-        const count = requireNumber(citation.count, `${what}.citation.count`, fail);
-        if (!Number.isInteger(count) || count <= 0) {
-            throw fail(`${what}.citation.count must be a positive integer`);
-        }
-    }
-    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) {
+};
+/** `searchResultSignalsSchema` — the Match image cosine, nullable. */
+const checkSignals = (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);
-}
+    requireNullableNumber(record.image, `${what}.image`, fail);
+};
 // ── The item ─────────────────────────────────────────────────────────────────
 /**
  * Prove one wire value is a {@link SearchResultItem}, raising through `fail` at
@@ -181,7 +49,7 @@ function checkCandidateVerdict(value, what, fail) {
  * contract (nothing on the emit path parses, so stripping would invent a
  * normalisation the wire never had).
  */
-export function checkSearchResultItem(value, what, fail) {
+export const checkSearchResultItem = (value, what, fail) => {
     const record = requireRecord(value, what, fail);
     requireString(record.variantId, `${what}.variantId`, fail);
     requireString(record.brand, `${what}.brand`, fail);
@@ -209,32 +77,23 @@ export function checkSearchResultItem(value, what, 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));
+    palette.forEach((swatch, index) => {
+        checkPaletteSwatch(swatch, `${what}.palette[${index}]`, fail);
+    });
     if (record.colourMeta !== undefined) {
         checkColourMeta(record.colourMeta, `${what}.colourMeta`, fail);
     }
-    if (record.signals !== undefined)
+    if (record.signals !== undefined) {
         checkSignals(record.signals, `${what}.signals`, fail);
+    }
     requireOptionalBoolean(record.retired, `${what}.retired`, fail);
     requireOptionalBoolean(record.sampleable, `${what}.sampleable`, fail);
     requireOptionalBoolean(record.belowFloor, `${what}.belowFloor`, fail);
     requireOptionalBoolean(record.admittedOnColour, `${what}.admittedOnColour`, fail);
-    if (record.siblingCount !== undefined) {
-        requireIntegerAtLeast(record.siblingCount, `${what}.siblingCount`, fail, 1);
-    }
-    if (record.variants !== undefined) {
-        const variants = requireArray(record.variants, `${what}.variants`, fail);
-        variants.forEach((variant, index) => checkCollapsedVariant(variant, `${what}.variants[${index}]`, fail));
-    }
-    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));
-}
+export const checkSearchResultItems = (items, what, fail) => {
+    items.forEach((item, index) => {
+        checkSearchResultItem(item, `${what}[${index}]`, fail);
+    });
+};

package/source-material-validation.d.ts

@@ -1,7 +1,7 @@
 import type { PostSourceMaterialCommentResult, SourceMaterialBatchDetail, SourceMaterialCommentThread } 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;
+export declare const checkSourceMaterialBatchDetail: (value: unknown, batchId: string) => SourceMaterialBatchDetail;
 /** Validate a comment-thread body, returning it typed, or throw explaining why. */
-export declare function checkSourceMaterialCommentThread(value: unknown, sourceId: string): SourceMaterialCommentThread;
+export declare const checkSourceMaterialCommentThread: (value: unknown, sourceId: string) => SourceMaterialCommentThread;
 /** Validate a posted-comment body, returning it typed, or throw explaining why. */
-export declare function checkPostSourceMaterialCommentResult(value: unknown, sourceId: string): PostSourceMaterialCommentResult;
+export declare const checkPostSourceMaterialCommentResult: (value: unknown, sourceId: string) => PostSourceMaterialCommentResult;

package/source-material-validation.js

@@ -48,23 +48,21 @@ const SOURCE_ROLES = [
     "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 detailFailure = (batchId) => (reason) => MaterialGraphError.unexpected(`GET /api/v1/source-material/${batchId} returned a malformed body: ${reason}`);
+const 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 {
+        analysedAt: requireNonEmptyString(record.analysedAt, `${what}.analysedAt`, fail),
         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),
+        status: requireEnum(record.status, ANALYSIS_STATUSES, `${what}.status`, fail),
     };
-}
+};
 /** `sourceMaterialCommentAuthorSchema`'s `attribution` members, verbatim. */
 const COMMENT_ATTRIBUTIONS = ["reported"];
 /** The canonical cap on both author fields: `.trim().min(1).max(160)`. */
@@ -84,27 +82,27 @@ const AUTHOR_FIELD_MAX = 160;
  * schema caps. A validator that is looser than the contract is a validator that
  * lets the two drift without anything failing.
  */
-function checkCommentBase(record, what, fail) {
+const checkCommentBase = (record, what, fail) => {
     const author = requireRecord(record.author, `${what}.author`, fail);
     const recordedBy = requireRecord(record.recordedBy, `${what}.recordedBy`, fail);
     return {
-        commentId: requireNonEmptyString(record.commentId, `${what}.commentId`, fail),
         author: {
-            name: requireTrimmedBoundedString(author.name, `${what}.author.name`, AUTHOR_FIELD_MAX, fail),
-            organisation: requireNullableTrimmedBoundedString(author.organisation, `${what}.author.organisation`, AUTHOR_FIELD_MAX, fail),
             // Closed here, matching the canonical `z.literal("reported")`, while the
             // published type is `OpenEnum` so a newer server value keeps
             // type-checking — the same split the analysis enums make.
             attribution: requireEnum(author.attribution, COMMENT_ATTRIBUTIONS, `${what}.author.attribution`, fail),
+            name: requireTrimmedBoundedString(author.name, `${what}.author.name`, AUTHOR_FIELD_MAX, fail),
+            organisation: requireNullableTrimmedBoundedString(author.organisation, `${what}.author.organisation`, AUTHOR_FIELD_MAX, fail),
         },
+        body: requireNonEmptyString(record.body, `${what}.body`, fail),
+        commentId: requireNonEmptyString(record.commentId, `${what}.commentId`, fail),
+        createdAt: requireNonEmptyString(record.createdAt, `${what}.createdAt`, fail),
         recordedBy: {
             principalId: requireNonEmptyString(recordedBy.principalId, `${what}.recordedBy.principalId`, fail),
         },
-        body: requireNonEmptyString(record.body, `${what}.body`, fail),
-        createdAt: requireNonEmptyString(record.createdAt, `${what}.createdAt`, fail),
     };
-}
-function checkComment(value, what, fail) {
+};
+const checkComment = (value, what, fail) => {
     const record = requireRecord(value, what, fail);
     // Same reasoning as `analyses`: no `.default([])` canonically, so an absent
     // `replies` is malformed rather than empty.
@@ -113,8 +111,8 @@ function checkComment(value, what, fail) {
         ...checkCommentBase(record, what, fail),
         replies: replies.map((reply, index) => checkCommentBase(requireRecord(reply, `${what}.replies[${index}]`, fail), `${what}.replies[${index}]`, fail)),
     };
-}
-function checkFile(value, what, fail) {
+};
+const 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
@@ -133,11 +131,7 @@ function checkFile(value, what, fail) {
     // 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),
+        analyses: analyses.map((analysis, index) => checkAnalysis(analysis, `${what}.analyses[${index}]`, fail)),
         // `requireSafeInteger`, NOT `requireIntegerAtLeast(…, 0)`. Canonically these
         // are a bare `z.number().int()` on the INHERITED
         // `sourceMaterialFileReceiptSchema`, which carries no lower bound — so a
@@ -150,17 +144,21 @@ function checkFile(value, what, fail) {
         // 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),
+        comments: comments.map((comment, index) => checkComment(comment, `${what}.comments[${index}]`, fail)),
+        commentsTruncated,
+        filename: requireString(record.filename, `${what}.filename`, fail),
+        mediaType: requireString(record.mediaType, `${what}.mediaType`, fail),
         pages: record.pages === null
             ? null
             : requireSafeInteger(record.pages, `${what}.pages`, fail),
+        role: requireEnum(record.role, SOURCE_ROLES, `${what}.role`, fail),
+        sha256: requireString(record.sha256, `${what}.sha256`, fail),
+        sourceId: requireString(record.sourceId, `${what}.sourceId`, fail),
         url: requireString(record.url, `${what}.url`, fail),
-        analyses: analyses.map((analysis, index) => checkAnalysis(analysis, `${what}.analyses[${index}]`, fail)),
-        comments: comments.map((comment, index) => checkComment(comment, `${what}.comments[${index}]`, fail)),
-        commentsTruncated,
     };
-}
+};
 /** Validate a batch-detail body, returning it typed, or throw explaining why. */
-export function checkSourceMaterialBatchDetail(value, batchId) {
+export const checkSourceMaterialBatchDetail = (value, batchId) => {
     const fail = detailFailure(batchId);
     const record = requireRecord(value, "body", fail);
     const sources = requireArray(record.sources, "body.sources", fail);
@@ -169,21 +167,19 @@ export function checkSourceMaterialBatchDetail(value, batchId) {
         createdAt: requireString(record.createdAt, "body.createdAt", fail),
         sources: sources.map((file, index) => checkFile(file, `body.sources[${index}]`, fail)),
     };
-}
-function commentsFailure(verb, sourceId) {
-    return (reason) => MaterialGraphError.unexpected(`${verb} .../sources/${sourceId}/comments returned a malformed body: ${reason}`);
-}
+};
+const commentsFailure = (verb, sourceId) => (reason) => MaterialGraphError.unexpected(`${verb} .../sources/${sourceId}/comments returned a malformed body: ${reason}`);
 /** Validate a comment-thread body, returning it typed, or throw explaining why. */
-export function checkSourceMaterialCommentThread(value, sourceId) {
+export const checkSourceMaterialCommentThread = (value, sourceId) => {
     const fail = commentsFailure("GET", sourceId);
     const record = requireRecord(value, "body", fail);
     const comments = requireArray(record.comments, "body.comments", fail);
     return {
-        sourceId: requireString(record.sourceId, "body.sourceId", fail),
         comments: comments.map((comment, index) => checkComment(comment, `body.comments[${index}]`, fail)),
+        sourceId: requireString(record.sourceId, "body.sourceId", fail),
         truncated: requireBoolean(record.truncated, "body.truncated", fail),
     };
-}
+};
 /** `storedSourceMaterialCommentSchema`'s discriminator members, verbatim. */
 const STORED_COMMENT_KINDS = ["root", "reply"];
 /**
@@ -195,7 +191,7 @@ const STORED_COMMENT_KINDS = ["root", "reply"];
  * defect this discriminated union was added to fix, and a mirror that did it
  * would put the lie back on the client side.
  */
-function checkStoredComment(value, what, fail) {
+const checkStoredComment = (value, what, fail) => {
     const record = requireRecord(value, what, fail);
     const kind = requireEnum(record.kind, STORED_COMMENT_KINDS, `${what}.kind`, fail);
     if (kind === "reply") {
@@ -206,13 +202,13 @@ function checkStoredComment(value, what, fail) {
         };
     }
     return { kind: "root", ...checkComment(record, what, fail) };
-}
+};
 /** Validate a posted-comment body, returning it typed, or throw explaining why. */
-export function checkPostSourceMaterialCommentResult(value, sourceId) {
+export const checkPostSourceMaterialCommentResult = (value, sourceId) => {
     const fail = commentsFailure("POST", sourceId);
     const record = requireRecord(value, "body", fail);
     return {
-        sourceId: requireString(record.sourceId, "body.sourceId", fail),
         comment: checkStoredComment(record.comment, "body.comment", fail),
+        sourceId: requireString(record.sourceId, "body.sourceId", fail),
     };
-}
+};

package/spec-facet-types.d.ts

@@ -1,9 +1,9 @@
-export interface SpecFacetValue {
+export type SpecFacetValue = {
     value: string;
     variants: number;
     brands: number;
     label?: string;
-}
+};
 /**
  * A NUMERIC facet's observed span and the coverage behind it.
  *
@@ -17,20 +17,21 @@ export interface SpecFacetValue {
  * `unparseableVariants` is the honesty companion: values recorded here that are
  * not numbers, which a range EXCLUDES rather than reading as zero.
  */
-export interface SpecFacetRange {
+export type SpecFacetRange = {
     min: number;
     max: number;
     variants: number;
     unparseableVariants: number;
-}
-export interface SpecFacet {
+};
+export type SpecFacet = {
     attributeId: string;
     name: string;
     isArray: boolean;
     /**
      * How this facet is queried. `token` — pick a value from `values` and send it
-     * as `attribute:value`. `numeric` — `values` is EMPTY and `range` carries the
-     * span; send inclusive bounds via `specRangeCriterion` instead.
+     * as a `{field: attributeId, op: "in", values: [...]}` filter leaf.
+     * `numeric` — `values` is EMPTY and `range` carries the span; send inclusive
+     * bounds as `{field: attributeId, op: "gte"/"lte", value}` leaves instead.
      */
     kind: "token" | "numeric" | (string & {});
     brands: number;
@@ -39,15 +40,9 @@ export interface SpecFacet {
     /** Present ONLY on a `numeric` facet. */
     range?: SpecFacetRange;
     description?: string;
-}
-export interface SpecFacetsListResponse {
+};
+export type SpecFacetsListResponse = {
     mode: "facets";
     count: number;
     facets: SpecFacet[];
-}
-export interface SpecFacetsDistributionResponse {
-    mode: "distribution";
-    attributeId: string;
-    count: number;
-    values: SpecFacetValue[];
-}
+};

package/spec-types.d.ts

@@ -16,16 +16,17 @@
  * - `client.search({ filters: [...] })` — spec gates layered onto a RANKED
  *   (colour / visual / lexical) search. Reach for it when relevance still
  *   matters: "something like this seed, but Class A".
- * - `client.bySpec(...)` — the value-anchored, SPEC-ONLY primitive, which takes
- *   the same criteria as `attribute:value` strings (build them with the helpers
- *   in `./specifications`). Reach for it when the spec is the whole question and
- *   ranking would be noise.
+ * - `client.listVariants({ filters })` — the value-anchored, SPEC-ONLY
+ *   primitive, which takes a `{field: attributeId, op, ...}` filter leaf
+ *   (build one term with the helpers in `./specifications`, or a plain
+ *   object literal for anything else). Reach for it when the spec is the
+ *   whole question and ranking would be noise.
  *
  * Discover the tokens before you spend them: `client.specificationFacets()` for
  * what is facetable at all, `client.attributeValues()` for one attribute's
- * values, `client.resolveAttribute()` / `client.resolveAttributeValue()` to turn
- * a phrase into a canonical pair. A hand-guessed token returns an honest empty
- * answer, which is the hardest kind of bug to see.
+ * values, `client.listAttributes({ query })` to turn a phrase into a canonical
+ * attribute id. A hand-guessed token returns an honest empty answer, which is
+ * the hardest kind of bug to see.
  */
 /**
  * The virtual attribute id that matches a certification PROGRAMME wherever it
@@ -57,18 +58,24 @@ export type CertificationProgrammeAttributeId = typeof CERTIFICATION_PROGRAMME_A
  * 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()`.
+ * and `client.attributeValues()`, or find an attribute from free text with
+ * `client.listAttributes({ query })`.
  */
-export interface SpecTermFilter {
+export type SpecTermFilter = {
     attributeId: string;
     term: string;
-}
-/** A negative spec criterion; absence of a value remains unproven. */
-export interface SpecExclusionFilter {
+};
+/**
+ * A negative spec criterion. `whenUnstated` (absent = `"drop"`) controls what an
+ * UNKNOWN effective value does: `"drop"` requires a known value, so a variant
+ * that never states the attribute does not pass; `"pass"` admits it — a variant
+ * only fails by STATING the excluded term.
+ */
+export type SpecExclusionFilter = {
     attributeId: string;
     excludesTerm: string;
-}
+    whenUnstated?: "drop" | "pass";
+};
 /**
  * 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
@@ -90,10 +97,10 @@ export type SpecPresenceFilter = {
  * virtual {@link CERTIFICATION_PROGRAMME_ATTRIBUTE_ID}. Structurally assignable
  * to {@link SpecFilter}, so it drops straight into `search({ filters })`.
  */
-export interface CertificationProgrammeFilter {
+export type 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

package/spec-types.js

@@ -16,16 +16,17 @@
  * - `client.search({ filters: [...] })` — spec gates layered onto a RANKED
  *   (colour / visual / lexical) search. Reach for it when relevance still
  *   matters: "something like this seed, but Class A".
- * - `client.bySpec(...)` — the value-anchored, SPEC-ONLY primitive, which takes
- *   the same criteria as `attribute:value` strings (build them with the helpers
- *   in `./specifications`). Reach for it when the spec is the whole question and
- *   ranking would be noise.
+ * - `client.listVariants({ filters })` — the value-anchored, SPEC-ONLY
+ *   primitive, which takes a `{field: attributeId, op, ...}` filter leaf
+ *   (build one term with the helpers in `./specifications`, or a plain
+ *   object literal for anything else). Reach for it when the spec is the
+ *   whole question and ranking would be noise.
  *
  * Discover the tokens before you spend them: `client.specificationFacets()` for
  * what is facetable at all, `client.attributeValues()` for one attribute's
- * values, `client.resolveAttribute()` / `client.resolveAttributeValue()` to turn
- * a phrase into a canonical pair. A hand-guessed token returns an honest empty
- * answer, which is the hardest kind of bug to see.
+ * values, `client.listAttributes({ query })` to turn a phrase into a canonical
+ * attribute id. A hand-guessed token returns an honest empty answer, which is
+ * the hardest kind of bug to see.
  */
 /**
  * The virtual attribute id that matches a certification PROGRAMME wherever it