@ultimat3/http 29.4.0 → 30.0.0

package/src/compress-read.ts

@@ -0,0 +1,115 @@
+// The one read of a response body the `compress` stage ever does: counted against the length the
+// response declared, bounded by the request's deadline, and able to hand back everything it took
+// so an answer it gave up on still arrives whole. Split from the rule that decides when to read.
+
+type Reader = ReadableStreamDefaultReader<Uint8Array>;
+type Read = Awaited<ReturnType<Reader['read']>>;
+type GiveUp = 'longer-than-declared' | 'deadline' | 'read-failed';
+
+/** What a counted read ended with: every byte, or the reason it stopped and how to carry on. */
+export type Drained =
+  | { readonly complete: true; readonly chunks: readonly Uint8Array[] }
+  | {
+      readonly complete: false;
+      readonly chunks: readonly Uint8Array[];
+      readonly reason: GiveUp;
+      /** The read already asked of the source when the deadline won; its bytes still belong. */
+      readonly pending?: Promise<Read>;
+      readonly failure?: unknown;
+    };
+
+/** Undefined when the signal fires first. The read keeps going, and is the caller's to collect. */
+const readBefore = (
+  read: Promise<Read>,
+  signal: AbortSignal | undefined,
+): Promise<Read | undefined> => {
+  if (signal === undefined) return read;
+  if (signal.aborted) return Promise.resolve(undefined);
+  return new Promise((resolve, reject) => {
+    const expired = (): void => resolve(undefined);
+    signal.addEventListener('abort', expired, { once: true });
+    const settle = (): void => signal.removeEventListener('abort', expired);
+    read.then(
+      (value) => {
+        settle();
+        resolve(value);
+      },
+      (failure: unknown) => {
+        settle();
+        reject(failure);
+      },
+    );
+  });
+};
+
+/**
+ * Counted, because the header is a claim and only the header was checked. The buffer never holds
+ * more than the declared length, which `inBounds` capped: the chunk that overruns is kept aside to
+ * be sent on, never added. Bounded in time too: this runs after the deadline's race has ended, and
+ * an answer that was going to send its headers at once must not wait on a body that stalled.
+ */
+export const drainCounted = async (
+  reader: Reader,
+  declared: number,
+  signal: AbortSignal | undefined,
+): Promise<Drained> => {
+  const chunks: Uint8Array[] = [];
+  let held = 0;
+  for (;;) {
+    const pending = reader.read();
+    let next: Read | undefined;
+    try {
+      next = await readBefore(pending, signal);
+    } catch (failure) {
+      return { complete: false, chunks, reason: 'read-failed', failure };
+    }
+    if (next === undefined) {
+      // Observed now, so a client that leaves before the replay is pulled cannot turn the source's
+      // later failure into an unhandled rejection. The replay's construction pull happens to
+      // observe it today (high-water mark 1); this must not depend on that. It still awaits it.
+      pending.catch(() => undefined);
+      return { complete: false, chunks, reason: 'deadline', pending };
+    }
+    if (next.done) return { complete: true, chunks };
+    if (held + next.value.byteLength > declared) {
+      chunks.push(next.value);
+      return { complete: false, chunks, reason: 'longer-than-declared' };
+    }
+    chunks.push(next.value);
+    held += next.value.byteLength;
+  }
+};
+
+/** The bytes the read took, then the rest of the source, as if nothing had looked at them. */
+export const replayDrained = (
+  chunks: readonly Uint8Array[],
+  reader: Reader,
+  pending: Promise<Read> | undefined,
+): ReadableStream<Uint8Array> => {
+  const queue = [...chunks];
+  let inFlight = pending;
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      const held = queue.shift();
+      if (held !== undefined) {
+        controller.enqueue(held);
+        return;
+      }
+      const next = await (inFlight ?? reader.read());
+      inFlight = undefined;
+      if (next.done) controller.close();
+      else controller.enqueue(next.value);
+    },
+    cancel: (reason) => reader.cancel(reason),
+  });
+};
+
+export const concatChunks = (chunks: readonly Uint8Array[]): Uint8Array<ArrayBuffer> => {
+  const out = new Uint8Array(chunks.reduce((total, chunk) => total + chunk.byteLength, 0));
+  let at = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, at);
+    at += chunk.byteLength;
+  }
+  return out;
+};

