@ultimat3/schema 3.0.0 → 4.1.0

package/CLAUDE.md

@@ -15,7 +15,9 @@ Tier 0. **Imports no `@ultimat3/*` package — not even `@ultimat3/core`.**
 
 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.
+`standard.ts` and `errors.ts` depend on nothing but each other. `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.
 
 **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
@@ -75,6 +77,14 @@ Gotchas:
   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`.
+- **An object parse reads every declared field with `Object.hasOwn` and answers a null-prototype
+  object** — the same two halves `recordSchema` has. A raw `value[key]` read `toString` off the
+  PROTOTYPE, so a field named after one was unsatisfiable for every input and its `.default()`
+  never fired; a `{}` output let a declared `__proto__` field write through the setter. Never
+  reintroduce either half, and never assume a parsed object has `Object.prototype` on it.
+- `t.date` refuses a clock time with no offset and no `Z` (`iso-date.ts`): a zone-less string is a
+  different instant per host `TZ`, and `coerceQuery` puts it one query parameter from the wire.
+  A date-only string carries no clock time and is UTC by spec, so it still parses.
 - 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/schema",
-  "version": "3.0.0",
+  "version": "4.1.0",
   "description": "Ultimate's validation seam: Standard Schema interface, the t namespace, JSON Schema output",
   "license": "MIT",
   "type": "module",

package/src/coerce.ts

@@ -2,6 +2,7 @@
 // HTTP layer has strings that "mean" numbers. Actions, jobs and MCP calls receive real JSON and
 // must never get this leniency.
 
+import { isZonelessDateTime } from './iso-date';
 import type { SchemaNode } from './node';
 import { tryIntrospect } from './provider';
 
@@ -56,6 +57,10 @@ export function coerceNode(node: SchemaNode, raw: unknown): unknown {
     }
     case 'date': {
       if (typeof raw !== 'string') return raw;
+      // Returned untouched rather than converted, this function's standing contract: converting
+      // it resolves a zone-less clock time through the CONTAINER's `TZ`, so `?at=2026-08-19T10:00`
+      // meant a different instant per pod. Validation states the refusal.
+      if (isZonelessDateTime(raw)) return raw;
       const parsed = new Date(raw);
       return Number.isNaN(parsed.getTime()) ? raw : parsed;
     }

package/src/errors.ts

@@ -4,6 +4,31 @@
 
 import { formatIssues } from './standard';
 
