@ultimat3/core 4.1.0 → 5.0.0

package/CLAUDE.md

@@ -8,7 +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 | `singleLine()` on every interpolated field. A `string` renders fine and can still carry a newline, which writes a line an operator reads as a genuine message |
+| 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 |
@@ -39,11 +39,21 @@ const, then assigns it).
 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 at the SIX renderers of that format and never at the
-call sites — `UltimateError.format()` here, `SchemaError.format()` in `@ultimat3/schema`,
-`renderErrorLines` in `@ultimat3/http`, `renderFrameworkError` in `@ultimat3/mcp`, and
-`renderFinding` / `detailLines` in `@ultimat3/cli` — because a rule every author must remember is a
-rule the next author forgets. It is not a general sanitiser: a cause is prose and keeps its quotes,
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "4.1.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/errors.ts

@@ -70,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;
@@ -95,14 +106,12 @@ export class UltimateError extends Error {
    * ```
    */
   format(options?: FormatErrorOptions): string {
-    // `singleLine`, because this format is line-oriented and `cause` may hold a caller's string:
-    // one newline in it writes a second line an operator reads as a genuine framework message.
-    const lines = [
-      `${singleLine(this.code)}: ${singleLine(this.title)}`,
-      `  cause: ${singleLine(this.cause)}`,
-      `  fix:   ${singleLine(this.fix)}`,
-    ];
-    if (options?.docs === true) lines.push(`  docs:  ${singleLine(this.docs)}`);
+    // 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/index.ts

@@ -44,7 +44,6 @@ export type {
   CacheTier,
   DatabaseConfig,
   JobsConfig,
-  JobsDriver,
   McpConfig,
   OfflineStrategy,
   PwaConfig,