package/src/compress.ts

@@ -0,0 +1,173 @@
+// The `compress` stage's one rule: which answers leave the container gzipped, and the read that
+// gets their bytes. Bun's own coder and no option: a handler that must not be coded says
+// `no-transform`. Every other answer is handed back as the same object, its body never touched.
+import { logger } from '@ultimat3/core';
+import { concatChunks, drainCounted, replayDrained } from './compress-read';
+import { addVary } from './response';
+
+/** Below this the gzip header and trailer eat what the coding saves. */
+export const COMPRESS_MIN_BYTES = 1_024;
+
+/**
+ * The most one request may make `gzipSync` hold the event loop for. Measured 2026-11-03, level 6,
+ * high-entropy text, median of 15: 2.35 ms at 256 KiB against 9.58 ms at 1 MiB (about 29 ms at
+ * 1 MiB on slower hardware, where 1 MiB let ~34 anonymous req/s pin a core). Stylesheets code
+ * about 15x faster than that worst case.
+ */
+export const COMPRESS_MAX_BYTES = 262_144;
+
+const GZIP_LEVEL = 6;
+
+/** Text only: images and fonts are coded already, and `text/event-stream` must never be held. */
+const COMPRESSIBLE_TYPES: ReadonlySet<string> = new Set([
+  'text/html',
+  'text/css',
+  'text/javascript',
+  'application/javascript',
+  'application/json',
+  'application/manifest+json',
+  'image/svg+xml',
+  'application/xml',
+  'text/xml',
+  'application/rss+xml',
+  'application/atom+xml',
+  'text/vtt',
+]);
+
+/**
+ * BREACH: a private document reflects a secret beside attacker input, and a coded length measures
+ * how well the two match. `no-cache` is here because it is the one spelling that passes the
+ * `cache-headers` review on a signed-in answer without becoming `private`.
+ */
+const WITHHOLDS_CODING = /(?:^|[\s,])(?:private|no-store|no-cache|no-transform)(?=$|[\s,=])/i;
+
+const DECLARED_LENGTH = /^\d+$/;
+
+const IMMUTABLE = /(?:^|[\s,])immutable(?=$|[\s,=])/i;
+
+/**
+ * Whether a `content-type` is one this stage codes. Exported for the one reader that must agree
+ * with it: `@ultimat3/cli`'s test holding every public framework route to a declared length.
+ */
+export const isCompressibleType = (contentType: string | null): boolean => {
+  const type = contentType?.split(';')[0]?.trim().toLowerCase();
+  return type !== undefined && COMPRESSIBLE_TYPES.has(type);
+};
+
+/**
+ * A signed-in answer is coded only when `immutable`: a header like `stale-while-revalidate=60`
+ * withholds nothing and offers nothing, so the `cache-headers` review leaves it as written, and
+ * the body beside it is still the visitor's. The ACTOR is what makes it personal, never the header.
+ */
+const compressibleKind = (headers: Headers, anonymous: boolean): boolean => {
+  const cacheControl = headers.get('cache-control') ?? '';
+  return (
+    isCompressibleType(headers.get('content-type')) &&
+    !WITHHOLDS_CODING.test(cacheControl) &&
+    (anonymous || IMMUTABLE.test(cacheControl))
+  );
+};
+
+/** HEAD is GET's headers with no body (RFC 9110 §9.3.2), so it is coded exactly as GET is. */
+const CODED_METHODS: ReadonlySet<string> = new Set(['GET', 'HEAD']);
+
+/** RFC 9110 §12.5.3, `gzip` by name. A `*` is not read as consent to a coding it never named. */
+const acceptsGzip = (header: string | null): boolean => {
+  for (const member of header?.split(',') ?? []) {
+    const [coding, ...params] = member.split(';').map((part) => part.trim().toLowerCase());
+    if (coding !== 'gzip') continue;
+    const weight = params.find((param) => param.startsWith('q='));
+    return weight === undefined || Number(weight.slice(2)) > 0;
+  }
+  return false;
+};
+
+const inBounds = (length: string | null): length is string =>
+  length !== null &&
+  DECLARED_LENGTH.test(length) &&
+  Number(length) >= COMPRESS_MIN_BYTES &&
+  Number(length) <= COMPRESS_MAX_BYTES;
+
+const rebuilt = (response: Response, body: BodyInit | null, headers: Headers): Response =>
+  new Response(body, { status: response.status, statusText: response.statusText, headers });
+
+const coded = (response: Response, bytes: Uint8Array<ArrayBuffer>, head: boolean): Response => {
+  const gzipped = Bun.gzipSync(bytes, { level: GZIP_LEVEL });
+  const headers = new Headers(response.headers);
+  headers.set('content-encoding', 'gzip');
+  headers.set('content-length', String(gzipped.byteLength));
+  // A byte offset into the identity bytes means nothing in these.
+  headers.delete('accept-ranges');
+  headers.delete('transfer-encoding');
+  const etag = headers.get('etag');
+  // A strong validator promises these exact bytes, and the identity answer has other ones.
+  if (etag !== null && !etag.startsWith('W/')) headers.set('etag', `W/${etag}`);
+  return rebuilt(response, head ? null : gzipped, headers);
+};
+
+/** Identity after a read began. Never the declared length: the failed read just disproved it. */
+const identity = (
+  response: Response,
+  body: ReadableStream<Uint8Array> | Uint8Array<ArrayBuffer>,
+) => {
+  const headers = new Headers(response.headers);
+  if (body instanceof Uint8Array) headers.set('content-length', String(body.byteLength));
+  else headers.delete('content-length');
+  return rebuilt(response, body, headers);
+};
+
+export interface CompressContext {
+  /** `isAnonymous(ctx.actor)`. Declared, never defaulted: a forgotten actor must not code. */
+  readonly anonymous: boolean;
+  /** The request's: past it, a body still being read goes out as identity. */
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * The answer to send. Total: a compression failure is never a request failure, and the log line
+ * carries it.
+ */
+export const compressResponse = async (
+  request: Request,
+  response: Response,
+  { anonymous, signal }: CompressContext,
+): Promise<Response> => {
+  if (!compressibleKind(response.headers, anonymous)) return response;
+  // On coded and identity alike, before any other refusal: a shared cache must not hand this
+  // client's copy to one that refused the coding, whichever of the two this client got.
+  addVary(response, ['accept-encoding']);
+  const length = response.headers.get('content-length');
+  if (
+    !CODED_METHODS.has(request.method) ||
+    response.status !== 200 ||
+    !acceptsGzip(request.headers.get('accept-encoding')) ||
+    response.headers.has('content-encoding') ||
+    response.headers.has('content-range') ||
+    !inBounds(length) ||
+    response.body === null ||
+    response.bodyUsed
+  ) {
+    return response;
+  }
+  const reader = response.body.getReader();
+  const drained = await drainCounted(reader, Number(length), signal);
+  if (!drained.complete) {
+    logger.warn('http.compress_failed', {
+      reason: drained.reason,
+      declaredBytes: Number(length),
+      ...(drained.failure === undefined ? {} : { error: drained.failure }),
+    });
+    return identity(response, replayDrained(drained.chunks, reader, drained.pending));
+  }
+  const bytes = concatChunks(drained.chunks);
+  try {
+    return coded(response, bytes, request.method === 'HEAD');
+  } catch (failure) {
+    logger.warn('http.compress_failed', {
+      reason: 'gzip-failed',
+      declaredBytes: Number(length),
+      error: failure,
+    });
+    return identity(response, bytes);
+  }
+};

package/src/config.ts

@@ -6,6 +6,7 @@
 import {
   DEFAULT_ENVIRONMENT,
   DEFAULT_HEALTH_DETAIL_PEERS,
+  MAX_TIMER_MS,
   tryResolveEnvironment,
 } from '@ultimat3/core';
 import { assertCorsConfig, type CorsConfig, DEFAULT_CORS } from './cors';
@@ -181,13 +182,6 @@ const assertFiniteCount = (
 
 const MAX_PORT = 65_535;
 
-/**
- * The longest delay a timer holds: a signed 32-bit count of milliseconds, about 24.8 days. Past
- * it `setTimeout` arms ~1 ms, so a "longer" request budget timed every request out at once.
- * `requestTimeoutMs` is screened against it and `deadline.ts` reads the inbound header by it.
- */
-export const MAX_TIMER_MS = 2_147_483_647;
-
 /**
  * Nobody has 64 proxies in front of one process; a bigger number is a typo, not a topology.
  *

package/src/context.ts

@@ -12,10 +12,12 @@ import {
   traceId as newTraceId,
   type Role,
   readCookie,
+  runWithContext,
   type ServiceBag,
   systemClock,
   useContext,
   uuidV7,
+  withChildContext,
 } from '@ultimat3/core';
 import { localeConfig } from '@ultimat3/i18n';
 import { timeConfig } from '@ultimat3/time';
@@ -265,6 +267,54 @@ export const requestContext = (init: RequestContextInit): RequestContext => {
  */
 export const asCtx = (ctx: RequestContext): Ctx => ctx;
 
+/**
+ * Run `fn` as this request with nobody behind it: what a SHARED document (`isr`, `static`) renders
+ * in. A stored page is answered to every later visitor, so it may vary on what its key carries and
+ * nothing else: `url` (already narrowed by the caller to what the key holds) and the locale.
+ *
+ * Still a request, which is why this is not a bare `withChildContext({ actor })`: that builds a
+ * plain `ctxOf`, where `setRedirect()` and `useRequestHeader()` answer `X_NO_REQUEST`. And not a
+ * spread of `ctx` alone, whose services were built for the visitor: the same leak by another door.
+ * So the child supplies the rebuilt services, and the request's fields go over it, for the reason
+ * `requestContext` spreads in that order: a service named `url` never shadows the request's own.
+ * `ctx.services` is non-enumerable (`bindRequestServices`), so the spread leaves the child's.
+ *
+ * Everything the visitor put on the context goes, by allow-list where a list exists. The inbound
+ * headers are EMPTY, not filtered: `x-api-key`, `x-forwarded-email` and whatever a proxy adds next
+ * are not names a deny-list can know, and no header is in the key — `accept-language` already did
+ * its work as `ctx.locale`, which IS. The zone is the default, since an actor's or a cookie's is
+ * not in the key (`preferences.ts`). `locale` stays: bounded, keyed, and no secret.
+ *
+ * What `fn` writes is on `scope`: read a redirect back with `takeRedirect(scope)`, never `ctx`.
+ * `scope.headers` is `ctx.headers`, so a response header set inside still reaches the response.
+ */
+export const withAnonymousRequest = <T>(
+  ctx: RequestContext,
+  url: URL,
+  fn: (scope: RequestContext) => T,
+): T =>
+  runWithContext(asCtx(ctx), () => {
+    const tz = timeConfig().defaultZone;
+    return withChildContext({ actor: anonymousActor(), tz }, () => {
+      const child = useContext();
+      const scope: RequestContext = {
+        ...child,
+        ...ctx,
+        actor: child.actor,
+        tz,
+        url,
+        requestHeaders: new Headers(),
+        ip: null,
+        peer: null,
+        clientBuildId: null,
+        authz: undefined,
+        rateLimit: undefined,
+        readBody: undefined,
+      };
+      return runWithContext(asCtx(scope), () => fn(scope));
+    });
+  });
+
 /**
  * The ambient `Ctx`, WIDENED to the request shape and not yet proven to be one. Private for that
  * reason: every export below runs it through `assertInRequest` first. The cast is the inverse of

package/src/cors.ts

@@ -1,7 +1,14 @@
 // 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 {
+  BUILD_ID_HEADER,
+  DATES_HEADER,
+  IDEMPOTENCY_HEADER,
+  RECORDS_HEADER,
+  REPLAYED_HEADER,
+  REQUEST_TIMEOUT_HEADER,
+} from '@ultimat3/core';
 import { corsConfigInvalid } from './errors';
 
 export interface CorsConfig {
@@ -17,12 +24,38 @@ export interface CorsConfig {
 export const DEFAULT_CORS: CorsConfig = {
   origins: [],
   methods: ['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE'],
-  allowHeaders: ['content-type', 'authorization', BUILD_ID_HEADER, 'x-request-id'],
-  exposeHeaders: ['x-request-id', BUILD_ID_HEADER, 'retry-after'],
+  // What the typed clients send: a keyed write fails preflight without its idempotency key.
+  allowHeaders: [
+    'content-type',
+    'authorization',
+    BUILD_ID_HEADER,
+    'x-request-id',
+    IDEMPOTENCY_HEADER,
+    REQUEST_TIMEOUT_HEADER,
+    'traceparent',
+  ],
+  // What they read: with the records header hidden, a typed call answers the envelope itself.
+  exposeHeaders: [
+    'x-request-id',
+    BUILD_ID_HEADER,
+    'retry-after',
+    RECORDS_HEADER,
+    DATES_HEADER,
+    REPLAYED_HEADER,
+    'ratelimit-limit',
+    'ratelimit-remaining',
+    'ratelimit-reset',
+    'deprecation',
+    'sunset',
+    'link',
+  ],
   credentials: true,
   maxAgeSeconds: 600,
 };
 
+/** What `Origin` carries, and `URL.origin` answers, when there is no origin to name. */
+const OPAQUE_ORIGIN = 'null';
+
 /**
  * The one combination the browser refuses — `*` with credentials — refused HERE instead, at the
  * one moment an author can act on it. It used to resolve to "no CORS headers at all": the natural
@@ -35,6 +68,12 @@ export const assertCorsConfig = (config: CorsConfig): void => {
       "origins includes '*' while credentials is true — no browser accepts that pair",
     );
   }
+  if (config.origins.includes(OPAQUE_ORIGIN)) {
+    throw corsConfigInvalid(
+      "origins includes 'null', the origin every sandboxed iframe on the web sends, so any site could read the reply. URL.parse('localhost:3000').origin is that string",
+      "list the scheme too: configureHttp({ cors: { origins: ['http://localhost:3000'] } })",
+    );
+  }
 };
 
 /**
@@ -46,7 +85,7 @@ export const assertCorsConfig = (config: CorsConfig): void => {
  * 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);
+  origin !== null && origin !== OPAQUE_ORIGIN && config.origins.includes(origin);
 
 /**
  * The one answer to "may this origin READ our reply?" — the value of

package/src/csrf.ts

@@ -5,7 +5,7 @@
 // went through. `setRedirect` exists so those form posts work without JS, which makes them a
 // first-class surface here rather than a legacy one.
 
-import { classifyAddress, proveSameOrigin } from '@ultimat3/core';
+import { peerAddressClass, proveSameOrigin, renderFixShellArg } from '@ultimat3/core';
 import type { CorsConfig } from './cors';
 import { originListed } from './cors';
 import { HttpError } from './errors';
@@ -25,6 +25,8 @@ export const DEFAULT_CSRF: CsrfConfig = { mode: 'origin' };
 
 /** Methods with no side effects, per RFC 9110. A CSRF check on these is a check on nothing. */
 const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS', 'TRACE']);
+/** RFC 6750 §2.1: the scheme, case-insensitive, then a token. A bare `Bearer` carries nothing. */
+const BEARER = /^bearer +\S/i;
 
 export interface CsrfCheckInput {
   readonly method: string;
@@ -32,14 +34,23 @@ export interface CsrfCheckInput {
   readonly selfOrigin: string;
   readonly origin: string | null;
   readonly secFetchSite: string | null;
-  /** A bearer token is not ambient: a cross-site page cannot make the browser attach one. */
-  readonly hasAuthorizationHeader: boolean;
+  /**
+   * The raw `Authorization` header. Only `Bearer` exempts: no browser attaches one on its own,
+   * and a script setting it cross-origin needs a CORS preflight this app's `cors.origins` decides.
+   * Basic, Digest and Negotiate are re-sent from the browser's cache — as ambient as a cookie.
+   */
+  readonly authorization: string | null;
   /**
    * No session resolved. NOT an exemption: a sign-in form is forgeable too (login CSRF — the
    * visitor ends up in the attacker's account), so an anonymous write that carries browser
    * evidence is judged exactly as a credentialed one. See `checkCsrf` for the one thing it buys.
    */
   readonly anonymous: boolean;
+  /**
+   * The route declared `meta.csrf: 'cookieless'` (and so its own authenticator). Exempt only
+   * while `anonymous`: a caller that something DID authenticate is judged as any other.
+   */
+  readonly cookieless?: boolean | undefined;
   readonly cors: CorsConfig;
   readonly config: CsrfConfig;
 }
@@ -63,8 +74,11 @@ export type CsrfVerdict =
 export const checkCsrf = (input: CsrfCheckInput): CsrfVerdict => {
   if (input.config.mode === 'off') return { ok: true };
   if (SAFE_METHODS.has(input.method)) return { ok: true };
-  if (input.hasAuthorizationHeader) return { ok: true };
+  if (input.authorization !== null && BEARER.test(input.authorization)) return { ok: true };
   if (input.anonymous && input.origin === null && input.secFetchSite === null) return { ok: true };
+  // No cookie can make this request anyone's, and no cookie is minted by it: a cross-origin
+  // client posting a code and its verifier is the endpoint's whole purpose, not a forgery.
+  if (input.anonymous && input.cookieless === true) return { ok: true };
 
   // The rule itself is core's, shared with the sync node's upgrade: one answer to "did this
   // come from this app?" on every surface an ambient credential reaches.
@@ -99,16 +113,35 @@ export const selfOrigin = (url: URL, https: boolean): string =>
 export const csrfBlocked = (
   pathname: string,
   reason: string,
-  ip: string | null = null,
+  ip: string | null,
+  origin: string,
 ): HttpError =>
-  ip !== null && classifyAddress(ip) === 'loopback'
+  ip !== null && peerAddressClass(ip) === 'loopback'
     ? new HttpError({
         code: 'X_CSRF_BLOCKED',
         cause: `${pathname} refused a write it could not show came from this app: ${reason}`,
-        fix: "curl -H 'sec-fetch-site: same-origin' -X POST http://localhost:3000/the-path-above   # a local client proves same-origin the way a browser does; the session cookie still decides who is calling",
+        fix: `curl -H 'sec-fetch-site: same-origin' -X POST ${renderFixShellArg(`${origin}${pathname}`, "'<the url of this request>'")}   # a local client proves same-origin the way a browser does; the session cookie still decides who is calling`,
       })
     : new HttpError({
         code: 'X_CSRF_BLOCKED',
         cause: `${pathname} refused a write it could not show came from this app: ${reason}`,
-        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",
+        fix: "call it with an Authorization: Bearer token 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",
       });
+
+/**
+ * `meta.csrf: 'cookieless'` is a claim about the route's credential, so it holds only where the
+ * route names that credential itself: without `meta.authenticate` the app's cookie authenticator
+ * runs there, and the exemption would wave through the forged write this stage exists to refuse.
+ */
+export const assertRouteCsrf = (
+  meta: { readonly name: string; readonly csrf?: 'cookieless'; readonly authenticate?: unknown },
+  path: string,
+): void => {
+  if (meta.csrf !== 'cookieless' || meta.authenticate !== undefined) return;
+  throw new HttpError({
+    code: 'X_CONFIG_INVALID',
+    cause: `route ${meta.name} (${path}) declares csrf: 'cookieless' but no meta.authenticate, so the app's configureAuthenticator() — the session cookie — still decides who calls it`,
+    fix: `meta: { csrf: 'cookieless', authenticate: () => null }   # on the route declaring ${meta.name}, or its own non-cookie credential; or drop csrf: 'cookieless'`,
+    meta: { route: meta.name, path, option: 'csrf' },
+  });
+};

package/src/deadline.ts

@@ -4,8 +4,8 @@
 // until the process died, and SIGTERM then waited out the whole drain budget for work that would
 // never finish.
 
-import { REQUEST_TIMEOUT_HEADER, systemClock } from '@ultimat3/core';
-import { type HttpConfig, MAX_TIMER_MS } from './config';
+import { MAX_TIMER_MS, REQUEST_TIMEOUT_HEADER, systemClock } from '@ultimat3/core';
+import type { HttpConfig } from './config';
 import { requestTimedOut } from './errors';
 
 /**

package/src/error-facts.ts

@@ -2,8 +2,10 @@
 // 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 type { ErrorRetry } from '@ultimat3/core';
 import {
   ERROR_DOCS_URL,
+  errorRetry,
   FRAMEWORK_CODE,
   failureStack,
   hasPublicCause,
@@ -13,6 +15,7 @@ import {
   stringField,
 } from '@ultimat3/core';
 import type { ValidationIssue } from '@ultimat3/schema';
+import { issueRuleFacts } from '@ultimat3/schema';
 import { declaredStatusFor, statusFor } from './error-status';
 import { HTTP_ERROR_TITLES } from './errors';
 import { type ProblemMeta, problemMetaKeysFor, wireMeta } from './problem-meta';
@@ -204,6 +207,9 @@ function issuesOf(error: unknown): readonly ValidationIssue[] | undefined {
         // Forced, never copied. See the paragraph above.
         received: '',
         message,
+        // The rule a translator keys on, and its declared params — schema's one reader, which
+        // keeps a string `rule` and scalar `params` only, member by member.
+        ...issueRuleFacts(entry),
       });
     }
     return issues;
@@ -241,7 +247,20 @@ function metaOf(error: unknown, code: string): ProblemMeta | undefined {
  */
 export const problemTypeFor = (code: string): string => `urn:ultimate:error:${singleLine(code)}`;
 
-/** RFC-9457 problem document. `code`/`cause`/`fix`/`docs` are our extensions. */
+/**
+ * Core's `errorRetry`, total, for `retryAfterOf`'s reason: `retry` is a getter read on a value this
+ * package did not build, in the frame that decides what the caller sees. Refusing to be read is
+ * `terminal`, which is what the same value's unclassified failure answers.
+ */
+const retryOf = (error: unknown): ErrorRetry => {
+  try {
+    return errorRetry(error);
+  } catch {
+    return 'terminal';
+  }
+};
+
+/** RFC-9457 problem document. `code`/`cause`/`fix`/`docs`/`retry` are our extensions. */
 export interface ProblemDocument {
   readonly type: string;
   readonly title: string;
@@ -252,6 +271,11 @@ export interface ProblemDocument {
   readonly cause: string;
   readonly fix: string;
   readonly docs: string;
+  /**
+   * May the same call be sent again: core's class, the one a thrown `UltimateError` carries. On
+   * every document, hidden ones included: it says what to do, never what happened.
+   */
+  readonly retry: ErrorRetry;
   readonly requestId: string | undefined;
   /**
    * The rejections, addressed by path, for a failure that produced them. TOP-LEVEL and not an
@@ -351,6 +375,7 @@ export const toProblem = (
         ? facts.fix
         : (facts.callerFix ?? (hidden ? explainFix(facts.code) : facts.fix)),
     docs: facts.docs,
+    retry: retryOf(error),
     requestId: meta.requestId,
     ...(issues === undefined ? {} : { issues }),
     ...(carried === undefined ? {} : { meta: carried }),

package/src/error-map-http.ts

@@ -55,6 +55,9 @@ export const HTTP_ERROR_STATUS = {
   X_RATE_LIMIT_INVALID: 500,
   // The shared store did not answer, so nothing decided. An operator's fault, never the caller's.
   X_RATE_LIMIT_STORE_UNAVAILABLE: 500,
+  // The store's own deadline passed. The store degrades on it rather than throwing, so a request
+  // answered with it is the store's bug; 500, and never a 503 the `admit` stage alone answers.
+  X_RATE_LIMIT_STORE_TIMEOUT: 500,
   // The two the `admit` stage answers with, and the only 503s the pipeline produces. Both carry
   // `retry-after`: a shed request that does not say when to come back is a request that comes
   // back immediately, which is the load it was shed to avoid.