@ultimat3/schema 23.0.0 → 25.0.0

package/src/iso-date.ts

@@ -20,7 +20,28 @@ const UTC_OFFSET = /(?:z|[+-]\d{2}:?\d{2})$/i;
  * because RFC 3339 §5.6 permits a lowercase `t` and `z`.
  */
 const ISO_SHAPE =
-  /^\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?$/i;
+  /^(\d{4})-(\d{2})-(\d{2})(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?$/i;
+
+/**
+ * Days per month, January first, in a common year. **Twin: `daysInMonth` in
+ * `packages/time/src/plain-date.ts`** — this package is tier 0 and cannot import `@ultimat3/time`,
+ * so the Gregorian table is restated rather than shared. The two are held equal by the parity
+ * table in `iso-date.test.ts` and `packages/time/src/plain-date.test.ts`; edit both or neither.
+ */
+const DAYS_IN_MONTH: readonly number[] = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+
+const isLeapYear = (year: number): boolean =>
+  (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+
+/**
+ * The half a regex cannot hold. `new Date('2026-02-30')` does not refuse — it answers March 2nd —
+ * so a typo validated, and the instant that was stored is one the caller never wrote.
+ */
+function isCalendarDay(year: number, month: number, day: number): boolean {
+  const days = DAYS_IN_MONTH[month - 1];
+  if (days === undefined) return false;
+  return day >= 1 && day <= (month === 2 && isLeapYear(year) ? 29 : days);
+}
 
 /** What a `t.date` string must not be: a clock time with no offset and no `Z`. */
 export function isZonelessDateTime(value: string): boolean {
@@ -28,9 +49,12 @@ export function isZonelessDateTime(value: string): boolean {
 }
 
 /**
- * True when `value` is an ISO-8601 date, or date-time carrying `Z` or an offset: the only strings
- * whose instant is the same on every host. Check it before `new Date(value)`, every time.
+ * True when `value` is an ISO-8601 date, or date-time carrying `Z` or an offset, naming a day its
+ * month has: the only strings whose instant is the same on every host and is the one written.
+ * Check it before `new Date(value)`, every time.
  */
 export function isIsoDateTime(value: string): boolean {
-  return ISO_SHAPE.test(value) && !isZonelessDateTime(value);
+  const match = ISO_SHAPE.exec(value);
+  if (match === null || isZonelessDateTime(value)) return false;
+  return isCalendarDay(Number(match[1]), Number(match[2]), Number(match[3]));
 }

package/src/json-schema.ts

@@ -5,6 +5,7 @@
 
 import { describeValue } from './describe-value';
 import { SchemaUnsupportedError } from './errors';
+import { JSON_MAX_DEPTH } from './json-value';
 import { CURRENCY_CODE_PATTERN, MAX_MONEY_SCALE } from './money-value';
 import { requiredKeys, type SchemaNode, type SchemaRefinement } from './node';
 import { PROTOTYPE_KEYS } from './prototype-keys';
@@ -34,6 +35,13 @@ export interface JsonSchema {
   readonly minLength?: number;
   readonly maxLength?: number;
   readonly pattern?: string;
+  /**
+   * The RegExp flags `pattern` is applied with, when there are any. JSON Schema's `pattern` has no
+   * flag syntax and an inline `(?i)` is not ECMA-262, so they travel beside it as an extension a
+   * consumer that compiles the pattern (`@ultimat3/mcp`'s arg validator) reads; the prose copy in
+   * `description` is for a reader.
+   */
+  readonly 'x-ultimate-pattern-flags'?: string;
   readonly minimum?: number;
   readonly maximum?: number;
   readonly enum?: readonly (string | number)[];
@@ -99,6 +107,9 @@ function stringNode(node: SchemaNode): JsonSchema {
     ...(node.minLength === undefined ? {} : { minLength: node.minLength }),
     ...(node.maxLength === undefined ? {} : { maxLength: node.maxLength }),
     ...(node.pattern === undefined ? {} : { pattern: node.pattern }),
+    ...(node.pattern === undefined || node.patternFlags === undefined || node.patternFlags === ''
+      ? {}
+      : { 'x-ultimate-pattern-flags': node.patternFlags }),
   };
 }
 
@@ -148,10 +159,22 @@ function patternNote(node: SchemaNode): string | undefined {
     : `pattern is applied with RegExp flags "${flags}"`;
 }
 
+/**
+ * JSON Schema has no keyword for nesting depth, so `t.json()`'s bound is stated in prose — the
+ * narrower-of-the-two rule this file's header states: `{}` alone promised a document 300 levels
+ * deep that the parser refuses.
+ */
+function jsonNote(node: SchemaNode): string | undefined {
+  return node.kind === 'json'
+    ? `any JSON value, nested at most ${JSON_MAX_DEPTH} levels deep`
+    : undefined;
+}
+
 function convert(node: SchemaNode): JsonSchema {
   const refinements = node.refinements ?? [];
   const notes = [
     node.description,
+    jsonNote(node),
     patternNote(node),
     ...refinements.map((refinement) => refinement.message),
   ].filter((part): part is string => part !== undefined);
@@ -272,6 +295,10 @@ function convert(node: SchemaNode): JsonSchema {
         additionalProperties: false,
       });
     }
+    // No `type`: an empty schema is JSON Schema's own spelling of "any JSON value", and every
+    // instance it validates is JSON already. The depth bound rides in `description` (`jsonNote`).
+    case 'json':
+      return annotate({});
     default:
       return annotate({});
   }
@@ -315,7 +342,7 @@ export function toJsonSchema(schema: unknown, options?: ToJsonSchemaOptions): Js
   };
 }
 
