@ultimat3/schema 20.2.1 → 22.0.0

package/CLAUDE.md

@@ -139,6 +139,10 @@ Gotchas:
 - `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.
+- `t.date` refuses any string that is not ISO-8601 in shape (`isIsoDateTime`, `As of 2026-09-23`,
+  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.
 - **`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

package/README.md

@@ -132,6 +132,18 @@ This package is tier 0 and cannot import `@ultimat3/core`, so `SchemaError` repr
 `isUltimateError()` from core matches it. Register the codes once from any package that imports
 both: `registerErrorCodes(SCHEMA_ERROR_CODES)`.
 
+### Error classes
+
+Every error class `src/index.ts` exports, for `instanceof` inside one process. Across a wire or
+a job boundary the class is gone and the `code` is what survives — match on that.
+
+| Class | Code | Declared in |
+|---|---|---|
+| `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` |
+| `SchemaUnsupportedError` (extends `SchemaError`) | `X_SCHEMA_UNSUPPORTED` | `src/errors.ts` |
+| `ValidationFailedError` (extends `SchemaError`) | `X_VALIDATION_FAILED` | `src/errors.ts` |
+
 ## Swapping the library
 
 The builtin validators (`validators.ts`) are the shipped default — small, dependency-free, no

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/schema",
-  "version": "20.2.1",
+  "version": "22.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,7 +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 { isIsoDateTime } from './iso-date';
 import type { SchemaNode } from './node';
 import { tryIntrospect } from './provider';
 
@@ -60,7 +60,9 @@ export function coerceNode(node: SchemaNode, raw: unknown): unknown {
       // 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;
+      // Non-ISO text (`3/14/2026`) is left untouched for the same reason: `new Date` reads it at
+      // the host's local midnight.
+      if (!isIsoDateTime(raw)) return raw;
       const parsed = new Date(raw);
       return Number.isNaN(parsed.getTime()) ? raw : parsed;
     }

package/src/index.ts

@@ -40,6 +40,8 @@ export {
   ULTIMATE_ERROR_BRAND,
   ValidationFailedError,
 } from './errors';
+// Exported for `@ultimat3/time`'s `fromIso`: one ISO-shape rule, whichever door a date comes in by.
+export { isIsoDateTime } from './iso-date';
 export type {
   JsonSchema,
   JsonSchemaDialect,

package/src/iso-date.ts

@@ -1,6 +1,6 @@
-// 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.
+// Single responsibility: the one rule deciding whether a STRING is an ISO-8601 date or date-time
+// that names an instant on its own. Its own file because the validator, the HTTP coercion and
+// `@ultimat3/time`'s `fromIso` have to answer identically — two copies is how they came to disagree.
 
 /**
  * A clock time, and the zone it is stated in. `2026-08-19T10:00` carries the first and not the
@@ -10,14 +10,27 @@
  * 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;
 
+/**
+ * The ISO-8601 shape, and nothing else. `new Date` also parses `'March 14, 2026'`, `'3/14/2026'`
+ * and `'12'` — each at the host's LOCAL midnight, so the instant depended on `TZ`. Case-insensitive
+ * 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;
+
 /** 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);
 }
+
+/**
+ * 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.
+ */
+export function isIsoDateTime(value: string): boolean {
+  return ISO_SHAPE.test(value) && !isZonelessDateTime(value);
+}

package/src/validators.ts

@@ -20,7 +20,7 @@ import {
 import { charCount } from './char-count';
 import { expected } from './describe-value';
 import { discriminatedUnionSchema } from './discriminated-union';
-import { isZonelessDateTime } from './iso-date';
+import { isIsoDateTime, isZonelessDateTime } from './iso-date';
 import { type MoneyValue, moneySchema } from './money-value';
 import type { SchemaNode } from './node';
 import { isPrototypeKey, PROTOTYPE_KEYS } from './prototype-keys';
@@ -370,6 +370,11 @@ const dateSchema: Schema<Date | string | number, Date> = makeSchema<Date | strin
       if (typeof value === 'string' && isZonelessDateTime(value)) {
         return fail(path, expected('an ISO-8601 date-time with an offset or Z', value));
       }
+      // `new Date` also parses `'March 14, 2026'` and `'12'` at the host's local midnight, so the
+      // shape is checked first: a string that is not ISO-8601 is refused, not guessed at.
+      if (typeof value === 'string' && !isIsoDateTime(value)) {
+        return fail(path, expected('an ISO-8601 date-time', value));
+      }
       const parsed = new Date(value);
       return Number.isNaN(parsed.getTime())
         ? fail(path, expected('an ISO-8601 date-time', value))