@ultimat3/http 2.0.0 → 3.0.0

package/CLAUDE.md

@@ -156,7 +156,12 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 - 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 +192,17 @@ 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.
 - **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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/http",
-  "version": "2.0.0",
+  "version": "3.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": "3.0.0",
+    "@ultimat3/i18n": "3.0.0",
+    "@ultimat3/schema": "3.0.0",
+    "@ultimat3/time": "3.0.0"
   }
 }

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';
 
 /**
@@ -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,
@@ -228,10 +232,6 @@ 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.
@@ -250,35 +250,38 @@ 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') ??
+    str(error, 'title') ??
     HTTP_ERROR_TITLES[code as keyof typeof HTTP_ERROR_TITLES] ??
-    str(record, 'message') ??
+    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 +289,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/finalize.ts

@@ -26,9 +26,14 @@ 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 });
     }
     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,