@ultimat3/http 29.4.0 → 30.1.0

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

@@ -59,4 +59,30 @@ export const TIER_0_ERROR_STATUS = {
   X_INTERNAL: 500,
   // @ultimat3/core — a Set-Cookie value would be dropped, misread or injectable
   X_COOKIE_INVALID: 500,
+  // @ultimat3/core — an outbound HTTP call passed its deadline or went idle
+  X_OUTBOUND_TIMEOUT: 504,
+  // @ultimat3/core — an outbound HTTP call got no response
+  X_OUTBOUND_UNREACHABLE: 503,
+  // @ultimat3/core — an outbound HTTP call was told to wait
+  X_OUTBOUND_THROTTLED: 503,
+  // @ultimat3/core — an outbound HTTP call answered a retryable status
+  X_OUTBOUND_UNAVAILABLE: 502,
+  // @ultimat3/core — an outbound HTTP call answered a non-retryable status
+  X_OUTBOUND_REFUSED: 502,
+  // @ultimat3/core — an outbound HTTP response body passed its byte cap
+  X_OUTBOUND_TOO_LARGE: 502,
+  // @ultimat3/core — an outbound HTTP call refused the address it would reach
+  X_OUTBOUND_HOST_BLOCKED: 400,
+  // @ultimat3/core — an outbound HTTP call answered a redirect
+  X_OUTBOUND_REDIRECTED: 502,
+  // @ultimat3/core — an outbound HTTP response did not match its schema
+  X_OUTBOUND_BODY_INVALID: 502,
+  // @ultimat3/core — a circuit breaker is open and refused the call
+  X_BREAKER_OPEN: 503,
+  // @ultimat3/core — a path parameter and the request body or query name one key with two values
+  X_HTTP_PATH_INPUT_CONFLICT: 400,
+  // @ultimat3/core — a handler threw a 4xx code its errors: list does not declare. Reachable: `x dev`
+  // raises it inside a request. The handler broke its own contract, so it is a 500 and never the
+  // 4xx it replaced; production answers the original and this row is not read.
+  X_ERROR_UNDECLARED: 500,
 } satisfies Readonly<Record<string, number>>;

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

@@ -84,4 +84,26 @@ export const TIER_1_ERROR_STATUS = {
   X_SITEMAP_ENTRY_INVALID: 500,
   // @ultimat3/storage — the requested byte range starts past the end of the object
   X_STORAGE_RANGE_UNSATISFIABLE: 416,
+  // @ultimat3/db — statement on a finished transaction
+  X_DB_TRANSACTION_CLOSED: 500,
+  // @ultimat3/storage — the object changed while it was being promoted
+  X_STORAGE_OBJECT_CHANGED: 409,
+  // @ultimat3/db — the connection pooler refused the libpq options a pool connects with
+  X_DB_POOLER_OPTIONS_REFUSED: 503,
+  // @ultimat3/storage — an upload grant was asked for without the size of the file
+  X_STORAGE_UPLOAD_SIZE_UNDECLARED: 422,
+  // @ultimat3/storage — a write was sent and its answer lost, and the disk could not say whether it landed
+  X_STORAGE_WRITE_OUTCOME_UNKNOWN: 500,
+  // @ultimat3/db — a keyset page holds a null in one of its sort keys
+  X_KEYSET_NULL_KEY: 500,
+  // @ultimat3/storage — this disk cannot take an upload in parts
+  X_STORAGE_MULTIPART_UNSUPPORTED: 501,
+  // @ultimat3/storage — no open multipart upload has that id
+  X_STORAGE_UPLOAD_UNKNOWN: 404,
+  // @ultimat3/storage — the parts named do not match the parts stored
+  X_STORAGE_PARTS_INVALID: 422,
+  // @ultimat3/money — a typed amount could not be read in this locale
+  X_MONEY_INPUT_INVALID: 422,
+  // @ultimat3/seo — a route meta og declares both image and capture
+  X_SEO_OG_IMAGE_CONFLICT: 500,
 } satisfies Readonly<Record<string, number>>;

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

