@ultimat3/core 4.0.0 → 5.0.0

package/CLAUDE.md

@@ -8,6 +8,7 @@ is a change to every package.
 | Deps | none (`bun-types` only) |
 | Errors | subclass `UltimateError`; never `throw new Error` |
 | Values in a message | `renderCauseValue()` / `renderFixLiteral()`; never raw `JSON.stringify`, `String()` or `${…}` on an `unknown` |
+| Rendering the 3-line format | nothing to remember — `UltimateError`'s CONSTRUCTOR escapes `code`, `title`, `cause`, `fix` and `docs` with `singleLine()`. Call it yourself only when you render a shape this class never built, e.g. a `Finding` |
 | A value a CALLER supplied | `describeValue()` — shape, never content. `renderCauseValue` is safe against throwing, not against leaking |
 | Reading a caught value | `renderThrowable()` / `isThrownError()` / `stringField()`; never `error.message`, `error instanceof Error` or `typeof error.code === 'string'` directly — the probe throws before the renderer runs |
 | New code | add to `CORE_CODE_TITLES` in `error-codes.ts`, else the title is auto-humanised |
@@ -32,6 +33,33 @@ parameters typed `unknown` that reach a `cause:` / `fix:`, and it cannot see a v
 through a local helper first (`packages/ui/src/components/ErrorState.tsx` builds a `message`
 const, then assigns it).
 
