@ultimat3/http 19.1.2 → 19.2.0

package/CLAUDE.md

@@ -250,9 +250,24 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   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)`:
+  renders for a framework code (`registerProblemMeta` refuses to declare one). 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.
+- **`meta` reaches the document only by declaration — per code, per key, app codes only**
+  (`As of 2026-09-05`). `meta` is the operator-only bag: `bodyInvalid` keeps the body excerpt
+  there, the limiter its internal key, core's `assert` the rejected value, `env-example.ts` file
+  paths, and each of those relies on `toProblem` never rendering it. So "carry `meta`" was never
+  an option, and an app whose `X_SESSION_CHECKOUT_BUSY` put `{ sessionId, title, state }` there
+  had its island recover the id by running a UUID regex over `cause`. `registerProblemMeta({
+  X_SESSION_CHECKOUT_BUSY: ['sessionId', 'title', 'state'] })` (`problem-meta.ts`) is the seam,
+  in `registerErrorStatus`'s shape and refusing what it refuses — a framework-owned code —
+  plus `issues` (one home, one bound) and `__proto__`. `wireMeta` copies the declared keys that
+  are set, member by member through `Object.defineProperty`, all-or-nothing for `issuesOf`'s
+  reason and bounded at `MAX_PROBLEM_META_BYTES`; `toProblem` drops it under exactly the
+  `opaque` condition that blanks `cause`, which is also the belt on "both registrations are
+  needed": a code with keys and no status is unclassified. The typed client
+  (`@ultimat3/action`'s `metaFromWire`) puts the member back on `RemoteActionError.meta`, under
+  the four members that class owns.
 - **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

package/README.md

@@ -342,6 +342,30 @@ identifier a client switches on, per code, with no host to resolve or rot. `docs
 in a table row and a table row has no anchor. Assert against `problemTypeFor` and
 `ERROR_DOCS_URL`, never against a copy of either string.
 
+An error's `meta` is **operator-only by default** and the document never carries it: that bag is
+where `bodyInvalid` keeps the excerpt the parser choked on, where the limiter keeps the internal
+key it promoted an anonymous caller to, and where core's `assert` keeps the rejected value. An app
+that wants a key on the wire declares it, per code, beside the status — and both declarations
+are needed, because a code with no status is an unclassified 5xx whose `meta` is blanked with
+its `cause`:
+
+```ts
+import { registerErrorStatus, registerProblemMeta } from '@ultimat3/http';
+
+registerErrorStatus({ X_SESSION_CHECKOUT_BUSY: 409 });
+registerProblemMeta({ X_SESSION_CHECKOUT_BUSY: ['sessionId', 'title', 'state'] });
+```
+
+The document then carries `meta: { sessionId, title, state }` — the declared keys that are set,
+copied member by member (`__proto__` skipped at every depth), and nothing else off the error. It
+is all-or-nothing, as `issues` is: one value JSON cannot carry (a `Date`, a `bigint`, a class
+instance, a cycle) or a serialisation past `MAX_PROBLEM_META_BYTES` (4096) drops the whole member,
+because a document missing one declared key is a claim the server never made. Absent when no
+declared key is set — never `{}`. A framework-owned code is refused (`X_PROBLEM_META_INVALID`),
+as is `issues`, which has its own top-level home. `@ultimat3/action`'s typed client puts the
+member back on the rebuilt error's `meta`, so an island reads `error.meta.sessionId` where it
+used to run a regex over `cause`.
+
 ## Boundaries
 
 Tier 2. Imports `@ultimat3/core`, `@ultimat3/schema`, `@ultimat3/i18n` and `@ultimat3/time` —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/http",
-  "version": "19.1.2",
+  "version": "19.2.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": "19.1.2",
-    "@ultimat3/i18n": "19.1.2",
-    "@ultimat3/schema": "19.1.2",
-    "@ultimat3/time": "19.1.2"
+    "@ultimat3/core": "19.2.0",
+    "@ultimat3/i18n": "19.2.0",
+    "@ultimat3/schema": "19.2.0",
+    "@ultimat3/time": "19.2.0"
   }
 }

package/src/error-facts.ts

@@ -6,6 +6,7 @@ import { ERROR_DOCS_URL, renderCauseValue, singleLine, stringField } from '@ulti
 import type { ValidationIssue } from '@ultimat3/schema';
 import { declaredStatusFor, statusFor } from './error-map';
 import { HTTP_ERROR_TITLES } from './errors';
