@instruments/materialgraph 0.25.0 → 0.27.0

package/validation.d.ts

@@ -14,26 +14,26 @@
  * owned by the calling module — so one payload's failures all read alike without
  * this file knowing what a Match frame or a Run event is.
  */
-import { MaterialGraphError } from "./errors.js";
+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 function isRecord(value: unknown): value is Record<string, unknown>;
+export declare const isRecord: (value: unknown) => value is Record<string, unknown>;
 /** A `z.object({…})`. */
-export declare function requireRecord(value: unknown, what: string, fail: ValidationFailure): Record<string, unknown>;
+export declare const requireRecord: (value: unknown, what: string, fail: ValidationFailure) => Record<string, unknown>;
 /** A `z.string()`. */
-export declare function requireString(value: unknown, what: string, fail: ValidationFailure): string;
+export declare const requireString: (value: unknown, what: string, fail: ValidationFailure) => string;
 /** A `z.string().min(1)`. */
-export declare function requireNonEmptyString(value: unknown, what: string, fail: ValidationFailure): string;
+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 function requireOptionalString(value: unknown, what: string, fail: ValidationFailure): void;
+export declare const requireOptionalString: (value: unknown, what: string, fail: ValidationFailure) => void;
 /** A `z.string().nullable()`. */
-export declare function requireNullableString(value: unknown, what: string, fail: ValidationFailure): string | null;
+export declare const requireNullableString: (value: unknown, what: string, fail: ValidationFailure) => string | null;
 /** A `z.string().min(1).nullable()`. */
-export declare function requireNullableNonEmptyString(value: unknown, what: string, fail: ValidationFailure): string | null;
+export declare const requireNullableNonEmptyString: (value: unknown, what: string, fail: ValidationFailure) => string | null;
 /**
  * A `z.string().trim().min(1).max(max)`.
  *
@@ -43,29 +43,29 @@ export declare function requireNullableNonEmptyString(value: unknown, what: stri
  * 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 function requireTrimmedBoundedString(value: unknown, what: string, max: number, fail: ValidationFailure): string;
+export declare const requireTrimmedBoundedString: (value: unknown, what: string, max: number, fail: ValidationFailure) => string;
 /** A `z.string().trim().min(1).max(max).nullable()`. */
-export declare function requireNullableTrimmedBoundedString(value: unknown, what: string, max: number, fail: ValidationFailure): string | null;
+export declare const requireNullableTrimmedBoundedString: (value: unknown, what: string, max: number, fail: ValidationFailure) => string | null;
 /** A `z.boolean()`. */
-export declare function requireBoolean(value: unknown, what: string, fail: ValidationFailure): boolean;
+export declare const requireBoolean: (value: unknown, what: string, fail: ValidationFailure) => boolean;
 /** A `z.boolean().optional()`. */
-export declare function requireOptionalBoolean(value: unknown, what: string, fail: ValidationFailure): void;
+export declare const requireOptionalBoolean: (value: unknown, what: string, fail: ValidationFailure) => void;
 /**
  * A `z.number()`. Zod 4 rejects `NaN` AND `±Infinity` for it, and `1e999` parses
  * out of JSON as `Infinity`, so finiteness is a reachable check.
  */
-export declare function requireNumber(value: unknown, what: string, fail: ValidationFailure): number;
+export declare const requireNumber: (value: unknown, what: string, fail: ValidationFailure) => number;
 /** A `z.number().optional()`. */
-export declare function requireOptionalNumber(value: unknown, what: string, fail: ValidationFailure): void;
+export declare const requireOptionalNumber: (value: unknown, what: string, fail: ValidationFailure) => void;
 /** A `z.number().nullable()`. */
