@ultimat3/schema 23.0.0 → 25.0.0

package/CLAUDE.md

@@ -5,7 +5,7 @@ Tier 0. **Imports no `@ultimat3/*` package — not even `@ultimat3/core`.**
 | Rule | |
 |---|---|
 | Deps | none (`bun-types` only) |
-| Errors | `SchemaError` mirrors `UltimateError` field-for-field **and message-for-message** (`code: title — cause`); keep `Symbol.for('ultimate.error')` |
+| Errors | `SchemaError` mirrors `UltimateError` field-for-field **and message-for-message** (`code: title — cause`), `format({ docs })`, `retry` (always `'terminal'`) and a `toJSON().meta` that cannot throw (`render-meta.ts`, core's `renderMetaRecord` restated); keep `Symbol.for('ultimate.error')` |
 | New validator | add to `validators.ts` **and** `TNamespace` **and** `t.ts` **and** `json-schema.ts` |
 | IR | every schema carries `.node: SchemaNode`; generators read that, never the closure |
 | **Issue messages** | the shape of the rejected value, **never its content** — see `describe-value.ts` |
@@ -15,12 +15,14 @@ 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".
-`standard.ts` and `errors.ts` depend on nothing but each other and `error-codes.ts`, a leaf of
+`standard.ts` and `errors.ts` depend on nothing but each other, `render-meta.ts` (which reaches
+`describe-value`) and `error-codes.ts`, a leaf of
 plain data that core imports ALONE so a browser graph never keeps the `SchemaError` classes. `iso-date.ts` imports nothing and
 is imported by `validators.ts` and `coerce.ts` — the two doors a `t.date` string comes through, so
 the rule that a clock time must carry an offset or `Z` has one copy, not one per door.
@@ -58,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
@@ -68,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.
 
@@ -144,7 +148,29 @@ Gotchas:
   22.0.0): `'March 14, 2026'`, `'3/14/2026'` and `'12'` all parsed at the host's LOCAL midnight.
   `iso-date.test.ts` runs the refusal set under two `TZ` values in subprocesses and requires one
   answer. A number (epoch ms) still passes — it names an instant on every host.
-- Adding a `SchemaKind` means updating `json-schema.ts` and `coerce.ts` in the same commit.
+- **`isIsoDateTime` checks the day against the month** (`As of 2026-10`): `new Date('2026-02-30')`
+  answers March 2nd. `DAYS_IN_MONTH` restates `daysInMonth` in `packages/time/src/plain-date.ts`
+  (tier 0 cannot import `time`); the `CALENDAR_PARITY` table in `iso-date.test.ts` and its twin in
+  `packages/time/src/plain-date.test.ts` hold them equal — the `time` copy asks BOTH predicates.
+- **`t.url` is `isAbsoluteUrl` (`absolute-url.ts`), not bare `URL.canParse`**: input the parser
+  would strip (edge spaces / C0 controls, any tab or newline) is refused, since the validator
+  returns the string as written. Not `href === value` — that refuses `https://example.com`.
+  Non-http schemes still pass; narrowing them is an owner call nobody has made.
+- **`isPlainObject` is a PROTOTYPE test** (`Object.prototype` or `null`). A `Map`, a `Date` and a
+  class instance parsed to `{}`. Cost: an object from another realm is refused too.
+- **`.default(v)` runs `v` through the schema at declaration** — `X_SCHEMA_DEFAULT_INVALID`, the
+  sibling of `X_SCHEMA_DEFAULT_UNSHAREABLE`, whose title (cannot be copied) does not state this.
+- **Async is "has a callable `then`"** (`isThenable` in `standard.ts`), never `instanceof Promise`:
+  a non-native thenable read as a result has no `issues`, so it was a success with no value.
+- **`coerceNode` on a union tries every member** and takes the first whose result `fits`
+  (`node-fits.ts`, one level deep, never validation). A string some member takes as a string is
+  returned untouched first, so `number | string` never turns `01234` into 1234. Numerics are
+  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` (`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
@@ -162,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,17 +40,49 @@ 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.
 
 Unknown object keys are **dropped**, never forwarded — an action cannot be mass-assigned.
 
