@instruments/materialgraph 0.2.0 → 0.3.0

package/specifications.js

@@ -42,6 +42,11 @@ export function hasSpec(attributeId) {
  * 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")] });
@@ -64,6 +69,10 @@ export function specCriterion(attributeId, value) {
  * 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")]);

package/types.d.ts

@@ -12,9 +12,19 @@
  * server value still type-checks, and objects that may grow fields are read
  * structurally (unknown keys pass through untouched — the client never strips).
  */
+import type { BySpecVerdict } from "./by-spec-types.js";
+import type { MaterialDetail, MaterialTile } from "./material-types.js";
 import type { SearchFilter, SearchSuggestion } from "./search-refinement-types.js";
 /** A widened string-literal union: known members autocomplete, unknown values still type-check. */
 export type OpenEnum<T extends string> = T | (string & {});
+/**
+ * A JSON value, recursively — exactly what survives a `jsonb` round-trip
+ * unchanged. Used where a payload's SHAPE belongs to its producer but its values
+ * must still be JSON: `Date`, `bigint`, `undefined`, and functions are not.
+ */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
 /** One palette swatch of a material's main image. */
 export interface PaletteSwatch {
     hex: string;
@@ -48,60 +58,15 @@ export interface MaterialColour {
 }
 /** Where the served image came from. */
 export type ImageSource = OpenEnum<"r2" | "origin">;
-/** The grid-card projection of a material. */
-export interface MaterialTile {
-    variantId: string;
-    brand: string;
-    product: string;
-    variantName: string | null;
-    imageUrl: string | null;
-    imageSource: ImageSource | null;
-    category: string | null;
-    colour: MaterialColour;
-}
-/** A canonical attribute/term pair carried on a detail record. */
-export interface MaterialFacet {
-    attributeId: string;
-    term: string;
-}
-/**
- * One dimensional configuration of a material. Numeric fields are millimetres
- * (mass in kilograms); string fields are the source's own descriptors. The
- * index signature preserves the corpus's long tail of rarer keys.
- */
-export interface DimensionEntry {
-    label?: string;
-    tile_size?: string;
-    measurement_basis?: string;
-    width_mm?: number;
-    length_mm?: number;
-    height_mm?: number;
-    depth_mm?: number;
-    thickness_mm?: number;
-    diameter_mm?: number;
-    visible_projection_mm?: number;
-    weight_kg?: number;
-    [key: string]: unknown;
-}
-/** The record projection of a material — the tile plus detail-only fields. */
-export interface MaterialDetail extends MaterialTile {
-    brandSlug: string;
-    productId: string;
-    color: string | null;
-    materialBankId: string | null;
-    installationImageUrl: string | null;
-    displayCategory: string | null;
-    categoryPath: string[];
-    palette: PaletteSwatch[];
-    facets: MaterialFacet[];
-    dimensions: DimensionEntry[] | null;
-}
+export type { DimensionEntry, MaterialAvailability, MaterialDetail, MaterialFacet, MaterialSuccessor, MaterialTile, } from "./material-types.js";
 /** Per-signal scores, present on a result when `explain` was requested. */
 export interface SearchResultSignals {
     image: number | null;
     category: number | null;
     colour: number | null;
     lexical: number | null;
+    /** Text→image RERANK cosine — non-null only for a seeded search carrying `text`. */
+    text: number | null;
 }
 /** An accepted/measured visual meaning — descriptive evidence, never a ranking cause. */
 export interface VisualMeaning {
@@ -131,8 +96,21 @@ export interface SearchResultItem {
     score: number;
     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;
     siblingCount?: number;
     visualMeanings?: VisualMeaning[];
+    /**
+     * The shared report card for this hit against the request's `filters` (required
+     * cells) and `preferences` (preferred cells). Present (full view only) whenever a
+     * spec filter or preference was given. Reuses the by-spec verdict shape — the
+     * shared CandidateVerdict mirror; see {@link MaterialVerdict}.
+     */
+    verdict?: BySpecVerdict;
 }
 /** The lean `view:"card"` result item — identity + name + thumbnail + score. */
 export interface SearchCardItem {
@@ -385,31 +363,7 @@ export interface ResolveAttributeResponse {
     candidates: AttributeCandidate[];
 }
 export type * from "./catalog-discovery-types.js";
-export interface BySpecMatchedCell {
-    attributeId: string;
-    confidence: number | null;
-    sourceBasis: string | null;
-}
-export interface BySpecMatch {
-    variantId: string;
-    brand: string;
-    product: string;
-    variant: string;
-    color: string | null;
-    imageUrl: string | null;
-    hex: string | null;
-    matched: BySpecMatchedCell[];
-    minConfidence: number | null;
-}
-export interface BySpecResponse {
-    criteria: Array<{
-        attribute: string;
-        value: string;
-    }>;
-    totalMatches: number;
-    brandsSpanned: number;
-    matches: BySpecMatch[];
-}
+export type * from "./by-spec-types.js";
 export interface WhoamiResponse {
     principal: string;
     scopes: string[];
@@ -453,6 +407,11 @@ export interface SearchInput {
     };
     mood?: string;
     sort?: OpenEnum<"relevance" | "light" | "dark" | "vivid" | "muted" | "colourful">;
+    /**
+     * Seed a visual search from an existing variant's image (`variantId`) or a
+     * pre-computed image vector (`vector`). Only the `{ variantId }` form carries a
+     * seed variant, so it is the only form `verdicts` can diff a candidate against.
+     */
     similarTo?: {
         variantId: string;
     } | {
@@ -468,8 +427,16 @@ export interface SearchInput {
         category?: number;
         colour?: number;
         lexical?: number;
+        /** Text rerank multiplier applied when a seeded search also carries `text` (default 0.4). */
+        text?: number;
     };
     filters?: SearchFilter[];
+    /**
+     * SOFT spec criteria (rank-never-exclude). Same shape as `filters`; a preference
+     * never removes a result — it adds a `preferred` cell to each hit's `verdict` and
+     * demotes a failed/missing preferred hit WITHIN its page only.
+     */
+    preferences?: SearchFilter[];
     limit?: number;
     cursor?: string;
     explain?: boolean;
@@ -478,6 +445,13 @@ export interface SearchInput {
     count?: boolean;
     /** Only return materials with at least one catalog image. Default false (full catalog). */
     hasImages?: boolean;
+    /**
+     * Opt-in seed-relative verdict cells (MG-629). Only meaningful with
+     * `similarTo: { variantId }`: each hit's `verdict` gains `preferred` cells
+     * diffing its comparable attributes (numeric + a `colour` axis) against the
+     * seed's, with directional deviations. Inert on every other seed form.
+     */
+    verdicts?: boolean;
     /** Result projection — `"full"` (default) or the lean `"card"` grid form. */
     view?: OpenEnum<"full" | "card">;
 }
@@ -534,7 +508,19 @@ export interface MatchInput {
     detectionLabel?: string;
     materialFunction?: string;
     detectionCategory?: string;
+    /**
+     * Opt-in: also return quality-floor rejects, flagged `belowFloor: true` and
+     * appended after the kept results. Absent/false = default behaviour;
+     * `droppedBelowFloor` is unchanged.
+     */
+    includeBelowFloor?: boolean;
     requestedType?: OpenEnum<"swatch" | "installation" | "flatplan">;
+    /** Hard spec gates forwarded verbatim to the inner search — term match or presence, each with an optional trust bar. */
+    filters?: SearchFilter[];
+    /** Soft criteria (rank-never-exclude). A miss demotes within the page but never removes a hit. */
+    preferences?: SearchFilter[];
+    /** Opt in to seed-relative verdict cells; inert unless the inner search carries a variant seed. */
+    verdicts?: boolean;
 }
 /** Options for a batch material read. */
 export interface MaterialsBatchOptions {

package/validation.d.ts

@@ -0,0 +1,119 @@
+/**
+ * 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";
+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>;
+/** A `z.object({…})`. */
+export declare function requireRecord(value: unknown, what: string, fail: ValidationFailure): Record<string, unknown>;
+/** A `z.string()`. */
+export declare function requireString(value: unknown, what: string, fail: ValidationFailure): string;
+/** A `z.string().min(1)`. */
+export declare function 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;
+/** A `z.string().nullable()`. */
+export declare function 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;
+/** A `z.boolean()`. */
+export declare function requireBoolean(value: unknown, what: string, fail: ValidationFailure): boolean;
+/** A `z.boolean().optional()`. */
+export declare function 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;
+/** A `z.number().optional()`. */
+export declare function requireOptionalNumber(value: unknown, what: string, fail: ValidationFailure): void;
+/** A `z.number().nullable()`. */
+export declare function 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;
+/** A `z.number().min(min).max(max).nullable()`. */
+export declare function 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 function 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;
+/** A `z.enum([…])` — CLOSED, exactly like the canonical member list. */
+export declare function 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;
+/** A `z.array(…)`. */
+export declare function 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[];
+/** 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[];
+/**
+ * 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 function 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 function requireJsonRecord(value: unknown, what: string, fail: ValidationFailure): Record<string, JsonValue>;

package/validation.js

@@ -0,0 +1,241 @@
+/**
+ * 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);
+}
+/** A `z.object({…})`. */
+export function 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")
+        throw fail(`${what} is not a string`);
+    return value;
+}
+/** A `z.string().min(1)`. */
+export function 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 function 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)
+        return null;
+    return requireString(value, what, fail);
+}
+/** A `z.string().min(1).nullable()`. */
+export function requireNullableNonEmptyString(value, what, fail) {
+    if (value === null)
+        return null;
+    return requireNonEmptyString(value, what, fail);
+}
+/** A `z.boolean()`. */
+export function 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)
+        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) {
+    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)
+        return;
+    requireNumber(value, what, fail);
+}
+/** A `z.number().nullable()`. */
+export function 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) {
+    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)
+        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 function 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) {
+    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 function 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)
+        return null;
+    return requireEnum(value, allowed, what, fail);
+}
+/** A `z.array(…)`. */
+export function 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)
+        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) {
+    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.
+ *
+ * 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 function requireJsonValue(value, what, fail) {
+    if (value === null)
+        return null;
+    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))
+            throw fail(`${what} is not a finite number`);
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item, index) => requireJsonValue(item, `${what}[${index}]`, fail));
+    }
+    if (isRecord(value)) {
+        // A PLAIN object only. `isRecord` alone is not enough: it answers true for a
+        // `Date`, a `Map`, and any class instance, none of which have own enumerable
+        // entries — so recursing over them would silently accept them as `{}` while
+        // `z.json()` rejects them outright. A `Date` reaching `jsonb` is exactly the
+        // failure this check exists to stop.
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw fail(`${what} is not a JSON value`);
+        }
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+            key,
+            requireJsonValue(item, `${what}.${key}`, 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 function 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;
+}