+import { type ProblemMeta, problemMetaKeysFor, wireMeta } from './problem-meta';
 
 /** Everything a renderer (problem+json, overlay, terminal) needs from a throwable. */
 export interface ErrorFacts {
@@ -179,6 +180,22 @@ function issuesOf(error: unknown): readonly ValidationIssue[] | undefined {
   }
 }
 
+/**
+ * The declared `meta` keys of a throwable, carried, or `undefined`. The declaration is read by
+ * the CODE — never by the class, which the framework cannot see across a bundle — and the walk
+ * itself is `wireMeta`'s. Total, for `retryAfterOf`'s reason: `meta` is a property read on a
+ * value this package did not build, in the frame that decides what the caller sees.
+ */
+function metaOf(error: unknown, code: string): ProblemMeta | undefined {
+  const keys = problemMetaKeysFor(code);
+  if (keys === undefined || typeof error !== 'object' || error === null) return undefined;
+  try {
+    return wireMeta((error as Record<string, unknown>)['meta'], keys);
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * RFC-9457 `type`, per code. A URN, and deliberately not a URL: `type` is the document's PRIMARY
  * identifier for the problem KIND — a client switches on it — while `docs` is where a human goes
@@ -214,6 +231,14 @@ export interface ProblemDocument {
    * `[]` says "validated clean", which is a different and false claim.
    */
   readonly issues?: readonly ValidationIssue[] | undefined;
+  /**
+   * The keys of the error's `meta` that `registerProblemMeta` declared for its code, JSON-safe
+   * and bounded — and nothing else off `meta`, which is the operator-only bag the rest of this
+   * package keeps OUT of the document (`HttpError`'s doc comment says why). ABSENT when the code
+   * declares none, when none of the declared keys is set, and when one of them cannot be carried
+   * — all-or-nothing, like `issues`, and for its reason.
+   */
+  readonly meta?: ProblemMeta | undefined;
 }
 
 /** The title a caller gets for a failure the framework cannot name. */
@@ -257,6 +282,9 @@ export const toProblem = (
   // withhold — it names the fields and the expectations of something the caller was never meant to
   // see the inside of. `X_INPUT_INVALID` is a declared 4xx, so it is never opaque.
   const issues = opaque ? undefined : issuesOf(error);
+  // The same condition, for the same reason: a code nobody classified cannot have declared any
+  // key either, so this is the belt on `registerProblemMeta`'s "both registrations are needed".
+  const carried = opaque ? undefined : metaOf(error, facts.code);
   return {
     type: problemTypeFor(facts.code),
     title: opaque ? INTERNAL_TITLE : facts.title,
@@ -269,6 +297,7 @@ export const toProblem = (
     docs: facts.docs,
     requestId: meta.requestId,
     ...(issues === undefined ? {} : { issues }),
+    ...(carried === undefined ? {} : { meta: carried }),
   };
 };
 

package/src/error-map.ts

@@ -31,6 +31,7 @@ export const ERROR_STATUS = {
   // and declaring a status the framework already owns. 500 is the honest answer to either.
   X_NO_REQUEST: 500,
   X_ERROR_STATUS_INVALID: 500,
+  X_PROBLEM_META_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.
@@ -338,6 +339,14 @@ export const ERROR_STATUS = {
   // runtime and makes that answer a reviewed one instead of an accident, which is the whole reason
   // this table is closed.
   X_UI_FORM_PATH_INVALID: 500,
+  // @ultimat3/render — an island handed props it cannot carry: an undeclared key, a value that is
+  // not JSON, or a bag over `ISLAND_PROPS_MAX_BYTES`. The author's fault and never the caller's,
+  // so 500 is the honest class — and it HAS to be a declared 500. Without a row the code was an
+  // unclassified failure, and `toProblem` blanks the cause of one of those outside dev
+  // (`isUnclassifiedFailure`): a 34-row catalog over the cap took a page down with a problem
+  // document that said "the details are in this process's logs" about an error whose whole
+  // value is the sentence naming the prop and its bytes. Measured on ai-maxxing, 2026-09-05.
+  X_ISLAND_PROPS_INVALID: 500,
   // @ultimat3/mail
   // The deployment configured no transport. It reaches a caller only through an inline
   // `send(…, { sync: true })` inside a request; the queued path dead-letters instead. A server-side

package/src/errors.ts

@@ -22,6 +22,7 @@ export const HTTP_OWNED_ERROR_CODES = [
   'X_PIPELINE_FINALIZE_FAILED',
   'X_NO_REQUEST',
   'X_ERROR_STATUS_INVALID',
+  'X_PROBLEM_META_INVALID',
   'X_CORS_CONFIG_INVALID',
   'X_CSP_DIRECTIVE_INVALID',
   'X_RATE_LIMIT_NOT_SHARED',
@@ -84,6 +85,7 @@ export const HTTP_ERROR_TITLES: Readonly<Record<HttpOwnedErrorCode, string>> = {
   X_PIPELINE_FINALIZE_FAILED: 'a finalize stage threw instead of finishing the response',
   X_NO_REQUEST: 'the inbound request is not in scope here',
   X_ERROR_STATUS_INVALID: 'an error code cannot be mapped to that status',
+  X_PROBLEM_META_INVALID: 'a problem document cannot carry that meta declaration',
   X_CORS_CONFIG_INVALID: 'the cors config can never produce a working response',
   X_CSP_DIRECTIVE_INVALID: 'a csp extension would emit something other than the directive it names',
   X_RATE_LIMIT_NOT_SHARED: 'the rate limit is declared fleet-wide and the store is per-process',
@@ -240,7 +242,11 @@ export const buildSkew = (clientBuildId: string, serverBuildId: string): HttpErr
   new HttpError({
     code: 'X_BUILD_SKEW',
     cause: `client sent build ${clientBuildId}, server is running ${serverBuildId}`,
-    fix: 'reload the page — the service worker will fetch the new build manifest',
+    // Not "reload": a reload re-enters the same service worker, which stamps the same stale
+    // id and earns this same refusal. The worker heals itself on this response (it needs the
+    // `x-ultimate-build` header the `context` stage stamps beside this throw); a client with
+    // no worker only ever sees this once, on the request that carried a stale id by hand.
+    fix: 'the service worker recovers on this response; a stale tab that cannot, clears its registration',
   });
 
 export const serverNotStarted = (member: string): HttpError =>
@@ -292,6 +298,18 @@ export const errorStatusInvalid = (code: string, reason: string): HttpError =>
     fix: `x errors list --json   # then registerErrorStatus({ ${code}: 422 }) with a status the framework does not already own`,
   });
 
+/**
+ * At boot, beside `errorStatusInvalid` and for the same class of mistake: a declaration the
+ * document could never honour — a framework-owned code, whose `meta` is operator-only; a key that
+ * is not one (`issues` rides at the top level already); or a second, different list for one code.
+ */
+export const problemMetaInvalid = (code: string, reason: string): HttpError =>
+  new HttpError({
+    code: 'X_PROBLEM_META_INVALID',
+    cause: `${code} cannot carry that meta: ${reason}`,
+    fix: `registerProblemMeta({ ${code}: ['<key>'] }) with the keys this app's error puts in meta, beside its registerErrorStatus() call`,
+  });
+
 /**
  * At `defineHttpConfig`, never on the request. A CORS pair a browser can never accept resolves to
  * "emit no CORS headers at all", which is unreadable from the console: every cross-origin call

package/src/index.ts

@@ -115,6 +115,8 @@ export type { PeerIdentity } from './peer-identity';
 export { peerIdentity } from './peer-identity';
 export type { HandleInit, Pipeline, PipelineDeps } from './pipeline';
 export { createPipeline, PIPELINE_STAGES } from './pipeline';
+export type { ProblemMeta, ProblemMetaValue } from './problem-meta';
+export { MAX_PROBLEM_META_BYTES, registerProblemMeta, resetProblemMeta } from './problem-meta';
 export type {
   Bucket,
   MemoryRateLimitStore,

package/src/problem-meta.ts

@@ -0,0 +1,197 @@
+// Which of an error's `meta` keys a problem document may carry, per code — and the copy of them
+// that leaves the process. Split from `error-map.ts` (457 lines against the 500-line ceiling) and
+// kept beside it in shape: `registerErrorStatus` is the app's declaration of the HTTP half of a
+// code, and this is the second half of the same declaration, written in the same file of the app.
+//
+// OPT-IN, PER KEY, BY CODE — never "carry `meta`". `meta` is the framework's OPERATOR-ONLY bag
+// and four packages depend on it never reaching a caller: `bodyInvalid` puts the fragment of the
+// body the parser choked on there (a `{"password": …}` excerpt, once), the rate limiter puts the
+// internal key it promoted an anonymous caller to, core's `assert` puts the rejected VALUE, and
+// `env-example.ts` puts file paths. A blanket carry would have shipped every one of them to the
+// network tab. So an app names the keys, for the codes it owns, and everything else stays where
+// it was. Measured need: an app's `X_SESSION_CHECKOUT_BUSY` carried `{ sessionId, title, state }`
+// in `meta` and its island recovered the id by running a UUID regex over `cause`.
+
+import { ERROR_STATUS } from './error-map';
+import { problemMetaInvalid } from './errors';
+
+/** What a problem document's `meta` member holds — JSON, and nothing JSON cannot carry. */
+export type ProblemMetaValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly ProblemMetaValue[]
+  | { readonly [key: string]: ProblemMetaValue };
+
+export type ProblemMeta = Readonly<Record<string, ProblemMetaValue>>;
+
+/**
+ * The serialised ceiling, in bytes, of what a document carries under `meta`. A problem body is a
+ * refusal, not a payload: `MAX_PROBLEM_ISSUES` bounds the other extension for the same reason.
+ * Over the cap the member is dropped WHOLE, never cut — a subset of keys is a claim the server
+ * never made, and a client reading `meta.sessionId` off a document that dropped `sessionId` to
+ * make room has no way to tell "absent" from "cut".
+ */
+export const MAX_PROBLEM_META_BYTES = 4096;
+
+/**
+ * A key is spelled the way a code's `meta` key is spelled in source. `issues` is refused by name
+ * because it already has a top-level home (`ProblemDocument.issues`, parsed and bounded on its
+ * own terms), and a second copy under `meta.issues` is two places for a client to read one fact.
+ * `__proto__` is refused because `JSON.parse` on the receiving side mints it as a real own key.
+ */
+const KEY = /^[A-Za-z_$][\w$]*$/;
+const RESERVED_KEYS: ReadonlySet<string> = new Set(['issues', '__proto__']);
+
+/** Per app-owned code, the `meta` keys its documents carry. A `Map`, for `APP_ERROR_STATUS`'s reason. */
+const DECLARED = new Map<string, readonly string[]>();
+
+const sameKeys = (left: readonly string[], right: readonly string[]): boolean =>
+  left.length === right.length && left.every((key, at) => key === right[at]);
+
+/**
+ * Declare, per code, which `meta` keys the problem document carries. Call it once at boot, in
+ * the module that declares the codes — beside `registerErrorStatus`, and BOTH are needed: a code
+ * with no declared status is an unclassified 5xx, and `toProblem` blanks everything but the code
+ * and the request id on one of those, `meta` included.
+ *
+ * ```ts
+ * registerErrorStatus({ X_SESSION_CHECKOUT_BUSY: 409 });
+ * registerProblemMeta({ X_SESSION_CHECKOUT_BUSY: ['sessionId', 'title', 'state'] });
+ * ```
+ *
+ * Framework-owned codes are refused, exactly as `registerErrorStatus` refuses them: their `meta`
+ * is where the framework keeps what a caller must not be handed, and an app that could declare
+ * `X_RATE_LIMITED: ['key']` would publish the limiter's internal key on every 429.
+ */
+export const registerProblemMeta = (
+  declarations: Readonly<Record<string, readonly string[]>>,
+): void => {
+  for (const [code, keys] of Object.entries(declarations)) {
+    if (frameworkOwns(code)) {
+      throw problemMetaInvalid(code, 'the framework owns that code, and its meta is operator-only');
+    }
+    if (keys.length === 0) {
+      throw problemMetaInvalid(code, 'the key list is empty — omit the code instead');
+    }
+    for (const key of keys) {
+      if (typeof key !== 'string' || !KEY.test(key)) {
+        throw problemMetaInvalid(code, `${JSON.stringify(key)} is not a meta key`);
+      }
+      if (RESERVED_KEYS.has(key)) {
+        throw problemMetaInvalid(
+          code,
+          key === 'issues'
+            ? '`issues` already rides at the top level of the document'
+            : `\`${key}\` is not a key a document may carry`,
+        );
+      }
+    }
+    const existing = DECLARED.get(code);
+    if (existing !== undefined && !sameKeys(existing, keys)) {
+      throw problemMetaInvalid(code, `already declared as [${existing.join(', ')}] by this app`);
+    }
+    DECLARED.set(code, [...keys]);
+  }
+};
+
+/** Test seam. Production registers once at boot and never unregisters. */
+export const resetProblemMeta = (): void => DECLARED.clear();
+
+/** The keys declared for a code, or `undefined` when nothing was — which is every framework code. */
+export const problemMetaKeysFor = (code: string): readonly string[] | undefined =>
+  DECLARED.get(code);
+
+/**
+ * A code this package's table maps is the framework's. A `Set` of the table's own keys, for the
+ * reason `frameworkStatus` reads that table through `Object.hasOwn`: it is an object literal,
+ * and `registerProblemMeta({ toString: [...] })` must not find a function in it.
+ */
+const FRAMEWORK_CODES: ReadonlySet<string> = new Set(Object.keys(ERROR_STATUS));
+const frameworkOwns = (code: string): boolean => FRAMEWORK_CODES.has(code);
+
+/**
+ * The declared keys of `meta`, copied member by member into a fresh document, or `undefined`.
+ *
+ * TOTAL — `meta` is a property read on a value this package did not build, in the frame that
+ * decides what the caller sees (`retryAfterOf`'s reason). ALL-OR-NOTHING, for `issuesOf`'s
+ * reason: a document carrying `sessionId` and silently missing `state` is a claim the server
+ * never made. So one value JSON cannot carry — a function, a `bigint`, a `Date`, a class
+ * instance, a non-finite number, a cycle — drops the WHOLE member, and so does a serialisation
+ * past `MAX_PROBLEM_META_BYTES`. A structural walk and never a `JSON.stringify` round trip: the
+ * round trip drops a function and an `undefined` SILENTLY, which is the footgun rather than the
+ * check (`@ultimat3/render`'s `island-props.ts` walks for the same reason).
+ *
+ * ABSENT when nothing survives — never `{}`. `{}` says "the server declared meta and had none",
+ * which a client cannot tell from "the server carries no meta for this code".
+ */
+export function wireMeta(source: unknown, keys: readonly string[]): ProblemMeta | undefined {
+  try {
+    if (typeof source !== 'object' || source === null) return undefined;
+    const meta = source as Record<string, unknown>;
+    const out: Record<string, ProblemMetaValue> = {};
+    let carried = 0;
+    for (const key of keys) {
+      if (!Object.hasOwn(meta, key)) continue;
+      const value = jsonSafe(meta[key], new Set());
+      if (value === MISSING) return undefined;
+      define(out, key, value);
+      carried += 1;
+    }
+    if (carried === 0) return undefined;
+    const bytes = new TextEncoder().encode(JSON.stringify(out)).byteLength;
+    return bytes > MAX_PROBLEM_META_BYTES ? undefined : out;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The one value the walk cannot answer with, distinct from the `null` JSON can carry. */
+const MISSING: unique symbol = Symbol('problem-meta.missing');
+
+/**
+ * A plain own data property, whatever the name: `out[key] = value` for the one name `__proto__`
+ * runs `Object.prototype`'s setter instead of adding a key. `registerProblemMeta` refuses that
+ * name at the top level; a NESTED object off the error is walked here with the same care, and
+ * the key is skipped outright — the receiving `JSON.parse` would mint it as an own key again.
+ */
+function define(out: Record<string, ProblemMetaValue>, key: string, value: ProblemMetaValue): void {
+  Object.defineProperty(out, key, { value, writable: true, enumerable: true, configurable: true });
+}
+
+function jsonSafe(value: unknown, seen: Set<object>): ProblemMetaValue | typeof MISSING {
+  if (value === null) return null;
+  if (typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number') return Number.isFinite(value) ? value : MISSING;
+  if (typeof value !== 'object') return MISSING;
+  if (seen.has(value)) return MISSING;
+  seen.add(value);
+  let out: ProblemMetaValue | typeof MISSING = MISSING;
+  if (Array.isArray(value)) {
+    const items: ProblemMetaValue[] = [];
+    for (const item of value as readonly unknown[]) {
+      const safe = jsonSafe(item, seen);
+      if (safe === MISSING) return MISSING;
+      items.push(safe);
+    }
+    out = items;
+  } else if (isPlainObject(value)) {
+    const record: Record<string, ProblemMetaValue> = {};
+    for (const [key, item] of Object.entries(value)) {
+      if (key === '__proto__') continue;
+      const safe = jsonSafe(item, seen);
+      if (safe === MISSING) return MISSING;
+      define(record, key, safe);
+    }
+    out = record;
+  }
+  seen.delete(value);
+  return out;
+}
+
+/** A `Date`, a `Map`, an error, a class instance: each serialises to something other than itself. */
+function isPlainObject(value: object): value is Record<string, unknown> {
+  const proto: unknown = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}

package/src/stages.ts

@@ -160,6 +160,11 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
       if (answered !== undefined) return answered;
 
       ctx.clientBuildId = request.header(config.buildIdHeader);
+      // Stamped BEFORE the assertion, so the refusal carries it too. A skew answer that
+      // withholds the server's own id tells a client it is stale without telling it what to
+      // become — and the one caller that can act on that, the service worker holding the
+      // stale id, then has no way to tell this 409 from any other.
+      if (config.buildId !== null) ctx.headers.set(config.buildIdHeader, config.buildId);
       request.assertBuild();
 
       const pathname = stripBasePath(ctx.url.pathname, config.basePath);