+Refused at the boundary rather than guessed at (`As of 2026-10`):
+
+| Schema | Refuses | Because |
+|---|---|---|
+| `t.date` | a day its month does not have — `2026-02-30`, `2026-04-31`, month `13` | `new Date` rolls it over to March 2nd; `@ultimat3/time`'s `plainDate` already refused it |
+| `t.url` | leading / trailing spaces and C0 controls, a tab or newline anywhere | the URL parser strips them in silence and the validator returns the string as written. Trim before parsing |
+| `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.
 
@@ -75,6 +108,11 @@ extension **and** appended to `description`, which is the only field an LLM read
 is guaranteed to see. `.refine()` returns a plain `Schema`, so refining after `extend`/`pick`/`omit`
 — which rebuild from the shape and would drop the rule — is a type error rather than a comment.
 
+A flagged `.pattern(/^[a-z]+$/i)` keeps its flags the same two ways: JSON Schema's `pattern` has no
+flag syntax (an inline `(?i)` is not ECMA-262), so the projection publishes `pattern` plus an
+`x-ultimate-pattern-flags: 'i'` extension a compiling consumer reads (`@ultimat3/mcp`'s arg
+validator), and states the flags in `description` for a reader.
+
 ### `discriminatedUnion` names the branch it judged
 
 ```ts
@@ -146,8 +184,9 @@ a job boundary the class is gone and the `code` is what survives — match on th
 
 | Class | Code | Declared in |
 |---|---|---|
+| `DefaultInvalidError` (extends `SchemaError`) | `X_SCHEMA_DEFAULT_INVALID` | `src/errors.ts` |
 | `DiscriminantInvalidError` (extends `SchemaError`) | `X_SCHEMA_DISCRIMINANT_INVALID` | `src/errors.ts` |
-| `SchemaError` | any schema code; the base of the three that extend it. Extends `Error`, not core's `UltimateError` — schema imports nothing — and carries the same `Symbol.for('ultimate.error')` brand so `isUltimateError` answers `true` | `src/errors.ts` |
+| `SchemaError` | any schema code; the base of the four that extend it. Extends `Error`, not core's `UltimateError` — schema imports nothing — and carries the same `Symbol.for('ultimate.error')` brand so `isUltimateError` answers `true` | `src/errors.ts` |
 | `SchemaUnsupportedError` (extends `SchemaError`) | `X_SCHEMA_UNSUPPORTED` | `src/errors.ts` |
 | `ValidationFailedError` (extends `SchemaError`) | `X_VALIDATION_FAILED` | `src/errors.ts` |
 
@@ -173,11 +212,18 @@ swap. `introspect()` is what OpenAPI/MCP generation needs; a provider without it
 
 ```ts
 toJsonSchema(publishPost);                    // OpenAPI 3.1 (2020-12)
-toMcpInputSchema(publishPost);                // MCP tools/list (draft-07, no $schema)
+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.
+untouched so validation still produces the real error. It never invents data: only a **decimal**
+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": "23.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/absolute-url.ts

@@ -0,0 +1,20 @@
+// Single responsibility: the one rule deciding whether a string is an absolute URL `t.url` may
+// return as written — parseable, and not a string the parser had to cut before it could read it.
+
+/**
+ * What the URL parser DISCARDS before it reads anything: leading and trailing C0 controls and
+ * spaces, and every tab or newline wherever it sits (WHATWG URL §4.4, the two "validation error"
+ * strips). `URL.canParse` reports none of it, and this validator returns the string it was given —
+ * so `' https://a.b'` validated, was stored untrimmed, and rendered into an `href` as a relative
+ * path. The parsed `href` is only stable for input the parser did not have to cut.
+ *
+ * Deliberately NOT `new URL(value).href === value`: that refuses `https://example.com` (the href
+ * gains a `/`) and any upper-case host, which are the same URL written differently, not a
+ * different string than the one validated.
+ */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: the controls are the rule.
+const URL_PARSER_STRIPS = /^[\u0000-\u0020]|[\u0000-\u0020]$|[\t\n\r]/;
+
+export function isAbsoluteUrl(value: string): boolean {
+  return !URL_PARSER_STRIPS.test(value) && URL.canParse(value);
+}

package/src/builder.ts

@@ -2,12 +2,19 @@
 // that turns a check function plus an IR node into a Standard-Schema-conforming object.
 
 import { describeValue } from './describe-value';
