@ultimat3/schema 24.0.0 → 25.0.0

package/CLAUDE.md

@@ -15,8 +15,9 @@ Tier 0. **Imports no `@ultimat3/*` package — not even `@ultimat3/core`.**
 | Re-exports | `action`, `query`, `jobs`, `entity` re-export `t` verbatim so an authoring file imports one package — never let them wrap or copy it |
 
 Module order (no cycles):
-`char-count → describe-value → node → builder → money-value → validators → discriminated-union →
-provider → t`. `char-count.ts` is imported by BOTH `validators.ts` (which rejects on length) and
+`char-count → describe-value → node → builder → money-value → json-value → validators →
+discriminated-union → provider → t` (`node-fits` and `json-schema` read `json-value` too).
+`char-count.ts` is imported by BOTH `validators.ts` (which rejects on length) and
 `describe-value.ts` (which renders the length in the same message), because they disagreed: the
 rule counted code points and the message counted UTF-16 units, so `t.string.min(3)` refused `'👍a'`
 with "at least 3 chars, received a string of 3 characters".
@@ -59,8 +60,8 @@ is the whole edit `As of 2026-08-27`** — the title and its `terminal` retry cl
 derived from this set, where they used to be a hand-kept duplicate in core plus a hand-written
 retry list a fifth code would have been silently missing from.
 
-`ERROR_DOCS_URL` in `errors.ts` is the third deliberate tier-0 duplicate, beside `singleLine` and
-`ULTIMATE_ERROR_BRAND` — one URL, spelled out, because `SchemaError` cannot import
+`ERROR_DOCS_URL` in `errors.ts` is the second deliberate tier-0 duplicate, beside `singleLine` —
+one URL, spelled out, because `SchemaError` cannot import
 `@ultimat3/core`'s constant. There is no per-code URL anywhere in the framework: codes live in
 `wiki/Error-Codes.md` as table ROWS and a table row has no anchor, so
 `https://ultimate.dev/errors/<code>` was a 404 on every error and was deleted `As of 2026-08-23`. Change it
@@ -69,9 +70,11 @@ here and in `packages/core/src/error-codes.ts` in the same edit. **It is pinned
 `UltimateError`'s, which was the one copy with no mechanical check at all and the one that decides
 where every schema refusal sends its reader.
 
-**These three are the whole of the duplication that remains, and the edge does not reach them.**
-`core -> schema` was declared 2026-08-27 and collapsed five copies on the CORE side; `singleLine`,
-`ERROR_DOCS_URL` and `ULTIMATE_ERROR_BRAND` go the other way, and `schema -> core` stays forbidden
+**These two are the whole of the duplication that remains, and the edge does not reach them.**
+`core -> schema` was declared 2026-08-27 and collapsed five copies on the CORE side, and
+`ULTIMATE_ERROR_BRAND` in 25.0.0 — declared HERE once, imported by core's `errors.ts`, because one
+value name has one declaring package (`scripts/factory-names.ts`). `singleLine` and
+`ERROR_DOCS_URL` go the other way, and `schema -> core` stays forbidden
 on its merits — `t` is in every bundle graph an app has, so a dependency here is a dependency
 everywhere.
 
@@ -165,9 +168,9 @@ Gotchas:
   decimal only (`DECIMAL`); `Number()` also reads `0x10`.
 - Adding a `SchemaKind` means updating `json-schema.ts`, `coerce.ts` and `node-fits.ts` in the same commit.
 - **`wire-schema.ts` is the one MCP tool-schema narrowing** (`toWireSchema`, `toWireOutputSchema`,
-  `WireJsonSchema`): `@ultimat3/mcp`'s `tools/list` and `@ultimat3/action`'s `.tool()` both publish
-  through it, so one declaration has one tool document. It lived in `mcp` (tier 4), out of
-  `action`'s reach, and the two documents differed (`format`, output bounds).
+  `WireJsonSchema`): `@ultimat3/mcp`'s `tools/list` (`toolFrom`, the one tool projection
+  since 25.0.0 deleted `.tool()`) publishes through it. It lived in `mcp` (tier 4) while
+  `action` carried a second projection, and the two documents differed (`format`, output bounds).
 - **`ToJsonSchemaOptions.dialect` is a closed vocabulary read with `Object.hasOwn`** (`As of
   2026-09-06`). `DIALECTS[dialect]` on an object literal answered the `Object` FUNCTION for
   `dialect: 'constructor'` — measured: `$schema` held it, `JSON.stringify` dropped the key in
@@ -185,6 +188,13 @@ Gotchas:
   a schema change is not allowed to edit. `refinements` and `discriminant` are both fields for that
   reason: a refined string still reads as a string, and a discriminated union still reads as a
   union, everywhere. `lazy` and `tuple` cannot be — which is why neither has shipped.
