@ultimat3/http 11.2.0 → 12.0.0

package/src/error-facts.ts

@@ -0,0 +1,193 @@
+// Every RENDERING of a throwable the framework has: the normalised facts, the RFC-9457 problem
+// 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 { declaredStatusFor, statusFor } from './error-map';
+import { HTTP_ERROR_TITLES } from './errors';
+
+/** Everything a renderer (problem+json, overlay, terminal) needs from a throwable. */
+export interface ErrorFacts {
+  readonly code: string;
+  readonly title: string;
+  readonly cause: string;
+  readonly fix: string;
+  readonly docs: string;
+  readonly status: number;
+  /** Present only when the process is in dev mode; never sent to a client in prod. */
+  readonly stack: string | 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;
+};
+
+/**
+ * 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 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(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(error, 'cause') ?? str(error, 'message') ?? renderCauseValue(error);
+  return {
+    code,
+    title,
+    cause,
+    // `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`,
+    // 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
+    // not build — and it must not be the `https://ultimate.dev/errors/<code>` link that answered
+    // 404 on every problem document this package has ever rendered.
+    docs: str(error, 'docs') ?? ERROR_DOCS_URL,
+    status: statusFor(code),
+    stack: str(error, 'stack'),
+  };
+};
+
+/**
+ * `Retry-After`, in whole seconds, for a refusal that computed one — or `undefined`.
+ *
+ * The contract it reads is already written down by the packages BELOW this one: `@ultimat3/auth`'s
+ * `kdfOverloaded` says "`retryAfterSeconds` rides in `meta` because this package cannot reach an
+ * HTTP header; the host reads it onto `Retry-After`", and `rateLimited` in this package carries the
+ * same field. Nothing was the host. So a 503 shed by the KDF gate and a 429 from an account lockout
+ * both told the caller to come back and never said when — which is the shed-with-no-delay pattern
+ * the `admit` stage exists to avoid, one layer in.
+ *
+ * Total, for `str`'s reason one function up: `meta` is a property read on a value this package did
+ * not build, and it is read in the frame that decides what the caller sees.
+ */
+export function retryAfterOf(error: unknown): number | undefined {
+  if (typeof error !== 'object' || error === null) return undefined;
+  try {
+    const meta: unknown = (error as Record<string, unknown>)['meta'];
+    if (typeof meta !== 'object' || meta === null) return undefined;
+    const seconds: unknown = (meta as Record<string, unknown>)['retryAfterSeconds'];
+    if (typeof seconds !== 'number' || !Number.isFinite(seconds) || seconds < 0) return undefined;
+    // At least one second, exactly as `RateLimitDecision.retryAfterSeconds` is clamped: `0` reads
+    // as "retry now", which is the stampede a Retry-After exists to spread.
+    return Math.max(1, Math.ceil(seconds));
+  } 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
+ * to read about it, and those stopped being the same string when `docs` became one wiki page for
+ * every code. Collapsing `type` onto that page too would have given a 422 body-invalid and a 403
+ * forbidden the same identifier, which is the one thing a `type` may not do.
+ *
+ * A URN has no host to resolve, so it cannot rot the way `https://ultimate.dev/errors/<code>` did
+ * — it was never dereferenceable and never claimed to be, which RFC 9457 §3.1.1 explicitly allows.
+ * `code` carries the same string as a plain member for a reader that would rather not parse a URI.
+ */
+export const problemTypeFor = (code: string): string => `urn:ultimate:error:${singleLine(code)}`;
+
+/** RFC-9457 problem document. `code`/`cause`/`fix`/`docs` are our extensions. */
+export interface ProblemDocument {
+  readonly type: string;
+  readonly title: string;
+  readonly status: number;
+  readonly detail: string;
+  readonly instance: string | undefined;
+  readonly code: string;
+  readonly cause: string;
+  readonly fix: string;
+  readonly docs: string;
+  readonly requestId: string | undefined;
+}
+
+/** The title a caller gets for a failure the framework cannot name. */
+const INTERNAL_TITLE = 'unhandled server error';
+
+/**
+ * The cause a caller gets for one. An unclassified 5xx has no `cause` of its own, so `factsOf`
+ * falls through to the throwable's `message` — a driver's DSN, the row Postgres rejected, an
+ * absolute path — and `toProblem` handed it to whoever asked. `error-page.ts` locked the BROWSER
+ * out of exactly this and said so in its header; the two audiences then disagreed about one
+ * condition. The real text is not lost: the `error-map` stage logs it as a redactable FIELD and
+ * reports every 5xx to the error monitor, both keyed by the request id below.
+ */
+const INTERNAL_CAUSE =
+  'the server failed while handling this request; the details are in this process\u2019s logs and ' +
+  'error reports, under this request id';
+
+/**
+ * A 5xx nobody declared a status for — not the framework's table, not the app's
+ * `registerErrorStatus` — or one whose code is `X_INTERNAL`. That is the discriminator, and not
+ * `status >= 500` alone: a declared code has an authored cause, and blanking `X_DRAINING`'s would
+ * take away the one instruction in it.
+ *
+ * `X_INTERNAL` is in the framework's table and still belongs here, because it is the framework's
+ * own word for "nobody classified this": `factsOf` mints it for a throwable carrying no code, and
+ * core's `toError()` wraps a caught value into an `InternalError` whose cause is
+ * `renderCauseValue(value)` — the driver's message, verbatim. Nothing in an `X_INTERNAL` is
+ * actionable by the caller; the code and the request id are.
+ */
+const isUnclassifiedFailure = (code: string, status: number): boolean =>
+  status >= 500 && (code === 'X_INTERNAL' || declaredStatusFor(code) === undefined);
+
+export const toProblem = (
+  error: unknown,
+  meta: { instance?: string; requestId?: string; dev?: boolean } = {},
+): ProblemDocument => {
+  const facts = factsOf(error);
+  const opaque = meta.dev !== true && isUnclassifiedFailure(facts.code, facts.status);
+  return {
+    type: problemTypeFor(facts.code),
+    title: opaque ? INTERNAL_TITLE : facts.title,
+    status: facts.status,
+    detail: opaque ? INTERNAL_CAUSE : facts.cause,
+    instance: meta.instance,
+    code: facts.code,
+    cause: opaque ? INTERNAL_CAUSE : facts.cause,
+    fix: facts.fix,
+    docs: facts.docs,
+    requestId: meta.requestId,
+  };
+};
+
+/** The exact three lines the terminal prints, reused by the overlay and `--json`. */
+export const renderErrorLines = (error: unknown): string => {
+  const facts = factsOf(error);
+  // The newlines here are the format's own. Every interpolated field goes through `singleLine`
+  // so a caller-controlled value cannot add a third one — this string is rendered into the dev
+  // overlay's `<pre>`, where HTML escaping does not help because a newline is not markup.
+  return [
+    `${singleLine(facts.code)}: ${singleLine(facts.title)}`,
+    `  cause: ${singleLine(facts.cause)}`,
+    `  fix:   ${singleLine(facts.fix)}`,
+  ].join('\n');
+};

package/src/error-map.ts

@@ -1,8 +1,8 @@
 // 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 { ERROR_DOCS_URL, renderCauseValue, singleLine, stringField } from '@ultimat3/core';
-import { errorStatusInvalid, HTTP_ERROR_TITLES } from './errors';
+// Rendering a throwable for a reader is `error-facts.ts`; this file answers only the status.
+import { errorStatusInvalid } from './errors';
 
 /**
  * code -> status. Codes owned by other packages are listed here on purpose: HTTP
@@ -48,8 +48,10 @@ export const ERROR_STATUS = {
   X_RATE_LIMIT_BUCKET_CONFLICT: 500,
   // Construction time as well: the limiter installed cannot enforce a bucket a route declares.
   X_RATE_LIMIT_BUCKET_UNBOUND: 500,
-  // `defineHttpConfig` time, both of them: a declaration the deployment owes and did not make.
+  // `defineHttpConfig` time, all three: a declaration the deployment owes and did not make, or
+  // made against a bucket nothing declares.
   X_RATE_LIMIT_SCOPE_UNSET: 500,
+  X_RATE_LIMIT_TENANT_BUCKET_UNKNOWN: 500,
   X_TRUST_PROXY_UNSET: 500,
   // Raised by `toBucket` while a route or an action is being projected, never on the request.
   X_RATE_LIMIT_INVALID: 500,
@@ -138,6 +140,23 @@ export const ERROR_STATUS = {
   // signed-in caller to a sign-in page that cannot give them a tenant.
   X_TENANCY_ACTOR_ORG_REQUIRED: 403,
   X_TENANCY_CROSS_DENIED: 403,
+  // The three aggregate refusals, all 500 and all deliberately NOT a 4xx, for the reason
+  // `X_QUERY_NOT_PAGEABLE` below is one: nothing the caller sends changes the answer, and the fix
+  // is an edit to the read itself. They earn ROWS rather than a pin in `scripts/error-map-backlog.ts`
+  // because each carries an instruction the app's author needs and an unmapped 5xx is blanked —
+  // `toProblem` replaces an undeclared code's cause with `INTERNAL_CAUSE`, so pinning them would
+  // answer "the server failed while handling this request" for a fault whose own `fix:` names the
+  // exact call to write instead. A row costs no extra page: `stages.ts` reports every `status >= 500`
+  // either way.
+  //
+  // Reached with a request waiting, all three, which is why they are not in the backlog's entity
+  // group ("misuse a handler's author makes") — the mixed-currency and the ±2^53 refusals are
+  // decided by the ROWS, so a read that answered for two years starts failing on the day the data
+  // crosses the line, and `approximateCount()` on a chain whose predicates came from the caller's
+  // own optional filters is one query string away.
+  X_AGGREGATE_UNSUPPORTED: 500,
+  X_AGGREGATE_MIXED_CURRENCY: 500,
+  X_APPROXIMATE_COUNT_FILTERED: 500,
   // @ultimat3/db — the constraints a request trips, both 409. db's own `fix:` for the unique
   // violation says "answer 409, which is what a raced signup is", and `X_ENTITY_DUPLICATE` — the
   // same event one layer up — is 409 above; a foreign key rides with it because both halves of it
@@ -216,6 +235,14 @@ export const ERROR_STATUS = {
   // configuration fault either way, so 500 and never a 4xx — nothing the caller sent is wrong, and
   // this is exactly the condition somebody should be paged for.
   X_MAIL_CREDENTIAL_MISSING: 500,
+  // @ultimat3/mcp — the one MCP code that is answered on a REQUEST rather than inside a JSON-RPC
+  // envelope, which is what the rest of that package's backlog group says about the others: the
+  // transport refused before dispatch, so there is no call to answer. 429 because
+  // `mcpHttpRoute` already builds that response by hand (`transport-http.ts`'s `throttled`), with
+  // `retry-after` beside it. The row is what keeps the two surfaces from disagreeing the day the
+  // MCP host is mounted inside this pipeline — a code that renders 429 on one and 500 on the other
+  // is exactly the split this table exists to prevent.
+  X_MCP_RATE_LIMITED: 429,
   // @ultimat3/core
   // The caller asked for a format the pipeline cannot produce (`?f=avif`): the request names an
   // unsupported representation, which is 415 — not a 500, which would blame the server for it.
@@ -303,197 +330,19 @@ 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();
 
-// 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 =>
-  frameworkStatus(code) ?? APP_ERROR_STATUS.get(code) ?? DEFAULT_STATUS;
-
-/** Everything a renderer (problem+json, overlay, terminal) needs from a throwable. */
-export interface ErrorFacts {
-  readonly code: string;
-  readonly title: string;
-  readonly cause: string;
-  readonly fix: string;
-  readonly docs: string;
-  readonly status: number;
-  /** Present only when the process is in dev mode; never sent to a client in prod. */
-  readonly stack: string | 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;
-};
-
-/**
- * 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 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(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(error, 'cause') ?? str(error, 'message') ?? renderCauseValue(error);
-  return {
-    code,
-    title,
-    cause,
-    // `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`,
-    // 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
-    // not build — and it must not be the `https://ultimate.dev/errors/<code>` link that answered
-    // 404 on every problem document this package has ever rendered.
-    docs: str(error, 'docs') ?? ERROR_DOCS_URL,
-    status: statusFor(code),
-    stack: str(error, 'stack'),
-  };
-};
-
-/**
- * `Retry-After`, in whole seconds, for a refusal that computed one — or `undefined`.
- *
- * The contract it reads is already written down by the packages BELOW this one: `@ultimat3/auth`'s
- * `kdfOverloaded` says "`retryAfterSeconds` rides in `meta` because this package cannot reach an
- * HTTP header; the host reads it onto `Retry-After`", and `rateLimited` in this package carries the
- * same field. Nothing was the host. So a 503 shed by the KDF gate and a 429 from an account lockout
- * both told the caller to come back and never said when — which is the shed-with-no-delay pattern
- * the `admit` stage exists to avoid, one layer in.
- *
- * Total, for `str`'s reason one function up: `meta` is a property read on a value this package did
- * not build, and it is read in the frame that decides what the caller sees.
- */
-export function retryAfterOf(error: unknown): number | undefined {
-  if (typeof error !== 'object' || error === null) return undefined;
-  try {
-    const meta: unknown = (error as Record<string, unknown>)['meta'];
-    if (typeof meta !== 'object' || meta === null) return undefined;
-    const seconds: unknown = (meta as Record<string, unknown>)['retryAfterSeconds'];
-    if (typeof seconds !== 'number' || !Number.isFinite(seconds) || seconds < 0) return undefined;
-    // At least one second, exactly as `RateLimitDecision.retryAfterSeconds` is clamped: `0` reads
-    // as "retry now", which is the stampede a Retry-After exists to spread.
-    return Math.max(1, Math.ceil(seconds));
-  } 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
- * to read about it, and those stopped being the same string when `docs` became one wiki page for
- * every code. Collapsing `type` onto that page too would have given a 422 body-invalid and a 403
- * forbidden the same identifier, which is the one thing a `type` may not do.
- *
- * A URN has no host to resolve, so it cannot rot the way `https://ultimate.dev/errors/<code>` did
- * — it was never dereferenceable and never claimed to be, which RFC 9457 §3.1.1 explicitly allows.
- * `code` carries the same string as a plain member for a reader that would rather not parse a URI.
- */
-export const problemTypeFor = (code: string): string => `urn:ultimate:error:${singleLine(code)}`;
-
-/** RFC-9457 problem document. `code`/`cause`/`fix`/`docs` are our extensions. */
-export interface ProblemDocument {
-  readonly type: string;
-  readonly title: string;
-  readonly status: number;
-  readonly detail: string;
-  readonly instance: string | undefined;
-  readonly code: string;
-  readonly cause: string;
-  readonly fix: string;
-  readonly docs: string;
-  readonly requestId: string | undefined;
-}
-
-/** The title a caller gets for a failure the framework cannot name. */
-const INTERNAL_TITLE = 'unhandled server error';
-
-/**
- * The cause a caller gets for one. An unclassified 5xx has no `cause` of its own, so `factsOf`
- * falls through to the throwable's `message` — a driver's DSN, the row Postgres rejected, an
- * absolute path — and `toProblem` handed it to whoever asked. `error-page.ts` locked the BROWSER
- * out of exactly this and said so in its header; the two audiences then disagreed about one
- * condition. The real text is not lost: the `error-map` stage logs it as a redactable FIELD and
- * reports every 5xx to the error monitor, both keyed by the request id below.
- */
-const INTERNAL_CAUSE =
-  'the server failed while handling this request; the details are in this process\u2019s logs and ' +
-  'error reports, under this request id';
-
 /**
- * A 5xx nobody declared a status for — not the framework's table, not the app's
- * `registerErrorStatus` — or one whose code is `X_INTERNAL`. That is the discriminator, and not
- * `status >= 500` alone: a declared code has an authored cause, and blanking `X_DRAINING`'s would
- * take away the one instruction in it.
+ * The status SOMEBODY declared for a code — the framework or the app — or `undefined` when
+ * nobody did. The two questions `statusFor` used to answer at once are separate on purpose:
+ * "what do we answer" is always a number, and "did anyone classify this" is what `error-facts.ts`
+ * reads to decide whether a 5xx may carry the throwable's own words back to the caller.
  *
- * `X_INTERNAL` is in the framework's table and still belongs here, because it is the framework's
- * own word for "nobody classified this": `factsOf` mints it for a throwable carrying no code, and
- * core's `toError()` wraps a caught value into an `InternalError` whose cause is
- * `renderCauseValue(value)` — the driver's message, verbatim. Nothing in an `X_INTERNAL` is
- * actionable by the caller; the code and the request id are.
+ * 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.
  */
-const isUnclassifiedFailure = (code: string, status: number): boolean =>
-  status >= 500 &&
-  (code === 'X_INTERNAL' || (frameworkStatus(code) === undefined && !APP_ERROR_STATUS.has(code)));
+export const declaredStatusFor = (code: string): number | undefined =>
+  frameworkStatus(code) ?? APP_ERROR_STATUS.get(code);
 
-export const toProblem = (
-  error: unknown,
-  meta: { instance?: string; requestId?: string; dev?: boolean } = {},
-): ProblemDocument => {
-  const facts = factsOf(error);
-  const opaque = meta.dev !== true && isUnclassifiedFailure(facts.code, facts.status);
-  return {
-    type: problemTypeFor(facts.code),
-    title: opaque ? INTERNAL_TITLE : facts.title,
-    status: facts.status,
-    detail: opaque ? INTERNAL_CAUSE : facts.cause,
-    instance: meta.instance,
-    code: facts.code,
-    cause: opaque ? INTERNAL_CAUSE : facts.cause,
-    fix: facts.fix,
-    docs: facts.docs,
-    requestId: meta.requestId,
-  };
-};
-
-/** The exact three lines the terminal prints, reused by the overlay and `--json`. */
-export const renderErrorLines = (error: unknown): string => {
-  const facts = factsOf(error);
-  // The newlines here are the format's own. Every interpolated field goes through `singleLine`
-  // so a caller-controlled value cannot add a third one — this string is rendered into the dev
-  // overlay's `<pre>`, where HTML escaping does not help because a newline is not markup.
-  return [
-    `${singleLine(facts.code)}: ${singleLine(facts.title)}`,
-    `  cause: ${singleLine(facts.cause)}`,
-    `  fix:   ${singleLine(facts.fix)}`,
-  ].join('\n');
-};
+export const statusFor = (code: string): number => declaredStatusFor(code) ?? DEFAULT_STATUS;

package/src/errors.ts

@@ -30,6 +30,7 @@ export const HTTP_OWNED_ERROR_CODES = [
   'X_RATE_LIMIT_SCOPE_UNSET',
   'X_RATE_LIMIT_INVALID',
   'X_RATE_LIMIT_STORE_UNAVAILABLE',
+  'X_RATE_LIMIT_TENANT_BUCKET_UNKNOWN',
   'X_TRUST_PROXY_UNSET',
   'X_OVERLOADED',
   'X_CSRF_BLOCKED',
@@ -83,6 +84,7 @@ export const HTTP_ERROR_TITLES: Readonly<Record<HttpOwnedErrorCode, string>> = {
   X_RATE_LIMIT_SCOPE_UNSET: 'the deployment has not said where the rate limiter keeps its counters',
   X_RATE_LIMIT_INVALID: 'a declared rate limit computes to numbers the limiter cannot run on',
   X_RATE_LIMIT_STORE_UNAVAILABLE: 'the shared rate-limit store did not answer, so nothing decided',
+  X_RATE_LIMIT_TENANT_BUCKET_UNKNOWN: 'the tenant allowance names a bucket nothing declares',
   X_TRUST_PROXY_UNSET: 'proxy headers are trusted without saying how many proxies are in front',
   X_OVERLOADED: 'in-flight requests are at the configured ceiling',
   X_CSRF_BLOCKED: 'a credentialed write arrived from an origin that is not allowed to make it',
@@ -289,7 +291,7 @@ export const corsConfigInvalid = (reason: string): HttpError =>
   new HttpError({
     code: 'X_CORS_CONFIG_INVALID',
     cause: `cors config rejected: ${reason}`,
-    fix: "in app.config.ts set http.cors.credentials: false, or replace http.cors.origins: ['*'] with the exact origins allowed to call this app",
+    fix: "call configureHttp({ cors: { credentials: false } }) at module scope in a file under apps/*/, or replace origins: ['*'] with the exact origins allowed to call this app",
   });
 
 /**
@@ -303,7 +305,7 @@ export const cspDirectiveInvalid = (where: string, value: string): HttpError =>
   new HttpError({
     code: 'X_CSP_DIRECTIVE_INVALID',
     cause: `${where} is not a csp token: ${JSON.stringify(value)}`,
-    fix: 'in app.config.ts write one http.security.csp.extend entry per directive, each source its own array element — a directive name is [a-z][a-z0-9-]*, and no source may contain a space, a comma or a semicolon',
+    fix: 'in the configureHttp({ security: { csp: { extend } } }) call write one entry per directive, each source its own array element — a directive name is [a-z][a-z0-9-]*, and no source may contain a space, a comma or a semicolon',
   });
 
 export const routeConflict = (path: string, detail: string): HttpError =>
@@ -325,7 +327,7 @@ export const trustProxyUnset = (): HttpError =>
     code: 'X_TRUST_PROXY_UNSET',
     cause:
       'http.trustProxy is true and http.trustedProxyHops is not set, so x-forwarded-for would be read from a position the client controls',
-    fix: 'in app.config.ts set http.trustedProxyHops to the number of proxies that append to x-forwarded-for — 1 for a single ingress or ALB, 2 for a CDN in front of one — or set http.trustProxy: false when this process is reached directly',
+    fix: 'set TRUSTED_PROXY_HOPS in the deployment environment to the number of proxies that append to x-forwarded-for — 1 for a single ingress or ALB, 2 for a CDN in front of one — and leave it unset for a process that is reached directly; an embedder calling defineHttpConfig itself passes { trustProxy: true, trustedProxyHops: 1 }',
   });
 
 /**
@@ -351,7 +353,7 @@ export const overloaded = (inflight: number, ceiling: number): HttpError =>
   new HttpError({
     code: 'X_OVERLOADED',
     cause: `${inflight} requests are already in flight and http.maxInflight is ${ceiling}`,
-    fix: 'retry after the Retry-After header; to serve more at once raise http.maxInflight in app.config.ts, and add replicas to match',
+    fix: 'retry after the Retry-After header; to serve more at once call configureHttp({ maxInflight: 2000 }) at module scope in a file under apps/*/, and add replicas to match',
   });
 
 /**
@@ -362,7 +364,7 @@ export const csrfBlocked = (pathname: string, reason: string): HttpError =>
   new HttpError({
     code: 'X_CSRF_BLOCKED',
     cause: `${pathname} refused a credentialed write: ${reason}`,
-    fix: "call it with an Authorization header instead of the session cookie, add the calling origin to http.cors.origins in app.config.ts, or set http.csrf.mode: 'off' if this app has no cookie session at all",
+    fix: "call it with an Authorization header instead of the session cookie, add the calling origin to configureHttp({ cors: { origins } }), or configureHttp({ csrf: { mode: 'off' } }) if this app has no cookie session at all",
   });
 
 /**
@@ -374,6 +376,6 @@ export const requestTimedOut = (method: string, pathname: string, timeoutMs: num
   new HttpError({
     code: 'X_TIMEOUT',
     cause: `${method} ${pathname} did not finish within ${timeoutMs}ms`,
-    fix: 'pass ctx.signal to every outbound call (fetch(url, { signal: ctx.signal })) and call throwIfAborted(ctx) before expensive work, or raise http.requestTimeoutMs in app.config.ts',
+    fix: 'pass ctx.signal to every outbound call (fetch(url, { signal: ctx.signal })) and call throwIfAborted(ctx) before expensive work, or call configureHttp({ requestTimeoutMs: 60_000 }) at module scope in a file under apps/*/',
     meta: { timeoutMs },
   });

