@ultimat3/schema 22.15.0 → 24.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` |
@@ -20,7 +20,8 @@ provider → t`. `char-count.ts` is imported by BOTH `validators.ts` (which reje
 `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.
@@ -144,7 +145,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` 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).
 - **`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

package/README.md

@@ -46,6 +46,15 @@ namespace member (`t.nullable`) and a free function (`nullableSchema`) — symme
 
 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 |
+
 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
@@ -75,6 +84,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 +160,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 +188,16 @@ 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 and .tool() returns
+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));
 ```
 
 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), 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": "22.15.0",
+  "version": "24.0.0",
   "description": "Ultimate's validation seam: Standard Schema interface, the t namespace, JSON Schema output",
   "license": "MIT",
   "type": "module",
@@ -20,6 +20,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*-fixture.ts",
     "CLAUDE.md",
     "README.md",
     "LICENSE"

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,25 @@
 // 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 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. */
 function numeric(raw: unknown): number | undefined {
-  if (typeof raw !== 'string' || raw.trim() === '') return undefined;
+  if (typeof raw !== 'string' || !DECIMAL.test(raw.trim())) return undefined;
   const value = Number(raw);
   return Number.isFinite(value) ? value : undefined;
 }
@@ -38,9 +47,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 +79,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 +106,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,11 +120,18 @@ 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;
     }
     default:
       return raw;

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

@@ -3,6 +3,7 @@
 // and carries the same `Symbol.for('ultimate.error')` brand — `isUltimateError()` still matches.
 
 import { SCHEMA_ERROR_CODES } from './error-codes';