-/** The exact shape an MCP `tools/list` entry needs: draft-07, no `$schema`. */
+/** Draft-07, no `$schema`: the document `wire-schema.ts` narrows to what an MCP tool publishes. */
 export function toMcpInputSchema(schema: unknown): JsonSchema {
   return toJsonSchema(schema, { dialect: 'draft-07', includeDialect: false });
 }

package/src/json-value.ts

@@ -0,0 +1,205 @@
+// Single responsibility: the framework's ONE `JsonValue` declaration and `t.json()`, the validator
+// that admits exactly the values `JSON.stringify` and a Postgres `jsonb` round-trip unchanged.
+// Its own file for `money-value.ts`'s reason: it is a builtin whose SHAPE other packages alias.
+
+import {
+  type Check,
+  fail,
+  failWith,
+  isPlainObject,
+  makeSchema,
+  pass,
+  type Schema,
+} from './builder';
+import { expected } from './describe-value';
+import type { SchemaNode } from './node';
+import type { StandardIssue } from './standard';
+import { unstorable } from './unstorable-text';
+
+/**
+ * Any value JSON can carry. Readonly, because a parsed payload is data the handler reads; the copy
+ * `t.json()` answers is its own, so nothing it holds is shared with the caller's input.
+ */
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly JsonValue[]
+  | { readonly [key: string]: JsonValue };
+
+/**
+ * How many containers `t.json()` lets nest. A FIXED bound, not an option: the walk recurses once
+ * per level and `JSON.parse` builds 100 000 levels from 200 KB of brackets, so an unbounded walk
+ * was a `RangeError` — a 500 — for any caller who sent one. 256 holds a rich-text document (each
+ * list level is an array and an object) with room to spare. Narrower is `.refine()`'s job.
+ */
+export const JSON_MAX_DEPTH = 256;
+
+/** A path segment chain, materialised only for an issue: a copy per node is O(n × depth). */
+interface At {
+  readonly parent: At | readonly PropertyKey[];
+  readonly segment: number;
+}
+
+function pathOf(at: At | readonly PropertyKey[]): PropertyKey[] {
+  const segments: number[] = [];
+  let cursor = at;
+  while (!Array.isArray(cursor)) {
+    const link = cursor as At;
+    segments.push(link.segment);
+    cursor = link.parent;
+  }
+  return [...(cursor as readonly PropertyKey[]), ...segments.reverse()];
+}
+
+interface Walk {
+  readonly issues: StandardIssue[];
+  /** The containers enclosing the current one: meeting one again is a cycle. */
+  readonly open: Set<object>;
+  /** A container already accepted, with its height, so a shared one is walked ONCE. */
+  readonly done: Map<object, { readonly value: JsonValue; readonly height: number }>;
+  /** A container already refused: its issues are reported, at the first position it was met. */
+  readonly refused: Set<object>;
+}
+
+type Step = { readonly ok: true; readonly value: JsonValue; readonly height: number } | null;
+
+const CYCLE = 'expected a JSON value, received a cycle (a reference back to an enclosing value)';
+const NOT_PLAIN = 'expected a JSON value, received an object that is not a plain object or array';
+
+function refuse(state: Walk, at: At | readonly PropertyKey[], message: string): null {
+  state.issues.push({ message, path: pathOf(at) });
+  return null;
+}
+
+function scalar(value: unknown, at: At | readonly PropertyKey[], state: Walk): Step {
+  if (value === null || typeof value === 'boolean') return { ok: true, value, height: 0 };
+  if (typeof value === 'number') {
+    return Number.isFinite(value)
+      ? { ok: true, value, height: 0 }
+      : refuse(state, at, expected('a JSON value', value));
+  }
+  if (typeof value === 'string') {
+    const reason = unstorable(value);
+    return reason === undefined
+      ? { ok: true, value, height: 0 }
+      : refuse(state, at, `${expected('a JSON value', value)} ${reason}`);
+  }
+  return refuse(state, at, expected('a JSON value', value));
+}
+
+function walk(value: unknown, at: At | readonly PropertyKey[], depth: number, state: Walk): Step {
+  if (typeof value !== 'object' || value === null) return scalar(value, at, state);
+  const array = Array.isArray(value);
+  if (!array && !isPlainObject(value)) {
+    // A Date names itself (`describeValue`); a Map, a Set or a class instance is "an object" there.
+    return refuse(state, at, value instanceof Date ? expected('a JSON value', value) : NOT_PLAIN);
+  }
+  if (state.open.has(value)) return refuse(state, at, CYCLE);
+  if (state.refused.has(value)) return null;
+  const seen = state.done.get(value);
+  const tooDeep = expected(`JSON nested at most ${JSON_MAX_DEPTH} levels deep`, value);
+  if (seen !== undefined) {
+    return depth + seen.height <= JSON_MAX_DEPTH
+      ? { ok: true, ...seen }
+      : refuse(state, at, tooDeep);
+  }
+  if (depth >= JSON_MAX_DEPTH) return refuse(state, at, tooDeep);
+
+  state.open.add(value);
+  const built = array ? walkArray(value, at, depth, state) : walkObject(value, at, depth, state);
+  state.open.delete(value);
+  if (built === null) {
+    state.refused.add(value);
+    return null;
+  }
+  state.done.set(value, built);
+  return { ok: true, ...built };
+}
+
+type Built = { readonly value: JsonValue; readonly height: number } | null;
+
+function walkArray(
+  items: readonly unknown[],
+  at: At | readonly PropertyKey[],
+  depth: number,
+  state: Walk,
+): Built {
+  const out: JsonValue[] = [];
+  let height = 0;
+  let ok = true;
+  // An index loop, never `entries()` on a sparse array alone: a hole reads `undefined` and is
+  // refused at its index, where `JSON.stringify` would have written `null` in silence.
+  for (let index = 0; index < items.length; index += 1) {
+    const step = walk(items[index], { parent: at, segment: index }, depth + 1, state);
+    if (step === null) ok = false;
+    else {
+      out.push(step.value);
+      height = Math.max(height, step.height);
+    }
+  }
+  return ok ? { value: out, height: height + 1 } : null;
+}
+
+function walkObject(
+  source: Record<string, unknown>,
+  at: At | readonly PropertyKey[],
+  depth: number,
+  state: Walk,
+): Built {
+  // Null-prototype, for `recordSchema`'s reason: every key here is the caller's, and on a `{}`
+  // literal `out['__proto__'] = …` re-prototypes the output instead of storing the key.
+  const out: Record<string, JsonValue> = Object.create(null) as Record<string, JsonValue>;
+  let height = 0;
+  let ok = true;
+  // The entry's POSITION is its path segment, never its key — the rule `recordSchema` states:
+  // a key is caller data, and an issue path reaches the problem document and the log line.
+  for (const [index, key] of Object.keys(source).entries()) {
+    const link: At = { parent: at, segment: index };
+    const reason = unstorable(key);
+    if (reason !== undefined) {
+      refuse(state, link, `expected an object key, received one ${reason}`);
+      ok = false;
+      continue;
+    }
+    const step = walk(source[key], link, depth + 1, state);
+    if (step === null) ok = false;
+    else {
+      out[key] = step.value;
+      height = Math.max(height, step.height);
+    }
+  }
+  return ok ? { value: out, height: height + 1 } : null;
+}
+
+const checkJson: Check<JsonValue> = (value, path) => {
+  const state: Walk = { issues: [], open: new Set(), done: new Map(), refused: new Set() };
+  const step = walk(value, path, 0, state);
+  if (step !== null) return pass(step.value);
+  // Every refusal pushes its issue; the fallback only keeps a refusal from ever reading as success.
+  return state.issues.length > 0
+    ? failWith(state.issues)
+    : fail(path, expected('a JSON value', value));
+};
+
+/**
+ * Whether a value has a JSON SHAPE, one level deep — `node-fits.ts`'s question for a union
+ * member. Not validation: a nested `undefined` still fits, and is refused by the parse after.
+ */
+export function isJsonShape(value: unknown): boolean {
+  if (value === null || typeof value === 'boolean' || typeof value === 'string') return true;
+  if (typeof value === 'number') return Number.isFinite(value);
+  return Array.isArray(value) || isPlainObject(value);
+}
+
+const JSON_NODE: SchemaNode = Object.freeze({ kind: 'json' });
+
+/**
+ * `t.json()` as a free function, shipped beside the namespace member as `nullableSchema` is.
+ * Every key is kept, `__proto__` and `constructor` included — a webhook body is somebody else's
+ * document — and answered on a null-prototype copy, so no key reaches a prototype.
+ */
+export function jsonSchema(): Schema<JsonValue, JsonValue> {
+  return makeSchema<JsonValue, JsonValue>(JSON_NODE, checkJson);
+}

