@instruments/materialgraph 0.2.0 → 0.4.0

package/source-material-validation.js

@@ -0,0 +1,109 @@
+/**
+ * The runtime validator for `GET /api/v1/source-material/{batchId}` — the
+ * hand-rolled, zero-runtime-dependency mirror of
+ * `sourceMaterialBatchDetailSchema` and its transitive closure
+ * (`sourceMaterialBatchDetailFileSchema`, `sourceImageAnalysisSchema`,
+ * `sourceImageAnalysisResultSchema`) in
+ * `packages/sources/src/source-material/contract.ts`.
+ *
+ * WHY IT EXISTS. `contract-parity.test.ts` proves the SDK's STATIC types match
+ * the canonical schemas; that is a compile-time proof about shapes and validates
+ * nothing at run time. This is the run-time half, and it must ACCEPT and REJECT
+ * exactly what the schema does — pinned by `source-material-parity.test.ts`.
+ *
+ * TWO CONTRACT PROPERTIES IT ENFORCES, both easy to lose in a refactor:
+ *   1. `analyses` is REQUIRED and an array on every file. `[]` means "nothing
+ *      computed yet"; an absent field is a broken response, not an empty one.
+ *      Preprocessing is manual today and automatic later — only the trigger
+ *      changes, never this contract.
+ *   2. `result` is a JSON record all the way down (`z.json()`), not `unknown`.
+ *      See `requireJsonValue` for why the schema is that strict and why this
+ *      mirror cannot actually fire over the wire.
+ *
+ * ENUMS ARE CLOSED here, matching the canonical `z.enum(…)` members, while the
+ * published types are `OpenEnum` so a newer server value keeps type-checking.
+ * The validator follows the SCHEMA: the type stays wider than what is proven,
+ * which is imprecise but never a lie — the same choice
+ * `search-result-validation.ts` makes for `basis`.
+ *
+ * Package-internal (not re-exported from `index.ts`): a published symbol is a
+ * permanent contract, and promoting it later is additive.
+ */
+import { MaterialGraphError } from "./errors.js";
+import { requireArray, requireEnum, requireSafeInteger, requireJsonRecord, requireNonEmptyString, requireRecord, requireString, } from "./validation.js";
+/** `sourceImageAnalysisKindSchema` members, verbatim. */
+const ANALYSIS_KINDS = ["scene_match"];
+/** `sourceImageAnalysisStatusSchema` members, verbatim. */
+const ANALYSIS_STATUSES = ["ok", "failed"];
+/** `sourceMaterialRoleSchema` members, verbatim. */
+const SOURCE_ROLES = [
+    "brief",
+    "reference_image",
+    "document",
+    "document_image",
+    "inspiration_image",
+    "unclassified",
+];
+function detailFailure(batchId) {
+    return (reason) => MaterialGraphError.unexpected(`GET /api/v1/source-material/${batchId} returned a malformed body: ${reason}`);
+}
+function checkAnalysis(value, what, fail) {
+    const record = requireRecord(value, what, fail);
+    // `model` and `analysedAt` ARE `.min(1)` canonically — fields this endpoint
+    // introduces, where an empty value is meaningless and `model` already cannot
+    // be written empty. Parity here is achieved by the schema being strict, never
+    // by this mirror freelancing past it.
+    return {
+        kind: requireEnum(record.kind, ANALYSIS_KINDS, `${what}.kind`, fail),
+        model: requireNonEmptyString(record.model, `${what}.model`, fail),
+        status: requireEnum(record.status, ANALYSIS_STATUSES, `${what}.status`, fail),
+        result: requireJsonRecord(record.result, `${what}.result`, fail),
+        analysedAt: requireNonEmptyString(record.analysedAt, `${what}.analysedAt`, fail),
+    };
+}
+function checkFile(value, what, fail) {
+    const record = requireRecord(value, what, fail);
+    // NOT `requireDefaultedArray`: the schema has no `.default([])`, so an absent
+    // `analyses` is a malformed body rather than an empty one. Keeping that
+    // distinction is the whole point of the always-an-array contract.
+    const analyses = requireArray(record.analyses, `${what}.analyses`, fail);
+    // `requireString`, NOT `requireNonEmptyString`, for the fields this endpoint
+    // INHERITS from the shared source-material contract (`sourceId`, `sha256`,
+    // `url` — plus `batchId`/`createdAt` below). Those are plain `z.string()`
+    // there and shared with the upload path; a client that rejected `""` would
+    // refuse a response the server can legitimately produce, and tightening them
+    // is a change to a contract this endpoint does not own.
+    return {
+        sourceId: requireString(record.sourceId, `${what}.sourceId`, fail),
+        role: requireEnum(record.role, SOURCE_ROLES, `${what}.role`, fail),
+        filename: requireString(record.filename, `${what}.filename`, fail),
+        mediaType: requireString(record.mediaType, `${what}.mediaType`, fail),
+        sha256: requireString(record.sha256, `${what}.sha256`, fail),
+        // `requireSafeInteger`, NOT `requireIntegerAtLeast(…, 0)`. Canonically these
+        // are a bare `z.number().int()` on the INHERITED
+        // `sourceMaterialFileReceiptSchema`, which carries no lower bound — so a
+        // negative is accepted there and must be accepted here.
+        //
+        // A negative `bytes` is nonsense and a negative `pages` more so, and this is
+        // still not the place to say so: a client validator holding an opinion the
+        // contract does not is how the two drift, and how a response the server may
+        // legitimately produce starts throwing at the boundary. Tightening those
+        // fields is a canonical change to a schema shared with the upload path, and
+        // belongs in its own ticket with this mirror following after.
+        bytes: requireSafeInteger(record.bytes, `${what}.bytes`, fail),
+        pages: record.pages === null ? null : requireSafeInteger(record.pages, `${what}.pages`, fail),
+        url: requireString(record.url, `${what}.url`, fail),
+        analyses: analyses.map((analysis, index) => checkAnalysis(analysis, `${what}.analyses[${index}]`, fail)),
+    };
+}
+/** Validate a batch-detail body, returning it typed, or throw explaining why. */
+export function checkSourceMaterialBatchDetail(value, batchId) {
+    const fail = detailFailure(batchId);
+    const record = requireRecord(value, "body", fail);
+    const sources = requireArray(record.sources, "body.sources", fail);
+    return {
+        batchId: requireString(record.batchId, "body.batchId", fail),
+        createdAt: requireString(record.createdAt, "body.createdAt", fail),
+        sources: sources.map((file, index) => checkFile(file, `body.sources[${index}]`, fail)),
+    };
+}