-export declare function requireNullableNumber(value: unknown, what: string, fail: ValidationFailure): number | null;
+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 function requireBoundedNumber(value: unknown, what: string, fail: ValidationFailure, min: number, max: number): number;
+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 function requireNullableBoundedNumber(value: unknown, what: string, fail: ValidationFailure, min: number, max: number): number | null;
+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.
@@ -80,22 +80,22 @@ export declare function requireNullableBoundedNumber(value: unknown, what: strin
  * which the schema rejects — so `requireIntegerAtLeast` is not this helper with
  * the bound dropped, and the safe-range test is why.
  */
-export declare function requireSafeInteger(value: unknown, what: string, fail: ValidationFailure): number;
+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 function requireIntegerAtLeast(value: unknown, what: string, fail: ValidationFailure, min: number): number;
+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 function requireEnum(value: unknown, allowed: readonly string[], what: string, fail: ValidationFailure): string;
+export declare const requireEnum: (value: unknown, allowed: readonly string[], what: string, fail: ValidationFailure) => string;
 /** A `z.enum([…]).nullable()`. */
-export declare function requireNullableEnum(value: unknown, allowed: readonly string[], what: string, fail: ValidationFailure): string | null;
+export declare const requireNullableEnum: (value: unknown, allowed: readonly string[], what: string, fail: ValidationFailure) => string | null;
 /** A `z.array(…)`. */
-export declare function requireArray(value: unknown, what: string, fail: ValidationFailure): unknown[];
+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 function requireDefaultedArray(value: unknown, what: string, fail: ValidationFailure): unknown[];
+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 function requireNonEmptyStringArray(value: unknown, what: string, fail: ValidationFailure): 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.
@@ -110,7 +110,7 @@ export declare function requireNonEmptyStringArray(value: unknown, what: string,
  * 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 function requireJsonValue(value: unknown, what: string, fail: ValidationFailure): JsonValue;
+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.
  *
@@ -128,4 +128,4 @@ export declare function requireJsonValue(value: unknown, what: string, fail: Val
  * genuinely does accept any record, and tightening a shared helper under them
  * would be a change none of them asked for.
  */
-export declare function requireJsonRecord(value: unknown, what: string, fail: ValidationFailure): Record<string, JsonValue>;
+export declare const requireJsonRecord: (value: unknown, what: string, fail: ValidationFailure) => Record<string, JsonValue>;

package/validation.js

@@ -1,60 +1,47 @@
-/**
- * The SDK's shared wire-validation primitives — the vocabulary every hand-rolled
- * mirror of a canonical Zod schema is built from.
- *
- * The SDK publishes with ZERO runtime dependencies, so it cannot call
- * `schema.parse()` on anything. Where a wire payload must be proven rather than
- * trusted, it is checked with these helpers and the result is pinned against the
- * real schema in `contract-parity.test.ts`. Each helper mirrors one Zod
- * construct, named for it, so a reviewer can read the mirror against the schema
- * line by line.
- *
- * Every helper takes the same three shapes: the value, a `what` path used in the
- * diagnostic (`results[3].verdict.cells[0].state`), and a {@link ValidationFailure}
- * owned by the calling module — so one payload's failures all read alike without
- * this file knowing what a Match frame or a Run event is.
- */
-import { MaterialGraphError } from "./errors.js";
-export function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
+export const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /** A `z.object({…})`. */
-export function requireRecord(value, what, fail) {
-    if (!isRecord(value))
+export const requireRecord = (value, what, fail) => {
+    if (!isRecord(value)) {
         throw fail(`${what} is not a JSON object`);
+    }
     return value;
-}
+};
 /** A `z.string()`. */
-export function requireString(value, what, fail) {
-    if (typeof value !== "string")
+export const requireString = (value, what, fail) => {
+    if (typeof value !== "string") {
         throw fail(`${what} is not a string`);
+    }
     return value;
-}
+};
 /** A `z.string().min(1)`. */
-export function requireNonEmptyString(value, what, fail) {
+export const requireNonEmptyString = (value, what, fail) => {
     const text = requireString(value, what, fail);
-    if (text.length === 0)
+    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 function requireOptionalString(value, what, fail) {
-    if (value === undefined)
+export const requireOptionalString = (value, what, fail) => {
+    if (value === undefined) {
         return;
+    }
     requireString(value, what, fail);
-}
+};
 /** A `z.string().nullable()`. */
-export function requireNullableString(value, what, fail) {
-    if (value === null)
+export const requireNullableString = (value, what, fail) => {
+    if (value === null) {
         return null;
+    }
     return requireString(value, what, fail);
-}
+};
 /** A `z.string().min(1).nullable()`. */
-export function requireNullableNonEmptyString(value, what, fail) {
-    if (value === null)
+export const requireNullableNonEmptyString = (value, what, fail) => {
+    if (value === null) {
         return null;
+    }
     return requireNonEmptyString(value, what, fail);
-}
+};
 /**
  * A `z.string().trim().min(1).max(max)`.
  *
@@ -64,70 +51,78 @@ export function requireNullableNonEmptyString(value, what, fail) {
  * 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 function requireTrimmedBoundedString(value, what, max, fail) {
+export const requireTrimmedBoundedString = (value, what, max, fail) => {
     const text = requireString(value, what, fail).trim();
-    if (text.length === 0)
+    if (text.length === 0) {
         throw fail(`${what} is empty once trimmed`);
-    if (text.length > max)
+    }
+    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 function requireNullableTrimmedBoundedString(value, what, max, fail) {
-    if (value === null)
+export const requireNullableTrimmedBoundedString = (value, what, max, fail) => {
+    if (value === null) {
         return null;
+    }
     return requireTrimmedBoundedString(value, what, max, fail);
-}
+};
 /** A `z.boolean()`. */
-export function requireBoolean(value, what, fail) {
-    if (typeof value !== "boolean")
+export const requireBoolean = (value, what, fail) => {
+    if (typeof value !== "boolean") {
         throw fail(`${what} is not a boolean`);
+    }
     return value;
-}
+};
 /** A `z.boolean().optional()`. */
-export function requireOptionalBoolean(value, what, fail) {
-    if (value === undefined)
+export const requireOptionalBoolean = (value, what, fail) => {
+    if (value === undefined) {
         return;
+    }
     requireBoolean(value, what, fail);
-}
+};
 /**
  * A `z.number()`. Zod 4 rejects `NaN` AND `±Infinity` for it, and `1e999` parses
  * out of JSON as `Infinity`, so finiteness is a reachable check.
  */
-export function requireNumber(value, what, fail) {
+export const requireNumber = (value, what, fail) => {
     if (typeof value !== "number" || !Number.isFinite(value)) {
         throw fail(`${what} is not a finite number`);
     }
     return value;
-}
+};
 /** A `z.number().optional()`. */
-export function requireOptionalNumber(value, what, fail) {
-    if (value === undefined)
+export const requireOptionalNumber = (value, what, fail) => {
+    if (value === undefined) {
         return;
+    }
     requireNumber(value, what, fail);
-}
+};
 /** A `z.number().nullable()`. */
-export function requireNullableNumber(value, what, fail) {
-    if (value === null)
+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 function requireBoundedNumber(value, what, fail, min, max) {
+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 function requireNullableBoundedNumber(value, what, fail, min, max) {
-    if (value === null)
+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.
@@ -142,56 +137,63 @@ export function requireNullableBoundedNumber(value, what, fail, min, max) {
  * which the schema rejects — so `requireIntegerAtLeast` is not this helper with
  * the bound dropped, and the safe-range test is why.
  */
-export function requireSafeInteger(value, what, fail) {
-    if (!Number.isSafeInteger(value))
+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 function requireIntegerAtLeast(value, what, fail, min) {
+export const requireIntegerAtLeast = (value, what, fail, min) => {
     const numeric = requireNumber(value, what, fail);
-    if (!Number.isInteger(numeric))
+    if (!Number.isInteger(numeric)) {
         throw fail(`${what} is not an integer`);
-    if (numeric < min)
+    }
+    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 function requireEnum(value, allowed, what, fail) {
+export const requireEnum = (value, allowed, what, fail) => {
     const text = requireString(value, what, fail);
     if (!allowed.includes(text)) {
         throw fail(`${what} is not one of ${allowed.join(" | ")} (${text})`);
     }
     return text;
-}
+};
 /** A `z.enum([…]).nullable()`. */
-export function requireNullableEnum(value, allowed, what, fail) {
-    if (value === null)
+export const requireNullableEnum = (value, allowed, what, fail) => {
+    if (value === null) {
         return null;
+    }
     return requireEnum(value, allowed, what, fail);
-}
+};
 /** A `z.array(…)`. */
-export function requireArray(value, what, fail) {
-    if (!Array.isArray(value))
+export const requireArray = (value, what, fail) => {
+    if (!Array.isArray(value)) {
         throw fail(`${what} is not an array`);
+    }
     return value;
-}
+};
 /**
  * A `z.array(…).default([])`: an OMITTED array is valid and materialises as
  * `[]`; a present non-array is not.
  */
-export function requireDefaultedArray(value, what, fail) {
-    if (value === undefined)
+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 function requireNonEmptyStringArray(value, what, fail) {
+export const requireNonEmptyStringArray = (value, what, fail) => {
     const items = requireArray(value, what, fail);
-    if (items.length === 0)
+    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.
@@ -206,16 +208,19 @@ export function 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 function requireJsonValue(value, what, fail) {
-    if (value === null)
+export const requireJsonValue = (value, what, fail) => {
+    if (value === null) {
         return null;
-    if (typeof value === "string" || typeof value === "boolean")
+    }
+    if (typeof value === "string" || typeof value === "boolean") {
         return value;
+    }
     if (typeof value === "number") {
         // `z.json()`'s number leaf rejects NaN and ±Infinity, and `1e999` parses out
         // of JSON as `Infinity` — so finiteness IS reachable, unlike the rest.
-        if (!Number.isFinite(value))
+        if (!Number.isFinite(value)) {
             throw fail(`${what} is not a finite number`);
+        }
         return value;
     }
     if (Array.isArray(value)) {
@@ -237,7 +242,7 @@ export function 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.
  *
@@ -255,10 +260,10 @@ export function requireJsonValue(value, what, fail) {
  * genuinely does accept any record, and tightening a shared helper under them
  * would be a change none of them asked for.
  */
-export function requireJsonRecord(value, what, fail) {
+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;
-}
+};

package/webmcp.d.ts

@@ -1,6 +1,6 @@
 /** Canonical operation contracts. Consumers validate both boundaries and supply their own transport. */
-export interface WebMcpToolContract {
-    readonly name: "identify" | "search" | "compare" | "create_correction";
+export type WebMcpToolContract = {
+    readonly name: "search";
     readonly operationId: string;
     readonly path: string;
     readonly method: "POST";
@@ -13,5 +13,5 @@ export interface WebMcpToolContract {
     };
     readonly requiresVisibleConfirmation: boolean;
     readonly requiredHeaders: readonly string[];
-}
+};
 export { WEBMCP_TOOLS } from "./webmcp.generated.js";