@@ -119,4 +119,20 @@ export const TIER_2_ERROR_STATUS = {
   X_ENTITY_APPEND_ONLY: 409,
   // @ultimat3/entity — a predicate names an operator outside the vocabulary
   X_ENTITY_OPERATOR_UNKNOWN: 500,
+  // @ultimat3/auth — a consent was approved for a request the authorization server refuses
+  X_AUTH_CONSENT_INVALID: 422,
+  // @ultimat3/auth — a verification token was issued or consumed for a purpose nothing declared
+  X_VERIFICATION_PURPOSE_UNKNOWN: 400,
+  // @ultimat3/entity — a repository has no series
+  X_ENTITY_SERIES_UNSUPPORTED: 501,
+  // @ultimat3/entity — a time series asked for something no bucket can answer
+  X_ENTITY_SERIES_INVALID: 422,
+  // @ultimat3/entity — a view entity was asked to write a row
+  X_ENTITY_VIEW_READ_ONLY: 500,
+  // @ultimat3/auth — a passkey ceremony response failed its signature, origin, rp id, flag or counter check
+  X_PASSKEY_INVALID: 401,
+  // @ultimat3/auth — a passkey ceremony named a challenge that is unknown, already used or past its ttl
+  X_PASSKEY_CHALLENGE_EXPIRED: 401,
+  // @ultimat3/auth — a sensitive action ran without a fresh user-verified passkey proof for its digest
+  X_PASSKEY_STEP_UP_REQUIRED: 401,
 } satisfies Readonly<Record<string, number>>;

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

@@ -89,6 +89,10 @@ 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/jobs — an enqueue whose payload names an org the caller is not acting for. Raised in
+  // the handler that enqueued, so it reaches the socket; 403 like `X_TENANCY_ACTOR_MISMATCH`: the
+  // caller asked for work in another tenant. The worker's run-time refusal never answers a request.
+  X_JOB_TENANT_MISMATCH: 403,
   // @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
@@ -103,4 +107,24 @@ export const TIER_3_ERROR_STATUS = {
   X_QUERY_DOWNLOAD_TOKEN_INVALID: 403,
   // @ultimat3/query — a download URL is past its expiry
   X_QUERY_DOWNLOAD_TOKEN_EXPIRED: 410,
+  // @ultimat3/action — an idempotent action's answer cannot be stored as JSON, so no retry could replay it
+  X_IDEMPOTENCY_OUTPUT_UNSERIALIZABLE: 500,
+  // @ultimat3/action — a keyed run passed its hard ceiling
+  X_IDEMPOTENCY_RUN_CEILING: 504,
+  // @ultimat3/jobs — an inbound webhook could not be queued, so it was not acknowledged
+  X_WEBHOOK_RECEIVER_UNAVAILABLE: 503,
+  // @ultimat3/jobs — the event id a webhook receiver verified is not one it can key a job by
+  X_WEBHOOK_EVENT_ID_INVALID: 422,
+  // @ultimat3/query — a query's pinned http.path is not a valid path template
+  X_QUERY_HTTP_PATH_INVALID: 500,
+  // @ultimat3/realtime — no socket is open for the device a request addressed
+  X_DEVICE_OFFLINE: 503,
+  // @ultimat3/realtime — a device did not answer a request before its deadline
+  X_DEVICE_REQUEST_TIMEOUT: 504,
+  // @ultimat3/realtime — a device socket frame is over the framework frame limit
+  X_DEVICE_FRAME_TOO_LARGE: 413,
+  // @ultimat3/action — an action's usage meter is spent for this period
+  X_METER_EXCEEDED: 429,
+  // @ultimat3/action — an action's meter cannot be counted against
+  X_METER_INVALID: 500,
 } satisfies Readonly<Record<string, number>>;

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

