@ultimat3/http 29.3.2 → 30.0.0

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.

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

@@ -82,4 +82,28 @@ export const TIER_1_ERROR_STATUS = {
   X_STORAGE_ALREADY_PROMOTED: 409,
   // @ultimat3/seo — a sitemap entry carries a lastmod or a locale the sitemap cannot write
   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
@@ -97,4 +101,30 @@ export const TIER_3_ERROR_STATUS = {
   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,
+  // @ultimat3/query — rows were asked of a query that answers a file
+  X_QUERY_DOWNLOAD_ONLY: 400,
+  // @ultimat3/query — a download URL carries a token this app did not mint for it
+  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

@@ -21,6 +21,11 @@ export type {
   BearerResolver,
 } from './bearer-mount';
 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';
@@ -34,6 +39,7 @@ export {
   useRequestCookie,
   useRequestHeader,
   useRequestHeaders,
+  withAnonymousRequest,
 } from './context';
 export type { InboundCorrelation } from './correlation';
 export type { CorsConfig } from './cors';
@@ -111,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';
@@ -124,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';
@@ -183,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';
@@ -230,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,
 };