+/**
+ * The same escape `@ultimat3/core`'s `singleLine` performs. **Keep in sync**, and read the reason
+ * 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
+ * cause is the one most likely to carry a hostile string — it describes the value that failed
+ * validation, which is the request body.
+ */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: escaping them is the point.
+const CONTROL = /[\u0000-\u001f\u007f\u2028\u2029]/g;
+const ESCAPES: Readonly<Record<string, string>> = {
+  '\n': String.raw`\n`,
+  '\r': String.raw`\r`,
+  '\t': String.raw`\t`,
+  '\b': String.raw`\b`,
+  '\f': String.raw`\f`,
+};
+const singleLine = (text: string): string =>
+  text.replace(
+    CONTROL,
+    (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');
 
@@ -82,9 +107,11 @@ export class SchemaError extends Error {
 
   /** The same 3-line rendering as `UltimateError.format()`. */
   format(): string {
-    return [`${this.code}: ${this.title}`, `  cause: ${this.cause}`, `  fix:   ${this.fix}`].join(
-      '\n',
-    );
+    return [
+      `${singleLine(this.code)}: ${singleLine(this.title)}`,
+      `  cause: ${singleLine(this.cause)}`,
+      `  fix:   ${singleLine(this.fix)}`,
+    ].join('\n');
   }
 
   toJSON(): SchemaErrorJSON {

package/src/iso-date.ts

@@ -0,0 +1,23 @@
+// Single responsibility: the one rule deciding whether a date-time STRING names an instant on its
+// own. Its own file because both the validator and the HTTP coercion have to answer identically —
+// two copies of this pair is how the wire path and the validation path came to disagree.
+
+/**
+ * A clock time, and the zone it is stated in. `2026-08-19T10:00` carries the first and not the
+ * second, so `new Date` resolves it through the HOST process's zone: the same wire value is
+ * `14:00Z` on a `TZ=America/New_York` pod and `10:00Z` on a `TZ=UTC` one, from one request.
+ * That is the framework's "no date without an explicit zone, no ambient default anywhere" rule
+ * failing at the parse end rather than the format end.
+ *
+ * A date-only form carries no clock time and is UTC by specification, so it is not this.
+ *
+ * The same pair `@ultimat3/time`'s `fromIso` refuses on, character for character: one wire value,
+ * one rule, whichever door it comes through.
+ */
+const CLOCK_TIME = /[t ]\d{1,2}:\d{2}/i;
+const UTC_OFFSET = /(?:z|[+-]\d{2}:?\d{2})$/i;
+
+/** What a `t.date` string must not be: a clock time with no offset and no `Z`. */
+export function isZonelessDateTime(value: string): boolean {
+  return CLOCK_TIME.test(value) && !UTC_OFFSET.test(value);
+}

package/src/validators.ts

@@ -19,6 +19,7 @@ import {
 } from './builder';
 import { expected } from './describe-value';
 import { discriminatedUnionSchema } from './discriminated-union';
+import { isZonelessDateTime } from './iso-date';
 import { type MoneyValue, moneySchema } from './money-value';
 import type { SchemaNode } from './node';
 import type { InferInput, InferOutput, StandardIssue } from './standard';
@@ -172,9 +173,19 @@ export function objectSchema<S extends Shape>(shape: S): ObjectSchema<S> {
   const check: Check<ShapeOutput<S>> = (value, path) => {
     if (!isPlainObject(value)) return fail(path, expected('an object', value));
     const issues: StandardIssue[] = [];
-    const out: Record<string, unknown> = {};
+    // `Object.create(null)`, for `recordSchema`'s reason one screen down: on a `{}` literal
+    // `out['__proto__'] = value` hits the `Object.prototype` SETTER, so a DECLARED `__proto__`
+    // field parsed to `{}` whose prototype was the caller's object — every key of it then read
+    // back off a value nobody sent.
+    const out: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
     for (const [key, memberCheck] of checks) {
-      const result = memberCheck(value[key], [...path, key]);
+      // `Object.hasOwn`, never a raw index — the guard `coerce.ts` already applies to the same
+      // read. `value['toString']` answered the INHERITED function for an input that carried no
+      // such key, so a field named after a prototype member was unsatisfiable for every input,
+      // its `.default()` could never fire, and the HTTP path and this one disagreed about what
+      // the caller sent.
+      const raw = Object.hasOwn(value, key) ? value[key] : undefined;
+      const result = memberCheck(raw, [...path, key]);
       if (result.ok) {
         // Unknown keys are dropped, never forwarded — no mass assignment through an action.
         if (result.value !== undefined) out[key] = result.value;
@@ -349,6 +360,13 @@ const dateSchema: Schema<Date | string | number, Date> = makeSchema<Date | strin
         : pass(value);
     }
     if (typeof value === 'string' || typeof value === 'number') {
+      // Enforced, not documented: the node publishes `format: 'date-time'` and this refusal has
+      // always said ISO-8601, while `new Date` resolved a zone-less clock time through the host
+      // process's zone — reachable from the wire, since `coerceQuery` routes a `t.date` field
+      // here and a container's `TZ` then decided which instant a query parameter meant.
+      if (typeof value === 'string' && isZonelessDateTime(value)) {
+        return fail(path, expected('an ISO-8601 date-time with an offset or Z', value));
+      }
       const parsed = new Date(value);
       return Number.isNaN(parsed.getTime())
         ? fail(path, expected('an ISO-8601 date-time', value))