@ultimat3/schema 7.0.0 → 8.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; keep `Symbol.for('ultimate.error')` |
+| Errors | `SchemaError` mirrors `UltimateError` field-for-field **and message-for-message** (`code: title — cause`); 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` |
@@ -14,7 +14,11 @@ Tier 0. **Imports no `@ultimat3/*` package — not even `@ultimat3/core`.**
 | 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`.
+`char-count → describe-value → node → builder → money-value → validators → discriminated-union →
+provider → t`. `char-count.ts` is imported by BOTH `validators.ts` (which rejects on length) and
+`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. `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.
@@ -24,7 +28,8 @@ which is returned to the caller AND interpolated into the log line — and core'
 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
+else, in CHARACTERS (`char-count.ts`) — the unit the rule that rejected it counts in. 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

package/package.json

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

package/src/char-count.ts

@@ -0,0 +1,20 @@
+// Single responsibility: how many CHARACTERS a string has. One definition, because the rule that
+// rejects a string and the message that describes it must quote the same number — `validators.ts`
+// counts here, `describe-value.ts` renders from here, and they disagreed on any astral value.
+
+/**
+ * Code points, not UTF-16 code units — the unit `json-schema.ts` publishes `minLength`/`maxLength`
+ * in (JSON Schema defines them over code points), the unit the messages have always said ("chars"),
+ * and the unit Postgres' `char_length` counts in. `'👍'.length` is 2, so a count in code units
+ * refused a value the published schema, a human and the database all call one character — and,
+ * once `describeValue` also read `.length`, `t.string.min(3).safeParse('👍a')` answered
+ * "at least 3 chars, received a string of 3 characters", an off-by-one an agent cannot debug.
+ *
+ * Only a surrogate makes the two counts differ, so the string is walked only when one is present:
+ * every ASCII value keeps the O(1) read.
+ */
+const HAS_SURROGATE = /[\uD800-\uDBFF]/;
+
+export function charCount(value: string): number {
+  return HAS_SURROGATE.test(value) ? [...value].length : value.length;
+}

package/src/describe-value.ts

@@ -3,6 +3,8 @@
 // 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.
 
+import { charCount } from './char-count';
+
 /**
  * The shape of a rejected value — **never its content**.
  *
@@ -25,10 +27,11 @@ export function describeValue(value: unknown): string {
   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');
+      // `charCount`, never `.length`: the message has to quote the same unit as the rule that
+      // rejected the value, and `validators.ts` counts code points. Reading `.length` here made
+      // `t.string.min(3).safeParse('👍a')` say "at least 3 chars, received a string of
+      // 3 characters" — an off-by-one nobody can debug because it is not in the value.
+      return countOf(charCount(value), 'string', 'character');
     case 'number':
       return describeNumber(value);
     case 'boolean':

package/src/errors.ts

@@ -101,7 +101,14 @@ export class SchemaError extends Error {
     // failed validation, which is the request body.
     const code = singleLine(init.code);
     const title = singleLine(TITLES[init.code] ?? humanize(init.code));
-    super(`${code}: ${title}`, { cause: singleLine(init.cause) });
+    const cause = singleLine(init.cause);
+    // The cause is in `message` for the reason `UltimateError`'s constructor gives: `message` is
+    // the ONLY field a runtime prints when an error escapes uncaught — a worker log, a CI
+    // transcript, a stack trace — and `code: title` alone names which rule fired but not which
+    // field, row or value. `format()` still renders the canonical 3 lines from the fields, so the
+    // two cannot disagree. Kept identical to core's on purpose; both are tier 0 and neither may
+    // import the other.
+    super(`${code}: ${title} — ${cause}`, { cause });
     this.code = code;
     this.title = title;
     this.fix = singleLine(init.fix);

package/src/validators.ts

@@ -17,6 +17,7 @@ import {
   type ShapeInput,
   type ShapeOutput,
 } from './builder';
+import { charCount } from './char-count';
 import { expected } from './describe-value';
 import { discriminatedUnionSchema } from './discriminated-union';
 import { isZonelessDateTime } from './iso-date';
@@ -61,21 +62,6 @@ function describePattern(node: SchemaNode): string {
     : `/${node.pattern}/${node.patternFlags}`;
 }
 
-/**
- * Characters, not UTF-16 code units — the unit `json-schema.ts` already promises, since JSON
- * Schema defines `minLength`/`maxLength` over code points and the message here has always said
- * "chars". `'👍'.length` is 2, so `t.string.max(1)` refused a value the published schema, a human
- * and Postgres' `char_length` all count as one.
- *
- * Only a surrogate makes the two counts differ, so the string is walked only when one is present
- * — every ASCII value keeps the O(1) read this replaced.
- */
-const HAS_SURROGATE = /[\uD800-\uDBFF]/;
-
-function charCount(value: string): number {
-  return HAS_SURROGATE.test(value) ? [...value].length : value.length;
-}
-
 /**
  * Compiled once per schema, not once per validation. `lastIndex` is reset because a `g` or `y`
  * pattern carries it between calls — a cached global RegExp answers `false` for the second