+`singleLine` is the escape that keeps the 3-line contract to three lines, and it exists because
+`scripts/error-render.ts` **cannot see this class**. That gate refuses a parameter typed
+`unknown`/`any` reaching a `cause:`; a value that is already a `string` renders without throwing, so
+there is nothing for it to object to — while a newline in one adds a line to a format that is
+line-oriented in the terminal, in CI logs and inside the dev overlay's `<pre>`. Three holes shipped
+in `@ultimat3/auth` under a green check, the worst reachable by an unauthenticated stranger with one
+crafted OIDC token (issue #97).
+
+**It is applied in the CONSTRUCTOR, `As of 2026-08-20` — not at the renderers, which is where it
+went first and could not stay.** Escaping at each renderer was six call sites, and six is a number
+that only goes up: a seventh in this repo, and every renderer an APP writes, would each have had to
+remember. `format()` is also not the only reader — an uncaught throw prints `.message`, a log line
+takes `.cause`, `--json` takes `toJSON()` — so a per-renderer escape left three of four doors open.
+One constructor covers all of them, and `singleLine` is idempotent, so a call site that already
+escaped (`@ultimat3/auth` renders `claims.iss` at its source, quotes and all) is unharmed. `format()`
+therefore interpolates the fields bare: a second pass would be a second place that has to be right.
+The four renderers that still call it — `renderErrorLines` in `@ultimat3/http`,
+`renderFrameworkError` in `@ultimat3/mcp`, `renderFinding` / `detailLines` in `@ultimat3/cli` — take
+shapes this class never built (a `Finding`, a catalog entry), which is the one case left.
+
+It is not a general sanitiser: a cause is prose and keeps its quotes,
+its backslashes and its percent signs — only the control range is touched. Line breaks are the
+structural half; the rest of C0 and DEL ride along because a terminal reads a raw `\u001b` as an ANSI
+escape, so a cause could repaint the screen or hide the line above it. `@ultimat3/schema` carries a
+deliberate duplicate for the tier-0 reason below, pinned behaviourally by
+`single-line-pin.test.ts` in `@ultimat3/cli`.
+
 `describeValue` in `error-render.ts` is a character-for-character duplicate of `describeValue` in
 `packages/schema/src/describe-value.ts`, for the same tier-0 reason `SCHEMA_ERROR_CODE_TITLES` is
 one: schema and core are both tier 0 and `core → schema` is **not** a declared edge in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",

package/src/config.ts

@@ -8,7 +8,6 @@ import { ROLES, type Role } from './roles';
 export type ThemeMode = 'light' | 'dark' | 'system';
 export type OfflineStrategy = 'precache' | 'runtime' | 'network-only';
 export type CacheTier = 'memo' | 'lru' | 'shared' | 'isr' | 'cdn';
-export type JobsDriver = 'postgres' | 'redis' | 'nats';
 export type RealtimeTier = 'channels' | 'live-queries' | 'local-first';
 export type RealtimeTransport = 'memory' | 'nats' | 'redis';
 
@@ -83,7 +82,17 @@ export interface CacheConfig {
 }
 
 export interface JobsConfig {
-  readonly driver: JobsDriver;
+  /**
+   * No `driver`. It accepted `'postgres' | 'redis' | 'nats'`, was read by NOTHING, and boot always
+   * built `createPgDriver` — so `jobs: { driver: 'redis' }` did not throw, did not warn, and
+   * silently gave you Postgres. Deleted 2026-08-20, and it is the worse shape of the same defect
+   * `realtime.heartbeatMs` was: a knob that fails SILENTLY in the dangerous direction.
+   *
+   * The seam that works is `setJobDriver(driver)` — `setJobDriver(createPgDriver({ executor }))`,
+   * or `setJobDriver(createMemoryDriver())` in a test. Swap the driver, zero job-code change, which
+   * is the whole of what the `JobDriver` interface buys. There is no config line, and one that
+   * cannot be honoured is worse than none.
+   */
   readonly queues: readonly string[];
   readonly concurrency: number;
   readonly maxAttempts: number;
@@ -232,7 +241,6 @@ function defaults(name: string): Omit<AppConfig, 'name'> {
     database: { driver: 'postgres', ssl: false },
     cache: { driver: 'memory', urlEnv: undefined, defaultTtlMs: 60_000, tiers: ['memo', 'lru'] },
     jobs: {
-      driver: 'postgres',
       queues: [`${name}-default`],
       concurrency: 8,
       maxAttempts: 5,

package/src/error-render.ts

@@ -64,6 +64,53 @@ export function renderCauseValue(value: unknown): string {
   }
 }
 
+/**
+ * One line, always. Escapes every character that a line-oriented reader would treat as a line
+ * break, leaving everything else byte-identical.
+ *
+ * WHY this exists at all: `renderCauseValue` above is safe against a value that THROWS while
+ * rendering, and safe against a value that LEAKS. It is not safe against a value that is already
+ * a `string` — a `string` renders fine, so nothing objected to it — and a caller-controlled
+ * string can carry a newline. The 3-line contract format (`<code>` / `  cause: …` / `  fix:   …`)
+ * is line-oriented in the terminal, in CI logs and inside the dev overlay's `<pre>`, so one
+ * newline in a `cause` writes a second line an operator reads as a genuine framework message.
+ * Reproduced with a forged OIDC `iss` claim: an unauthenticated stranger with one crafted token.
+ *
+ * At the RENDERER, not at the call site, deliberately. `bun run error-render` cannot see this
+ * class — its rule is about `unknown` reaching a `cause:` — and three holes shipped in
+ * `@ultimat3/auth` alone under a green check. A rule every call site must remember is a rule the
+ * 296th call site forgets; there are six renderers of this format and no more, so escaping there
+ * is one place instead of every place (issue #97, option 3).
+ *
+ * `\u2028` and `\u2029` are included because they terminate a line for a JavaScript parser and
+ * for several log viewers, while `String.prototype.split('\n')` never sees them.
+ *
+ * The set is every C0 control, DEL, and `\u2028`/`\u2029`. Line breaks are the structural half —
+ * they add a line to a line-oriented format — and the rest ride along because a terminal reads them
+ * as commands of its own: a raw `\u001b` in a cause is an ANSI escape, so a value could repaint the
+ * screen, hide the line above it or move the cursor over what a reader had already been shown.
+ *
+ * NOT a general sanitiser. A `cause` is prose and keeps its quotes, its backslashes, its percent
+ * signs and every printable character it arrived with; only the control range is touched.
+ */
+export function singleLine(text: string): string {
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: escaping them is the point.
+  return text.replace(/[\u0000-\u001f\u007f\u2028\u2029]/g, (char) => {
+    const known = CONTROL_ESCAPES[char];
+    if (known !== undefined) return known;
+    return `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`;
+  });
+}
+
+/** The spellings a reader already knows from a JSON string, so the escape reads as an escape. */
+const CONTROL_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`,
+};
+
 /**
  * `value instanceof Error`, made total. The test itself can throw: a `Proxy`'s `getPrototypeOf`
  * trap runs during `instanceof`, and the one place this question is asked is a `catch` block that

package/src/errors.ts

@@ -3,7 +3,13 @@
 // overlay and `--json`. Never throw a bare Error anywhere in the framework.
 
 import { describeErrorCode } from './error-codes';
-import { isThrownError, renderCauseValue, renderMetaRecord, renderThrowable } from './error-render';
+import {
+  isThrownError,
+  renderCauseValue,
+  renderMetaRecord,
+  renderThrowable,
+  singleLine,
+} from './error-render';
 import { DEFAULT_ERROR_RETRY, type ErrorRetry, isErrorRetry, retryFor } from './error-retry';
 
 /**
@@ -64,16 +70,27 @@ export class UltimateError extends Error {
 
   constructor(init: UltimateErrorInit) {
     const described = describeErrorCode(init.code);
+    // Every line-bearing field is escaped HERE, once, and never again downstream. A `cause` is a
+    // single line by contract, and a caller controls one often enough to matter: `claims.iss` off
+    // an unverified JWT, an IdP's `error_description`, a forwarded IP. One newline in any of them
+    // writes a second line an operator, a CI log or a `<pre>` reads as a genuine framework
+    // message. Escaping at each RENDERER was the first fix and it cannot hold — it is six call
+    // sites today, a seventh whenever someone writes one, and zero of the renderers an APP writes.
+    // Escaping at construction is the one place that covers all of them, and it is what #97 called
+    // the real answer. `singleLine` is idempotent, so a call site that already escaped is unharmed.
+    const code = singleLine(init.code);
+    const title = singleLine(described.title);
+    const cause = singleLine(init.cause);
     // `message` carries the cause because it is the ONLY field a runtime prints when an
     // error escapes uncaught — a worker log, a CI transcript, a stack trace. A message of
     // just `code: title` tells an operator which rule fired but not which row, column or
     // value, which is the opposite of "errors are instructions". `format()` still renders
     // the canonical 3 lines from the fields, so the two never disagree.
-    super(`${init.code}: ${described.title} — ${init.cause}`, { cause: init.cause });
-    this.code = init.code;
-    this.title = described.title;
-    this.fix = init.fix;
-    this.docs = init.docs ?? described.docs;
+    super(`${code}: ${title} — ${cause}`, { cause });
+    this.code = code;
+    this.title = title;
+    this.fix = singleLine(init.fix);
+    this.docs = singleLine(init.docs ?? described.docs);
     this.retry = init.retry ?? retryFor(init.code);
     this.meta = init.meta;
     this.sourceError = init.sourceError;
@@ -89,6 +106,10 @@ export class UltimateError extends Error {
    * ```
    */
   format(options?: FormatErrorOptions): string {
+    // No `singleLine` here. The constructor already escaped all five fields, so a second pass
+    // would be a second place that has to be right — and the one that gets forgotten. This method
+    // is line-oriented and stays exactly 3 lines (4 with `docs`) because the fields cannot carry
+    // a line break, not because this joiner removes them.
     const lines = [`${this.code}: ${this.title}`, `  cause: ${this.cause}`, `  fix:   ${this.fix}`];
     if (options?.docs === true) lines.push(`  docs:  ${this.docs}`);
     return lines.join('\n');

package/src/exports/error-contract.ts

@@ -27,6 +27,7 @@ export {
   renderCauseValue,
   renderFixLiteral,
   renderThrowable,
+  singleLine,
   stringField,
 } from '../error-render';
 export type { ErrorRetry } from '../error-retry';

package/src/index.ts

@@ -44,7 +44,6 @@ export type {
   CacheTier,
   DatabaseConfig,
   JobsConfig,
-  JobsDriver,
   McpConfig,
   OfflineStrategy,
   PwaConfig,
@@ -159,6 +158,7 @@ export {
   resetErrorRetry,
   retryFor,
   SCHEMA_ERROR_CODE_TITLES,
+  singleLine,
   stringField,
   toUltimateError,
   ULTIMATE_ERROR_BRAND,