-import { SchemaError, ValidationFailedError, type ValidationIssue } from './errors';
+import {
+  DefaultInvalidError,
+  SchemaError,
+  ValidationFailedError,
+  type ValidationIssue,
+} from './errors';
 import type { SchemaNode, SchemaRefinement } from './node';
 import {
+  formatIssues,
   formatPath,
   type InferInput,
   type InferOutput,
+  isThenable,
   type StandardIssue,
   type StandardResult,
   type StandardSchemaV1,
@@ -43,9 +50,19 @@ export function failWith(issues: readonly StandardIssue[]): CheckErr {
   return { ok: false, issues };
 }
 
-/** An object with own keys — not null, not an array. The gate every object-ish check opens with. */
+/**
+ * A record of own keys: an object literal, or a null-prototype one (what this package's own
+ * object and record parsers answer). The gate every object-ish check opens with.
+ *
+ * The PROTOTYPE is the test, not "an object that is not an array": a `Map`, a `Date` and a class
+ * instance are all that, and each has no own enumerable keys the schema declared — so
+ * `t.record(t.number)` parsed a `Map` of anything to `{}` and an all-optional `t.object` parsed a
+ * `Date` to `{}`, a success carrying none of what was sent.
+ */
 export function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
+  if (typeof value !== 'object' || value === null) return false;
+  const prototype: unknown = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
 }
 
 /**
@@ -146,6 +163,22 @@ function defaultFactory<Out>(fallback: Out): () => Out {
   return () => structuredClone(fallback);
 }
 
+/**
+ * A fallback the schema itself refuses, refused where it is WRITTEN. `t.number.min(5).default(1)`
+ * parsed an omitted field to 1 — a value the same schema rejects when a caller sends it — and
+ * published `minimum: 5, default: 1` to every generated client. Wrong for every parse that omits
+ * the field, so the first import of the authoring file says so, as `defaultFactory` does.
+ */
+function assertDefaultValid<Out>(check: Check<Out>, fallback: Out): void {
+  const result = check(fallback, []);
+  if (result.ok) return;
+  throw new DefaultInvalidError({
+    // The issue text is the RULE (`describeValue` never echoes content), so quoting it is safe.
+    cause: `default() received ${describeValue(fallback)}, which this schema refuses — ${formatIssues(result.issues).join('; ')}`,
+    fix: 'edit the .default(…) named in the stack so its value satisfies the rule quoted in cause, or relax that rule on the schema',
+  });
+}
+
 /** The default declaration, dropped — for a wrapper that can no longer reach it. */
 function withoutDefault(node: SchemaNode): SchemaNode {
   const { hasDefault: _hasDefault, default: _default, ...rest } = node;
@@ -196,6 +229,8 @@ export function makeSchema<In, Out>(node: SchemaNode, check: Check<Out>): Schema
       );
     },
     default(fallback: Out): Schema<In | undefined, Out> {
+      // Rule before copy: a refused fallback has to be replaced, so its clone problem is moot.
+      assertDefaultValid(check, fallback);
       const fresh = defaultFactory(fallback);
       return makeSchema<In | undefined, Out>(
         // The node keeps the DECLARATION, never a copy: `node.default` is what OpenAPI, the MCP
@@ -234,7 +269,7 @@ export function makeSchema<In, Out>(node: SchemaNode, check: Check<Out>): Schema
 export function checkOf<In, Out>(schema: Schema<In, Out>): Check<Out> {
   return (value, path) => {
     const result = schema['~standard'].validate(value);
-    if (result instanceof Promise) {
+    if (isThenable(result)) {
       return fail(path, 'expected a synchronous schema, received an async one');
     }
     if (result.issues === undefined) return pass(result.value);

package/src/coerce.ts

@@ -2,16 +2,29 @@
 // HTTP layer has strings that "mean" numbers. Actions, jobs and MCP calls receive real JSON and
 // must never get this leniency.
 
+import { isPlainObject } from './builder';
 import { isIsoDateTime } from './iso-date';
 import type { SchemaNode } from './node';
+import { fits } from './node-fits';
 import { tryIntrospect } from './provider';
 
 const TRUE_VALUES = new Set(['1', 'true', 'yes', 'on']);
 const FALSE_VALUES = new Set(['0', 'false', 'no', 'off', '']);
 
-/** A numeric string as a number, or `undefined` for anything that is not confidently one. */
-function numeric(raw: unknown): number | undefined {
-  if (typeof raw !== 'string' || raw.trim() === '') return undefined;
+/**
+ * A DECIMAL numeral, and nothing else `Number()` reads: it also takes `0x10`, `0b11` and `0o17`,
+ * so `?page=0x10` arrived as page 16 — a number the caller never wrote in the only notation a
+ * query string, a form field and the published `type: number` have in common.
+ */
+const DECIMAL = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?$/i;
+
+/**
+ * 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;
 }
@@ -38,9 +51,7 @@ export function coerceNode(node: SchemaNode, raw: unknown): unknown {
 
   switch (node.kind) {
     case 'number': {
-      if (typeof raw !== 'string') return raw;
-      const value = Number(raw);
-      return raw.trim() !== '' && Number.isFinite(value) ? value : raw;
+      return numeric(raw) ?? raw;
     }
     case 'boolean':
       return booleanish(raw);
@@ -72,20 +83,23 @@ export function coerceNode(node: SchemaNode, raw: unknown): unknown {
       return itemNode === undefined ? items : items.map((item) => coerceNode(itemNode, item));
     }
     case 'record': {
-      if (typeof raw !== 'object' || node.valueNode === undefined) return raw;
+      if (!isPlainObject(raw) || node.valueNode === undefined) return raw;
       // A null prototype for the reason `recordSchema` uses one: on a `{}` literal, assigning
       // `out['__proto__']` hits the `Object.prototype` SETTER and the key vanishes, so the
       // record validator's deliberate refusal of it never ran — the key was reported absent
       // rather than rejected, on the one path (HTTP query) where it is caller-controlled.
       const out: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
-      for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
+      for (const [key, value] of Object.entries(raw)) {
         out[key] = coerceNode(node.valueNode, value);
       }
       return out;
     }
     case 'object': {
-      if (typeof raw !== 'object' || node.properties === undefined) return raw;
-      const source = raw as Record<string, unknown>;
+      // A plain object or nothing: `{ ...['x'] }` is `{ 0: 'x' }` and `{ ...new Date() }` is `{}`,
+      // so spreading anything else MADE an object the caller never sent — and an all-optional
+      // schema then accepted it. Untouched, validation says "expected an object".
+      if (!isPlainObject(raw) || node.properties === undefined) return raw;
+      const source = raw;
       const out: Record<string, unknown> = { ...source };
       for (const [key, child] of Object.entries(node.properties)) {
         // `Object.hasOwn`, never `key in source`: `{ ...source }` above already dropped what a
@@ -96,8 +110,8 @@ export function coerceNode(node: SchemaNode, raw: unknown): unknown {
       return out;
     }
     case 'money': {
-      if (typeof raw !== 'object') return raw;
-      const source = raw as Record<string, unknown>;
+      if (!isPlainObject(raw)) return raw;
+      const source = raw;
       // Through `numeric` for the same reason `scale` is: `Number('')` is 0, so a blank amount
       // field converted here would reach the validator as a legitimate zero and book an empty
       // price input as free. A blank stays a blank and fails validation, which is the real error.
@@ -110,12 +124,23 @@ export function coerceNode(node: SchemaNode, raw: unknown): unknown {
       return { ...source, minor, ...(scale === undefined ? {} : { scale }) };
     }
     case 'union': {
-      // Only unambiguous single-kind unions (e.g. `number | undefined`) are safe to coerce.
-      const kinds = new Set((node.anyOf ?? []).map((member) => member.kind));
-      if (kinds.size !== 1) return raw;
-      const [member] = node.anyOf ?? [];
-      return member === undefined ? raw : coerceNode(member, raw);
+      const members = node.anyOf ?? [];
+      // A string some member takes AS A STRING is never converted behind its back: under
+      // `number | string` a postcode `01234` must not arrive as 1234.
+      if (typeof raw === 'string' && members.some((member) => fits(member, raw))) return raw;
+      // Every member is tried, in declaration order, and the first whose coercion FITS it wins.
+      // The first member alone used to decide: `'auto' | 2` left `"2"` a string because `'auto'`
+      // needs no conversion, and a union of objects coerced every value by its first branch.
+      for (const member of members) {
+        const coerced = coerceNode(member, raw);
+        if (fits(member, coerced)) return coerced;
+      }
+      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/error-codes.ts

@@ -26,4 +26,5 @@ export const SCHEMA_ERROR_CODES: Readonly<Record<string, SchemaErrorCodeDeclarat
     X_SCHEMA_DEFAULT_UNSHAREABLE: {
       title: 'a schema default cannot be copied per parse',
     },
+    X_SCHEMA_DEFAULT_INVALID: { title: 'a schema default fails its own schema' },
   });

package/src/errors.ts

@@ -1,8 +1,10 @@
 // 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';
 
 /**
@@ -10,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.
  */
@@ -34,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
@@ -78,9 +77,16 @@ export interface SchemaErrorJSON {
   readonly cause: string;
   readonly fix: string;
   readonly docs: string;
+  /** Always present, as on `UltimateErrorJSON` — a client never has to infer it. */
+  readonly retry: 'terminal';
   readonly meta?: Readonly<Record<string, unknown>> | undefined;
 }
 
+export interface SchemaFormatOptions {
+  /** Append a 4th `docs:` line. Off by default, as `UltimateError.format()` has it. */
+  readonly docs?: boolean | undefined;
+}
+
 export class SchemaError extends Error {
   readonly [ULTIMATE_ERROR_BRAND] = true;
   override readonly name: string = 'SchemaError';
@@ -89,6 +95,12 @@ export class SchemaError extends Error {
   declare readonly cause: string;
   readonly fix: string;
   readonly docs: string;
+  /**
+   * `terminal` on every instance: a value that does not match its schema does not match it on
+   * attempt five. Carried HERE as well as in core's retry registry because `errorRetryOf` reads
+   * the field off the error, and a process that never imported core has no registry to ask.
+   */
+  readonly retry = 'terminal' as const;
   readonly meta: Readonly<Record<string, unknown>> | undefined;
 
   constructor(init: SchemaErrorInit) {
@@ -119,10 +131,10 @@ export class SchemaError extends Error {
   }
 
   /** The same 3-line rendering as `UltimateError.format()`, escaped in the same place: neither. */
-  format(): string {
-    return [`${this.code}: ${this.title}`, `  cause: ${this.cause}`, `  fix:   ${this.fix}`].join(
-      '\n',
-    );
+  format(options?: SchemaFormatOptions): string {
+    const lines = [`${this.code}: ${this.title}`, `  cause: ${this.cause}`, `  fix:   ${this.fix}`];
+    if (options?.docs === true) lines.push(`  docs:  ${this.docs}`);
+    return lines.join('\n');
   }
 
   toJSON(): SchemaErrorJSON {
@@ -132,7 +144,10 @@ export class SchemaError extends Error {
       cause: this.cause,
       fix: this.fix,
       docs: this.docs,
-      meta: this.meta,
+      retry: this.retry,
+      // A schema error's `meta` can hold what the caller sent; a `bigint` or a cycle in it threw
+      // here, at `--json` render time, one layer past a constructor that had already succeeded.
+      meta: renderMetaRecord(this.meta),
     };
   }
 }
@@ -185,6 +200,16 @@ export class DiscriminantInvalidError extends SchemaError {
   }
 }
 
+/** Thrown where `.default()` is WRITTEN: a fallback the schema itself refuses is wrong for every parse. */
+export class DefaultInvalidError extends SchemaError {
+  static readonly code = 'X_SCHEMA_DEFAULT_INVALID';
+  override readonly name = 'DefaultInvalidError';
+
+  constructor(init: Omit<SchemaErrorInit, 'code'>) {
+    super({ ...init, code: DefaultInvalidError.code });
+  }
+}
+
 export class SchemaUnsupportedError extends SchemaError {
   static readonly code = 'X_SCHEMA_UNSUPPORTED';
   override readonly name = 'SchemaUnsupportedError';

package/src/index.ts

@@ -22,22 +22,24 @@ 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 {
   SchemaErrorInit,
   SchemaErrorJSON,
+  SchemaFormatOptions,
   ValidationIssue,
 } from './errors';
 export {
+  DefaultInvalidError,
   DiscriminantInvalidError,
   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.
@@ -49,7 +51,9 @@ export type {
   JsonSchemaType,
   ToJsonSchemaOptions,
 } from './json-schema';
-export { nodeToJsonSchema, toJsonSchema, toMcpInputSchema } 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,
@@ -112,3 +116,5 @@ export {
   refineSchema,
   unionSchema,
 } from './validators';
+export type { WireJsonSchema } from './wire-schema';
+export { toWireOutputSchema, toWireSchema } from './wire-schema';