package/src/index.ts

@@ -2,6 +2,8 @@
 // listed here is an implementation detail and may change without a major bump.
 
 export type { RenderMode } from '@ultimat3/core';
+export type { AppHttpConfig, BootOwnedHttpKey } from './app-config';
+export { configuredHttp, configureHttp, mergeHttpConfig, resetHttpConfig } from './app-config';
 export { NEXT_PARAM, nextAfterSignIn, signInRedirect } from './auth-redirect';
 export type { HttpConfig, HttpConfigInput } from './config';
 export { defineHttpConfig, stripBasePath } from './config';
@@ -24,18 +26,20 @@ export type { CsrfCheckInput, CsrfConfig, CsrfMode, CsrfVerdict } from './csrf';
 export { checkCsrf, DEFAULT_CSRF, selfOrigin } from './csrf';
 export type { Deadline } from './deadline';
 export { REQUEST_TIMEOUT_HEADER, resolveTimeoutMs, startDeadline } from './deadline';
-export type { ErrorFacts, ProblemDocument } from './error-map';
+export type { ErrorFacts, ProblemDocument } from './error-facts';
 export {
-  DEFAULT_STATUS,
-  ERROR_STATUS,
   factsOf,
   problemTypeFor,
-  registerErrorStatus,
   renderErrorLines,
-  resetErrorStatus,
   retryAfterOf,
-  statusFor,
   toProblem,
+} from './error-facts';
+export {
+  DEFAULT_STATUS,
+  ERROR_STATUS,
+  registerErrorStatus,
+  resetErrorStatus,
+  statusFor,
 } from './error-map';
 export type {
   ErrorPageAction,
@@ -107,6 +111,7 @@ export type {
   RateLimiter,
   RateLimitKeyParts,
   RateLimitScope,
+  RateLimitSpend,
   RateLimitStore,
 } from './rate-limit';
 export {
@@ -116,8 +121,9 @@ export {
   DEFAULT_RATE_LIMIT,
   memoryRateLimitStore,
   rateLimitDecision,
-  rateLimitKey,
+  rateLimitSpends,
   resolveRateLimitConfig,
+  TENANT_SCOPE,
   toBucket,
 } from './rate-limit';
 export { assertRouteBuckets, withRouteBuckets } from './rate-limit-buckets';
@@ -129,6 +135,7 @@ export {
   rateLimitNotShared,
   rateLimitScopeUnset,
   rateLimitStoreUnavailable,
+  tenantBucketUnknown,
 } from './rate-limit-errors';
 export type {
   PgExecutor,

package/src/overlay.ts

@@ -2,7 +2,7 @@
 // `--json` emits, so a code/cause/fix string can never differ between the three
 // surfaces. Labels here ("cause", "fix", "notices") are protocol strings from the
 // error contract, not UI copy, so they are not routed through the i18n catalog.
-import { factsOf, renderErrorLines, toProblem } from './error-map';
+import { factsOf, renderErrorLines, toProblem } from './error-facts';
 import { acceptsHtml, escapeHtml } from './html-render';
 import { OVERLAY_STYLE } from './overlay-style';
 import { html } from './response';

package/src/pipeline.ts

@@ -237,6 +237,10 @@ export const createPipeline = (deps: PipelineDeps): Pipeline => {
         // address — an identity from an untrusted hop authenticates, which is worse than none.
         peer: peerIdentity(forwarded),
         signal: deadline.signal,
+        // The number behind that signal. `traceHeaders()` in core reads it off the ambient
+        // context, so every outbound hop this request makes carries what is LEFT of the budget
+        // rather than letting the next service start a fresh one of its own.
+        deadlineAt: deadline.deadlineAt,
         // The context is what app code reaches through core's ALS; without the inbound headers
         // on it, a cookie the server itself set could never be read back on the next request,
         // and `ctx.session` had no way to exist.