@@ -60,7 +60,7 @@ export const TIER_4_ERROR_STATUS = {
   // unclassified failure, and `toProblem` blanks the cause of one of those outside dev
   // (`isUnclassifiedFailure`): a 34-row catalog over the cap took a page down with a problem
   // document that said "the details are in this process's logs" about an error whose whole
-  // value is the sentence naming the prop and its bytes. Measured on ai-maxxing, 2026-09-05.
+  // value is the sentence naming the prop and its bytes. Measured on one adopter's app, 2026-09-05.
   X_ISLAND_PROPS_INVALID: 500,
   // A loader answered `withStatus` with a 3xx, or a status outside 200–599. Raised INSIDE the
   // request that ran the loader, so it needs a row for the same reason the line above does: an
@@ -148,4 +148,36 @@ export const TIER_4_ERROR_STATUS = {
   X_AGENT_TOOL_UNDECLARED: 500,
   // @ultimat3/ai — an agent's next request would not fit its model's context window
   X_AGENT_CONTEXT_EXHAUSTED: 500,
+  // @ultimat3/notify — another attempt holds this delivery
+  X_NOTIFY_DELIVERY_HELD: 409,
+  // @ultimat3/mcp — the request names an MCP protocol version this server does not serve
+  X_MCP_PROTOCOL_UNSUPPORTED: 400,
+  // @ultimat3/mcp — an MCP request header is absent or disagrees with the body
+  X_MCP_HEADER_MISMATCH: 400,
+  // @ultimat3/mcp — an MCP request came from a browser page on another origin
+  X_MCP_ORIGIN_REFUSED: 403,
+  // @ultimat3/mcp — an MCP request named a Host that is not this machine
+  X_MCP_HOST_REFUSED: 421,
+  // @ultimat3/ai — a provider refused a request as longer than the model context window
+  X_AI_CONTEXT_OVERFLOW: 500,
+  // @ultimat3/mcp — a remote MCP server failed or refused the call
+  X_MCP_REMOTE_REFUSED: 502,
+  // @ultimat3/mcp — a remote MCP server needs authorization this app does not hold
+  X_MCP_REMOTE_AUTH_REQUIRED: 502,
+  // @ultimat3/scraping — the PDF request names no single page size a print engine can lay out
+  X_SCRAPE_PDF_OPTIONS_INVALID: 422,
+  // @ultimat3/mcp — an MCP confirmation needs more approvers before the call runs
+  X_MCP_CONFIRMATION_QUORUM_PENDING: 409,
+  // @ultimat3/mcp — an MCP confirmation approval carries no valid signed evidence
+  X_MCP_CONFIRMATION_EVIDENCE_INVALID: 403,
+  // @ultimat3/mcp — mcpConfirmations approvers resolved a quorum no approver set can meet
+  X_MCP_CONFIRMATION_QUORUM_INVALID: 500,
+  // @ultimat3/mcp — a per-caller MCP catalog names one tool twice
+  X_MCP_CATALOG_TOOL_DUPLICATE: 500,
+  // @ultimat3/mcp — a per-caller MCP catalog could not be resolved
+  X_MCP_CATALOG_UNRESOLVED: 500,
+  // @ultimat3/mcp — an MCP call names no tenant
+  X_MCP_TENANT_REQUIRED: 400,
+  // @ultimat3/mcp — the tenant of an MCP call could not be resolved
+  X_MCP_TENANT_UNRESOLVED: 500,
 } satisfies Readonly<Record<string, number>>;

package/src/error-page.ts

@@ -12,14 +12,14 @@ import { OVERLAY_STYLE } from './overlay-style';
 import { html } from './response';
 
 /**
- * Where "Built with Ultimate" goes. Two literals and not a derivation off `ERROR_DOCS_URL`: the
- * wiki page it points at is a different destination that merely shares a prefix today. They live
- * here, next to their one renderer — a second surface that wants them (a CLI banner, a scaffolded
- * footer) is what would move them to `@ultimat3/core`.
+ * Where "Built with Ultimate" goes. A literal and not a derivation off `ERROR_DOCS_URL`: the wiki
+ * page it points at is a different destination that merely shares a prefix today. It is the one
+ * outside link: this page reaches every app without a page of its own, so a vendor homepage here
+ * was an advert on a stranger's site (removed in 30.0.0). A second surface that wants it is what
+ * would move it to `@ultimat3/core`.
  */
-export const ERROR_PAGE_LINKS = Object.freeze<Record<'repository' | 'homepage', string>>({
+export const ERROR_PAGE_LINKS = Object.freeze<Record<'repository', string>>({
   repository: 'https://github.com/developerz-ai/ultimate',
-  homepage: 'https://www.developerz.ai',
 });
 
 /** One key group in the framework catalog's `errors.*` namespace, which is what this page renders. */
@@ -175,7 +175,6 @@ export function renderErrorPage(input: ErrorPageInput): string {
   </section>
   <footer class="card">
     ${link(ERROR_PAGE_LINKS.repository, t('errors.page.builtWith'))}
-    ${link(ERROR_PAGE_LINKS.homepage, 'developerz.ai')}
   </footer>
 </main>
 </body>

package/src/error-status.ts

@@ -1,6 +1,15 @@
 // Reading the status table: the framework's row for a code through `Object.hasOwn`, the app's
 // own codes beside it (`registerErrorStatus`), and the answer a response gets. The table itself is
-// `error-map.ts`; split out when the table outgrew the file that also read it.
+// `error-map.ts`; the app's half lives in core (`error-status-declared.ts`), where `defineError`
+// writes it too.
+//
+// The table's internal seam, never the barrel: an app's writers are `defineError` and this module's
+// `registerErrorStatus`, and nothing else may write or read the app's half directly.
+import {
+  appErrorStatus,
+  declareAppErrorStatus,
+  resetAppErrorStatus,
+} from '@ultimat3/core/internal/error-status';
 import { ERROR_STATUS } from './error-map';
 import { errorStatusInvalid } from './errors';
 
@@ -21,19 +30,19 @@ const BY_CODE: Readonly<Record<string, number>> = ERROR_STATUS;
 const frameworkStatus = (code: string): number | undefined =>
   Object.hasOwn(BY_CODE, code) ? BY_CODE[code] : undefined;
 
-/**
- * Statuses for codes the APP owns. The table above is closed — it has to be, it is the
- * framework's own contract — and every code outside it fell to 500, so a wrong password was an
- * incident: `pipeline.ts` reports `status >= 500` to the error monitor, and a user's typo paged
- * whoever was on call. This is the app's half of the same table, kept separate so a registration
- * can never move `X_FORBIDDEN` off 403.
+/*
+ * Statuses for codes the APP owns live in `@ultimat3/core`'s `error-status-declared.ts`. The table
+ * above is closed — it has to be, it is the framework's own contract — and every code outside it
+ * fell to 500, so a wrong password was an incident: `pipeline.ts` reports `status >= 500` to the
+ * error monitor, and a user's typo paged whoever was on call. The app's half is kept separate so a
+ * registration can never move `X_FORBIDDEN` off 403, and it sits in core because `defineError`,
+ * the one declaration of an app code, writes it from there.
  */
-const APP_ERROR_STATUS = new Map<string, number>();
 
 /**
- * Declare the status for the codes this app throws. Call it once at boot, beside the module
- * that declares the codes — importing that module IS the registration, the convention
- * `registerActions` and `registerErrorCodes` already use.
+ * Declare the status for codes this app throws but does not DECLARE — a code it re-raises from a
+ * library, say. A code the app owns is declared with core's `defineError`, which takes its status
+ * in the same call. Call this once at boot; importing the module that calls it IS the registration.
  *
  * ```ts
  * registerErrorStatus({ X_CREDENTIALS_INVALID: 401, X_SIGNUP_CLOSED: 403 });
@@ -53,16 +62,16 @@ export const registerErrorStatus = (statuses: Readonly<Record<string, number>>):
     if (framework !== undefined) {
       throw errorStatusInvalid(code, `the framework already maps it to ${framework}`);
     }
-    const existing = APP_ERROR_STATUS.get(code);
+    const existing = appErrorStatus(code);
     if (existing !== undefined && existing !== status) {
       throw errorStatusInvalid(code, `already registered as ${existing} by this app`);
     }
-    APP_ERROR_STATUS.set(code, status);
+    declareAppErrorStatus(code, status);
   }
 };
 
 /** Test seam. Production registers once at boot and never unregisters. */
-export const resetErrorStatus = (): void => APP_ERROR_STATUS.clear();
+export const resetErrorStatus = (): void => resetAppErrorStatus();
 
 /**
  * The status SOMEBODY declared for a code — the framework or the app — or `undefined` when
@@ -73,10 +82,10 @@ 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.
+ * The app's half is a `Map`, which is why it never had `frameworkStatus`'s defect — prefer one for
+ * anything keyed by a value a caller chose.
  */
 export const declaredStatusFor = (code: string): number | undefined =>
-  frameworkStatus(code) ?? APP_ERROR_STATUS.get(code);
+  frameworkStatus(code) ?? appErrorStatus(code);
 
 export const statusFor = (code: string): number => declaredStatusFor(code) ?? DEFAULT_STATUS;

package/src/error-titles.ts

@@ -37,6 +37,7 @@ export const HTTP_OWNED_ERROR_CODES = [
   'X_WEBHOOK_SIGNATURE_INVALID',
   'X_WEBHOOK_SIGNATURE_STALE',
   'X_BEARER_MOUNT_INVALID',
+  'X_RATE_LIMIT_STORE_TIMEOUT',
 ] as const;
 
 export type HttpOwnedErrorCode = (typeof HTTP_OWNED_ERROR_CODES)[number];
@@ -71,6 +72,7 @@ export const HTTP_ERROR_TITLES: Readonly<Record<HttpOwnedErrorCode, string>> = {
   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',
+  X_RATE_LIMIT_STORE_TIMEOUT: 'the shared rate-limit store did not answer inside its own deadline',
 };
 
 // Registered at module load, unconditionally, in one call, so core's registry renders OUR title

package/src/errors.ts

@@ -255,12 +255,11 @@ export const problemMetaInvalid = (code: string, reason: string): HttpError =>
  * "emit no CORS headers at all", which is unreadable from the console: every cross-origin call
  * fails and nothing on the server said anything.
  */
-export const corsConfigInvalid = (reason: string): HttpError =>
-  new HttpError({
-    code: 'X_CORS_CONFIG_INVALID',
-    cause: `cors config rejected: ${reason}`,
-    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",
-  });
+export const corsConfigInvalid = (
+  reason: string,
+  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",
+): HttpError =>
+  new HttpError({ code: 'X_CORS_CONFIG_INVALID', cause: `cors config rejected: ${reason}`, fix });
 
 /**
  * At `defineHttpConfig`. A directive name and a source both go into the header VERBATIM, and the
@@ -409,7 +408,7 @@ 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 call configureHttp({ requestTimeoutMs: 60_000 }) at module scope in a file under apps/*/',
+    fix: 'make every vendor call with outbound({ url, vendor, dial, deadlineMs }) from @ultimat3/core/outbound, which hears ctx.signal and the deadline, and call throwIfAborted(ctx) before expensive work, or call configureHttp({ requestTimeoutMs: 60_000 }) at module scope in a file under apps/*/. A write past the deadline is refused: wrap work that must land whole, runToCompletion(() => withTransaction(fn)), never a statement inside the transaction, whose COMMIT stays refused',
     meta: { timeoutMs },
   });
 
@@ -423,13 +422,23 @@ export const requestTimedOut = (method: string, pathname: string, timeoutMs: num
  * that arrived, never the secret, and never the body — because a `cause` reaches both the caller
  * and the log store, and a credential in either is a leak wearing a diagnostic's clothes.
  */
-export const webhookSignatureInvalid = (pathname: string, reason: string): HttpError =>
+export const webhookSignatureInvalid = (
+  pathname: string,
+  reason: string,
+  via: WebhookVerifier = 'verifyWebhookSignature',
+): HttpError =>
   new HttpError({
     code: 'X_WEBHOOK_SIGNATURE_INVALID',
     cause: `${pathname} refused an inbound webhook: ${reason}`,
-    fix: 'sign the delivery with the secret this endpoint was registered under, or re-read the secret from your sender dashboard and pass it as verifyWebhookSignature(request, { secret })',
+    fix:
+      via === 'verifyBodyHmac'
+        ? 'verifyBodyHmac({ bytes, secret, given, encoding, prefix }) — compare encoding and prefix with the vendor docs, sign over the exact bytes the vendor names, and re-read the secret from the vendor dashboard'
+        : 'sign the delivery with the secret this endpoint was registered under, or re-read the secret from your sender dashboard and pass it as verifyWebhookSignature(request, { secret })',
   });
 
+/** The two inbound checks, named so a refusal's `fix:` is the call its caller made. */
+export type WebhookVerifier = 'verifyWebhookSignature' | 'verifyBodyHmac';
+
 /**
  * Signed correctly, and outside the replay window. Its own code because the repair is a different
  * one: a sender's clock, or a delivery being replayed off a capture. Same 401 — the credential is
@@ -453,10 +462,16 @@ export const webhookSignatureStale = (
  * repair is the route's configuration and nothing a sender does can fix it. `shape` is `typeof`
  * or "an empty string" — never the value, which is a credential when it is one.
  */
-export const webhookSecretMissing = (shape: string): HttpError =>
+export const webhookSecretMissing = (
+  shape: string,
+  via: WebhookVerifier = 'verifyWebhookSignature',
+): HttpError =>
   new HttpError({
     code: 'X_CONFIG_INVALID',
-    cause: `verifyWebhookSignature was given ${shape} as its secret, and a mac under an empty key is one anyone can compute — every forged delivery would verify`,
-    fix: "verifyWebhookSignature(request, { secret: process.env.WEBHOOK_SECRET ?? '' }) in the api/ route receiving it, with WEBHOOK_SECRET set in the deployment environment to the signing secret the sender shows for this endpoint — an unset variable is then refused here rather than verified against",
+    cause: `${via} was given ${shape} as its secret, and a mac under an empty key is one anyone can compute — every forged delivery would verify`,
+    fix:
+      via === 'verifyBodyHmac'
+        ? "verifyBodyHmac({ bytes, secret: process.env.VENDOR_WEBHOOK_SECRET ?? '', given, encoding }) in the receiver's verify, with VENDOR_WEBHOOK_SECRET set on the web role to the signing secret the vendor shows — an unset variable is then refused here rather than verified against"
+        : "verifyWebhookSignature(request, { secret: process.env.WEBHOOK_SECRET ?? '' }) in the receiver's verify, with WEBHOOK_SECRET set in the deployment environment to the signing secret the sender shows for this endpoint — an unset variable is then refused here rather than verified against",
     meta: { option: 'webhook secret' },
   });

package/src/finalize.ts

@@ -31,6 +31,7 @@ const lastResort = (): Response =>
       code: 'X_INTERNAL',
       cause: 'the error renderer itself failed, so nothing of the original error survives here',
       fix: 'grep the logs for pipeline.problem_failed — it carries the renderer failure this reply could not',
+      retry: 'terminal',
     }),
     {
       status: 500,

package/src/index.ts

@@ -24,6 +24,8 @@ export { bearerMount, bearerTokenOf, mountedPath } from './bearer-mount';
 /** One `Range:` reader for every route that answers bytes — `/_storage`, site assets, a download. */
 export type { RequestedRange } from './byte-range';
 export { byteWindow, contentRangeOf, parseByteRange, RANGE_UNSATISFIABLE } from './byte-range';
+export { PRIVATE_REVALIDATE } from './cache-policy';
+export { COMPRESS_MAX_BYTES, COMPRESS_MIN_BYTES, isCompressibleType } from './compress';
 export type { HttpConfig, HttpConfigInput } from './config';
 export { defineHttpConfig, MAX_PROXY_HOPS } from './config';
 export type { ActorView, RequestContext, RequestContextInit } from './context';
@@ -37,6 +39,7 @@ export {
   useRequestCookie,
   useRequestHeader,
   useRequestHeaders,
+  withAnonymousRequest,
 } from './context';
 export type { InboundCorrelation } from './correlation';
 export type { CorsConfig } from './cors';
@@ -114,7 +117,7 @@ export {
   socketIdleTimeoutSeconds,
 } from './idle-timeout';
 export type { LocaleConfig, TimeZoneConfig } from './locale';
-export { DEFAULT_LOCALE_CONFIG } from './locale';
+export { DEFAULT_LOCALE_CONFIG, DEFAULT_TZ_CONFIG } from './locale';
 export type { RequestAddress } from './locale-prefix';
 export { requestAddress } from './locale-prefix';
 export type { Middleware } from './middleware';
@@ -127,6 +130,13 @@ export {
   redirectForRouter,
   relocate,
 } from './navigation';
+export type {
+  ObjectRequest,
+  ObjectResponseOptions,
+  ObjectSource,
+  ServableObject,
+} from './object-response';
+export { notModified, objectResponse } from './object-response';
 export type { OverlayMeta, OverlayNotice } from './overlay';
 export { overlayResponse, wantsOverlay } from './overlay';
 export { OVERLAY_STYLE } from './overlay-style';
@@ -186,6 +196,7 @@ export {
   postgresRateLimitStore,
   SQL_RATE_LIMIT_TABLE,
 } from './rate-limit-postgres';
+export { RATE_LIMIT_STORE_DEADLINE_MS } from './rate-limit-store-deadline';
 export { setRedirect, takeRedirect } from './redirect';
 export type { QueryValues } from './request';
 export { UltimateRequest } from './request';
@@ -233,16 +244,20 @@ export type {
   WebSocketMount,
 } from './server';
 export { httpServer } from './server';
+export type { WebSocketOption } from './server-websocket';
 export type { DeleteCookieOptions } from './set-cookie';
 export { deleteCookie, setCookie } from './set-cookie';
-// The stage vocabulary comes from its declaration site, beside the fourteen implementations it
+// The stage vocabulary comes from its declaration site, beside the fifteen implementations it
 // names; `PIPELINE_STAGES` — the ORDER — stays `pipeline.ts`'s.
 export type { Stage, StageDoc, StageName, StagePhase, StageRun } from './stages';
 export type { InferOutput, Schema, ValidationOutcome } from './validate';
 export { formatIssue, validateBody, validateSync } from './validate';
+export type { BodyHmacOptions, VerifiedBody } from './webhook-hmac';
+export { verifyBodyHmac } from './webhook-hmac';
 export type { VerifiedWebhook, WebhookVerifyOptions } from './webhook-verify';
 export {
   DEFAULT_WEBHOOK_BODY_LIMIT,
   DEFAULT_WEBHOOK_TOLERANCE_MS,
   verifyWebhookSignature,
 } from './webhook-verify';
+export { type JoinedWebSocketMounts, joinWebSocketMounts } from './websocket-mounts';

package/src/locale.ts

@@ -4,7 +4,7 @@
 // lived here and all three disagreed with their owner about the same request.
 
 import { LOCALE_COOKIE } from '@ultimat3/i18n';
-import { TIMEZONE_HEADER } from '@ultimat3/time';
+import { TIMEZONE_DETECTED_COOKIE, TIMEZONE_HEADER } from '@ultimat3/time';
 
 export interface LocaleConfig {
   /** Cookie the client sets when the user picks a locale explicitly. */
@@ -15,6 +15,8 @@ export interface TimeZoneConfig {
   /** Header the client sets from `Intl.DateTimeFormat().resolvedOptions().timeZone`. */
   readonly header: string;
   readonly cookie: string;
+  /** The zone script's guess (`@ultimat3/render`'s `zoneScript`): never the chosen `cookie`. */
+  readonly detectedCookie: string;
 }
 
 /**
@@ -31,4 +33,5 @@ export const DEFAULT_LOCALE_CONFIG: LocaleConfig = {
 export const DEFAULT_TZ_CONFIG: TimeZoneConfig = {
   header: TIMEZONE_HEADER,
   cookie: 'x_timezone',
+  detectedCookie: TIMEZONE_DETECTED_COOKIE,
 };

package/src/object-response.ts

@@ -0,0 +1,134 @@
+// Single responsibility: the one correct answer to a GET for an object held elsewhere — its stored
+// type, its validator, one `Range:` window, the sandbox for a type a browser would run. `/_storage`,
+// `/media`, a download and an app's own route for an object a stranger may fetch all answer here.
+// Structural, because this package imports no storage: anything with these fields is servable.
+
+import {
+  contentRangeOf,
+  parseByteRange,
+  RANGE_UNSATISFIABLE,
+  type RequestedRange,
+} from './byte-range';
+import type { CacheHint } from './response';
+import { applyCacheHeaders } from './response';
+import { storedObjectHeaders } from './stored-object-headers';
+
+/** What the answer needs to know before it opens anything. `StorageObject` is one of these. */
+export interface ServableObject {
+  /** The STORED type. An extension in the URL is the only party that can lie. */
+  readonly contentType: string;
+  readonly size: number;
+  /** The object's own validator. Absent or `''` (unknowable): no `etag` header, and no 304. */
+  readonly etag?: string | undefined;
+  /** Omitted, never invented: a made-up date is a validator a cache would go on to trust. */
+  readonly lastModified?: Date | undefined;
+}
+
+export interface ObjectSource {
+  readonly object: ServableObject;
+  /**
+   * Exactly those bytes, or the whole object with no range. Opened only once a body will be sent: a
+   * 304 and a 416 open nothing. Takes the range so a disk can serve a window, not drop a prefix.
+   */
+  readonly open: (range?: RequestedRange) => BodyInit | Promise<BodyInit>;
+}
+
+/** The one thing asked of the request, so a test or a non-pipeline caller needs no `Request`. */
+export interface ObjectRequest {
+  header(name: string): string | null;
+}
+
+export interface ObjectResponseOptions {
+  /** Applied to every answer. Omitted, the route's declared `meta.cache` decides as for any route. */
+  readonly cache?: CacheHint | undefined;
+  /** Replaces the stored-object sandbox rule, for a caller with its own, as a download has. */
+  readonly headers?: Readonly<Record<string, string>> | undefined;
+}
+
+/** `*`, a weak validator and a comma list all count — the etag is what has to match. */
+export function etagMatches(header: string | null, etag: string): boolean {
+  if (header === null) return false;
+  if (header.trim() === '*') return true;
+  return header.split(',').some((candidate) => candidate.trim().replace(/^W\//, '') === etag);
+}
+
+/**
+ * The 304 for a client already holding `etag`, or nothing for the caller to go on and answer. It
+ * repeats the validator and whatever posture `headers` carry (RFC 9110 §15.4.5).
+ */
+export function notModified(
+  request: ObjectRequest,
+  etag: string,
+  headers?: HeadersInit,
+): Response | undefined {
+  if (!etagMatches(request.header('if-none-match'), etag.replace(/^W\//, ''))) return undefined;
+  const answer = new Headers(headers);
+  answer.set('etag', etag);
+  return new Response(null, { status: 304, headers: answer });
+}
+
+/**
+ * Whether `if-range` still names these bytes. Compared strongly, and a date only if it is exactly
+ * the object's: a window of an older revision spliced onto this one is two files in one download.
+ */
+function ifRangeHolds(header: string | null, etag: string | undefined, modified?: Date): boolean {
+  if (header === null) return true;
+  const validator = header.trim();
+  if (validator.startsWith('W/')) return false;
+  if (validator.startsWith('"')) return etag === validator;
+  return modified?.toUTCString() === validator;
+}
+
+/** A provider's etag may arrive already quoted, and quoting it again answers an invalid header. */
+const quotedEtag = (etag: string): string =>
+  etag.startsWith('"') || etag.startsWith('W/"') ? etag : `"${etag}"`;
+
+/**
+ * Revalidation costs a request and no bytes, which is the trade an authorized response wants: the
+ * bytes do not change under a validator, but the actor's permission to read them can be revoked.
+ * The size is the object's description, so the length declared is the length `open` must deliver.
+ */
+export async function objectResponse(
+  request: ObjectRequest,
+  source: ObjectSource,
+  options: ObjectResponseOptions = {},
+): Promise<Response> {
+  const { object } = source;
+  const headers = new Headers({
+    'content-type': object.contentType,
+    'accept-ranges': 'bytes',
+    // A type a browser would RUN (html, svg, xml) is a download, never a page on this origin.
+    ...(options.headers ?? storedObjectHeaders(object.contentType)),
+  });
+  if (object.lastModified !== undefined) {
+    headers.set('last-modified', object.lastModified.toUTCString());
+  }
+  const answer = (body: BodyInit | null, status: number): Response => {
+    const response = new Response(body, { status, headers });
+    return options.cache === undefined ? response : applyCacheHeaders(response, options.cache);
+  };
+
+  const etag =
+    object.etag === undefined || object.etag === '' ? undefined : quotedEtag(object.etag);
+  if (etag !== undefined) {
+    headers.set('etag', etag);
+    if (notModified(request, etag) !== undefined) return answer(null, 304);
+  }
+
+  const { size } = object;
+  // A range of another revision is no range at all: the whole object, never a 416 either.
+  const range = ifRangeHolds(request.header('if-range'), etag, object.lastModified)
+    ? parseByteRange(request.header('range'), size)
+    : undefined;
+  if (range === RANGE_UNSATISFIABLE) {
+    headers.set('content-range', `bytes */${String(size)}`);
+    return answer(null, 416);
+  }
+  if (range === undefined) {
+    headers.set('content-length', String(size));
+    return answer(await source.open(), 200);
+  }
+  headers.set('content-range', contentRangeOf(range, size));
+  headers.set('content-length', String(range.end - range.start + 1));
+  return answer(await source.open(range), 206);
+}

package/src/overlay.ts

@@ -75,7 +75,16 @@ export const renderOverlay = (error: unknown, meta: OverlayMeta = {}): string =>
     dev: true,
   });
   const where = `${meta.method ?? ''} ${meta.path ?? ''}`.trim();
-  return `<style>${OVERLAY_STYLE}</style>
+  // A whole document, `lang` and `<title>` included: an e2e test's accessibility audit reads the
+  // overlay like any page, and a fragment has neither.
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>${escapeHtml(`${facts.code} ${facts.title}`)}</title>
+<style>${OVERLAY_STYLE}</style>
+</head>
+<body>
 <main>
   <section class="card">
     <h1>${escapeHtml(facts.code)} <span class="title">${escapeHtml(facts.title)}</span></h1>
@@ -105,7 +114,9 @@ export const renderOverlay = (error: unknown, meta: OverlayMeta = {}): string =>
     <h2>json</h2>
     <pre>${escapeHtml(JSON.stringify(problem, null, 2))}</pre>
   </section>
-</main>`;
+</main>
+</body>
+</html>`;
 };
 
 export const overlayResponse = (error: unknown, meta: OverlayMeta = {}): Response =>