@instruments/materialgraph 0.30.0 → 0.32.0

package/search-index-plan-types.d.ts

@@ -8,7 +8,7 @@
 import type { ColourRegionRange } from "./colour-region-types.js";
 import type { CorpusScope } from "./corpus-scope-types.js";
 /** One attribute the plan wants: its terms, or any value when `presence`. */
-export type SearchIndexPlanWant = {
+type SearchIndexPlanWant = {
     attributeId: string;
     /** Share of the category's materials stating the attribute, 0 to 1. */
     fill: number;
@@ -71,3 +71,4 @@ export type SearchPlanReceipt = {
     source: "dictionary" | "jev";
     version: string;
 };
+export {};

package/search-result-validation.d.ts

@@ -7,5 +7,3 @@ import type { ValidationFailure } from "./validation.js";
  * normalisation the wire never had).
  */
 export declare const checkSearchResultItem: (value: unknown, what: string, fail: ValidationFailure) => void;
-/** Prove every entry of a `results[]` array is a {@link SearchResultItem}. */
-export declare const checkSearchResultItems: (items: readonly unknown[], what: string, fail: ValidationFailure) => void;

package/search-result-validation.js

@@ -17,7 +17,7 @@
  *
  * ENUMS ARE CLOSED, matching the canonical `z.enum(…)` members.
  */
-import { requireArray, requireBoolean, requireEnum, requireNullableNumber, requireNullableString, requireNumber, requireOptionalBoolean, requireOptionalString, requireRecord, requireString, } from "./validation.js";
+import { requireArray, requireBoolean, requireEnum, requireNullableString, requireNumber, requireOptionalBoolean, requireOptionalString, requireRecord, requireString, } from "./validation.js";
 // ── Leaf checks ──────────────────────────────────────────────────────────────
 /** `palette[]` — `{ hex, proportion, name: string.nullable().optional() }`. */
 const checkPaletteSwatch = (value, what, fail) => {
@@ -36,11 +36,6 @@ const checkColourMeta = (value, what, fail) => {
     requireOptionalString(record.dominantFamily, `${what}.dominantFamily`, fail);
     requireOptionalString(record.dominantHex, `${what}.dominantHex`, fail);
 };
-/** `searchResultSignalsSchema` — the Match image cosine, nullable. */
-const checkSignals = (value, what, fail) => {
-    const record = requireRecord(value, what, fail);
-    requireNullableNumber(record.image, `${what}.image`, fail);
-};
 // ── The item ─────────────────────────────────────────────────────────────────
 /**
  * Prove one wire value is a {@link SearchResultItem}, raising through `fail` at
@@ -83,17 +78,6 @@ export const checkSearchResultItem = (value, what, 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.sampleable, `${what}.sampleable`, fail);
-    requireOptionalBoolean(record.belowFloor, `${what}.belowFloor`, fail);
-    requireOptionalBoolean(record.admittedOnColour, `${what}.admittedOnColour`, fail);
-};
-/** Prove every entry of a `results[]` array is a {@link SearchResultItem}. */
-export const checkSearchResultItems = (items, what, fail) => {
-    items.forEach((item, index) => {
-        checkSearchResultItem(item, `${what}[${index}]`, fail);
-    });
 };

package/specifications.d.ts

@@ -1,12 +1,4 @@
-import type { CertificationProgrammeFilter, SpecExclusionFilter, SpecPresenceFilter, SpecTermFilter } from "./spec-types.js";
-/**
- * A hard criterion excluding one canonical value.
- *
- * By default retains only variants with a KNOWN value (unstated does not
- * pass). Pass `whenUnstated: "pass"` to admit unstated variants too — only a
- * variant that STATES the excluded term is dropped.
- */
-export declare const excludeSpec: (attributeId: string, excludesTerm: string, whenUnstated?: "drop" | "pass") => SpecExclusionFilter;
+import type { CertificationProgrammeFilter, SpecPresenceFilter, SpecTermFilter } from "./spec-types.js";
 /**
  * A term-equality criterion for `search({ filters })` — the attribute must
  * carry this canonical value.

package/specifications.js

@@ -15,18 +15,6 @@
  * object literal needs no encoder (MG-2222).
  */
 import { CERTIFICATION_PROGRAMME_ATTRIBUTE_ID } from "./spec-types.js";
-/**
- * A hard criterion excluding one canonical value.
- *
- * By default retains only variants with a KNOWN value (unstated does not
- * pass). Pass `whenUnstated: "pass"` to admit unstated variants too — only a
- * variant that STATES the excluded term is dropped.
- */
-export const excludeSpec = (attributeId, excludesTerm, whenUnstated) => ({
-    attributeId,
-    excludesTerm,
-    ...(whenUnstated === undefined ? {} : { whenUnstated }),
-});
 /**
  * A term-equality criterion for `search({ filters })` — the attribute must
  * carry this canonical value.

package/types.d.ts

@@ -78,13 +78,6 @@ export type MaterialColour = {
 /** Where the served image came from. */
 export type ImageSource = OpenEnum<"r2" | "origin">;
 export type { MaterialAvailability, MaterialTile } from "./material-types.js";
-/**
- * Match only: the image-space cosine between the query image and this row's
- * image, in [0,1]. Null when it was not measured.
- */
-export type SearchResultSignals = {
-    image: number | null;
-};
 /**
  * One material in a search / match result list.
  *
@@ -110,7 +103,7 @@ export type SearchResultItem = {
      * against Material Bank's own catalogue, so a result list can be joined to a
      * cart, an order or an analytics event without a per-result lookup.
      * Populated on EVERY lane: `search()` (all four arms), `match()`, and
-     * `matchStream()` frames.
+     * full search responses.
      * ABSENT means no MB identity is known for the variant — never that the SKU
      * cannot be ordered. Presence identifies the source; it does not establish sampleability.
      */
@@ -165,63 +158,9 @@ export type SearchResultItem = {
     colourChip?: {
         hex: string;
     };
-    /**
-     * Selected mode's weighted primary score; see `maxScore`. On a Match page
-     * this is the retrieval score and does NOT order the page: the order is
-     * colour agreement, then `confidence` (MG-1900).
-     */
+    /** Selected mode's weighted primary score; see maxScore. */
     score: number;
-    /**
-     * Match only. How close this material is to the query, as an ABSOLUTE
-     * image-space similarity in [0,1], not adjusted for colour — the same unit as
-     * `qualityFloor` and `comparison.bestRejected`, so all three sit on one axis.
-     *
-     * Never normalised against the page, so the same material reads the same in
-     * two different searches. It is the TRUE value and MAY reach 1 — rendering it
-     * so that no card claims "100%" is yours to do (round toward zero, or show
-     * "99%+"); `Math.round` prints 100% from 0.995 up. Capping it server-side
-     * would put it on a different ceiling from `comparison.bestRejected`, which
-     * publishes the same unit uncapped, and the two are meant to be comparable.
-     * A Match page lists rows whose colour agrees (`colourDistance` under 0.1)
-     * first, then unmeasured ones, then the rest, and orders each set by this
-     * number. `score` is the retrieval score and lives on a different scale.
-     */
-    confidence?: number;
-    /**
-     * `confidence` as a word — `strong` >= 0.85, `good` >= 0.72, `fair` >= 0.55
-     * (the default quality floor), `weak` below it and only reachable under
-     * `includeBelowFloor`. Present exactly when `confidence` is.
-     */
-    confidenceBand?: "strong" | "good" | "fair" | "weak";
-    /**
-     * Match only. OKLab earth mover's distance between the query crop's palette
-     * and this material's, reading both palettes' proportions. Under 0.1 the
-     * colour agrees. `null` means the material carries no stored palette —
-     * UNKNOWN colour, never "no colour" and never "distant". Absent when the
-     * colour stage did not run.
-     */
-    colourDistance?: number | null;
-    /** `colourDistance` as a word, or null when unmeasurable. */
-    colourBand?: string | null;
-    signals?: SearchResultSignals;
     retired?: boolean;
-    /**
-     * Present (true) only on quality-floor rejects returned under `includeBelowFloor`
-     * (match only) — the item failed the match image-quality floor and would be
-     * dropped by default. Appended after the kept results.
-     */
-    belowFloor?: boolean;
-    /**
-     * Present (true) only on Match rows the colour probe admitted (match only):
-     * this material is as close in colour as the catalogue gets, and its image
-     * similarity is BELOW the match quality floor by design. It is on the page
-     * because nothing image-retrieved is nearer in colour, not because it cleared
-     * the floor — present it as a colour answer or suppress it knowingly. Absent
-     * (never `false`) on rows that came through image retrieval. Distinct from
-     * {@link SearchResultItem.belowFloor}, which marks rejects returned only under
-     * `includeBelowFloor`.
-     */
-    admittedOnColour?: boolean;
     /**
      * Resolved values for the attribute ids sent in `returnAttributes`, keyed by
      * attribute id. ABSENT entirely when `returnAttributes` was not sent.

package/validation.d.ts

@@ -15,37 +15,19 @@
  * this file knowing what a Match frame or a Run event is.
  */
 import type { MaterialGraphError } from "./errors.js";
-import type { JsonValue } from "./types.js";
 /**
  * Builds the one error a validation run raises. The calling module supplies it,
  * so the message names that payload and quotes its source.
  */
 export type ValidationFailure = (reason: string) => MaterialGraphError;
-export declare const isRecord: (value: unknown) => value is Record<string, unknown>;
 /** A `z.object({…})`. */
 export declare const requireRecord: (value: unknown, what: string, fail: ValidationFailure) => Record<string, unknown>;
 /** A `z.string()`. */
 export declare const requireString: (value: unknown, what: string, fail: ValidationFailure) => string;
-/** A `z.string().min(1)`. */
-export declare const requireNonEmptyString: (value: unknown, what: string, fail: ValidationFailure) => string;
 /** A `z.string().optional()`: absent is fine, present-but-wrong is not. */
 export declare const requireOptionalString: (value: unknown, what: string, fail: ValidationFailure) => void;
 /** A `z.string().nullable()`. */
 export declare const requireNullableString: (value: unknown, what: string, fail: ValidationFailure) => string | null;
-/** A `z.string().min(1).nullable()`. */
-export declare const requireNullableNonEmptyString: (value: unknown, what: string, fail: ValidationFailure) => string | null;
-/**
- * A `z.string().trim().min(1).max(max)`.
- *
- * The `.trim()` is a TRANSFORM, so the schema's parsed output is the trimmed
- * string and its length bounds apply AFTER trimming. A mirror that checked the
- * raw length would disagree with the schema twice over: it would accept a
- * whitespace-only value the schema rejects, and reject a padded value the schema
- * accepts. Returns the trimmed string, which is what the schema returns.
- */
-export declare const requireTrimmedBoundedString: (value: unknown, what: string, max: number, fail: ValidationFailure) => string;
-/** A `z.string().trim().min(1).max(max).nullable()`. */
-export declare const requireNullableTrimmedBoundedString: (value: unknown, what: string, max: number, fail: ValidationFailure) => string | null;
 /** A `z.boolean()`. */
 export declare const requireBoolean: (value: unknown, what: string, fail: ValidationFailure) => boolean;
 /** A `z.boolean().optional()`. */
@@ -55,77 +37,7 @@ export declare const requireOptionalBoolean: (value: unknown, what: string, fail
  * out of JSON as `Infinity`, so finiteness is a reachable check.
  */
 export declare const requireNumber: (value: unknown, what: string, fail: ValidationFailure) => number;
-/** A `z.number().optional()`. */
-export declare const requireOptionalNumber: (value: unknown, what: string, fail: ValidationFailure) => void;
-/** A `z.number().nullable()`. */
-export declare const requireNullableNumber: (value: unknown, what: string, fail: ValidationFailure) => number | null;
-/**
- * A `z.number().min(min).max(max)`. `NaN` and both infinities fail the
- * comparisons, exactly as the bounded Zod schema rejects them.
- */
-export declare const requireBoundedNumber: (value: unknown, what: string, fail: ValidationFailure, min: number, max: number) => number;
-/** A `z.number().min(min).max(max).nullable()`. */
-export declare const requireNullableBoundedNumber: (value: unknown, what: string, fail: ValidationFailure, min: number, max: number) => number | null;
-/**
- * A bare `z.number().int()` — integer, finite, and within the SAFE range, with
- * NO lower bound.
- *
- * Measured against the pinned Zod (4.4.3), `.int()` is exactly
- * `Number.isSafeInteger`: it accepts `0`, `-1`, and `±MAX_SAFE_INTEGER`, and
- * rejects `1.5`, `±2**53`, `NaN`, and `±Infinity`.
- *
- * Two ways to get this wrong, both of which break parity in a different
- * direction. Adding a `min: 0` REJECTS a negative the schema accepts — a client
- * refusing a legitimate response. Using `Number.isInteger` ACCEPTS `2**53`,
- * which the schema rejects — so `requireIntegerAtLeast` is not this helper with
- * the bound dropped, and the safe-range test is why.
- */
-export declare const requireSafeInteger: (value: unknown, what: string, fail: ValidationFailure) => number;
-/** A `z.number().int().min(min)` — the integer constraint AND the lower bound. */
-export declare const requireIntegerAtLeast: (value: unknown, what: string, fail: ValidationFailure, min: number) => number;
 /** A `z.enum([…])` — CLOSED, exactly like the canonical member list. */
 export declare const requireEnum: (value: unknown, allowed: readonly string[], what: string, fail: ValidationFailure) => string;
-/** A `z.enum([…]).nullable()`. */
-export declare const requireNullableEnum: (value: unknown, allowed: readonly string[], what: string, fail: ValidationFailure) => string | null;
 /** A `z.array(…)`. */
 export declare const requireArray: (value: unknown, what: string, fail: ValidationFailure) => unknown[];
-/**
- * A `z.array(…).default([])`: an OMITTED array is valid and materialises as
- * `[]`; a present non-array is not.
- */
-export declare const requireDefaultedArray: (value: unknown, what: string, fail: ValidationFailure) => unknown[];
-/** A `z.array(z.string()).min(1)` — non-empty, and every element a string. */
-export declare const requireNonEmptyStringArray: (value: unknown, what: string, fail: ValidationFailure) => string[];
-/**
- * A `z.json()` — a JSON value, recursively: `string | number | boolean | null`,
- * an array of them, or an object of them, at ANY depth.
- *
- * WHY THIS EXISTS, given it can never fire over the wire. Every SDK response
- * has already been through `JSON.parse`, so a `Date`, `bigint`, `undefined`, or
- * function CANNOT be present by construction — this check is unreachable in
- * practice. It is here for PARITY: the canonical `sourceImageAnalysisResultSchema`
- * uses `z.json()` precisely because those four break differently on the way to
- * `jsonb` (a `bigint` throws in `JSON.stringify`, an `undefined` is silently
- * dropped, and a `Date` round-trips as an ISO *string* — a different type read
- * back than written). The mirror has to reject what the schema rejects or the
- * parity test is lying. Do not delete this as dead code.
- */
-export declare const requireJsonValue: (value: unknown, what: string, fail: ValidationFailure) => JsonValue;
-/**
- * A `z.record(z.string(), z.json())` — a PLAIN JSON object of JSON values.
- *
- * Deliberately NOT `requireRecord` + walk the entries. That combination has a
- * top-level hole: `Object.entries(new Date())` and `Object.entries(new Map())`
- * are both `[]`, so there is nothing to recurse over and the value is accepted
- * as `{}` — while `z.record(z.string(), z.json())` rejects both outright. A
- * "non-array object" guard would close those two and still miss a class instance
- * with real own properties, which canonical also rejects. Only a prototype test
- * matches, and {@link requireJsonValue} already applies it at every depth — so
- * this delegates there and then narrows to an object, rather than reimplementing
- * the test and acquiring the same hole one level up.
- *
- * `requireRecord` is left alone: its other callers mirror `z.object({…})`, which
- * genuinely does accept any record, and tightening a shared helper under them
- * would be a change none of them asked for.
- */
-export declare const requireJsonRecord: (value: unknown, what: string, fail: ValidationFailure) => Record<string, JsonValue>;

package/validation.js

@@ -1,4 +1,4 @@
-export const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /** A `z.object({…})`. */
 export const requireRecord = (value, what, fail) => {
     if (!isRecord(value)) {
@@ -13,14 +13,6 @@ export const requireString = (value, what, fail) => {
     }
     return value;
 };
-/** A `z.string().min(1)`. */
-export const requireNonEmptyString = (value, what, fail) => {
-    const text = requireString(value, what, fail);
-    if (text.length === 0) {
-        throw fail(`${what} is an empty string`);
-    }
-    return text;
-};
 /** A `z.string().optional()`: absent is fine, present-but-wrong is not. */
 export const requireOptionalString = (value, what, fail) => {
     if (value === undefined) {
@@ -35,39 +27,6 @@ export const requireNullableString = (value, what, fail) => {
     }
     return requireString(value, what, fail);
 };
-/** A `z.string().min(1).nullable()`. */
-export const requireNullableNonEmptyString = (value, what, fail) => {
-    if (value === null) {
-        return null;
-    }
-    return requireNonEmptyString(value, what, fail);
-};
-/**
- * A `z.string().trim().min(1).max(max)`.
- *
- * The `.trim()` is a TRANSFORM, so the schema's parsed output is the trimmed
- * string and its length bounds apply AFTER trimming. A mirror that checked the
- * raw length would disagree with the schema twice over: it would accept a
- * whitespace-only value the schema rejects, and reject a padded value the schema
- * accepts. Returns the trimmed string, which is what the schema returns.
- */
-export const requireTrimmedBoundedString = (value, what, max, fail) => {
-    const text = requireString(value, what, fail).trim();
-    if (text.length === 0) {
-        throw fail(`${what} is empty once trimmed`);
-    }
-    if (text.length > max) {
-        throw fail(`${what} is longer than ${max} characters (${text.length})`);
-    }
-    return text;
-};
-/** A `z.string().trim().min(1).max(max).nullable()`. */
-export const requireNullableTrimmedBoundedString = (value, what, max, fail) => {
-    if (value === null) {
-        return null;
-    }
-    return requireTrimmedBoundedString(value, what, max, fail);
-};
 /** A `z.boolean()`. */
 export const requireBoolean = (value, what, fail) => {
     if (typeof value !== "boolean") {
@@ -92,68 +51,6 @@ export const requireNumber = (value, what, fail) => {
     }
     return value;
 };
-/** A `z.number().optional()`. */
-export const requireOptionalNumber = (value, what, fail) => {
-    if (value === undefined) {
-        return;
-    }
-    requireNumber(value, what, fail);
-};
-/** A `z.number().nullable()`. */
-export const requireNullableNumber = (value, what, fail) => {
-    if (value === null) {
-        return null;
-    }
-    return requireNumber(value, what, fail);
-};
-/**
- * A `z.number().min(min).max(max)`. `NaN` and both infinities fail the
- * comparisons, exactly as the bounded Zod schema rejects them.
- */
-export const requireBoundedNumber = (value, what, fail, min, max) => {
-    if (typeof value !== "number" || !(value >= min && value <= max)) {
-        throw fail(`${what} is not a number within [${min}, ${max}]`);
-    }
-    return value;
-};
-/** A `z.number().min(min).max(max).nullable()`. */
-export const requireNullableBoundedNumber = (value, what, fail, min, max) => {
-    if (value === null) {
-        return null;
-    }
-    return requireBoundedNumber(value, what, fail, min, max);
-};
-/**
- * A bare `z.number().int()` — integer, finite, and within the SAFE range, with
- * NO lower bound.
- *
- * Measured against the pinned Zod (4.4.3), `.int()` is exactly
- * `Number.isSafeInteger`: it accepts `0`, `-1`, and `±MAX_SAFE_INTEGER`, and
- * rejects `1.5`, `±2**53`, `NaN`, and `±Infinity`.
- *
- * Two ways to get this wrong, both of which break parity in a different
- * direction. Adding a `min: 0` REJECTS a negative the schema accepts — a client
- * refusing a legitimate response. Using `Number.isInteger` ACCEPTS `2**53`,
- * which the schema rejects — so `requireIntegerAtLeast` is not this helper with
- * the bound dropped, and the safe-range test is why.
- */
-export const requireSafeInteger = (value, what, fail) => {
-    if (!Number.isSafeInteger(value)) {
-        throw fail(`${what} is not a safe integer`);
-    }
-    return requireNumber(value, what, fail);
-};
-/** A `z.number().int().min(min)` — the integer constraint AND the lower bound. */
-export const requireIntegerAtLeast = (value, what, fail, min) => {
-    const numeric = requireNumber(value, what, fail);
-    if (!Number.isInteger(numeric)) {
-        throw fail(`${what} is not an integer`);
-    }
-    if (numeric < min) {
-        throw fail(`${what} is below the minimum of ${min}`);
-    }
-    return numeric;
-};
 /** A `z.enum([…])` — CLOSED, exactly like the canonical member list. */
 export const requireEnum = (value, allowed, what, fail) => {
     const text = requireString(value, what, fail);
@@ -162,13 +59,6 @@ export const requireEnum = (value, allowed, what, fail) => {
     }
     return text;
 };
-/** A `z.enum([…]).nullable()`. */
-export const requireNullableEnum = (value, allowed, what, fail) => {
-    if (value === null) {
-        return null;
-    }
-    return requireEnum(value, allowed, what, fail);
-};
 /** A `z.array(…)`. */
 export const requireArray = (value, what, fail) => {
     if (!Array.isArray(value)) {
@@ -176,24 +66,6 @@ export const requireArray = (value, what, fail) => {
     }
     return value;
 };
-/**
- * A `z.array(…).default([])`: an OMITTED array is valid and materialises as
- * `[]`; a present non-array is not.
- */
-export const requireDefaultedArray = (value, what, fail) => {
-    if (value === undefined) {
-        return [];
-    }
-    return requireArray(value, what, fail);
-};
-/** A `z.array(z.string()).min(1)` — non-empty, and every element a string. */
-export const requireNonEmptyStringArray = (value, what, fail) => {
-    const items = requireArray(value, what, fail);
-    if (items.length === 0) {
-        throw fail(`${what} is empty`);
-    }
-    return items.map((item, index) => requireString(item, `${what}[${index}]`, fail));
-};
 /**
  * A `z.json()` — a JSON value, recursively: `string | number | boolean | null`,
  * an array of them, or an object of them, at ANY depth.
@@ -208,7 +80,7 @@ export const requireNonEmptyStringArray = (value, what, fail) => {
  * back than written). The mirror has to reject what the schema rejects or the
  * parity test is lying. Do not delete this as dead code.
  */
-export const requireJsonValue = (value, what, fail) => {
+const requireJsonValue = (value, what, fail) => {
     if (value === null) {
         return null;
     }
@@ -243,27 +115,3 @@ export const requireJsonValue = (value, what, fail) => {
     }
     throw fail(`${what} is not a JSON value`);
 };
-/**
- * A `z.record(z.string(), z.json())` — a PLAIN JSON object of JSON values.
- *
- * Deliberately NOT `requireRecord` + walk the entries. That combination has a
- * top-level hole: `Object.entries(new Date())` and `Object.entries(new Map())`
- * are both `[]`, so there is nothing to recurse over and the value is accepted
- * as `{}` — while `z.record(z.string(), z.json())` rejects both outright. A
- * "non-array object" guard would close those two and still miss a class instance
- * with real own properties, which canonical also rejects. Only a prototype test
- * matches, and {@link requireJsonValue} already applies it at every depth — so
- * this delegates there and then narrows to an object, rather than reimplementing
- * the test and acquiring the same hole one level up.
- *
- * `requireRecord` is left alone: its other callers mirror `z.object({…})`, which
- * genuinely does accept any record, and tightening a shared helper under them
- * would be a change none of them asked for.
- */
-export const requireJsonRecord = (value, what, fail) => {
-    const json = requireJsonValue(value, what, fail);
-    if (json === null || typeof json !== "object" || Array.isArray(json)) {
-        throw fail(`${what} is not a JSON object`);
-    }
-    return json;
-};