@ultimat3/schema 1.2.0 → 2.0.0

package/CLAUDE.md

@@ -0,0 +1,90 @@
+# @ultimat3/schema — agent notes
+
+Tier 0. **Imports no `@ultimat3/*` package — not even `@ultimat3/core`.**
+
+| Rule | |
+|---|---|
+| Deps | none (`bun-types` only) |
+| Errors | `SchemaError` mirrors `UltimateError` field-for-field; 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` |
+| Coercion | HTTP boundary only — never call it from actions, jobs or MCP |
+| Exports | explicit in `src/index.ts`; no `export *`; a namespace member and its free function ship together (`t.nullable`/`nullableSchema`) |
+| 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):
+`describe-value → node → builder → money-value → validators → discriminated-union → provider → t`.
+`standard.ts` and `errors.ts` depend on nothing but each other.
+
+**An issue message is a public surface.** `@ultimat3/http` folds it into `X_BODY_INVALID`'s `cause`,
+which is returned to the caller AND interpolated into the log line — and core's logger redacts by
+KEY, so a value baked into a string has no key left to redact. `'password'` being in `redactedKeys`
+did not help: `expected(…, value)` had already written `received "hunter2"` before the logger saw
+it. Every rejected value goes through `describeValue`, which reports length and type and nothing
+else. No dev flag re-enables the echo — one misconfigured environment is the same breach, and a dev
+overlay already holds the raw body. `describe-value.test.ts` is the enforcement.
+
+`X_SCHEMA_DISCRIMINANT_INVALID` is thrown where a `discriminatedUnion` is BUILT, not where a value
+is parsed. A member with no literal at the discriminant, or a second member claiming a tag the
+first already owns, can never be routed to — so it is wrong for every input, and the first import
+of the authoring file is the earliest honest place to say so.
+
+`SCHEMA_ERROR_CODES` in `errors.ts` is data, not a `registerErrorCodes()` call — this package is
+tier 0 and cannot import `@ultimat3/core` to reach it. `@ultimat3/core`'s `schema-error-codes.ts`
+carries a duplicate of these titles and registers them unconditionally, so every process gets the
+real titles just by importing core. Add a code here **and** update that duplicate in the same
+change — `schema-error-codes-pin.test.ts` in `@ultimat3/cli` fails the build if they disagree.
+
+`MoneyValue` in `money-value.ts` — its own file, because it is the only builtin whose *shape* other
+packages alias — is the framework's **one** declaration of a money value. Tier 0 is
+the only tier every package may import, and `@ultimat3/money`'s `Money` and `@ultimat3/entity`'s
+`MoneyValue` are aliases of it. Never let either restate the shape: it was three structural copies,
+entity's had a `bigint` `minor`, and a row that layer decoded then failed both `t.money` and
+`JSON.stringify`. `minor` stays a `number` for the same reason it is a `number` here — this node is
+the OpenAPI contract, and money crosses every wire the framework projects.
+
+`MoneyValue.scale` is the **optional** decimal exponent `minor` counts in, `0…MAX_MONEY_SCALE`
+(15, the last power of ten that is itself a safe integer). Absent means the currency's own minor
+unit, which is every value that predates it — so `{ minor, currency }` parses to exactly
+`{ minor, currency }`, key for key, and the validator adds nothing. What a legal scale is lives in
+`isMoneyScale` here and nowhere else; `@ultimat3/money` imports it rather than restating the
+bound. Adding it to the type means adding it in three more places in the same change — the node's
+`properties`, `json-schema.ts` (optional, never `required`, or a generated client refuses a value
+this validator accepts) and `coerce.ts` (a query string carries it as text like everything else).
+
+`MoneyValue.currency` is bounded by `isCurrencyCode`, `isMoneyScale`'s twin, over
+`CURRENCY_CODE_PATTERN` — the pattern **source**, exported because the two projections that cannot
+call a predicate need the string: `json-schema.ts`'s published `pattern` and `@ultimat3/entity`'s
+Postgres `~` CHECK (`currencyCheck`). It was four copies of `^[A-Z]{3}$` across three packages,
+each individually correct, and only a psql session would have seen them diverge. Keep the pattern
+inside the syntax ECMAScript, JSON Schema and POSIX ERE spell identically — anchors, a literal
+class, a bounded repetition. `@ultimat3/entity`'s `currency-check.live.test.ts` is what proves a
+real server still reads it the way the predicate does; a `\d` or a lookahead is where that stops.
+
+`t` delegates through `schemaProvider()` on every property access — that is what makes
+`configureSchemaProvider()` work for modules that already imported `t`. Do not cache members.
+
+```bash
+bun test                      # from packages/schema
+bun run typecheck
+```
+
+Gotchas:
+- `Schema<In, Out>` splits input from output: `.default()` makes the key optional on input and
+  present on output. Object key optionality is derived from that — don't hand-roll it.
+- `AnySchema = Schema<unknown, unknown>` is the general constraint. Never `any`.
+- Unknown object keys are dropped by design; JSON Schema says `additionalProperties: false`.
+- Adding a `SchemaKind` means updating `json-schema.ts` and `coerce.ts` in the same commit.
+- **Prefer a new `SchemaNode` FIELD to a new `SchemaKind`.** Every consumer that switches on `kind`
+  has a `default:` that degrades quietly — `json-schema.ts` emits `{}`, `coerce.ts` passes the raw
+  value through, `@ultimat3/action`'s `sample-input.ts` answers `null` — and they live in packages
+  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.
+- 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.
+- `@ultimat3/action`'s `sampleInput` does not read `refinements`, so a contract test over a refined
+  schema reports `X_CONTRACT_DRIFT` exactly as it already does for a bare `pattern`. Documented
+  there; fixing it is that package's change, not this one's.

package/README.md

@@ -9,7 +9,9 @@ type, a JSON Schema, an OpenAPI body, an MCP tool `inputSchema` and HTTP query c
 | the blessed `t` namespace | `t.ts` |
 | builtin validators behind `t` | `validators.ts` |
 | the introspectable IR every generator walks | `node.ts` |
-| `Schema` factory, `Infer` machinery | `builder.ts` |
+| `Schema` factory, `Infer` machinery, `.refine()` | `builder.ts` |
+| how a rejected value is described — its shape, never its content | `describe-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` |
 | HTTP-boundary coercion, kept out of validation | `coerce.ts` |
@@ -26,6 +28,7 @@ export const publishPost = t.object({
   title:    t.string.min(3).max(80),
   tags:     t.array(t.slug),
   price:    t.money,                 // { minor: 1999, currency: 'EUR' } — never a float
+                                     // { minor: 2, currency: 'USD', scale: 6 } is $0.000002
   timeZone: t.timezone,              // real IANA validation, not an annotation
   cursor:   t.optional(t.cursor),
 });
@@ -35,7 +38,7 @@ type PublishPost = Infer<typeof publishPost>;
 
 | Value schemas | Factories | Methods |
 |---|---|---|
-| `string` `number` `boolean` `date` `uuid` `email` `url` | `object` `array` `enum` `literal` `union` `record` `optional` `nullable` | `.default(v)` `.optional()` `.nullable()` `.describe(s)` |
+| `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` |
 
 `nullable` is a value the row holds; `optional` is the caller omitting the key. Both ship as a
@@ -43,6 +46,46 @@ namespace member (`t.nullable`) and a free function (`nullableSchema`) — symme
 
 Unknown object keys are **dropped**, never forwarded — an action cannot be mass-assigned.
 
+### Cross-field rules live on the schema
+
+A rule the IR cannot state structurally still belongs to the schema, or it moves into a handler and
+disappears from `openapi.json`, the MCP tool schema, the typed client and every form binding at
+once — axiom 2 broken for every such rule in the product.
+
+```ts
+const booking = t.object({ startDate: t.date, endDate: t.date }).refine({
+  name: 'end-after-start',                       // stable id → `x-ultimate-refinements`
+  message: 'endDate must be after startDate',    // the rule, never the value
+  path: ['endDate'],                             // which field the issue lands on
+  check: (value) => value.endDate > value.startDate,
+});
+```
+
+The predicate runs on the **parsed** output and only after the shape passed, so it compares coerced
+values and never defends against a type the schema already refused. What ships in the IR is the
+declaration, not the closure: `node.refinements`, projected as an `x-ultimate-refinements`
+extension **and** appended to `description`, which is the only field an LLM reading a tool schema
+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.
+
+### `discriminatedUnion` names the branch it judged
+
+```ts
+const body = t.discriminatedUnion(
+  'kind',
+  t.object({ kind: t.literal('post'), slug: t.slug }),
+  t.object({ kind: t.literal('page'), title: t.string.min(3) }),
+);
+```
+
+`t.union` reports every member's reasons at once, so one bad field in a `post` body arrives as N
+contradictory complaints naming fields the caller never sent. This routes on `kind` first and
+reports that branch's issues only. A member with no literal (or enum) at the discriminant, or two
+members claiming one tag, is `X_SCHEMA_DISCRIMINANT_INVALID` **where the union is built** — a
+branch nothing can route to is wrong for every input, not for one request. The node stays
+`kind: 'union'` with a `discriminant` beside it, so every existing IR consumer keeps working, and
+JSON Schema gains `discriminator: { propertyName }`.
+
 **You rarely import this package.** `action`, `query`, `jobs` and `entity` each re-export the same
 `t`, so an authoring file imports its primitive and nothing else. Import `@ultimat3/schema` directly
 only where there is no primitive to hang the schema off — app config, a standalone view schema, a
@@ -56,10 +99,18 @@ parse(t.object({ postId: t.uuid, notify: t.boolean }), { postId: 'abc', notify:
 
 ```text
 X_VALIDATION_FAILED: value did not match its schema