+- **`t.json()` is a `SchemaKind`, the one exception to the line above** (`As of 2026-10`):
+  `unknown` means the IR cannot describe a value, `json` that it can — and every foreign
+  `default:` already projects it correctly (`{}`, raw pass-through, a `null` sample, admin's JSON
+  textarea). `JsonValue` in `json-value.ts` is the framework's one declaration; `cli`, `render`,
+  `manifest` and `realtime` still restate it. Its path segments are POSITIONS (the `t.record`
+  rule), shared values are memoised by height so a DAG is linear, and `JSON_MAX_DEPTH` is fixed:
+  a caller-set bound needs a declaration-time refusal code this package does not have yet.
 - A refinement is carried as a **declaration** (`name`, `message`, `path`), never a closure: a
   predicate cannot cross into OpenAPI or an MCP tool schema, and `refine`'s `message` is rendered
   verbatim on both — so it states the rule and never interpolates a value.

package/README.md

@@ -11,6 +11,7 @@ type, a JSON Schema, an OpenAPI body, an MCP tool `inputSchema` and HTTP query c
 | the introspectable IR every generator walks | `node.ts` |
 | `Schema` factory, `Infer` machinery, `.refine()` | `builder.ts` |
 | how a rejected value is described — its shape, never its content | `describe-value.ts` |
+| `JsonValue`, `t.json()` / `jsonSchema()`, `JSON_MAX_DEPTH` | `json-value.ts` |
 | a union routed by one literal key | `discriminated-union.ts` |
 | `configureSchemaProvider()` — the swap point | `provider.ts` |
 | schema → JSON Schema (OpenAPI + MCP) | `json-schema.ts` |
@@ -39,7 +40,7 @@ type PublishPost = Infer<typeof publishPost>;
 | Value schemas | Factories | Methods |
 |---|---|---|
 | `string` `number` `boolean` `date` `uuid` `email` `url` | `object` `array` `enum` `literal` `union` `discriminatedUnion` `record` `optional` `nullable` `refine` | `.default(v)` `.optional()` `.nullable()` `.describe(s)` `.refine(r)` |
-| `money` `timezone` `locale` `slug` `cursor` | `object(...).extend/.pick/.omit` | `string.min/.max/.pattern`, `number.min/.max/.int` |
+| `money` `timezone` `locale` `slug` `cursor` `json()` | `object(...).extend/.pick/.omit` | `string.min/.max/.pattern`, `number.min/.max/.int` |
 
 `nullable` is a value the row holds; `optional` is the caller omitting the key. Both ship as a
 namespace member (`t.nullable`) and a free function (`nullableSchema`) — symmetrically.
@@ -55,10 +56,33 @@ Refused at the boundary rather than guessed at (`As of 2026-10`):
 | `t.object` `t.record` `t.money` | anything whose prototype is not `Object.prototype` or `null` — a `Map`, a `Date`, a class instance | none has the own keys the schema declared, so it parsed to `{}` |
 | `.default(v)` | a `v` the schema itself rejects — `X_SCHEMA_DEFAULT_INVALID`, thrown where it is declared | an omitted field parsed to a value the same schema refuses when sent |
 
+### `t.json()` — a payload whose shape is somebody else's
+
+```ts
+import { t, type Infer, type JsonValue } from '@ultimat3/schema';
+
+export const hook = t.object({ event: t.slug, payload: t.json() });
+export const payload: JsonValue = ({} as Infer<typeof hook>).payload;
+// entity column: json(t.json()) — a jsonb that stores what it was sent
+```
+
+| Accepts | Refuses (with the issue's path) |
+|---|---|
+| `null`, booleans, finite numbers, strings, arrays and plain / null-prototype objects of them, recursively | `undefined` (an array hole too), functions, symbols, bigints, `NaN` / `±Infinity`, a `Date`, a `Map` / `Set` / class instance / typed array, a cycle |
+| every key, `__proto__` and `constructor` included — answered on a null-prototype copy | a NUL or a lone UTF-16 surrogate in a string or a key — Postgres `jsonb` refuses both (measured, PG 17) |
+| at most `JSON_MAX_DEPTH` (256) nested containers | one more: the walk recurses per level, and an unbounded one was a `RangeError` |
+
+A path into a JSON object is the entry's **position** (`payload[2][0]`), never its key — the
+`t.record` rule. A value shared twice is walked once, so a DAG is linear, not exponential. The
+JSON Schema is `{}` with the depth bound in `description`; the bound is fixed — narrow it with
+`.refine()`. Node `kind: 'json'`, distinct from `unknown` ("the IR cannot say").
+
 Every string-backed schema (`string` `uuid` `email` `url` `timezone` `locale` `slug` `cursor`, with
-any `.min/.max/.pattern`) and every `t.record` key **refuses U+0000** — the one character Postgres
-`text` and `jsonb` cannot store, so a NUL that passed reached the row write as a 500. Tabs, newlines
-and the other C0 controls stay legal text. The issue names the fact, never the value:
+any `.min/.max/.pattern`) and every `t.record` key **refuses U+0000 and a lone UTF-16 surrogate** —
+the rule `t.json()` applies, one predicate (`unstorable-text.ts`). Postgres `text` and `jsonb` cannot
+store a NUL, `jsonb` refuses a lone surrogate, and into `text` Bun's sql writes U+FFFD in its place,
+so either reached the row write as a 500 or a silent rewrite. A well-formed pair (an emoji), tabs,
+newlines and the other C0 controls stay legal text. The issue names the fact, never the value:
 `title: expected a non-empty string, received a string of 3 characters that contains a NUL
 character (U+0000)`. Not published in the JSON Schema — it is a storage fact, not a format.
 