package/src/money-value.ts

@@ -106,7 +106,7 @@ export const moneySchema: Schema<MoneyValue, MoneyValue> = makeSchema<MoneyValue
     const currency = value['currency'];
     const scale = value['scale'];
     const issues: StandardIssue[] = [];
-    // Safe, not merely whole: `money()` and `entity`'s `parseMinor` both demand a safe integer, so
+    // Safe, not merely whole: `fromMinor()` and `entity`'s `parseMinor` both demand a safe integer, so
     // `Number.isInteger` here let 2^53 through the boundary as a 200 and failed at the row write
     // as a 500 — the same value refused twice, once with a field path and once without.
     if (typeof minor !== 'number' || !Number.isSafeInteger(minor)) {

package/src/node-fits.ts

@@ -0,0 +1,51 @@
+// Single responsibility: does a value have the SHAPE a node names, one level deep — the question
+// `coerce.ts` asks to pick the union member a raw HTTP value was written for.
+
+import { isPlainObject } from './builder';
+import { isJsonShape } from './json-value';
+import type { SchemaNode } from './node';
+
+/**
+ * Whether `value` is the SHAPE `node` names — one level deep, which is all a union needs to pick
+ * a branch. Not validation: it never reads a bound, a pattern or a refinement, so a value that
+ * fits can still be refused, with the real message, by the schema it is handed to next.
+ *
+ * An object fits when every LITERAL field it declares holds that literal — the tag of a
+ * discriminated union, read off the IR without asking which key the discriminant is.
+ */
+export function fits(node: SchemaNode, value: unknown): boolean {
+  switch (node.kind) {
+    case 'string':
+      return typeof value === 'string';
+    case 'number':
+      return typeof value === 'number';
+    case 'boolean':
+      return typeof value === 'boolean';
+    case 'date':
+      return value instanceof Date;
+    case 'literal':
+      return value === node.literal;
+    case 'enum':
+      return (node.values ?? []).some((member) => member === value);
+    case 'array':
+      return Array.isArray(value);
+    case 'record':
+    case 'money':
+      return isPlainObject(value);
+    case 'object': {
+      if (!isPlainObject(value)) return false;
+      return Object.entries(node.properties ?? {}).every(
+        ([key, child]) =>
+          child.kind !== 'literal' ||
+          (child.optional === true && !Object.hasOwn(value, key)) ||
+          (Object.hasOwn(value, key) && value[key] === child.literal),
+      );
+    }
+    case 'union':
+      return (node.anyOf ?? []).some((member) => fits(member, value));
+    case 'json':
+      return isJsonShape(value);
+    default:
+      return false;
+  }
+}

package/src/node.ts

@@ -14,6 +14,14 @@ export type SchemaKind =
   | 'union'
   | 'record'
   | 'money'
+  /**
+   * Any JSON value — `t.json()`. A kind and not a field on `unknown`, because they are different
+   * facts: `unknown` is the IR saying it CANNOT describe a value (`@ultimat3/entity`'s view of a
+   * column it has no node for), `json` is the IR saying exactly what it holds. Every foreign
+   * `default:` already degrades to the right projection — `{}`, a raw pass-through, a `null`
+   * sample, admin's JSON textarea — so a consumer that has never heard of it is still correct.
+   */
+  | 'json'
   | 'unknown';
 
 /** JSON Schema `format`, plus the framework's own semantic formats. */
@@ -54,7 +62,8 @@ export interface SchemaNode {
   /**
    * The RegExp's flags, carried beside the source for the same reason. Dropping them made
    * `t.string.pattern(/^[a-z]+$/i)` reject `ABC` while quoting the pattern that matches it.
-   * JSON Schema's `pattern` has no flags, so `json-schema.ts` states them in `description`.
+   * JSON Schema's `pattern` has no flags, so `json-schema.ts` publishes them as
+   * `x-ultimate-pattern-flags` beside it, and states them in `description` for a reader.
    */
   readonly patternFlags?: string | undefined;
   readonly minimum?: number | undefined;

package/src/render-meta.ts

@@ -0,0 +1,53 @@
+// Single responsibility: an error's `meta` as a record `JSON.stringify` cannot throw on. The twin
+// of `renderMetaRecord` in `packages/core/src/error-render.ts`, restated because this package is
+// tier 0 and may not import core — `SchemaError.toJSON()` makes the same `--json` promise.
+
+import { describeValue } from './describe-value';
+
+type Meta = Readonly<Record<string, unknown>>;
+
+/** `JSON.stringify` with its throw removed: did the value survive being serialised at all? */
+function canRender(value: unknown): boolean {
+  try {
+    JSON.stringify(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** A record's own keys, or none — a `Proxy` may refuse to be enumerated. */
+function metaKeys(meta: Meta): readonly string[] {
+  try {
+    return Object.keys(meta);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * One entry, kept as it is when it serialises. What does not is DESCRIBED, never echoed: a schema
+ * error's `meta` holds the value a caller sent, so `describeValue` — shape and length, no content —
+ * is the only rendering this package has for one. A function is described too: `JSON.stringify`
+ * drops it without throwing, but copying a `toJSON` across would have it invoked one layer out.
+ */
+function metaEntry(meta: Meta, key: string): unknown {
+  try {
+    const value = meta[key];
+    return canRender(value) && typeof value !== 'function' ? value : describeValue(value);
+  } catch {
+    return 'a value that cannot be read';
+  }
+}
+
+/**
+ * `meta` is machine-read, so a record that serialises is returned UNCHANGED, identity included.
+ * Only what cannot be rendered degrades, one key at a time — a `bigint` or a cycle in one entry
+ * must not cost the reader the entries beside it, and must not throw at `--json` render time.
+ */
+export function renderMetaRecord(meta: Meta | undefined): Meta | undefined {
+  if (meta === undefined || canRender(meta)) return meta;
+  const out: Record<string, unknown> = {};
+  for (const key of metaKeys(meta)) out[key] = metaEntry(meta, key);
+  return out;
+}

package/src/standard.ts

@@ -96,11 +96,22 @@ export function toValidationIssues(issues: readonly StandardIssue[]): readonly V
   }));
 }
 
+/**
+ * Async by the rule `await` itself uses — a callable `then` — never `instanceof Promise`. A
+ * library's own promise class, a polyfill or a Promise from another realm fails that test, and was
+ * then read as a RESULT: no `issues` key, so a success, with `value` undefined. `parse` returned
+ * `undefined` for input nothing had validated.
+ */
+export function isThenable(value: unknown): value is PromiseLike<unknown> {
+  if ((typeof value !== 'object' && typeof value !== 'function') || value === null) return false;
+  return typeof (value as { then?: unknown }).then === 'function';
+}
+
 function assertSync<Output>(
   result: StandardResult<Output> | Promise<StandardResult<Output>>,
   vendor: string,
 ): StandardResult<Output> {
-  if (result instanceof Promise) {
+  if (isThenable(result)) {
     throw new SchemaUnsupportedError({
       cause: `${vendor} validated asynchronously in a synchronous call site`,
       fix: 'call validateAsync()/parseAsync() instead of validate()/parse()',

package/src/t.ts

@@ -3,6 +3,7 @@
 // even for modules that captured `t` at import time.
 
 import type { AnySchema, Refinement, Schema, Shape } from './builder';
+import type { JsonValue } from './json-value';
 import type { MoneyValue } from './money-value';
 import { schemaProvider } from './provider';
 import type { InferInput, InferOutput, StandardSchemaV1 } from './standard';
@@ -49,6 +50,14 @@ export const t: TNamespace = {
   get cursor(): StringSchema {
     return provider().cursor;
   },
+  /**
+   * `t.json()` — any JSON value: null, a boolean, a finite number, a string, and arrays and plain
+   * objects of them, at most `JSON_MAX_DEPTH` deep. The column it pairs with is entity's
+   * `json(t.json())`, a `jsonb` that stores what it was sent.
+   */
+  json(): Schema<JsonValue, JsonValue> {
+    return provider().json();
+  },
   object<S extends Shape>(shape: S): ObjectSchema<S> {
     return provider().object(shape);
   },

package/src/time-zone-name.ts

@@ -1,7 +1,7 @@
 // Single responsibility: is a string an IANA zone NAME? TIER 0'S ONE STATEMENT of the rule
 // `@ultimat3/time` enforces everywhere above it — a zone is `Area/Location`, and `UTC` is the one
-// exception. `@ultimat3/core` imported its own copy of this predicate until 2026-08-27 and now
-// re-exports this one, over the declared `core -> schema` edge.
+// exception. `@ultimat3/core` carried its own copy until 2026-08-27, then a re-export for the
+// `defaultTimeZone` validator, deleted with that key in 25.0.0.
 //
 // `@ultimat3/time`'s `canonicalTimeZone` is NOT a fourth copy and is deliberately left alone: it
 // answers a different question (the canonical SPELLING, memoised over ~445 listed zones plus a
@@ -14,9 +14,8 @@
  * Unobservable on ICU 78 — `+01:00` resolves to itself, so the slash rule below already refuses it,
  * and deleting this line changes no answer this package can currently produce. It stays because it
  * guards the runtime that folds an offset into `Etc/GMT-1`, which WOULD carry a slash, and because
- * `packages/core/src/time-zone-name.ts` and `packages/time/src/zone-canonical.ts` both carry the
- * same line: three statements of one rule may not differ, least of all in the half that is hard to
- * test.
+ * `packages/time/src/zone-canonical.ts` carries the same line: two statements of one rule may not
+ * differ, least of all in the half that is hard to test.
  */
 const NUMERIC_OFFSET = /^[+-]/;
 

package/src/unstorable-text.ts

@@ -0,0 +1,20 @@
+// Single responsibility: the ONE predicate naming a string Postgres cannot store as written — the
+// rule every string-backed validator (`t.string` and its kin, a `t.record` key, `t.json()`) shares,
+// so the three can never disagree about which input reaches the row write.
+
+const NUL = '\u0000';
+/** A lone UTF-16 surrogate. `String#isWellFormed` is ES2024 and the lib is ES2023. */
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+
+/**
+ * Why a string cannot be stored, or `undefined`. Both MEASURED against Postgres 17: a NUL is
+ * refused by `text` and `jsonb` alike (22021 / 22P05), a lone surrogate by `jsonb` (22P02) — and
+ * into `text`, Bun's sql encodes it as U+FFFD, so the row holds a different string than the
+ * caller sent while a memory store holds the original. Passing either moved the failure to the
+ * row write, as a 500 with no field path. Names the fact, never the content (`describe-value.ts`).
+ */
+export function unstorable(text: string): string | undefined {
+  if (text.includes(NUL)) return 'that contains a NUL character (U+0000)';
+  if (LONE_SURROGATE.test(text)) return 'that contains a lone UTF-16 surrogate';
+  return undefined;
+}

package/src/validators.ts

@@ -2,6 +2,7 @@
 // ArkType or Zod replace them wholesale via `configureSchemaProvider()` — neither ships; the IR and the
 // Standard Schema surface are what the rest of the framework actually depends on.
 
+import { isAbsoluteUrl } from './absolute-url';
 import {
   type AnySchema,
   type Check,
@@ -21,19 +22,17 @@ import { charCount } from './char-count';
 import { expected } from './describe-value';
 import { discriminatedUnionSchema } from './discriminated-union';
 import { isIsoDateTime, isZonelessDateTime } from './iso-date';
+import { type JsonValue, jsonSchema } from './json-value';
 import { type MoneyValue, moneySchema } from './money-value';
 import type { SchemaNode } from './node';
 import { isPrototypeKey, PROTOTYPE_KEYS } from './prototype-keys';
 import type { InferInput, InferOutput, StandardIssue } from './standard';
 import { isIanaZoneName } from './time-zone-name';
+import { unstorable } from './unstorable-text';
 
 const EMAIL_RE = /^[^\s@]+@[^\s@.]+(\.[^\s@.]+)+$/;
 const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const CURSOR_RE = /^[A-Za-z0-9_-]+$/;
-/** The one code point no Postgres `text` or `jsonb` value can hold — see `stringLike`. */
-const NUL = '\u0000';
-/** Names the fact, never the content: the issue-message rule in `describe-value.ts`. */
-const NUL_REFUSAL = 'that contains a NUL character (U+0000)';
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 
 export interface StringSchema extends Schema<string, string> {
@@ -88,11 +87,11 @@ function stringLike(node: SchemaNode, what: string, test?: (value: string) => bo
   const matchesPattern = patternTester(node);
   const check: Check<string> = (value, path) => {
     if (typeof value !== 'string') return fail(path, expected(what, value));
-    // U+0000 is the one character Postgres cannot store: `text` and `jsonb` both refuse it
-    // (SQLSTATE 22021 / 22P05), so a NUL that passed here reached the row write — or a `where`
-    // bind — as `X_DB_STATEMENT_FAILED`, a 500 blaming the server for a byte the caller sent.
-    // Only NUL: a tab, a newline or any other C0 control is legal text Postgres stores unchanged.
-    if (value.includes(NUL)) return fail(path, `${expected(what, value)} ${NUL_REFUSAL}`);
+    // A NUL or a lone surrogate passed here reached the row write — or a `where` bind — as
+    // `X_DB_STATEMENT_FAILED`, a 500 blaming the server for what the caller sent (`unstorable`).
+    // Only those: a tab, a newline or any other C0 control is legal text Postgres stores unchanged.
+    const unfit = unstorable(value);
+    if (unfit !== undefined) return fail(path, `${expected(what, value)} ${unfit}`);
     if (node.minLength !== undefined && charCount(value) < node.minLength) {
       return fail(path, expected(`${what} of at least ${node.minLength} chars`, value));
     }
@@ -312,10 +311,11 @@ export function recordSchema<S extends AnySchema>(
         // new spelling to learn. It is `Object.entries` order — integer-like keys sort ahead of
         // string ones — so it names an entry that exists rather than a byte offset in the body.
         const at = [...path, index];
-        // A record is stored as `jsonb` far more often than not, and jsonb refuses a NUL in a KEY
-        // exactly as it does in a value — so the key is refused here, by position, not quoted.
-        if (key.includes(NUL)) {
-          issues.push({ message: `expected a record key, received one ${NUL_REFUSAL}`, path: at });
+        // A record is stored as `jsonb` far more often than not, and jsonb refuses an unstorable
+        // KEY exactly as it does a value — so the key is refused here, by position, not quoted.
+        const unfitKey = unstorable(key);
+        if (unfitKey !== undefined) {
+          issues.push({ message: `expected a record key, received one ${unfitKey}`, path: at });
           continue;
         }
         if (isPrototypeKey(key)) {
@@ -413,6 +413,8 @@ export interface TNamespace {
   readonly locale: StringSchema;
   readonly slug: StringSchema;
   readonly cursor: StringSchema;
+  /** Any JSON value, bounded in depth — a payload whose shape is somebody else's. */
+  json(): Schema<JsonValue, JsonValue>;
   object<S extends Shape>(shape: S): ObjectSchema<S>;
   array<S extends AnySchema>(items: S): Schema<readonly InferInput<S>[], InferOutput<S>[]>;
   enum<const V extends readonly [string, ...string[]]>(values: V): Schema<V[number], V[number]>;
@@ -453,9 +455,7 @@ export const builtinT: TNamespace = Object.freeze({
   email: makeStringSchema({ kind: 'string', format: 'email' }, 'an email address', (value) =>
     EMAIL_RE.test(value),
   ),
-  url: makeStringSchema({ kind: 'string', format: 'uri' }, 'an absolute URL', (value) =>
-    URL.canParse(value),
-  ),
+  url: makeStringSchema({ kind: 'string', format: 'uri' }, 'an absolute URL', isAbsoluteUrl),
   date: dateSchema,
   money: moneySchema,
   timezone: makeStringSchema(
@@ -469,6 +469,7 @@ export const builtinT: TNamespace = Object.freeze({
     { kind: 'string', format: 'cursor', pattern: CURSOR_RE.source },
     'an opaque base64url cursor',
   ),
+  json: jsonSchema,
   object: objectSchema,
   array: arraySchema,
   enum: enumSchema,