package/spec-types.d.ts

@@ -30,6 +30,10 @@
  * in the last). A caller shouldn't have to know which bucket a programme fell
  * into, so this single virtual id matches the `programme` term across all four.
  *
+ * The `term` may be a display name or alias ("GREENGUARD Gold", "LEED"), resolved
+ * server-side to its canonical programme token, or a canonical token directly
+ * (e.g. `greenguard_certificate`, `has_greenguard_gold_certification`).
+ *
  * @example
  * // "find a GREENGUARD-certified alternative"
  * client.search({

package/spec-types.js

@@ -30,6 +30,10 @@
  * in the last). A caller shouldn't have to know which bucket a programme fell
  * into, so this single virtual id matches the `programme` term across all four.
  *
+ * The `term` may be a display name or alias ("GREENGUARD Gold", "LEED"), resolved
+ * server-side to its canonical programme token, or a canonical token directly
+ * (e.g. `greenguard_certificate`, `has_greenguard_gold_certification`).
+ *
  * @example
  * // "find a GREENGUARD-certified alternative"
  * client.search({

package/specifications.d.ts

@@ -38,6 +38,11 @@ export declare function hasSpec(attributeId: string): SpecPresenceFilter;
  * 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")] });
@@ -56,6 +61,10 @@ export declare function specCriterion(attributeId: string, value: string): strin
  * 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/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/suggest-types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Entity typeahead (MG-654) — the hand-mirrored wire types for
+ * `GET /api/v1/search/suggest`, plus the one query-shaping rule the endpoint
+ * imposes.
+ *
+ * Split out of `types.ts` for the repository's source-file size budget, the same
+ * reason `catalog-discovery-types.ts` sits beside it; both are re-exported from
+ * `types.ts`, so importers see no difference.
+ */
+/** Which kind of entity a suggestion is — and therefore what `refId` means. */
+export type SuggestKind = "product" | "brand" | "category";
+/** How the query met the suggestion's label. Strongest first. */
+export type SuggestMatch = "prefix" | "word" | "contains" | "fuzzy";
+/** One ranked typeahead suggestion, carrying the identity it resolves to. */
+export interface Suggestion {
+    kind: SuggestKind;
+    /** The entity's name as written, for display. */
+    label: string;
+    /**
+     * The resolvable identity: a product id, a brand slug, or a product-type key.
+     * Selecting a suggestion should navigate to this, not re-search `label`.
+     */
+    refId: string;
+    match: SuggestMatch;
+    brandSlug: string | null;
+    brandName: string | null;
+    categoryKey: string | null;
+    /** A representative variant, so a client can open a material record directly. */
+    variantId: string | null;
+    variantCount: number;
+}
+/** The suggest response: the query as interpreted, plus the ranked suggestions. */
+export interface SuggestResponse {
+    /** The normalised query the corpus was matched against. */
+    query: string;
+    /** Ranked best-match-first. Empty when nothing came close — a miss, not an error. */
+    suggestions: Suggestion[];
+}
+/** Options for {@link MaterialGraphClient.suggest}. */
+export interface SuggestOptions {
+    /** How many suggestions to return (1–20, default 8). */
+    limit?: number;
+    /** Restrict to these kinds. Omit for all of them. */
+    kind?: SuggestKind | SuggestKind[];
+}
+/**
+ * Shape the query string for a suggest call.
+ *
+ * The only non-obvious rule: `kind` is a COMMA LIST on the wire (`product,brand`),
+ * which is the house convention for multi-value v1 params, so an array is joined
+ * here rather than being sent as repeated `?kind=` pairs the route would ignore.
+ * Undefined members are dropped by the transport.
+ */
+export declare function suggestQuery(q: string, options?: SuggestOptions): {
+    q: string;
+    limit?: number;
+    kind?: string;
+};

package/suggest-types.js

@@ -0,0 +1,21 @@
+/**
+ * Entity typeahead (MG-654) — the hand-mirrored wire types for
+ * `GET /api/v1/search/suggest`, plus the one query-shaping rule the endpoint
+ * imposes.
+ *
+ * Split out of `types.ts` for the repository's source-file size budget, the same
+ * reason `catalog-discovery-types.ts` sits beside it; both are re-exported from
+ * `types.ts`, so importers see no difference.
+ */
+/**
+ * Shape the query string for a suggest call.
+ *
+ * The only non-obvious rule: `kind` is a COMMA LIST on the wire (`product,brand`),
+ * which is the house convention for multi-value v1 params, so an array is joined
+ * here rather than being sent as repeated `?kind=` pairs the route would ignore.
+ * Undefined members are dropped by the transport.
+ */
+export function suggestQuery(q, options) {
+    const kind = Array.isArray(options?.kind) ? options.kind.join(",") : options?.kind;
+    return { q, limit: options?.limit, kind };
+}

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,8 @@ 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 "./suggest-types.js";
+export type * from "./by-spec-types.js";
 export interface WhoamiResponse {
     principal: string;
     scopes: string[];
@@ -453,6 +408,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 +428,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 +446,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 +509,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>;