+import { renderMetaRecord } from './render-meta';
 import { formatIssues } from './standard';
 
 /**
@@ -78,9 +79,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 +97,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 +133,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 +146,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 +202,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

@@ -30,9 +30,11 @@ export { SCHEMA_ERROR_CODES } from './error-codes';
 export type {
   SchemaErrorInit,
   SchemaErrorJSON,
+  SchemaFormatOptions,
   ValidationIssue,
 } from './errors';
 export {
+  DefaultInvalidError,
   DiscriminantInvalidError,
   isSchemaError,
   SchemaError,
@@ -49,7 +51,7 @@ export type {
   JsonSchemaType,
   ToJsonSchemaOptions,
 } from './json-schema';
-export { nodeToJsonSchema, toJsonSchema, toMcpInputSchema } from './json-schema';
+export { nodeToJsonSchema, toJsonSchema } from './json-schema';
 export type { MoneyValue } from './money-value';
 export {
   CURRENCY_CODE_PATTERN,
@@ -112,3 +114,5 @@ export {
   refineSchema,
   unionSchema,
 } from './validators';
+export type { WireJsonSchema } from './wire-schema';
+export { toWireOutputSchema, toWireSchema } from './wire-schema';

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

@@ -34,6 +34,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 +106,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 }),
   };
 }
 
@@ -315,7 +325,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/node-fits.ts

@@ -0,0 +1,48 @@
+// 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 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));
+    default:
+      return false;
+  }
+}

package/src/node.ts

@@ -54,7 +54,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/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,
@@ -453,9 +454,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(

package/src/wire-schema.ts

@@ -0,0 +1,126 @@
+// 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.
+
+import type { JsonSchema } from './json-schema';
+import { toMcpInputSchema } from './json-schema';
+
+/**
+ * The subset a tool's `inputSchema` and `outputSchema` speak, and the one `@ultimat3/mcp`'s
+ * `validateArgs` holds a hand-written tool to. Narrow on purpose: a tool schema an agent cannot
+ * fully understand is a tool it will call wrong.
+ */
+export interface WireJsonSchema {
+  readonly type?: 'object' | 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'null';
+  readonly title?: string;
+  readonly description?: string;
+  readonly properties?: Readonly<Record<string, WireJsonSchema>>;
+  readonly required?: readonly string[];
+  readonly additionalProperties?: boolean;
+  readonly items?: WireJsonSchema;
+  readonly enum?: readonly (string | number | boolean | null)[];
+  readonly const?: string | number | boolean | null;
+  readonly default?: unknown;
+  /**
+   * NOT in the subset: `format` NAMES a rule whose meaning lives in this package (`uuid`, `email`,
+   * `iana-time-zone`), and `validateArgs` cannot hold a hand-written tool to it without a second
+   * definition of each one. `never`, so a narrowing that starts copying it again fails to compile.
+   * `pattern` is the opposite case — the rule travels WITH the schema, so it is kept.
+   */
+  readonly format?: never;
+  readonly minimum?: number;
+  readonly maximum?: number;
+  readonly minLength?: number;
+  readonly maxLength?: number;
+  /** A `RegExp.source`, JSON Schema semantics (a partial match unless it anchors itself). */
+  readonly pattern?: string;
+  /** The flags `pattern` compiles with — JSON Schema's `pattern` carries none. */
+  readonly 'x-ultimate-pattern-flags'?: string;
+  readonly anyOf?: readonly WireJsonSchema[];
+}
+
+/** A Standard Schema → a tool's `inputSchema`. Throws `X_SCHEMA_UNSUPPORTED` when it cannot say. */
+export function toWireSchema(schema: unknown): WireJsonSchema {
+  return narrow(toMcpInputSchema(schema));
+}
+
+/**
+ * A Standard Schema → a tool's `outputSchema`, or `undefined` when its root is not an object (MCP's
+ * `structuredContent` is one) or it cannot be introspected. STRUCTURE ONLY: a client refuses a call
+ * whose `structuredContent` misses this document, and a bound, a pattern or `additionalProperties:
+ * false` on a value the server produced (a query's rows are never re-parsed) is a promise nothing
+ * enforces on the way out.
+ */
+export function toWireOutputSchema(schema: unknown): WireJsonSchema | undefined {
+  let rich: JsonSchema;
+  try {
+    rich = toMcpInputSchema(schema);
+  } catch {
+    return undefined;
+  }
+  return rich.type === 'object' ? shape(rich) : undefined;
+}
+
+// exactOptionalPropertyTypes: every field is attached only when present, never as an explicit
+// `undefined` — `tools/list` serialises this object verbatim.
+function narrow(source: JsonSchema): WireJsonSchema {
+  return {
+    ...(source.type === undefined ? {} : { type: source.type }),
+    ...(source.title === undefined ? {} : { title: source.title }),
+    ...(source.description === undefined ? {} : { description: source.description }),
+    ...(source.properties === undefined ? {} : { properties: mapKeys(source.properties, narrow) }),
+    ...(source.required === undefined ? {} : { required: source.required }),
+    // The subset says yes or no to extra keys; an unrepresentable value schema becomes `true`
+    // (permit) rather than a rejection the agent was never warned about.
+    ...(source.additionalProperties === undefined
+      ? {}
+      : { additionalProperties: source.additionalProperties !== false }),
+    ...(source.items === undefined ? {} : { items: narrow(source.items) }),
+    ...(source.enum === undefined ? {} : { enum: source.enum }),
+    ...(source.const === undefined ? {} : { const: source.const }),
+    ...(source.default === undefined ? {} : { default: source.default }),
+    ...(source.minimum === undefined ? {} : { minimum: source.minimum }),
+    ...(source.maximum === undefined ? {} : { maximum: source.maximum }),
+    ...(source.minLength === undefined ? {} : { minLength: source.minLength }),
+    ...(source.maxLength === undefined ? {} : { maxLength: source.maxLength }),
+    ...(source.pattern === undefined ? {} : { pattern: source.pattern }),
+    ...(source['x-ultimate-pattern-flags'] === undefined
+      ? {}
+      : { 'x-ultimate-pattern-flags': source['x-ultimate-pattern-flags'] }),
+    ...(source.anyOf === undefined ? {} : { anyOf: source.anyOf.map(narrow) }),
+  };
+}
+
+function shape(source: JsonSchema): WireJsonSchema {
+  return {
+    ...(source.type === undefined ? {} : { type: source.type }),
+    ...(source.title === undefined ? {} : { title: source.title }),
+    ...(source.description === undefined ? {} : { description: source.description }),
+    ...(source.properties === undefined ? {} : { properties: mapKeys(source.properties, shape) }),
+    ...(source.required === undefined ? {} : { required: source.required }),
+    ...(source.items === undefined ? {} : { items: shape(source.items) }),
+    ...(source.enum === undefined ? {} : { enum: source.enum }),
+    ...(source.const === undefined ? {} : { const: source.const }),
+    ...(source.anyOf === undefined ? {} : { anyOf: source.anyOf.map(shape) }),
+  };
+}
+
+/**
+ * `out[key] = …` is not an assignment for exactly one name: `__proto__` runs `Object.prototype`'s
+ * setter and RE-PROTOTYPES the record, so a declared field vanishes from `tools/list`.
+ */
+function mapKeys(
+  properties: Readonly<Record<string, JsonSchema>>,
+  each: (child: JsonSchema) => WireJsonSchema,
+): Readonly<Record<string, WireJsonSchema>> {
+  const out: Record<string, WireJsonSchema> = {};
+  for (const [key, child] of Object.entries(properties)) {
+    Object.defineProperty(out, key, {
+      value: each(child),
+      writable: true,
+      enumerable: true,
+      configurable: true,
+    });
+  }
+  return out;
+}