@ultimat3/schema 9.0.0 → 10.0.0

package/CLAUDE.md

@@ -43,6 +43,14 @@ carries a duplicate of these titles and registers them unconditionally, so every
 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.
 
+`ERROR_DOCS_URL` in `errors.ts` is the third deliberate tier-0 duplicate, beside `singleLine` and
+`ULTIMATE_ERROR_BRAND` — one URL, spelled out, because `SchemaError` cannot import
+`@ultimat3/core`'s constant. There is no per-code URL anywhere in the framework: codes live in
+`wiki/Error-Codes.md` as table ROWS and a table row has no anchor, so
+`https://ultimate.dev/errors/<code>` was a 404 on every error and was deleted `As of 2026-08-23`. Change it
+here and in `packages/core/src/error-codes.ts` in the same edit. **There is no pin test yet** —
+one belongs in `@ultimat3/cli` beside `single-line-pin.test.ts`, which may legally import both.
+
 `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

package/package.json

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

package/src/errors.ts

@@ -23,6 +23,10 @@ const ESCAPES: Readonly<Record<string, string>> = {
   '\b': String.raw`\b`,
   '\f': String.raw`\f`,
 };
+// `ESCAPES[char]` is a computed read on a plain object and is safe by DOMAIN, not by luck: the
+// key is whatever `CONTROL` matched, so it is exactly one control character — and no
+// `Object.prototype` member has a single-character name. Every other computed read in this file
+// goes through `Object.hasOwn`.
 const singleLine = (text: string): string =>
   text.replace(
     CONTROL,
@@ -32,6 +36,18 @@ const singleLine = (text: string): string =>
 /** Same well-known symbol `@ultimat3/core` brands with. Keep in sync, never rename. */
 export const ULTIMATE_ERROR_BRAND: unique symbol = Symbol.for('ultimate.error');
 
+/**
+ * The same one URL `@ultimat3/core`'s `ERROR_DOCS_URL` holds. **Keep in sync**, and read the
+ * reason there — briefly: `wiki/` is the only public documentation surface, codes live on that
+ * page in table ROWS, and a table row has no anchor, so there is no per-code URL to build.
+ *
+ * Spelled out rather than imported for the same reason `singleLine` and the brand symbol above
+ * are: `schema` and `core` are both tier 0, so `schema` may not import `core` (imports go DOWN,
+ * never sideways). Neither tier-0 package can check the copy against its source, so the pin
+ * belongs in `@ultimat3/cli` beside `single-line-pin.test.ts` — it is NOT written yet.
+ */
+const ERROR_DOCS_URL = 'https://github.com/developerz-ai/ultimate/wiki/Error-Codes';
+
 export interface SchemaErrorCodeDeclaration {
   readonly title: string;
   readonly docs?: string | undefined;
@@ -100,7 +116,13 @@ export class SchemaError extends Error {
     // 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.
     const code = singleLine(init.code);
-    const title = singleLine(TITLES[init.code] ?? humanize(init.code));
+    // `Object.hasOwn`, never the read alone: `init.code` is a bare string an app or a provider
+    // chose, so `TITLES['constructor']` answered with the `Object` FUNCTION and `singleLine` then
+    // called `.replace` on it — the error that reports a bad value died reporting it, and the
+    // caller got a `TypeError` in place of its own failure. Same discriminator as
+    // `@ultimat3/action`'s `IRREGULAR[word]`.
+    const declared = Object.hasOwn(TITLES, init.code) ? TITLES[init.code] : undefined;
+    const title = singleLine(declared ?? humanize(init.code));
     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
@@ -112,7 +134,7 @@ export class SchemaError extends Error {
     this.code = code;
     this.title = title;
     this.fix = singleLine(init.fix);
-    this.docs = singleLine(init.docs ?? `https://ultimate.dev/errors/${init.code}`);
+    this.docs = singleLine(init.docs ?? ERROR_DOCS_URL);
     this.meta = init.meta;
   }
 

package/src/json-schema.ts

@@ -75,10 +75,19 @@ const FORMAT_MAP: Readonly<Record<string, string>> = Object.freeze({
   cursor: 'ultimate-cursor',
 });
 
+/**
+ * `Object.hasOwn`, never the read alone: `node.format` comes from a schema PROVIDER's IR, so
+ * `FORMAT_MAP['constructor']` answered with the `Object` function and `?? node.format` could not
+ * rescue it — `JSON.stringify` then dropped `format` from the published document in silence.
+ * Same discriminator as `@ultimat3/action`'s `BY_FORMAT[node.format]`, one package up.
+ */
+const publishedFormat = (format: string): string =>
+  Object.hasOwn(FORMAT_MAP, format) ? (FORMAT_MAP[format] ?? format) : format;
+
 function stringNode(node: SchemaNode): JsonSchema {
   return {
     type: 'string',
-    ...(node.format === undefined ? {} : { format: FORMAT_MAP[node.format] ?? node.format }),
+    ...(node.format === undefined ? {} : { format: publishedFormat(node.format) }),
     ...(node.minLength === undefined ? {} : { minLength: node.minLength }),
     ...(node.maxLength === undefined ? {} : { maxLength: node.maxLength }),
     ...(node.pattern === undefined ? {} : { pattern: node.pattern }),