@ultimat3/http 2.0.0 → 4.0.0

package/CLAUDE.md

@@ -55,8 +55,16 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   a caller may SHORTEN it with `x-request-timeout-ms`, never lengthen it. Two halves, both needed:
   the abort is what cooperative code unwinds on, and the race in `execute` is what answers the
   socket when a handler never looked at the signal. `X_TIMEOUT` is borrowed (core's concept) and
-  already mapped to 504. Always `deadline.clear()` in the `finally` — a live timer keeps the event
-  loop from going idle, so a process that answered everything still refuses to exit.
+  already mapped to 504. **`ctx.signal` is the deadline OR the caller going away**, `As of
+  2026-08`: `pipeline.ts` hands `startDeadline` the inbound `Request.signal` and the two are joined
+  with `AbortSignal.any`, which is what `context.ts` had documented and nothing wired — a closed
+  tab held its handler, its pool slot and its vendor connection for the whole 30s. `expired` stays
+  the timer's alone: it answers the SOCKET, and a caller that hung up has no socket to answer.
+  With `requestTimeoutMs: 0` the caller's signal is handed through as-is rather than the shared
+  never-aborted singleton, which every such request used to share — one `abort` listener per
+  request, accumulating for the life of the process. Always `deadline.clear()` in the `finally` —
+  a live timer keeps the event loop from going idle, so a process that answered everything still
+  refuses to exit.
 - **`admit` is the second stage, and it refuses before ANY work.** `isDraining()` had no reader in
   this package while this file claimed the layer answered 503 on it; past `config.maxInflight`
   (1000, `0` disables) a request is shed `X_OVERLOADED` with `retry-after`. Both set the header on
@@ -82,6 +90,17 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   and not reported and therefore kept for the full retention. The message is the CODE alone. The
   other half is `@ultimat3/schema`'s `describeValue` (shape, never content) and it is the
   load-bearing one; this half is what makes the value redactable at all.
+- **A rejected BODY is not a log field either — `bodyInvalid`'s `issues` may name only what the
+  framework chose** (`As of 2026-08-19`). `request.ts` built `could not parse ${type}: ${String(error)}`,
+  and the runtime's `SyntaxError` quotes the token it choked on: a `POST` of
+  `{"password": hunter2SuperSecret}` answered `422` with that identifier in `cause`, which goes to
+  the CALLER through `toProblem` and to the log store as the unredactable field `cause`. Two rules,
+  both needed. The caller-facing `issues` are a fixed vocabulary — `could not parse the body as
+  JSON`, and the LIST of accepted content-types rather than the one that was sent — and everything
+  the caller supplied rides in `bodyInvalid`'s third argument, `meta`, which `toProblem` never
+  renders. The parser's own message goes through core's `renderThrowable`, never `String(error)`:
+  `bun run error-render` cannot see this class of defect, because a `catch` binding is not a
+  parameter, so it is a review rule here and a blind spot there.
 - **A browser that fails `auth: 'required'` is redirected; an agent gets the problem document.**
   One condition, two audiences, decided once in `auth-redirect.ts` and applied in the `error-map`
   stage before the overlay. `config.signInPath` is `null` until an app names its page, because a
@@ -153,10 +172,22 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   can never import each other, so the only conversion between `{ limit, windowMs }` and a `Bucket`
   sitting in one of them is why a `query` could not declare a rate limit at all. It is beside
   `Bucket` and the maths it validates, and it throws http's own `X_RATE_LIMIT_INVALID`.
+- **`ERROR_STATUS`'s keys are LITERAL, not an index signature** (`As of 2026-08-19`). The
+  annotation was `Readonly<Record<string, number>>`, which made `ERROR_STATUS.X_QUERY_NOT_PAGABLE`
+  a legal read answering `undefined` — a mistyped row in the one table the framework's whole error
+  contract rests on. It is now an object literal `satisfies Readonly<Record<string, number>>`, so a
+  typo is a compile error; `error-map.test.ts` pins that with a `@ts-expect-error`. Read it by a
+  code the framework did not mint through `statusFor()`, which goes via the file-local `BY_CODE`
+  view and keeps `Object.hasOwn`.
 - Statuses live in `error-map.ts` only. No other file writes a status number. The framework's
   table (`ERROR_STATUS`) is closed; an app declares its own codes' statuses with
   `registerErrorStatus()`, which refuses a code the framework already holds. Without that half,
-  every app code was 500 and `pipeline.ts` paged the on-call for a wrong password.
+  every app code was 500 and `pipeline.ts` paged the on-call for a wrong password. There is
+  deliberately **no projection of the app's half**: `appErrorStatus()` was exported for "`x errors
+  list` and the manifest" and neither ever called it (deleted 2026-08). It could not have worked —
+  `APP_ERROR_STATUS` is process-global runtime state filled by the app's own imports, while both
+  named surfaces are build artefacts derived from source, so in a CLI process it answers `{}`.
+  Wiring one means deriving it from source, not re-exporting the map.
 - **The context carries the inbound headers, never the `Request`.** `ctx.requestHeaders` is set
   once at construction; `useRequestHeader` / `useRequestCookie` are what app code reads, and
   `UltimateRequest.cookie()` is what `hooks.authenticate` reads. A `Request` on the context is a
@@ -187,6 +218,34 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   hit: the stage that renders a throw has nothing left to render its own. Every degraded answer goes
   *through* the recover stage, never around it — reporting, logging and the overlay each keep one
   call site.
+- **Both guards in that tail are TOTAL against a throwable that fights being read** (`As of
+  2026-08`). `recoverWith`'s catch built its log line with `String(failure)`, which is itself a
+  `TypeError` on a null-prototype object — thrown out of the one guard documented "never throws, by
+  construction", from the frame with nothing above it. It is a log FIELD now, the same rule the
+  `error-map` stage already follows, and `logger.emit` degrades a hostile field per key. The second
+  half is `factsOf`: it read `record['code']` directly, and that read is a getter call or a
+  `Proxy`'s `get` trap on a value the framework did not build — so a handler throwing one took the
+  recover stage AND the `problem()` the guard degrades to, and `handle()` rejected. Every field
+  comes off the throwable through core's `stringField`. Never spell either read inline again:
+  `String(x)`, `${x}` and a bare property read on a caught value are all the same defect, and
+  `error-render.ts` names seven prior instances.
+- **A table keyed by a `code` is read with `Object.hasOwn`, never `[code] !== undefined`** (`As of
+  2026-08`). `code` is a string off a throwable this package did not build, so `ERROR_STATUS` and
+  `HTTP_ERROR_TITLES` — object literals, and therefore holders of every name on
+  `Object.prototype` — answered `'toString'`, `'constructor'`, `'valueOf'` and `'hasOwnProperty'`
+  with a FUNCTION. `statusFor` handed that to `new Response(body, { status })`, a `RangeError`
+  raised inside `recoverWith`'s fallback, and `handle()` rejected: the same defect class as the
+  reads above, arriving through a lookup instead of a property. `registerErrorStatus` had the third
+  copy, refusing an app code named `toString` with a cause reading `the framework already maps it
+  to function toString() { [native code] }`. `scripts/error-map.ts` reads this table correctly and
+  always has. `APP_ERROR_STATUS` is a `Map`, which is why it never had the bug — prefer one for
+  anything keyed by a value a caller chose.
+- **`recoverWith`'s fallback is INSIDE its `try`.** `return problem(ctx.error, …)` sat beside the
+  guard, so the file whose one promise is "never throws, by construction" rested on every reader
+  below that line being total. The degraded answer is a literal `problem+json` document naming
+  `X_INTERNAL`, built with no call that could fail in turn, and the renderer's own failure goes to
+  the log as `pipeline.problem_failed` — a last resort sharing a code path with what just broke is
+  not one.
 - **The memory rate-limit store is bounded, and the eviction order is part of the guarantee.**
   The key falls back to the connection address (`rateLimitKey`), so a scan rotating through an
   IPv6 /64 mints one entry per request — an unbounded map hands the flood the process. Every
@@ -195,6 +254,14 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   and it evicts the entries **closest to full** first: throwing away a spent bucket is a free
   reset for whoever spent it, so the most-throttled key is the last one to go. Never swap that
   comparator for insertion order or an LRU — recency is not the same as worthlessness here.
+- **The limiter takes a `Clock`; `Date.now()` is not read here** (`As of 2026-08-19`). `rate-limit.ts`
+  read it inline while BOTH production call sites (`server.ts`, `pipeline.ts`) built their limiter
+  with no override, so the bucket maths that decides whether a caller is throttled could not be
+  frozen by any test — while `@ultimat3/auth`'s credential limiter has taken an injected `Clock`
+  since it shipped. `createRateLimiter({ clock })` defaults to `systemClock`, the same shape as
+  `createRequestContext`'s `init.clock`. Deliberately NOT a `clock` on `PipelineDeps`:
+  `deps.limiter` is already the one seam for handing the pipeline a limiter you built, and a second
+  entry point for one number is axiom 1.
 - **Where the limiter's counters live is DECLARED by the app, never inferred, and refused at
   boot — and there is no default.** `DEFAULT_RATE_LIMIT` carries no `scope`, so
   `resolveRateLimitConfig` refuses `X_RATE_LIMIT_SCOPE_UNSET` at `defineHttpConfig` when a limiter

package/README.md

@@ -59,6 +59,7 @@ What the lifecycle refuses on the caller's behalf, `As of 2026-08`:
 | `trustProxy: true` with no `trustedProxyHops` | `X_TRUST_PROXY_UNSET` at `defineHttpConfig`. **Breaking, `As of 2026-08`**: `trustProxy` now defaults to `false`, and `x-forwarded-for` is read at `entries.length - hops` — never at `[0]`, which is whatever the client typed |
 | a credentialed unsafe method that cannot be shown to be same-origin | `X_CSRF_BLOCKED` (403). `sec-fetch-site: same-origin`, `Origin` equal to this app, or an `Origin` in `cors.origins` — anything else is refused before the body is read |
 | a request past `requestTimeoutMs` (30s) | `ctx.signal` aborts and the socket is answered `X_TIMEOUT` (504); a caller may shorten the deadline with `x-request-timeout-ms`, never lengthen it |
+| the caller going away mid-request | `ctx.signal` aborts on the inbound `Request.signal` too, so a closed tab unwinds cooperative work instead of holding its pool slot for the rest of the budget. Both halves are one signal (`AbortSignal.any`), and `requestTimeoutMs: 0` still delivers the caller's |
 | a request while the process is draining | `X_DRAINING` (503) + `retry-after`, which is what `isDraining()` was always documented to do here and had no reader for |
 | a request past `maxInflight` (1000) | `X_OVERLOADED` (503) + `retry-after`, shed in the `admit` stage before any work |
 
@@ -99,6 +100,13 @@ so nothing can be wrong.
 maths stays in `createRateLimiter`, so every driver agrees on the numbers. **No shared store ships
 yet, `As of 2026-08`** — `memoryRateLimitStore()` is the only implementation in the framework.
 
+The maths reads an injected `Clock`, defaulting to `systemClock`: `createRateLimiter({ config,
+clock })`. **Breaking, `As of 2026-08-19`** — it took `now?: () => number` before and read
+`Date.now()` when nothing passed one, which both production call sites did, so the limiter that
+actually throttles a request could not be frozen. Replace `now: () => t` with
+`clock: frozenClock(t)`; a limiter you build yourself still reaches the pipeline through
+`PipelineDeps.limiter`, which stays the only seam for one.
+
 ### A route may bring its own bucket
 
 `meta.rateLimit` names a bucket; `meta.rateLimitBucket` is the numbers that bucket must hold.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/http",
-  "version": "2.0.0",
+  "version": "4.0.0",
   "description": "Owned request lifecycle over Bun.serve: router, ordered pipeline, problem+json errors",
   "license": "MIT",
   "type": "module",
@@ -31,9 +31,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "2.0.0",
-    "@ultimat3/i18n": "2.0.0",
-    "@ultimat3/schema": "2.0.0",
-    "@ultimat3/time": "2.0.0"
+    "@ultimat3/core": "4.0.0",
+    "@ultimat3/i18n": "4.0.0",
+    "@ultimat3/schema": "4.0.0",
+    "@ultimat3/time": "4.0.0"
   }
 }

package/src/deadline.ts

@@ -52,9 +52,21 @@ export const startDeadline = (input: {
   readonly config: HttpConfig;
   readonly method: string;
   readonly pathname: string;
+  /**
+   * The INBOUND `Request.signal` — the caller-went-away half of `ctx.signal`. Optional because a
+   * context can exist without a request (a job, a test), never because a server may skip it.
+   */
+  readonly clientSignal?: AbortSignal | undefined;
 }): Deadline => {
   const timeoutMs = resolveTimeoutMs(input.headers, input.config);
-  if (timeoutMs <= 0) return NO_DEADLINE;
+  const client = input.clientSignal;
+  // The caller's own signal, not the shared never-aborted one: with no deadline configured every
+  // request used to share a module-level singleton, so a handler that added an `abort` listener
+  // accumulated one per request for the life of the process — and no request could learn its
+  // caller had gone. `NO_DEADLINE` is left for the callers that genuinely have no client.
+  if (timeoutMs <= 0) {
+    return client === undefined ? NO_DEADLINE : { ...NO_DEADLINE, signal: client };
+  }
 
   const controller = new AbortController();
   let fire: (() => void) | undefined;
@@ -71,7 +83,12 @@ export const startDeadline = (input: {
   }, timeoutMs);
 
   return {
-    signal: controller.signal,
+    // Both halves, or the doc on `ctx.signal` is half true — which it was: nothing in this package
+    // read the inbound signal, so a browser closing the tab left the request holding its pool slot
+    // and its vendor connection for the whole budget, for a caller that is gone. `expired` stays
+    // the TIMER's alone: it is what answers the socket, and a socket the caller already closed has
+    // nothing to answer.
+    signal: client === undefined ? controller.signal : AbortSignal.any([client, controller.signal]),
     expired,
     timeoutMs,
     clear: () => clearTimeout(timer),

package/src/error-map.ts

@@ -1,7 +1,7 @@
 // The one place a framework error code becomes an HTTP status. A table, not a
 // switch chain: adding a code elsewhere in the framework means adding a row here,
 // and a missing row is a loud 500 rather than a silently wrong 200.
-import { renderCauseValue } from '@ultimat3/core';
+import { renderCauseValue, stringField } from '@ultimat3/core';
 import { errorStatusInvalid, HTTP_ERROR_TITLES } from './errors';
 
 /**
@@ -9,7 +9,7 @@ import { errorStatusInvalid, HTTP_ERROR_TITLES } from './errors';
  * is the only layer that knows what a status means, so no other package should
  * ever hardcode one.
  */
-export const ERROR_STATUS: Readonly<Record<string, number>> = {
+export const ERROR_STATUS = {
   // @ultimat3/http
   X_ROUTE_NOT_FOUND: 404,
   X_METHOD_NOT_ALLOWED: 405,
@@ -31,6 +31,10 @@ export const ERROR_STATUS: Readonly<Record<string, number>> = {
   // and declaring a status the framework already owns. 500 is the honest answer to either.
   X_NO_REQUEST: 500,
   X_ERROR_STATUS_INVALID: 500,
+  // A `hive()` whose `split()` returned no members. The caller cannot fix it by sending
+  // different input — the guard belongs in the app, either by returning at least one member
+  // or by skipping the hive when the source is empty — so it is the server's bug, not theirs.
+  X_HIVE_EMPTY: 500,
   // Thrown while `app.config.ts` resolves, so no request is ever answered with it — the row exists
   // because a code with no status is a 500 anyway and this table is the closed one.
   X_CORS_CONFIG_INVALID: 500,
@@ -97,6 +101,12 @@ export const ERROR_STATUS: Readonly<Record<string, number>> = {
   // the same class as `X_BODY_INVALID` and `X_INVARIANT_VIOLATED` above. Unmapped, a visitor
   // choosing "password" at a signup form was reported to the on-call monitor as a server fault.
   X_PASSWORD_WEAK: 422,
+  // 422 for the same reason as the row above, and deliberately not 500: `enrolTotp` throws it for a
+  // secret the CALLER supplied — an import from another MFA system, or a value off a form — and
+  // what failed is that value's content, not the server. `verifyTotp` never throws it (an
+  // unreadable stored secret is a non-verdict there, the rule `verifyAgainst` follows for a hash
+  // Bun cannot read), so a login checking a broken row cannot reach this status at all.
+  X_MFA_SECRET_INVALID: 422,
   // @ultimat3/entity
   X_NOT_FOUND: 404,
   X_ENTITY_DUPLICATE: 409,
@@ -122,6 +132,18 @@ export const ERROR_STATUS: Readonly<Record<string, number>> = {
   // at it), which 422 describes only for the insert.
   X_DB_UNIQUE_VIOLATION: 409,
   X_DB_FOREIGN_KEY_VIOLATION: 409,
+  // @ultimat3/jobs — the ONE jobs code with a row here, and the reason the rest are pinned in
+  // `scripts/error-map-backlog.ts` does not cover it. That pin says "a job runs with no socket
+  // attached; `ROLE=worker` opens no HTTP port at all" — true of `X_JOB_TIMEOUT` and every other
+  // worker-runtime code, and NOT true of a decode failure: `toJobRecord` runs wherever a row is
+  // READ, which includes the admin dashboard's job panel and `x jobs show` served over HTTP.
+  // 500, and it should page: a queue holding rows this build cannot read is an operator's
+  // problem, and nothing the caller sent is wrong.
+  X_JOB_ROW_STATUS_UNKNOWN: 500,
+  // Thrown by `registerJobs()` while the app's modules load, so no request is ever answered with
+  // it either — the row exists for the reason `X_CORS_CONFIG_INVALID`'s does: this table is the
+  // closed one, and a code with no row is a 500 anyway.
+  X_ACTION_JOB_UNBRIDGED: 500,
   // @ultimat3/policy
   X_POLICY_MISSING: 500,
   X_PERMISSION_UNKNOWN: 500,
@@ -155,6 +177,11 @@ export const ERROR_STATUS: Readonly<Record<string, number>> = {
   X_STORAGE_CHECKSUM_MISMATCH: 422,
   X_STORAGE_URL_INVALID: 403,
   X_STORAGE_URL_EXPIRED: 410,
+  // 500, not 403, and the distinction is the whole reason this code exists rather than
+  // reusing X_STORAGE_URL_INVALID: nothing is wrong with the caller's URL. The disk was
+  // built with no way to check a signature, which is the operator's misconfiguration and
+  // not an attacker — reporting it as 403 sends the on-call hunting somebody who is not there.
+  X_STORAGE_URL_UNVERIFIABLE: 500,
   // 409, not the 500 it fell through to: the object exists and the request is well formed — the
   // STATE is wrong. A validated upload lands under the quarantine segment and `promoteAttachment`
   // refuses it until the app's own scanner calls `releaseQuarantine`, which is a thing the caller
@@ -185,10 +212,29 @@ export const ERROR_STATUS: Readonly<Record<string, number>> = {
   X_TIMEOUT: 504,
   X_ABORTED: 499,
   X_INTERNAL: 500,
-};
+  // The keys are LITERAL — deliberately not `Readonly<Record<string, number>>`, which is what the
+  // annotation used to say. This table is the closed one, so `ERROR_STATUS.X_QUERY_NOT_PAGABLE`
+  // has to be a compile error rather than an `undefined` a test then asserts `toBeNumber()` on.
+  // Read it by a code the framework did not mint through `statusFor`, never by index.
+} satisfies Readonly<Record<string, number>>;
 
 export const DEFAULT_STATUS = 500;
 
+/**
+ * The framework's row for a code, or `undefined` — through `Object.hasOwn`, never `[code]`.
+ *
+ * `code` is a STRING read off a throwable this package did not build, and `ERROR_STATUS` is an
+ * object literal, so it holds every name on `Object.prototype`: an app throwing
+ * `{ code: 'toString' }` read a FUNCTION out of this table. `statusFor` handed it to
+ * `new Response(body, { status })` — a `RangeError` raised inside `recoverWith`'s fallback, the
+ * one frame with nothing above it, so `Pipeline.handle` REJECTED against its own contract.
+ * `scripts/error-map.ts` reads the same table this way already.
+ */
+const BY_CODE: Readonly<Record<string, number>> = ERROR_STATUS;
+
+const frameworkStatus = (code: string): number | undefined =>
+  Object.hasOwn(BY_CODE, code) ? BY_CODE[code] : undefined;
+
 /**
  * Statuses for codes the APP owns. The table above is closed — it has to be, it is the
  * framework's own contract — and every code outside it fell to 500, so a wrong password was an
@@ -214,8 +260,12 @@ export const registerErrorStatus = (statuses: Readonly<Record<string, number>>):
     }
     // The framework's own codes are not negotiable: an app that could map `X_UNAUTHENTICATED`
     // to 200 would be an app whose 401 contract every client already depends on, changed.
-    if (ERROR_STATUS[code] !== undefined) {
-      throw errorStatusInvalid(code, `the framework already maps it to ${ERROR_STATUS[code]}`);
+    // Through `frameworkStatus`, so this refusal cannot answer for a code the framework does not
+    // own: `registerErrorStatus({ toString: 401 })` was rejected with a cause reading `the
+    // framework already maps it to function toString() { [native code] }`.
+    const framework = frameworkStatus(code);
+    if (framework !== undefined) {
+      throw errorStatusInvalid(code, `the framework already maps it to ${framework}`);
     }
     const existing = APP_ERROR_STATUS.get(code);
     if (existing !== undefined && existing !== status) {
@@ -228,15 +278,13 @@ export const registerErrorStatus = (statuses: Readonly<Record<string, number>>):
 /** Test seam. Production registers once at boot and never unregisters. */
 export const resetErrorStatus = (): void => APP_ERROR_STATUS.clear();
 
-/** Every status the app declared, for `x errors list` and the manifest. */
-export const appErrorStatus = (): Readonly<Record<string, number>> =>
-  Object.fromEntries([...APP_ERROR_STATUS].sort(([a], [b]) => a.localeCompare(b)));
-
 // Framework table first: `registerErrorStatus` already refuses those codes, so the order is
 // belt-and-braces — but it is the belt that makes "the framework's statuses are fixed" true
 // even if a future caller reaches the map some other way.
+// `APP_ERROR_STATUS` is a `Map`, which is why its half never had `frameworkStatus`'s defect —
+// prefer one for anything keyed by a value a caller chose.
 export const statusFor = (code: string): number =>
-  ERROR_STATUS[code] ?? APP_ERROR_STATUS.get(code) ?? DEFAULT_STATUS;
+  frameworkStatus(code) ?? APP_ERROR_STATUS.get(code) ?? DEFAULT_STATUS;
 
 /** Everything a renderer (problem+json, overlay, terminal) needs from a throwable. */
 export interface ErrorFacts {
@@ -250,35 +298,43 @@ export interface ErrorFacts {
   readonly stack: string | undefined;
 }
 
-const str = (source: Record<string, unknown>, key: string): string | undefined => {
-  const value = source[key];
-  return typeof value === 'string' && value.length > 0 ? value : undefined;
+/**
+ * One string field off the throwable, through core's `stringField`. The read is a getter call —
+ * or a `Proxy`'s `get` trap — on a value the framework did not build, and it throws in the one
+ * place with nothing left to answer with: `factsOf` is called by the RECOVER stage, and again by
+ * the `problem()` that `recoverWith` degrades to, so a value that refuses to be read took both
+ * renderings and `handle()` rejected against its own contract.
+ */
+const str = (source: unknown, key: string): string | undefined => {
+  const value = stringField(source, key);
+  return value !== undefined && value.length > 0 ? value : undefined;
 };
 
-const asRecord = (value: unknown): Record<string, unknown> =>
-  typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : {};
-
 /**
  * Normalises any throwable into the framework's error contract. Non-Ultimate
  * throwables still get a code and a fix, because "errors are instructions" has to
  * hold for the accidental `TypeError` too.
  */
 export const factsOf = (error: unknown): ErrorFacts => {
-  const record = asRecord(error);
-  const code = str(record, 'code') ?? 'X_INTERNAL';
+  const code = str(error, 'code') ?? 'X_INTERNAL';
   // The error's own title first: every `UltimateError` resolves one from the code registry at
   // construction, so this renders the OWNING package's title — including the codes http only
   // borrows (`X_FORBIDDEN` is policy's, `X_UNAUTHENTICATED` is auth's) and so cannot title itself.
   // Falling through to `message` here shipped the code twice: `X_FORBIDDEN: policy denied… — …`.
   const title =
-    str(record, 'title') ??
-    HTTP_ERROR_TITLES[code as keyof typeof HTTP_ERROR_TITLES] ??
-    str(record, 'message') ??
+    str(error, 'title') ??
+    // `Object.hasOwn` for `statusFor`'s reason, one table over: `code: 'toString'` read the
+    // function off the prototype and put it in `title`, which is rendered into the problem
+    // document and the terminal.
+    (Object.hasOwn(HTTP_ERROR_TITLES, code)
+      ? HTTP_ERROR_TITLES[code as keyof typeof HTTP_ERROR_TITLES]
+      : undefined) ??
+    str(error, 'message') ??
     'unhandled server error';
   // The last fallback is the only one that touches the throwable whole, and every throwable a
   // request produces reaches it. `String()` runs the value's own `toString`, so the value that
   // took the request down took the 500 renderer with it and the server had nothing left to send.
-  const cause = str(record, 'cause') ?? str(record, 'message') ?? renderCauseValue(error);
+  const cause = str(error, 'cause') ?? str(error, 'message') ?? renderCauseValue(error);
   return {
     code,
     title,
@@ -286,11 +342,10 @@ export const factsOf = (error: unknown): ErrorFacts => {
     // `x logs tail` is in `PLANNED_COMMANDS` — it exits `X_NOT_IMPLEMENTED`. A fix line naming a
     // command that throws is axiom 4 inverted: the one instruction the reader is given fails.
     // `x errors explain` ships, and it is the command that answers "what is this code".
-    fix:
-      str(record, 'fix') ?? `x errors explain ${code} --json   # then fix the throwing call site`,
-    docs: str(record, 'docs') ?? `https://ultimate.dev/errors/${code}`,
+    fix: str(error, 'fix') ?? `x errors explain ${code} --json   # then fix the throwing call site`,
+    docs: str(error, 'docs') ?? `https://ultimate.dev/errors/${code}`,
     status: statusFor(code),
-    stack: str(record, 'stack'),
+    stack: str(error, 'stack'),
   };
 };
 

package/src/errors.ts

@@ -160,10 +160,23 @@ export const pathInvalid = (pathname: string, segment: string): HttpError =>
     fix: 'send the segment percent-encoded — encodeURIComponent(value); a literal % is %25',
   });
 
-export const bodyInvalid = (pathname: string, issues: readonly string[]): HttpError =>
+/**
+ * `issues` is the CALLER-facing half and must name only facts the framework itself chose — a
+ * schema rule, a byte count, a content-type the router supports. Anything the caller sent goes in
+ * `meta`, which `toProblem` never renders and `stages.ts` never writes into the log message: a
+ * `cause` reaches the log store as an unredactable field AND the problem document, so a value
+ * baked into it has no key left to redact. The runtime's `SyntaxError` quotes the token it choked
+ * on, which is how a fragment of `{"password": …}` used to travel in both directions at once.
+ */
+export const bodyInvalid = (
+  pathname: string,
+  issues: readonly string[],
+  meta?: Readonly<Record<string, unknown>>,
+): HttpError =>
   new HttpError({
     code: 'X_BODY_INVALID',
     cause: `${pathname} body rejected: ${issues.join('; ')}`,
+    ...(meta === undefined ? {} : { meta }),
     // `x schema show` is not a command — not in the registry and not in `PLANNED_COMMANDS`, so it
     // exits `X_CLI_UNKNOWN_COMMAND`. The same axiom-4 inversion `x logs tail` had in `error-map`:
     // the one instruction the reader is given fails when they run it. `x routes` ships, and

package/src/finalize.ts

@@ -12,6 +12,32 @@ import type { Stage } from './stages';
 /** Renders whatever sits on `ctx.error` into a Response. Never throws, by construction. */
 export type Recover = (request: UltimateRequest, ctx: RequestContext) => Promise<Response>;
 
+/**
+ * The answer when even rendering the problem document failed. Literals and one `new Response`,
+ * calling nothing that could fail in turn — a last resort that shares a code path with the thing
+ * that just broke is not one. Restating the RFC-9457 shape here is the cost of that: the client
+ * still gets a document its parser understands, with a code it can look up.
+ */
+const lastResort = (): Response =>
+  new Response(
+    JSON.stringify({
+      type: 'https://ultimate.dev/errors/X_INTERNAL',
+      title: 'unhandled server error',
+      status: 500,
+      detail: 'the error renderer itself failed, so nothing of the original error survives here',
+      code: 'X_INTERNAL',
+      cause: 'the error renderer itself failed, so nothing of the original error survives here',
+      fix: 'grep the logs for pipeline.problem_failed — it carries the renderer failure this reply could not',
+    }),
+    {
+      status: 500,
+      headers: {
+        'content-type': 'application/problem+json; charset=utf-8',
+        'cache-control': 'no-store',
+      },
+    },
+  );
+
 /**
  * The recover stage is the single place a throw becomes a status — so a throw INSIDE it (an app's
  * `onError` sink, a `devNotices` producer) has nothing left to render it. Rethrowing would break
@@ -26,11 +52,30 @@ export const recoverWith =
       const rendered = await stage?.run(request, ctx);
       if (rendered !== undefined) return rendered;
     } catch (failure) {
-      logger.error(
-        `the recover stage threw and cannot render itself [${ctx.requestId}]: ${String(failure)}`,
-      );
+      // FIELDS, never interpolation — and this is the file whose one promise is that it cannot
+      // itself throw. `String(failure)` runs the value's own coercion, so a null-prototype object
+      // (`Cannot convert object to primitive value`) or a `Proxy` threw a SECOND time out of the
+      // guard, and `handle`'s "always resolves to a Response" died in the one frame with nothing
+      // above it. `logger.emit` degrades a hostile field per key and never rethrows, which is
+      // exactly what a value nobody here built needs; it is also the shape `error-map` already
+      // uses, so the value stays redactable by key.
+      logger.error('pipeline.recover_failed', { requestId: ctx.requestId, error: failure });
+    }
+    // INSIDE a guard, not beside it — and that is this file's whole promise. The line renders a
+    // value nobody here built, so "never throws" rested on every reader below it being total, and
+    // one was not: `statusFor` read `ERROR_STATUS['toString']` off the prototype chain and handed
+    // `new Response(body, { status })` a function, so an app throwing `{ code: 'toString' }` made
+    // `handle()` REJECT from the one frame with nothing above it. That read is fixed in
+    // `error-map.ts`; this guard is what keeps the contract from depending on the next one.
+    try {
+      return problem(ctx.error, { instance: ctx.url.pathname, requestId: ctx.requestId });
+    } catch (failure) {
+      // No `ctx` read in this branch, deliberately: it is reached because reading `ctx` or the
+      // value on it threw, so reaching for one more field is how a guard throws out of the guard.
+      // `logger.emit` degrades a hostile field per key and never rethrows.
+      logger.error('pipeline.problem_failed', { error: failure });
+      return lastResort();
     }
-    return problem(ctx.error, { instance: ctx.url.pathname, requestId: ctx.requestId });
   };
 
 /**

package/src/index.ts

@@ -25,7 +25,6 @@ export type { Deadline } from './deadline';
 export { REQUEST_TIMEOUT_HEADER, resolveTimeoutMs, startDeadline } from './deadline';
 export type { ErrorFacts, ProblemDocument } from './error-map';
 export {
-  appErrorStatus,
   DEFAULT_STATUS,
   ERROR_STATUS,
   factsOf,

package/src/pipeline.ts

@@ -210,6 +210,10 @@ export const createPipeline = (deps: PipelineDeps): Pipeline => {
         config,
         method: raw.method.toUpperCase(),
         pathname: url.pathname,
+        // The caller-went-away half of `ctx.signal`, which `context.ts` documented and nothing
+        // wired: without it a closed tab kept its handler, its pool slot and its vendor
+        // connection alive for the whole `requestTimeoutMs`.
+        clientSignal: raw.signal,
       });
       const forwarded = {
         headers: raw.headers,

package/src/rate-limit.ts

@@ -2,6 +2,7 @@
 // dev/tests and against a shared tier in a multi-replica deployment — installed through
 // `createServer({ rateLimitStore })`, and refused at boot when its scope cannot keep the app's
 // declaration; the bucket maths lives here so every driver agrees on the numbers.
+import { type Clock, systemClock } from '@ultimat3/core';
 import { rateLimited, rateLimitInvalid, rateLimitNotShared, rateLimitScopeUnset } from './errors';
 
 /**
@@ -289,10 +290,20 @@ export interface RateLimiter {
 export const createRateLimiter = (options: {
   config: RateLimitConfig;
   store?: RateLimitStore;
-  now?: () => number;
+  /**
+   * The one source of "now" for the bucket maths. `Date.now()` used to be read inline here, and
+   * BOTH production call sites (`server.ts`, `pipeline.ts`) build their limiter without an
+   * override — so the limiter that actually throttles requests could not be frozen by any test,
+   * while `@ultimat3/auth`'s credential limiter has taken an injected `Clock` since it shipped.
+   * Defaulted rather than required, the same shape as `createRequestContext`'s `init.clock`;
+   * `PipelineDeps.limiter` stays the one seam for handing the pipeline a limiter of your own,
+   * because a second `clock` beside it would be a second way to set one number.
+   */
+  clock?: Clock;
 }): RateLimiter => {
   const store = options.store ?? memoryRateLimitStore();
-  const now = options.now ?? (() => Date.now());
+  const clock = options.clock ?? systemClock;
+  const now = (): number => clock.now().getTime();
   const bucketFor = (name: string): Bucket =>
     options.config.buckets[name] ??
     options.config.buckets[options.config.defaultBucket] ??

package/src/request.ts

@@ -3,7 +3,7 @@
 // context so they cannot drift from what the pipeline resolved.
 
 import type { Actor } from '@ultimat3/core';
-import { readWithinLimit } from '@ultimat3/core';
+import { readWithinLimit, renderThrowable } from '@ultimat3/core';
 import type { RequestContext } from './context';
 import { bodyInvalid, buildSkew } from './errors';
 import { readCookie } from './locale';
@@ -186,7 +186,12 @@ export class UltimateRequest {
         }).formData();
         return Object.fromEntries(form);
       } catch (error) {
-        throw bodyInvalid(this.pathname, [`could not parse ${type}: ${String(error)}`]);
+        // The parser's own message is a diagnostic, not an instruction, and it quotes the bytes
+        // it choked on — so it rides in `meta`, rendered by core rather than by `String(error)`,
+        // which is itself a `TypeError` on a null-prototype throwable.
+        throw bodyInvalid(this.pathname, ['could not parse multipart/form-data'], {
+          parseError: renderThrowable(error),
+        });
       }
     }
 
@@ -198,8 +203,23 @@ export class UltimateRequest {
       }
       if (type.startsWith('text/')) return body;
     } catch (error) {
-      throw bodyInvalid(this.pathname, [`could not parse ${type}: ${String(error)}`]);
+      // `JSON.parse` is the only thing above that throws — `new URLSearchParams(s)` and the
+      // `text/` branch accept any string — so the caller-facing half can name the format without
+      // echoing the `content-type` header the caller chose.
+      throw bodyInvalid(this.pathname, ['could not parse the body as JSON'], {
+        parseError: renderThrowable(error),
+        contentType: type,
+      });
     }
-    throw bodyInvalid(this.pathname, [`unsupported content-type ${type}`]);
+    // The list of what IS accepted, which is the actionable half; the value the caller sent is
+    // theirs already and is a log field here rather than a string in the message.
+    throw bodyInvalid(
+      this.pathname,
+      [
+        'content-type is not one of application/json, application/x-www-form-urlencoded, ' +
+          'multipart/form-data, text/*',
+      ],
+      { contentType: type },
+    );
   }
 }