@ultimat3/http 24.0.0 → 25.0.0

package/src/bearer-mount.ts

@@ -13,8 +13,12 @@ import { bearerMountInvalid, routeNotFound } from './errors';
 import type { RateLimitDecision, RateLimitStore } from './rate-limit';
 import { memoryRateLimitStore, toBucket } from './rate-limit';
 import { rateLimited } from './rate-limit-errors';
+import { rateLimitHeaders } from './rate-limit-headers';
 import type { UltimateRequest } from './request';
+import type { RequestFacts } from './request-facts';
+import { requestFacts } from './request-facts';
 import type { Route, RouteMeta } from './router';
+import { HTTP_METHODS } from './router';
 
 /**
  * What a token resolves to. Structurally `@ultimat3/mcp`'s `ResolvedToken`, so an app hands the
@@ -26,8 +30,16 @@ export interface BearerCaller {
   readonly scopes: ReadonlySet<string>;
 }
 
-/** `null` for a malformed, unknown, revoked or expired token — all one indistinguishable 401. */
-export type BearerResolver = (token: string) => Promise<BearerCaller | null> | BearerCaller | null;
+/**
+ * `null` for a malformed, unknown, revoked or expired token — all one indistinguishable 401.
+ * `facts` is how the request arrived (`RequestFacts`: the pipeline's address, user agent, `Origin`,
+ * path) — the same shape `@ultimat3/mcp` hands its resolver, so one resolver serves both. A
+ * one-argument resolver is still one.
+ */
+export type BearerResolver = (
+  token: string,
+  facts: RequestFacts,
+) => Promise<BearerCaller | null> | BearerCaller | null;
 
 export interface BearerMountRateLimit {
   readonly limit: number;
@@ -86,6 +98,9 @@ const tokenKey = (token: string): string =>
  * The mounted routes. Refuses at construction (`X_BEARER_MOUNT_INVALID`) a prefix that is not a
  * plain path or would shadow `/api` / `/_x`, a scope naming a primitive no route carries, and two
  * primitives that would land on one mounted path.
+ *
+ * The last routes returned are the prefix's catch-all (`<prefix>/*rest`, every method), so no
+ * path under the prefix answers differently for being served: see `opaquePrefix`.
  */
 export function bearerMount(input: BearerMountInput): readonly Route[] {
   const { prefix } = input;
@@ -134,20 +149,38 @@ export function bearerMount(input: BearerMountInput): readonly Route[] {
   // concurrent requests could share.
   const callers = new WeakMap<RequestContext, { caller: BearerCaller; key: string }>();
 
-  const authenticate: NonNullable<RouteMeta['authenticate']> = async (request, ctx) => {
-    const token = bearerTokenOf(request.header('authorization'));
-    if (token === null) {
-      ctx.headers.set('www-authenticate', 'Bearer');
-      return null;
-    }
-    const caller = await input.resolveToken(token);
-    if (caller === null) {
-      ctx.headers.set('www-authenticate', 'Bearer error="invalid_token"');
-      return null;
-    }
-    callers.set(ctx, { caller, key: tokenKey(token) });
-    return caller.actor;
-  };
+  // One authenticator per mounted route, closed over ITS scope, so the cut is decided in the `auth`
+  // stage — before `body` and `authz`. Decided in the handler, an out-of-scope token was answered
+  // 422 with the schema's issues or 403 with the policy's reason, both confirming the primitive.
+  // `null` is the catch-all's: a scope no token holds, so a valid token is told 404 exactly where
+  // an out-of-scope one is, and a missing or bad one gets the same challenge as on a served path.
+  const authenticatorOf =
+    (scope: string | null): NonNullable<RouteMeta['authenticate']> =>
+    async (request, ctx) => {
+      const token = bearerTokenOf(request.header('authorization'));
+      if (token === null) {
+        ctx.headers.set('www-authenticate', 'Bearer');
+        return null;
+      }
+      // `ctx.ip` is the pipeline's trusted-hop answer — the facts never read a forwarding header.
+      const facts = requestFacts({ headers: request.raw.headers, url: ctx.url, address: ctx.ip });
+      const caller = await input.resolveToken(token, facts);
+      if (caller === null) {
+        ctx.headers.set('www-authenticate', 'Bearer error="invalid_token"');
+        return null;
+      }
+      // Hidden, never forbidden: a 403 would confirm the primitive exists to a token that was
+      // not issued for it — the enumeration MCP's catalog refuses the same way.
+      // And never free: the refusal spends the token's allowance as a served call does (which the
+      // handler charges, once, so the two paths never both spend) — else a token walks the cut
+      // unmetered, and `RateLimit-*` on one 404 but not another tells hidden from unknown.
+      if (scope === null || !caller.scopes.has(scope)) {
+        await spend(tokenKey(token), ctx);
+        throw routeNotFound(ctx.method, ctx.url.pathname);
+      }
+      callers.set(ctx, { caller, key: tokenKey(token) });
+      return caller.actor;
+    };
 
   const spend = async (key: string, ctx: RequestContext): Promise<void> => {
     if (bucket === undefined) return;
@@ -157,12 +190,9 @@ export function bearerMount(input: BearerMountInput): readonly Route[] {
       1,
       clock.now().getTime(),
     );
-    ctx.headers.set('ratelimit-limit', String(decision.limit));
-    ctx.headers.set('ratelimit-remaining', String(decision.remaining));
-    ctx.headers.set(
-      'ratelimit-reset',
-      String(Math.max(0, Math.ceil((decision.resetAtMs - clock.now().getTime()) / 1000))),
-    );
+    for (const [name, value] of Object.entries(rateLimitHeaders(decision, clock.now().getTime()))) {
+      ctx.headers.set(name, value);
+    }
     // `rateLimited` carries the seconds in `meta`, which the error-map stage turns into
     // `Retry-After` — the same 429 every other limit in the framework answers.
     if (!decision.allowed) throw rateLimited(`${prefix}|token`, decision.retryAfterSeconds);
@@ -182,11 +212,11 @@ export function bearerMount(input: BearerMountInput): readonly Route[] {
       mounted.push({
         method: route.method,
         path,
-        meta: { ...route.meta, auth: 'required', authenticate },
+        meta: { ...route.meta, auth: 'required', authenticate: authenticatorOf(scope) },
         handler: async (request: UltimateRequest, ctx: RequestContext) => {
           const resolved = callers.get(ctx);
-          // Hidden, never forbidden: a 403 would confirm the primitive exists to a token that
-          // was not issued for it — the enumeration MCP's catalog refuses the same way.
+          // The authenticator already answered an out-of-scope token; this is the fail-closed
+          // floor for a handler driven without the `auth` stage.
           if (resolved === undefined || !resolved.caller.scopes.has(scope)) {
             throw routeNotFound(ctx.method, ctx.url.pathname);
           }
@@ -196,5 +226,30 @@ export function bearerMount(input: BearerMountInput): readonly Route[] {
       });
     }
   }
-  return mounted;
+  return [...mounted, ...opaquePrefix(prefix, authenticatorOf(null))];
 }
+
+/** Every method a client can send. HEAD is GET's (`router.ts`'s `routeFor`), never its own route. */
+const CATCH_ALL_METHODS = HTTP_METHODS.filter((method) => method !== 'HEAD');
+
+/**
+ * `<prefix>/*rest` for every method, behind the mount's own authenticator. Without it a request
+ * with no token answered 401 on a served path and 404 — or 405 naming the served methods — on
+ * every other, so an anonymous walk of the prefix listed the cut. 401 with the `Bearer` challenge
+ * is the uniform answer because it is the TRUE one for a real client anywhere under the prefix:
+ * nothing there is reachable without a token. A static or param route still outranks a wildcard,
+ * so the mounted routes, and any route the app serves under the prefix itself, keep answering.
+ */
+const opaquePrefix = (
+  prefix: string,
+  authenticate: NonNullable<RouteMeta['authenticate']>,
+): readonly Route[] =>
+  CATCH_ALL_METHODS.map((method) => ({
+    method,
+    path: `${prefix}/*rest`,
+    meta: { name: `bearer-mount:${prefix}`, auth: 'required', authenticate },
+    // Reached only if the authenticator did not run: fail closed, with the miss it stands for.
+    handler: (_request: UltimateRequest, ctx: RequestContext) => {
+      throw routeNotFound(ctx.method, ctx.url.pathname);
+    },
+  }));

package/src/config.ts

@@ -3,11 +3,20 @@
 // `app.config.ts`, which this file claimed for four majors while `AppConfig` has never carried an
 // `http` key: an app declares its half through `configureHttp()` (`app-config.ts`) and the boot
 // lays its own facts over it before calling this.
-import { DEFAULT_ENVIRONMENT, tryResolveEnvironment } from '@ultimat3/core';
+import {
+  DEFAULT_ENVIRONMENT,
+  DEFAULT_HEALTH_DETAIL_PEERS,
+  tryResolveEnvironment,
+} from '@ultimat3/core';
 import { assertCorsConfig, type CorsConfig, DEFAULT_CORS } from './cors';
 import { type CsrfConfig, DEFAULT_CSRF } from './csrf';
-import { httpCountInvalid, trustProxyUnset } from './errors';
-import { assertHealthDetailPeers, DEFAULT_HEALTH_DETAIL_PEERS } from './health-disclosure';
+import {
+  buildIdHeaderDeleted,
+  drainTimeoutDeleted,
+  httpCountInvalid,
+  trustProxyUnset,
+} from './errors';
+import { assertHealthDetailPeers } from './health-disclosure';
 import {
   DEFAULT_LOCALE_CONFIG,
   DEFAULT_TZ_CONFIG,
@@ -24,7 +33,6 @@ export interface HttpConfig {
   readonly basePath: string;
   /** Build id this process serves; `null` disables skew detection (dev). */
   readonly buildId: string | null;
-  readonly buildIdHeader: string;
   readonly dev: boolean;
   /**
    * Where a browser that failed `auth: 'required'` is sent, or `null` to answer it with the
@@ -74,18 +82,6 @@ export interface HttpConfig {
    * retries multiply the load.
    */
   readonly maxInflight: number;
-  /**
-   * How long SIGTERM waits for in-flight requests before hard-stopping, or `null` when this app
-   * has not said and core's own deadline stands.
-   *
-   * `null` and not a 15s default, because the two are different claims and only one of them may
-   * reach `configureLifecycle`. `createServer` applied the resolved number unconditionally, so an
-   * app that had already written `configureLifecycle({ deadlineMs: 600_000 })` — the edit
-   * `X_SHUTDOWN_TIMEOUT`'s own `fix:` line prints — had it silently reverted by the next line of
-   * boot, in every process that serves web. Declaring this key IS declaring the drain budget for
-   * the whole process; leaving it out is declining to.
-   */
-  readonly drainTimeoutMs: number | null;
   readonly locale: LocaleConfig;
   readonly tz: TimeZoneConfig;
   readonly cors: CorsConfig;
@@ -99,7 +95,6 @@ export interface HttpConfigInput {
   readonly hostname?: string;
   readonly basePath?: string;
   readonly buildId?: string | null;
-  readonly buildIdHeader?: string;
   readonly dev?: boolean;
   readonly signInPath?: string | null;
   readonly trustProxy?: boolean;
@@ -109,7 +104,6 @@ export interface HttpConfigInput {
   readonly bodyLimitBytes?: number;
   readonly requestTimeoutMs?: number;
   readonly maxInflight?: number;
-  readonly drainTimeoutMs?: number;
   readonly locale?: Partial<LocaleConfig>;
   readonly tz?: Partial<TimeZoneConfig>;
   readonly cors?: Partial<CorsConfig>;
@@ -235,7 +229,22 @@ const resolveTrustedProxyHops = (trustProxy: boolean, declared: number | undefin
   );
 };
 
+/**
+ * Keys this config once carried and no longer reads. A typed caller is stopped by
+ * `HttpConfigInput` itself; this is for the one that is not — plain JS, a spread of a parsed
+ * object, a cast — so a deleted knob is an instruction rather than a number ignored in silence.
+ */
+export const refuseDeletedHttpKeys = (input: object): void => {
+  // Core's rule for a removed key (`core/src/config-removed.ts`): `undefined` is a layer not
+  // saying, so a spread carrying the key unset passes on both surfaces; any other value is written.
+  const written = (key: string): boolean =>
+    Object.hasOwn(input, key) && (input as Record<string, unknown>)[key] !== undefined;
+  if (written('drainTimeoutMs')) throw drainTimeoutDeleted();
+  if (written('buildIdHeader')) throw buildIdHeaderDeleted();
+};
+
 export const defineHttpConfig = (input: HttpConfigInput = {}): HttpConfig => {
+  refuseDeletedHttpKeys(input);
   // `ULTIMATE_ENV` is the framework's one environment key and `NODE_ENV` is only its fallback, so
   // reading `NODE_ENV` alone made a deployment that declared production the documented way serve
   // the dev overlay and a report-only CSP. Non-throwing and `?? DEFAULT_ENVIRONMENT`, the same
@@ -272,7 +281,6 @@ export const defineHttpConfig = (input: HttpConfigInput = {}): HttpConfig => {
     // `undefined` falls back to the environment; an explicit `null` is the declaration that
     // switches skew detection off, and `??` would have read it as unset.
     buildId: input.buildId === undefined ? (env('BUILD_ID') ?? null) : input.buildId,
-    buildIdHeader: input.buildIdHeader ?? 'x-ultimate-build',
     dev,
     signInPath: input.signInPath ?? null,
     trustProxy,
@@ -304,16 +312,6 @@ export const defineHttpConfig = (input: HttpConfigInput = {}): HttpConfig => {
       'a whole number of requests, where 0 means never shed',
       'maxInflight: 1_000',
     ),
-    drainTimeoutMs:
-      input.drainTimeoutMs === undefined || input.drainTimeoutMs === null
-        ? null
-        : assertFiniteCount(
-            'drainTimeoutMs',
-            input.drainTimeoutMs,
-            Number.MAX_SAFE_INTEGER,
-            'a whole number of milliseconds, or null for the lifecycle default',
-            'drainTimeoutMs: 15_000',
-          ),
     locale: { ...DEFAULT_LOCALE_CONFIG, ...input.locale },
     tz: { ...DEFAULT_TZ_CONFIG, ...input.tz },
     cors,

package/src/context.ts

@@ -6,7 +6,7 @@ import {
   anonymousActor,
   type Clock,
   type Ctx,
-  createContext,
+  ctxOf,
   isAnonymous,
   type Logger,
   traceId as newTraceId,
@@ -15,7 +15,7 @@ import {
   type ServiceBag,
   systemClock,
   useContext,
-  uuid,
+  uuidV7,
 } from '@ultimat3/core';
 import { localeConfig } from '@ultimat3/i18n';
 import { timeConfig } from '@ultimat3/time';
@@ -36,8 +36,8 @@ import type { Route, RouteParams } from './router';
  * `CtxServices` with `declare module` to declare `ctx.posts`, and every service it declared then
  * became a required member of every context literal in the framework — this file failed to
  * compile inside `examples/dummy` with `TS2739: missing posts, orgs` while the framework's own
- * gate, which augments nothing, stayed green. `createRequestContext` now spreads
- * `createContext()`'s result, so the members only an app's boot can supply arrive with it and the
+ * gate, which augments nothing, stayed green. `requestContext` now spreads
+ * `ctxOf()`'s result, so the members only an app's boot can supply arrive with it and the
  * literal below is checked in full.
  *
  * The `extends` is therefore back to doing what it was always claimed to do: a member core adds
@@ -118,7 +118,7 @@ export interface RequestContext extends Ctx {
    */
   pathLocale: string | undefined;
   tz: string;
-  /** What the CLIENT says it is running, from `config.buildIdHeader`. `assertBuild()` reads it. */
+  /** What the CLIENT says it is running, from core's `BUILD_ID_HEADER`. `assertBuild()` reads it. */
   clientBuildId: string | null;
   input: unknown;
   authz: AuthzDecision | undefined;
@@ -166,15 +166,15 @@ export interface RequestContextInit {
   readonly services?: ServiceBag;
 }
 
-export const createRequestContext = (init: RequestContextInit): RequestContext => {
+export const requestContext = (init: RequestContextInit): RequestContext => {
   const clock = init.clock ?? systemClock;
-  const requestId = init.requestId ?? uuid(clock);
+  const requestId = init.requestId ?? uuidV7(clock);
   // core's `traceId()`, never `uuid()`: a dashed UUIDv7 is not a 32-hex W3C trace id, and a
   // collector rejects the span that carries one — while the log lines beside it, which quote the
   // same field, look fine. Two ids for one request that cannot be joined.
   const traceId = init.traceId ?? newTraceId();
   // COMPOSED from core's constructor rather than built beside it, and that is what deletes the
-  // last cast in this file. `createContext` returns a `Ctx` that already carries the app's
+  // last cast in this file. `ctxOf` returns a `Ctx` that already carries the app's
   // `CtxServices` augmentation, so spreading it hands this literal the members only the app's boot
   // could supply — and the return below is checked in full, with nothing asserted anywhere.
   //
@@ -186,8 +186,8 @@ export const createRequestContext = (init: RequestContextInit): RequestContext =
   // `ctx.services.posts` beside it was populated. Composing makes that class of drift unwritable.
   //
   // `defineService` factories now install on this surface too, for the same reason: they are
-  // `createContext`'s and this is `createContext`.
-  const base = createContext({
+  // `ctxOf`'s and this is `ctxOf`.
+  const base = ctxOf({
     requestId,
     traceId,
     role: init.role,

package/src/correlation.ts

@@ -3,7 +3,7 @@
 // frozen the span's context: the caller's trace was discarded, the root span carried a fresh
 // UUIDv7 no collector accepts as a trace id, and the log lines quoted a third value.
 
-import { traceId as newTraceId, parseTraceparent, type SpanContext, uuid } from '@ultimat3/core';
+import { traceId as newTraceId, parseTraceparent, type SpanContext, uuidV7 } from '@ultimat3/core';
 import type { HttpConfig } from './config';
 
 /**
@@ -33,7 +33,7 @@ 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();
+  const requestId = inboundId !== null && REQUEST_ID.test(inboundId) ? inboundId : uuidV7();
   // 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

package/src/cors.ts

@@ -1,6 +1,7 @@
 // CORS with a locked default: same-origin only. Cross-origin access is a decision the app makes
 // once, in `configureHttp({ cors })`, never something a route can quietly opt into.
 
+import { BUILD_ID_HEADER } from '@ultimat3/core';
 import { corsConfigInvalid } from './errors';
 
 export interface CorsConfig {
@@ -16,8 +17,8 @@ export interface CorsConfig {
 export const DEFAULT_CORS: CorsConfig = {
   origins: [],
   methods: ['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE'],
-  allowHeaders: ['content-type', 'authorization', 'x-ultimate-build', 'x-request-id'],
-  exposeHeaders: ['x-request-id', 'x-ultimate-build', 'retry-after'],
+  allowHeaders: ['content-type', 'authorization', BUILD_ID_HEADER, 'x-request-id'],
+  exposeHeaders: ['x-request-id', BUILD_ID_HEADER, 'retry-after'],
   credentials: true,
   maxAgeSeconds: 600,
 };

package/src/deadline.ts

@@ -12,12 +12,9 @@ import { requestTimedOut } from './errors';
  * A caller may SHORTEN this request's deadline, never lengthen it. Honoured without trusting the
  * proxy, because the only thing it can buy an attacker is a faster 504 for their own request.
  *
- * The name is core's, re-exported rather than declared twice: this package READS the header and
- * `@ultimat3/core`'s typed-client wire path WRITES it, and a second literal is a propagation that
- * stops working the day one of the two strings is edited. Same shape as `logger.ts` re-exporting
- * `REDACTED` — one definition, one public path.
+ * The header name is core's `REQUEST_TIMEOUT_HEADER`, imported: this package READS it and core's
+ * typed-client wire path WRITES it, so one literal, at the tier both reach, with one import path.
  */
-export { REQUEST_TIMEOUT_HEADER };
 
 export interface Deadline {
   /** Aborted when the deadline passes. Handed to the context as `ctx.signal`. */

package/src/error-map-tier-0.ts

@@ -57,4 +57,6 @@ export const TIER_0_ERROR_STATUS = {
   X_RECORD_REJECTED: 500,
   X_SYNC_UNCONFIGURED: 500,
   X_INTERNAL: 500,
+  // @ultimat3/core — a Set-Cookie value would be dropped, misread or injectable
+  X_COOKIE_INVALID: 500,
 } satisfies Readonly<Record<string, number>>;

package/src/error-map-tier-1.ts

@@ -68,4 +68,6 @@ export const TIER_1_ERROR_STATUS = {
   X_STORAGE_PUT_FAILED: 500,
   // @ultimat3/storage — the object could not be read
   X_STORAGE_READ_FAILED: 500,
+  // @ultimat3/storage — the object is under retention or a legal hold
+  X_STORAGE_OBJECT_LOCKED: 409,
 } satisfies Readonly<Record<string, number>>;

package/src/error-map-tier-2.ts

@@ -115,4 +115,6 @@ export const TIER_2_ERROR_STATUS = {
   X_POLICY_SURFACE_UNKNOWN: 500,
   // @ultimat3/auth — a stored totp secret is not sealed, so it is never read as one
   X_MFA_SECRET_UNSEALED: 500,
+  // @ultimat3/entity — an append-only entity was asked to rewrite or remove a row
+  X_ENTITY_APPEND_ONLY: 409,
 } satisfies Readonly<Record<string, number>>;

package/src/error-map-tier-3.ts

@@ -89,4 +89,12 @@ export const TIER_3_ERROR_STATUS = {
   X_IDEMPOTENCY_RESERVATION_LOST: 409,
   // @ultimat3/jobs — the queue holds no job with this id
   X_JOB_NOT_FOUND: 404,
+  // @ultimat3/realtime — one principal holds too many sockets on this node
+  X_SOCKET_LIMIT: 429,
+  // @ultimat3/action — an idempotent replay would return a field redacted at rest
+  X_IDEMPOTENT_REPLAY_REDACTED: 409,
+  // @ultimat3/query — a query declares audit: true and no audit sink is installed
+  X_QUERY_AUDIT_SINK_MISSING: 500,
+  // @ultimat3/query — an audited read was refused because the audit sink rejected its record
+  X_QUERY_AUDIT_SINK_FAILED: 503,
 } satisfies Readonly<Record<string, number>>;

package/src/error-map-tier-4.ts

@@ -89,4 +89,28 @@ export const TIER_4_ERROR_STATUS = {
   X_MCP_BODY_TOO_LARGE: 413,
   // @ultimat3/ai — a vector store was read with no tenant bound inside an org request
   X_VECTOR_UNSCOPED: 500,
+  // @ultimat3/ai — an image or document block the role, model or wire format cannot take
+  X_AI_CONTENT_UNSUPPORTED: 422,
+  // @ultimat3/mcp — a gated MCP tool call waits for a person to approve it
+  X_MCP_CONFIRMATION_PENDING: 409,
+  // @ultimat3/mcp — an MCP confirmation expired before it was used or decided
+  X_MCP_CONFIRMATION_EXPIRED: 410,
+  // @ultimat3/mcp — a person rejected this MCP tool call
+  X_MCP_CONFIRMATION_REJECTED: 403,
+  // @ultimat3/mcp — an MCP confirmation was already decided
+  X_MCP_CONFIRMATION_DECIDED: 409,
+  // @ultimat3/mcp — no MCP confirmation has that id
+  X_MCP_CONFIRMATION_UNKNOWN: 404,
+  // @ultimat3/mcp — identical concurrent MCP calls kept racing one confirmation
+  X_MCP_CONFIRMATION_CONTESTED: 503,
+  // @ultimat3/mail — a delivery notification is not signed by its provider
+  X_MAIL_EVENT_UNVERIFIED: 401,
+  // @ultimat3/mail — a delivery notification is not a shape this receiver reads
+  X_MAIL_EVENT_INVALID: 400,
+  // @ultimat3/mail — an SNS endpoint the receiver needed did not answer
+  X_MAIL_EVENT_PROVIDER_UNREACHABLE: 503,
+  // @ultimat3/mcp — an MCP confirmation approval did not carry the arguments the agent sent
+  X_MCP_CONFIRMATION_ARGUMENTS_MISMATCH: 409,
+  // @ultimat3/ai — a model call named no model
+  X_AI_MODEL_UNRESOLVED: 500,
 } satisfies Readonly<Record<string, number>>;

package/src/error-page.ts

@@ -165,11 +165,11 @@ export function renderErrorPage(input: ErrorPageInput): string {
     <p class="lede">${escapeHtml(t(`errors.${copy.group}.body`, copy.vars))}</p>
     <p>${link(hrefFor(copy, input), t(`errors.${copy.group}.action`))}</p>
     <dl>
-      <dt>code</dt><dd>${escapeHtml(singleLine(input.code))}</dd>${
+      <dt>${escapeHtml(t('errors.page.code'))}</dt><dd>${escapeHtml(singleLine(input.code))}</dd>${
         input.requestId === undefined
           ? ''
           : `
-      <dt>request</dt><dd>${escapeHtml(singleLine(input.requestId))}</dd>`
+      <dt>${escapeHtml(t('errors.page.request'))}</dt><dd>${escapeHtml(singleLine(input.requestId))}</dd>`
       }
     </dl>
   </section>

package/src/error-titles.ts

@@ -0,0 +1,93 @@
+// @ultimat3/http's owned codes, their TITLES and the two retry classes, registered at import — the
+// one module `sideEffects` names, imported bare by the barrel and by `errors.ts`. Its readers are
+// in the SERVER realm (`x errors list`, a problem document, a job's retry), which reaches the
+// barrel. A browser never needs it: core's decoders take an unregistered code's title from the
+// problem body and a 429's `retry-after` from its `Retry-After` header. Until the package declared
+// `sideEffects`, all of http — router, limiter, error maps, 11.5 kB — rode into every action island.
+
+import { registerErrorCodes, registerErrorRetry } from '@ultimat3/core';
+
+/** Codes this package declares and owns. */
+export const HTTP_OWNED_ERROR_CODES = [
+  'X_ROUTE_NOT_FOUND',
+  'X_METHOD_NOT_ALLOWED',
+  'X_PATH_INVALID',
+  'X_BODY_INVALID',
+  'X_RATE_LIMITED',
+  'X_BUILD_SKEW',
+  'X_ROUTE_CONFLICT',
+  'X_SERVER_NOT_STARTED',
+  'X_PIPELINE_NO_RESPONSE',
+  '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',
+  'X_RATE_LIMIT_BUCKET_CONFLICT',
+  'X_RATE_LIMIT_BUCKET_UNBOUND',
+  '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',
+  'X_WEBHOOK_SIGNATURE_INVALID',
+  'X_WEBHOOK_SIGNATURE_STALE',
+  'X_BEARER_MOUNT_INVALID',
+] as const;
+
+export type HttpOwnedErrorCode = (typeof HTTP_OWNED_ERROR_CODES)[number];
+
+/** Human title per owned code. Kept next to the codes so one edit updates every surface. */
+export const HTTP_ERROR_TITLES: Readonly<Record<HttpOwnedErrorCode, string>> = {
+  X_ROUTE_NOT_FOUND: 'no route matches this request',
+  X_METHOD_NOT_ALLOWED: 'route exists but not for this method',
+  X_PATH_INVALID: 'a path segment is not valid percent-encoding',
+  X_BODY_INVALID: 'request body failed its schema',
+  X_RATE_LIMITED: 'rate limit exhausted for this key',
+  X_BUILD_SKEW: 'client build id does not match the server build id',
+  X_ROUTE_CONFLICT: 'two routes claim the same path',
+  X_SERVER_NOT_STARTED: 'server handle used before start()',
+  X_PIPELINE_NO_RESPONSE: 'a pipeline stage produced no response',
+  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',
+  X_RATE_LIMIT_BUCKET_CONFLICT: 'a route and the config declare different numbers for one bucket',
+  X_RATE_LIMIT_BUCKET_UNBOUND: 'the installed limiter cannot enforce a bucket a route declares',
+  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: 'an unsafe request that did not prove same-origin',
+  X_WEBHOOK_SIGNATURE_INVALID: 'the inbound webhook is not signed by the holder of this secret',
+  X_WEBHOOK_SIGNATURE_STALE: 'the inbound webhook is signed correctly and is too old to accept',
+  X_BEARER_MOUNT_INVALID: 'a bearer mount declaration cannot be served as written',
+};
+
+// Registered at module load, unconditionally, in one call, so core's registry renders OUR title
+// everywhere. Without this the registry humanises the code (`X_BUILD_SKEW` → "build skew"); with a
+// presence guard, a package that claimed one of these first would silently keep its own title.
+registerErrorCodes(
+  Object.fromEntries(Object.entries(HTTP_ERROR_TITLES).map(([code, title]) => [code, { title }])),
+);
+
+/**
+ * The two codes this package throws that a client is SUPPOSED to come back from, and both say
+ * when: each carries `retry-after` on the response. Unclassified defaults to `terminal`, which is
+ * right for the rest — a 404, a 422 and a wiring bug all fail the same way forever — but wrong for
+ * a shed request, whose whole contract is "not now". Only codes this package OWNS are listed:
+ * `X_TIMEOUT` and `X_DRAINING` are borrowed, and core classifies its own.
+ */
+registerErrorRetry({
+  X_RATE_LIMITED: 'retry-after',
+  X_OVERLOADED: 'retry-after',
+});