@@ -188,16 +212,18 @@ swap. `introspect()` is what OpenAPI/MCP generation needs; a provider without it
 
 ```ts
 toJsonSchema(publishPost);                    // OpenAPI 3.1 (2020-12)
-toWireSchema(publishPost);                    // an MCP tool's inputSchema: what tools/list serves and .tool() returns
+toWireSchema(publishPost);                    // an MCP tool's inputSchema: what tools/list serves
 toWireOutputSchema(publishPost);              // its outputSchema: structure only; undefined for a non-object root
 toJsonSchema(publishPost, { dialect: 'x' });  // X_SCHEMA_UNSUPPORTED — the two spellings are closed
 parse(publishPost, coerceQuery(publishPost, url.searchParams));
+numeric(' 12 ');                              // 12 — numeric('0x10'), numeric(' '): undefined
 ```
 
 Coercion is separate from validation on purpose: only the HTTP layer has strings that mean
 numbers. `coerceQuery` promotes repeated params to arrays and leaves anything ambiguous
 untouched so validation still produces the real error. It never invents data: only a **decimal**
-numeral becomes a number (`0x10` stays text), only a plain object is read as one (an array is never
+numeral becomes a number (`0x10` stays text; `numeric` is that one reader, for a boundary that
+holds a string and no schema node — admin's form decode), only a plain object is read as one (an array is never
 spread into `{ 0: … }`), and a union tries **every** member in declaration order — a string some
 member already accepts is left alone, and a union of objects coerces through the member whose
 literal fields the value carries.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/schema",
-  "version": "24.0.0",
+  "version": "25.0.0",
   "description": "Ultimate's validation seam: Standard Schema interface, the t namespace, JSON Schema output",
   "license": "MIT",
   "type": "module",
@@ -26,7 +26,7 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",

package/src/coerce.ts

@@ -18,8 +18,12 @@ const FALSE_VALUES = new Set(['0', 'false', 'no', 'off', '']);
  */
 const DECIMAL = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?$/i;
 
-/** A numeric string as a number, or `undefined` for anything that is not confidently one. */
-function numeric(raw: unknown): number | undefined {
+/**
+ * A numeric string as a number, or `undefined` for anything that is not confidently one. Exported
+ * for the other string-to-number boundary, admin's form decode: two readers of one posted numeral
+ * would disagree about `0x10`, which is the drift this rule exists to end.
+ */
+export function numeric(raw: unknown): number | undefined {
   if (typeof raw !== 'string' || !DECIMAL.test(raw.trim())) return undefined;
   const value = Number(raw);
   return Number.isFinite(value) ? value : undefined;
@@ -133,6 +137,10 @@ export function coerceNode(node: SchemaNode, raw: unknown): unknown {
       }
       return raw;
     }
+    // Named rather than left to `default`: a query parameter is TEXT, and text is already a JSON
+    // value. Parsing it would make `?q=12` a number for one caller and a string for the next.
+    case 'json':
+      return raw;
     default:
       return raw;
   }

package/src/error-brand.ts

@@ -0,0 +1,10 @@
+// Single responsibility: the ONE brand every framework error carries — `SchemaError` here,
+// `UltimateError` in `@ultimat3/core`, which imports this declaration over the `core -> schema`
+// edge. A leaf of its own for `error-codes.ts`'s reason: core's error contract is in every browser
+// bundle, and importing the brand from `errors.ts` would drag `SchemaError` and its table in too.
+
+/**
+ * Never renamed: the `Symbol.for` key is what a duplicated module instance recognises, so
+ * `isUltimateError()` stays true across two copies of a package in one process.
+ */
+export const ULTIMATE_ERROR_BRAND: unique symbol = Symbol.for('ultimate.error');

package/src/errors.ts

@@ -1,7 +1,8 @@
 // Single responsibility: this package's error codes. `@ultimat3/schema` is tier 0 and may not
 // import `@ultimat3/core`, so `SchemaError` reproduces the `UltimateError` shape structurally
-// and carries the same `Symbol.for('ultimate.error')` brand — `isUltimateError()` still matches.
+// and carries the one brand both classes share (`error-brand.ts`) — `isUltimateError()` matches.
 
+import { ULTIMATE_ERROR_BRAND } from './error-brand';
 import { SCHEMA_ERROR_CODES } from './error-codes';
 import { renderMetaRecord } from './render-meta';
 import { formatIssues } from './standard';
@@ -11,8 +12,8 @@ import { formatIssues } from './standard';
  * there — briefly: the 3-line format is line-oriented, and a `cause` may hold a value the caller
  * chose, so a newline in one writes a line an operator reads as a genuine framework message.
  *
- * Copied rather than imported for the same reason the brand symbol above is: `schema` and `core`
- * are both tier 0, so `schema` may not import `core` (imports go DOWN, never sideways). A schema
+ * Copied rather than imported: `schema` and `core` are both tier 0, and only `core -> schema` is a
+ * declared edge, so `schema` may not import `core`. A schema
  * cause is the one most likely to carry a hostile string — it describes the value that failed
  * validation, which is the request body.
  */
@@ -35,9 +36,6 @@ const singleLine = (text: string): string =>
     (char) => ESCAPES[char] ?? `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`,
   );
 
