@ultimat3/schema 2.0.0 → 4.0.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": "2.0.0",
+  "version": "4.0.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;
     }
@@ -81,7 +86,10 @@ export function coerceNode(node: SchemaNode, raw: unknown): unknown {
       const source = raw as Record<string, unknown>;
       const out: Record<string, unknown> = { ...source };
       for (const [key, child] of Object.entries(node.properties)) {
-        if (key in source) out[key] = coerceNode(child, source[key]);
+        // `Object.hasOwn`, never `key in source`: `{ ...source }` above already dropped what a
+        // prototype carries, so an `in` check put it back — a schema field named `toString` or
+        // `valueOf` was coerced from the INHERITED member and handed validation a function.
+        if (Object.hasOwn(source, key)) out[key] = coerceNode(child, source[key]);
       }
       return out;
     }
@@ -111,11 +119,17 @@ export function coerceNode(node: SchemaNode, raw: unknown): unknown {
   }
 }
 
+/**
+ * `Object.create(null)`, for the reason `@ultimat3/http`'s `parseQuery` already uses one: this
+ * record is built from caller-controlled keys. On a `{}` literal `out['__proto__'] = …` hits the
+ * prototype accessor instead of declaring a key, and every member of `Object.prototype` reads
+ * back as present when the client sent nothing.
+ */
 function toRecord(source: QuerySource): Record<string, string | readonly string[] | undefined> {
+  const out = Object.create(null) as Record<string, string | readonly string[] | undefined>;
   if (!(source instanceof URLSearchParams)) {
-    return { ...source };
+    return Object.assign(out, source);
   }
-  const out: Record<string, string | readonly string[]> = {};
   for (const key of new Set(source.keys())) {
     const all = source.getAll(key);
     out[key] = all.length > 1 ? all : (all[0] as string);
@@ -134,7 +148,8 @@ export function coerceQuery(schema: unknown, source: QuerySource): Record<string
 
   const out: Record<string, unknown> = { ...record };
   for (const [key, child] of Object.entries(node.properties)) {
-    if (!(key in record)) continue;
+    // See `toRecord`: a declared property is coerced only when the caller actually sent it.
+    if (!Object.hasOwn(record, key)) continue;
     const raw = record[key];
     out[key] = coerceNode(child, child.kind === 'array' ? (raw ?? []) : normaliseSingle(raw));
   }

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/provider.ts

@@ -11,8 +11,10 @@ export interface SchemaProvider {
   readonly vendor: string;
   readonly t: TNamespace;
   /**
-   * Return the IR for one of this provider's schemas. Required for OpenAPI and MCP tool
-   * schemas; omit it only if the provider also supplies `toJsonSchema`.
+   * Return the IR for one of this provider's schemas. Required for OpenAPI, MCP tool schemas
+   * and the admin form generator: `toJsonSchema()` calls it unconditionally and throws
+   * `X_SCHEMA_UNSUPPORTED` without it. There is no second way to describe a schema — the IR is
+   * the one projection surface, and every generator reads it.
    */
   introspect?(schema: unknown): SchemaNode | undefined;
 }

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))