-  cause: postId: expected a uuid, received "abc"; notify: expected a boolean, received "yes"
+  cause: postId: expected a uuid, received a string of 3 characters; notify: expected a boolean, received a string of 3 characters
   fix:   send input with the field(s) named in cause corrected to the expected type
 ```
 
+**An issue message names the shape of the rejected value, never its content**, and `received` on
+the issue is empty for the same reason. `@ultimat3/http` folds these messages into
+`X_BODY_INVALID`'s `cause`, which is returned to the caller *and* written to the log line — where
+the logger redacts by key and a value baked into a string has no key left to redact. Echoing the
+value meant a password-strength rule wrote every mistyped password to the central log index in
+cleartext. There is no dev-only escape hatch: a flag is one misconfigured environment away from
+being the same breach. `describe-value.ts` owns the rule and `describe-value.test.ts` enforces it.
+
 `error.issues` is `{ path, expected, received, message }[]` with paths like `items[0].price`;
 `formatIssues()` renders one line per issue for the dev overlay. `validate()` never throws and
 returns the Standard Schema result. Async libraries: `parseAsync()` / `validateAsync()`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/schema",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "description": "Ultimate's validation seam: Standard Schema interface, the t namespace, JSON Schema output",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "CLAUDE.md",
     "README.md",
     "LICENSE"
   ],

package/src/builder.ts

@@ -1,8 +1,9 @@
 // Single responsibility: the `Schema` type every builtin validator returns, and the factory
 // that turns a check function plus an IR node into a Standard-Schema-conforming object.
 
-import { ValidationFailedError, type ValidationIssue } from './errors';
-import type { SchemaNode } from './node';
+import { describeValue } from './describe-value';
+import { SchemaError, ValidationFailedError, type ValidationIssue } from './errors';
+import type { SchemaNode, SchemaRefinement } from './node';
 import {
   formatPath,
   type InferInput,
@@ -42,21 +43,28 @@ export function failWith(issues: readonly StandardIssue[]): CheckErr {
   return { ok: false, issues };
 }
 
-/** `expected uuid, received "abc"` — the message an agent can act on without guessing. */
-export function expected(what: string, value: unknown): string {
-  return `expected ${what}, received ${describeValue(value)}`;
+/** An object with own keys — not null, not an array. The gate every object-ish check opens with. */
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
-export function describeValue(value: unknown): string {
-  if (value === undefined) return 'undefined';
-  if (value === null) return 'null';
-  if (typeof value === 'string') return JSON.stringify(value);
-  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
-  if (Array.isArray(value)) return `array(${value.length})`;
-  if (value instanceof Date) {
-    return Number.isNaN(value.getTime()) ? 'Date(Invalid Date)' : `Date(${value.toISOString()})`;
-  }
-  return typeof value;
+/**
+ * A rule the IR cannot state structurally — `endDate > startDate`, `total === sum(lines)`. It
+ * lives on the schema rather than in a handler so it reaches OpenAPI, the MCP tool schema, the
+ * typed client and the form binding from the one declaration, like every other constraint.
+ *
+ * `message` is authored by the developer and rendered verbatim, so it must state the RULE and
+ * never the value — see `describe-value.ts` for why an issue message is a public surface.
+ */
+export interface Refinement<Out> {
+  /** Stable machine id, kebab-case: `end-after-start`. Projected as `x-ultimate-refinements`. */
+  readonly name: string;
+  /** The rule as a sentence, e.g. `endDate must be after startDate`. Never interpolate a value. */
+  readonly message: string;
+  /** Runs on the PARSED output, so a cross-field rule compares coerced values, not raw input. */
+  readonly check: (value: Out) => boolean;
+  /** Which field the issue is reported against. Absent reports it against the object itself. */
+  readonly path?: readonly string[] | undefined;
 }
 
 export interface Schema<In = unknown, Out = In> extends StandardSchemaV1<In, Out> {
@@ -73,6 +81,12 @@ export interface Schema<In = unknown, Out = In> extends StandardSchemaV1<In, Out
   nullable(): Schema<In | null, Out | null>;
   default(value: Out): Schema<In | undefined, Out>;
   describe(description: string): Schema<In, Out>;
+  /**
+   * Attach a cross-field rule. Returns a plain `Schema` on purpose — `extend`/`pick`/`omit`
+   * rebuild from the shape and would silently drop the refinement, so refining last is a type
+   * error to get wrong rather than a comment asking you not to.
+   */
+  refine(refinement: Refinement<Out>): Schema<In, Out>;
 }
 
 /** The general constraint for "some schema". Methods are bivariant, so this is a real supertype. */
@@ -102,6 +116,42 @@ export type ShapeInput<S extends Shape> = Simplify<
   }
 >;
 
+/**
+ * One FRESH copy of a default per parse. `.default([])` handed every parse the same array, so a
+ * handler pushing onto it made that push the next request's starting value for the life of the
+ * process — cross-request data bleed declared in a schema.
+ *
+ * Primitives are immutable, so they are still shared and cost nothing. Everything else is decided
+ * ONCE, here at declaration: a value `structuredClone` can copy is copied per parse, and one it
+ * cannot is refused at the first import of the authoring file — the same "wrong for every input,
+ * so say so where it is written" rule `X_SCHEMA_DISCRIMINANT_INVALID` follows. What that refuses
+ * was never a working declaration: `node.default` is published as JSON, so a default carrying a
+ * function or a symbol could not reach OpenAPI either.
+ *
+ * Known narrow cost: a class instance clones to a plain object, so a default that relied on its
+ * prototype loses it. Schema defaults are wire values, which is the only thing `node.default` can
+ * publish, so that shape was already outside what a default may mean.
+ */
+function defaultFactory<Out>(fallback: Out): () => Out {
+  if (fallback === null || typeof fallback !== 'object') return () => fallback;
+  try {
+    structuredClone(fallback);
+  } catch {
+    throw new SchemaError({
+      code: 'X_SCHEMA_DEFAULT_UNSHAREABLE',
+      cause: `default() received ${describeValue(fallback)}, which structuredClone cannot copy`,
+      fix: 'pass a JSON-shaped default (plain object, array, Date, Map, Set), or drop .default() and answer the absent value in the handler',
+    });
+  }
+  return () => structuredClone(fallback);
+}
+
+/** 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;
+  return rest;
+}
+
 function toIssues(result: CheckErr): readonly ValidationIssue[] {
   return result.issues.map((issue) => ({
     path: formatPath(issue.path),
@@ -133,7 +183,10 @@ export function makeSchema<In, Out>(node: SchemaNode, check: Check<Out>): Schema
     },
     optional(): Schema<In | undefined, Out | undefined> {
       return makeSchema<In | undefined, Out | undefined>(
-        { ...node, optional: true },
+        // `.default(x).optional()` published `default: x` while `parse` answered `undefined`:
+        // this wrapper short-circuits `undefined` before the default is ever reached, so a client
+        // honouring the published default assumed a value the server never produced.
+        withoutDefault({ ...node, optional: true }),
         (value, path) => (value === undefined ? pass(undefined) : check(value, path)),
       );
     },
@@ -143,14 +196,36 @@ export function makeSchema<In, Out>(node: SchemaNode, check: Check<Out>): Schema
       );
     },
     default(fallback: Out): Schema<In | undefined, Out> {
+      const fresh = defaultFactory(fallback);
       return makeSchema<In | undefined, Out>(
+        // The node keeps the DECLARATION, never a copy: `node.default` is what OpenAPI, the MCP
+        // tool schema and the typed client publish, and they describe what was written.
         { ...node, hasDefault: true, default: fallback },
-        (value, path) => (value === undefined ? pass(fallback) : check(value, path)),
+        (value, path) => (value === undefined ? pass(fresh()) : check(value, path)),
       );
     },
     describe(description: string): Schema<In, Out> {
       return makeSchema<In, Out>({ ...node, description }, check);
     },
+    refine(refinement: Refinement<Out>): Schema<In, Out> {
+      const declared: SchemaRefinement = {
+        name: refinement.name,
+        message: refinement.message,
+        ...(refinement.path === undefined ? {} : { path: [...refinement.path] }),
+      };
+      return makeSchema<In, Out>(
+        { ...node, refinements: [...(node.refinements ?? []), declared] },
+        (value, path) => {
+          // Shape first: a predicate written against `Out` must never be handed an unparsed
+          // value, or every refinement grows a defensive typeof the schema already performed.
+          const result = check(value, path);
+          if (!result.ok) return result;
+          return refinement.check(result.value)
+            ? result
+            : fail([...path, ...(refinement.path ?? [])], refinement.message);
+        },
+      );
+    },
   };
   return schema;
 }

package/src/coerce.ts

@@ -8,6 +8,22 @@ 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;
+  const value = Number(raw);
+  return Number.isFinite(value) ? value : undefined;
+}
+
+/** A truthy/falsy query-string spelling as a boolean, or the raw value when it is neither. */
+function booleanish(raw: unknown): unknown {
+  if (typeof raw !== 'string') return raw;
+  const lowered = raw.toLowerCase();
+  if (TRUE_VALUES.has(lowered)) return true;
+  if (FALSE_VALUES.has(lowered)) return false;
+  return raw;
+}
+
 export type QuerySource =
   | URLSearchParams
   | Readonly<Record<string, string | readonly string[] | undefined>>;
@@ -25,11 +41,17 @@ export function coerceNode(node: SchemaNode, raw: unknown): unknown {
       const value = Number(raw);
       return raw.trim() !== '' && Number.isFinite(value) ? value : raw;
     }
-    case 'boolean': {
+    case 'boolean':
+      return booleanish(raw);
+    case 'literal': {
+      // Toward the literal's OWN type, because `literalSchema` compares with `===`: without this
+      // a numeric or boolean `t.literal` was unsatisfiable over its own GET route — `t.literal(2)`
+      // received `"2"` and the endpoint 400d on every request — while the identical declaration
+      // worked over an action's JSON body and over MCP. A string literal needs nothing, which is
+      // exactly why the gap read as arbitrary.
       if (typeof raw !== 'string') return raw;
-      const lowered = raw.toLowerCase();
-      if (TRUE_VALUES.has(lowered)) return true;
-      if (FALSE_VALUES.has(lowered)) return false;
+      if (typeof node.literal === 'number') return numeric(raw) ?? raw;
+      if (typeof node.literal === 'boolean') return booleanish(raw);
       return raw;
     }
     case 'date': {
@@ -44,7 +66,11 @@ export function coerceNode(node: SchemaNode, raw: unknown): unknown {
     }
     case 'record': {
       if (typeof raw !== 'object' || node.valueNode === undefined) return raw;
-      const out: Record<string, unknown> = {};
+      // 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>)) {
         out[key] = coerceNode(node.valueNode, value);
       }
@@ -62,8 +88,16 @@ export function coerceNode(node: SchemaNode, raw: unknown): unknown {
     case 'money': {
       if (typeof raw !== 'object') return raw;
       const source = raw as Record<string, unknown>;
-      const minor = typeof source['minor'] === 'string' ? Number(source['minor']) : source['minor'];
-      return Number.isFinite(minor) ? { ...source, minor } : 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.
+      const rawMinor = source['minor'];
+      const minor = typeof rawMinor === 'string' ? numeric(rawMinor) : rawMinor;
+      if (typeof minor !== 'number' || !Number.isFinite(minor)) return raw;
+      // `scale` arrives as text from a query string exactly as `minor` does. Left a string it
+      // would fail validation on a value whose `minor` the same request just had converted.
+      const scale = numeric(source['scale']);
+      return { ...source, minor, ...(scale === undefined ? {} : { scale }) };
     }
     case 'union': {
       // Only unambiguous single-kind unions (e.g. `number | undefined`) are safe to coerce.

package/src/describe-value.ts

@@ -0,0 +1,71 @@
+// Single responsibility: render a REJECTED value as its shape, and the `expected X, received Y`
+// line every builtin validator fails with. Its whole job is the rule in `describeValue`'s doc
+// comment — the rejected value's content never appears in an issue message. Its own file so that
+// rule has one place to live and one test file to enforce it.
+
+/**
+ * The shape of a rejected value — **never its content**.
+ *
+ * WHY: an issue message is not a private diagnostic. `@ultimat3/http` folds these messages into
+ * `X_BODY_INVALID`'s `cause`, which is returned to the caller AND written to the log line; the
+ * logger redacts `fields`/`contextFields` by key, and a value baked into a message string has no
+ * key left to redact. Echoing the value meant a signup form with a password-strength rule wrote
+ * every mistyped password to the central log index in cleartext (30-day retention) and into the
+ * user's own network tab — same for a card number, an SSN, or an API key pasted in the wrong box.
+ *
+ * So: length and type, which is what a min/max/type violation actually needs, and nothing else.
+ * There is no dev-only escape hatch on purpose — a flag is one misconfigured environment away
+ * from being the same breach, and a dev overlay already holds the raw request body.
+ *
+ * Constants are exempt only where they carry no caller data: `undefined`, `null`, `NaN` and the
+ * infinities name themselves because "received a number" for a `NaN` reads as a lie.
+ */
+export function describeValue(value: unknown): string {
+  if (value === undefined) return 'undefined';
+  if (value === null) return 'null';
+  switch (typeof value) {
+    case 'string':
+      // Code units, not code points: the length checks in `validators.ts` use `.length` too, so a
+      // message quoting a different count than the rule that rejected it would send an agent
+      // chasing an off-by-one that is not there.
+      return countOf(value.length, 'string', 'character');
+    case 'number':
+      return describeNumber(value);
+    case 'boolean':
+      return 'a boolean';
+    case 'bigint':
+      return 'a bigint';
+    case 'symbol':
+      return 'a symbol';
+    case 'function':
+      return 'a function';
+    default:
+      break;
+  }
+  if (Array.isArray(value)) return countOf(value.length, 'array', 'item');
+  // `getTime()` rather than a value: an invalid Date is the one Date fact a caller can act on.
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? 'an invalid Date' : 'a Date';
+  return 'an object';
+}
+
+function describeNumber(value: number): string {
+  if (Number.isNaN(value)) return 'NaN';
+  if (value === Number.POSITIVE_INFINITY) return 'Infinity';
+  if (value === Number.NEGATIVE_INFINITY) return '-Infinity';
+  return 'a number';
+}
+
+function countOf(size: number, noun: string, unit: string): string {
+  if (size === 0) return `an empty ${noun}`;
+  const article = noun === 'array' ? 'an' : 'a';
+  return `${article} ${noun} of ${size} ${unit}${size === 1 ? '' : 's'}`;
+}
+
+/**
+ * `expected a uuid, received a string of 3 characters` — the message an agent can act on without
+ * guessing, and without the value ever leaving the process. `what` is authored by the schema, so
+ * it may say anything; the second half is `describeValue` and may not.
+ */
+export function expected(what: string, value: unknown): string {
+  return `expected ${what}, received ${describeValue(value)}`;
+}

package/src/discriminated-union.ts

@@ -0,0 +1,117 @@
+// Single responsibility: a union that dispatches on one literal key instead of trying every
+// member. Its own file because the dispatch table and its two authoring refusals are the whole of
+// it, and `validators.ts` is already at the size where one more composite stops being readable.
+
+import {
+  type AnySchema,
+  type Check,
+  checkOf,
+  fail,
+  isPlainObject,
+  makeSchema,
+  type Schema,
+} from './builder';
+import { expected } from './describe-value';
+import { DiscriminantInvalidError } from './errors';
+import type { SchemaNode } from './node';
+import type { InferInput, InferOutput } from './standard';
+
+/**
+ * What a tag can be — exactly what `SchemaNode.literal` and `SchemaNode.values` can hold. Spelled
+ * out rather than left `unknown` because these reach a `cause:` through `String()`, and a value an
+ * app controls reaching a refusal's own text is how three constructors learned to throw instead
+ * of refusing (`bun run error-render`).
+ */
+type SchemaTag = string | number | boolean | null | undefined;
+
+/** The literal(s) a member declares at the discriminant, or `undefined` if it declares none. */
+function declaredValues(node: SchemaNode, discriminant: string): readonly SchemaTag[] | undefined {
+  const child = node.properties?.[discriminant];
+  if (child === undefined) return undefined;
+  // `kind` gates rather than `literal !== undefined`: `t.literal(false)` is a legal discriminant
+  // and a truthiness test would have called it undeclared.
+  if (child.kind === 'literal') return [child.literal];
+  // An enum member is a legal discriminant too — one branch owning several codes is a real shape
+  // (`status: t.enum(['queued', 'running'])`), and refusing it would force a duplicated branch.
+  if (child.kind === 'enum' && child.values !== undefined && child.values.length > 0) {
+    return [...child.values];
+  }
+  return undefined;
+}
+
+function refuseUndeclared(discriminant: string, index: number, kind: string): never {
+  throw new DiscriminantInvalidError({
+    cause: `member #${index} of discriminatedUnion("${discriminant}") — IR kind "${kind}" — declares no literal at "${discriminant}"`,
+    fix: `give member #${index} a literal discriminant, t.object({ ${discriminant}: t.literal('…'), … }), or use t.union(...) if the members share no key`,
+    meta: { discriminant, index, kind },
+  });
+}
+
+function refuseDuplicate(discriminant: string, index: number, tag: SchemaTag): never {
+  throw new DiscriminantInvalidError({
+    cause: `member #${index} of discriminatedUnion("${discriminant}") claims the tag ${String(tag)}, which an earlier member already claims`,
+    fix: `give member #${index} its own value at "${discriminant}", or merge the two members into one`,
+    meta: { discriminant, index, tag: String(tag) },
+  });
+}
+
+/** `post | page | 2 | false` — every accepted tag, in declaration order. Developer data only. */
+function renderKnown(known: readonly SchemaTag[]): string {
+  return known.map((value) => String(value)).join(' | ');
+}
+
+/**
+ * A union whose branch is chosen by one key, not by trying every member in turn.
+ *
+ * Two things `t.union(...)` cannot do. The message: a failure reports the branch the discriminant
+ * NAMED — `t.union` reports every branch's reasons at once, so a typo in a `post` body arrived as
+ * N contradictory complaints and the field that was actually wrong was named in none of them. The
+ * IR: `discriminator.propertyName` reaches OpenAPI and the MCP tool schema, so a code generator
+ * emits one tagged type instead of an untagged `anyOf`.
+ *
+ * The node stays `kind: 'union'` with a `discriminant` beside it — see `node.ts` for why a new
+ * `SchemaKind` would have degraded silently in every consumer that already handles unions.
+ */
+export function discriminatedUnionSchema<S extends readonly [AnySchema, ...AnySchema[]]>(
+  discriminant: string,
+  ...members: S
+): Schema<InferInput<S[number]>, InferOutput<S[number]>> {
+  type Out = InferOutput<S[number]>;
+  const branches = new Map<unknown, Check<Out>>();
+  const known: SchemaTag[] = [];
+
+  for (const [index, member] of members.entries()) {
+    const values = declaredValues(member.node, discriminant);
+    if (values === undefined) refuseUndeclared(discriminant, index, member.node.kind);
+    const check = checkOf(member) as Check<Out>;
+    for (const value of values) {
+      // Letting the first declaration win would leave a member that can never run, which is the
+      // same defect as an unreachable case and is invisible until the wrong branch validates.
+      if (branches.has(value)) refuseDuplicate(discriminant, index, value);
+      branches.set(value, check);
+      known.push(value);
+    }
+  }
+
+  const node: SchemaNode = {
+    kind: 'union',
+    discriminant,
+    anyOf: members.map((member) => member.node),
+  };
+
+  return makeSchema<InferInput<S[number]>, Out>(node, (value, path) => {
+    if (!isPlainObject(value)) {
+      return fail(path, expected(`an object with a "${discriminant}" discriminant`, value));
+    }
+    const branch = branches.get(value[discriminant]);
+    if (branch === undefined) {
+      return fail(
+        [...path, discriminant],
+        expected(`one of ${renderKnown(known)}`, value[discriminant]),
+      );
+    }
+    // The named branch's issues, and only those: the caller already said which shape they meant,
+    // so the other branches' complaints are noise that hides the one real field error.
+    return branch(value, path);
+  });
+}