-/** Same well-known symbol `@ultimat3/core` brands with. Keep in sync, never rename. */
-export const ULTIMATE_ERROR_BRAND: unique symbol = Symbol.for('ultimate.error');
-
 /**
  * The same one URL `@ultimat3/core`'s `ERROR_DOCS_URL` holds. **Keep in sync**, and read the
  * reason there — briefly: `wiki/` is the only public documentation surface, codes live on that

package/src/index.ts

@@ -22,9 +22,10 @@ export { checkOf, fail, failWith, makeSchema, pass, VENDOR } from './builder';
 // not import this package — but `mcp` is tier 4 and can, so a copy there would have no excuse.
 export { charCount } from './char-count';
 export type { QuerySource } from './coerce';
-export { coerceInput, coerceNode, coerceQuery } from './coerce';
+export { coerceInput, coerceNode, coerceQuery, numeric } from './coerce';
 export { describeValue, expected } from './describe-value';
 export { discriminatedUnionSchema } from './discriminated-union';
+export { ULTIMATE_ERROR_BRAND } from './error-brand';
 export type { SchemaErrorCodeDeclaration } from './error-codes';
 export { SCHEMA_ERROR_CODES } from './error-codes';
 export type {
@@ -39,7 +40,6 @@ export {
   isSchemaError,
   SchemaError,
   SchemaUnsupportedError,
-  ULTIMATE_ERROR_BRAND,
   ValidationFailedError,
 } from './errors';
 // Exported for `@ultimat3/time`'s `fromIso`: one ISO-shape rule, whichever door a date comes in by.
@@ -52,6 +52,8 @@ export type {
   ToJsonSchemaOptions,
 } from './json-schema';
 export { nodeToJsonSchema, toJsonSchema } from './json-schema';
+export type { JsonValue } from './json-value';
+export { JSON_MAX_DEPTH, jsonSchema } from './json-value';
 export type { MoneyValue } from './money-value';
 export {
   CURRENCY_CODE_PATTERN,

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';
@@ -158,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);
@@ -282,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({});
   }

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

@@ -2,6 +2,7 @@
 // `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';
 
 /**
@@ -42,6 +43,8 @@ export function fits(node: SchemaNode, value: unknown): boolean {
     }
     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. */

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

@@ -22,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> {
@@ -89,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));
     }
@@ -313,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)) {
@@ -414,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]>;
@@ -468,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,

package/src/wire-schema.ts

@@ -1,6 +1,6 @@
 // Single responsibility: the JSON Schema subset an MCP tool publishes, and the two narrowings onto
-// it — an input's and an output's. One home, tier 0, so `@ultimat3/action`'s `.tool()` and
-// `@ultimat3/mcp`'s `tools/list` publish ONE document for one declaration rather than two.
+// it — an input's and an output's. One home, tier 0: `@ultimat3/mcp`'s `tools/list` is the one
+// tool projection, and no second one may publish a different document for the same declaration.
 
 import type { JsonSchema } from './json-schema';
 import { toMcpInputSchema } from './json-schema';