@ultimat3/http 23.0.0 → 25.0.0

package/src/deadline.ts

@@ -5,19 +5,16 @@
 // never finish.
 
 import { REQUEST_TIMEOUT_HEADER, systemClock } from '@ultimat3/core';
-import type { HttpConfig } from './config';
+import { type HttpConfig, MAX_TIMER_MS } from './config';
 import { requestTimedOut } from './errors';
 
 /**
  * A caller may SHORTEN this request's deadline, never lengthen it. Honoured without trusting the
  * proxy, because the only thing it can buy an attacker is a faster 504 for their own request.
  *
- * The name is core's, re-exported rather than declared twice: this package READS the header and
- * `@ultimat3/core`'s typed-client wire path WRITES it, and a second literal is a propagation that
- * stops working the day one of the two strings is edited. Same shape as `logger.ts` re-exporting
- * `REDACTED` — one definition, one public path.
+ * The header name is core's `REQUEST_TIMEOUT_HEADER`, imported: this package READS it and core's
+ * typed-client wire path WRITES it, so one literal, at the tier both reach, with one import path.
  */
-export { REQUEST_TIMEOUT_HEADER };
 
 export interface Deadline {
   /** Aborted when the deadline passes. Handed to the context as `ctx.signal`. */
@@ -46,13 +43,18 @@ const NO_DEADLINE: Deadline = {
   clear: () => undefined,
 };
 
-/** The configured budget, or the caller's if theirs is shorter. `0` means "no deadline". */
+/**
+ * The configured budget, or the caller's if theirs is shorter. `0` means "no deadline".
+ *
+ * An ask above `MAX_TIMER_MS` is no ask: no timer can hold it — the runtime arms such a delay as
+ * ~1 ms, so "a very long deadline" was `X_TIMEOUT` within a tick — and a caller may only shorten.
+ */
 export const resolveTimeoutMs = (headers: Headers, config: HttpConfig): number => {
   const configured = config.requestTimeoutMs;
   const raw = headers.get(REQUEST_TIMEOUT_HEADER);
   if (raw === null) return configured;
   const asked = Number.parseInt(raw, 10);
-  if (!Number.isFinite(asked) || asked < 1) return configured;
+  if (!Number.isFinite(asked) || asked < 1 || asked > MAX_TIMER_MS) return configured;
   return configured > 0 ? Math.min(configured, asked) : asked;
 };
 

package/src/error-facts.ts

@@ -5,6 +5,7 @@
 import {
   ERROR_DOCS_URL,
   FRAMEWORK_CODE,
+  hasPublicCause,
   isUltimateError,
   renderCauseValue,
   singleLine,
@@ -13,7 +14,7 @@ import {
 import type { ValidationIssue } from '@ultimat3/schema';
 import { declaredStatusFor, statusFor } from './error-status';
 import { HTTP_ERROR_TITLES } from './errors';
-import { hasPublicCause, type ProblemMeta, problemMetaKeysFor, wireMeta } from './problem-meta';
+import { type ProblemMeta, problemMetaKeysFor, wireMeta } from './problem-meta';
 
 /** Everything a renderer (problem+json, overlay, terminal) needs from a throwable. */
 export interface ErrorFacts {
@@ -270,6 +271,14 @@ export interface ProblemDocument {
   readonly meta?: ProblemMeta | undefined;
 }
 
+/**
+ * The fix a hidden document carries: the code's own registry entry, nothing off the throwable.
+ * `FRAMEWORK_CODE` gates it for `factsOf`'s reason — this is a command a reader pastes, and `code`
+ * is a string field off a value this package did not build.
+ */
+const explainFix = (code: string): string =>
+  FRAMEWORK_CODE.test(code) ? `x errors explain ${code} --json` : 'x errors list --json';
+
 /** The title a caller gets for a failure the framework cannot name. */
 const INTERNAL_TITLE = 'unhandled server error';
 
@@ -331,7 +340,14 @@ export const toProblem = (
     // The CALLER's fix outside dev: a production client cannot run `x policy explain`, and the
     // developer's line stays in the log this request wrote. Dev keeps the developer's, because the
     // reader of a dev response is the developer.
-    fix: meta.dev === true ? facts.fix : (facts.callerFix ?? facts.fix),
+    // HIDDEN, the developer's fix is withheld with the cause it was built beside: a driver or repo
+    // error writes its fix from the statement, the row or the path it failed on, so serving it
+    // under a blanked cause put back what the blanking took out. A declared `callerFix` is
+    // authored FOR the caller and still goes; otherwise the line names the code and nothing else.
+    fix:
+      meta.dev === true
+        ? facts.fix
+        : (facts.callerFix ?? (hidden ? explainFix(facts.code) : facts.fix)),
     docs: facts.docs,
     requestId: meta.requestId,
     ...(issues === undefined ? {} : { issues }),

package/src/error-map-http.ts

@@ -0,0 +1,94 @@
+// One slice of the status table `error-map.ts` composes: `@ultimat3/http`'s own codes.
+// A row here is a code owned by `@ultimat3/http`; `bun run new-error-code` appends to the slice its
+// `--package` belongs to, so no one file grows with every code the framework adds.
+
+export const HTTP_ERROR_STATUS = {
+  // @ultimat3/http
+  X_ROUTE_NOT_FOUND: 404,
+  X_METHOD_NOT_ALLOWED: 405,
+  // The request line itself is unreadable, so there is nothing to route: 400, and never a 500 —
+  // a malformed escape is the caller's typo, not this server's defect.
+  X_PATH_INVALID: 400,
+  X_BODY_INVALID: 422,
+  X_UNAUTHENTICATED: 401,
+  X_FORBIDDEN: 403,
+  X_RATE_LIMITED: 429,
+  X_BUILD_SKEW: 409,
+  X_ROUTE_CONFLICT: 500,
+  X_SERVER_NOT_STARTED: 500,
+  X_PIPELINE_NO_RESPONSE: 500,
+  // The request was answered and the answer could not be finished: the caller gets nothing usable
+  // either way, so this is the server's failure, never the caller's.
+  X_PIPELINE_FINALIZE_FAILED: 500,
+  // Both are wiring bugs, never a caller's mistake: reading a cookie where no request exists,
+  // and declaring a status the framework already owns. 500 is the honest answer to either.
+  X_NO_REQUEST: 500,
+  X_ERROR_STATUS_INVALID: 500,
+  X_PROBLEM_META_INVALID: 500,
+  // A `hive()` whose `split()` returned no members. The caller cannot fix it by sending
+  // different input — the guard belongs in the app, either by returning at least one member
+  // or by skipping the hive when the source is empty — so it is the server's bug, not theirs.
+  X_HIVE_EMPTY: 500,
+  // Thrown while `app.config.ts` resolves, so no request is ever answered with it — the row exists
+  // because a code with no status is a 500 anyway and this table is the closed one.
+  X_CORS_CONFIG_INVALID: 500,
+  // Core's code, borrowed by `defineHttpConfig` for a numeric knob that is not a count. Same
+  // construction-time shelf as the row above, and it needs a row for the same reason: this table
+  // is closed over every code the package can throw, borrowed ones included.
+  X_CONFIG_INVALID: 500,
+  X_CSP_DIRECTIVE_INVALID: 500,
+  // Thrown while the server is being constructed, so no request is ever answered with it either.
+  // The row exists because this table is the closed one: a code missing from it is a 500 anyway,
+  // and a code the framework owns must never fall through to the app's table.
+  X_RATE_LIMIT_NOT_SHARED: 500,
+  // Same construction-time class as the row above: a route and the config declare one bucket
+  // differently, and the process refuses to start rather than pick.
+  X_RATE_LIMIT_BUCKET_CONFLICT: 500,
+  // Construction time as well: the limiter installed cannot enforce a bucket a route declares.
+  X_RATE_LIMIT_BUCKET_UNBOUND: 500,
+  // `defineHttpConfig` time, all three: a declaration the deployment owes and did not make, or
+  // made against a bucket nothing declares.
+  X_RATE_LIMIT_SCOPE_UNSET: 500,
+  X_RATE_LIMIT_TENANT_BUCKET_UNKNOWN: 500,
+  X_TRUST_PROXY_UNSET: 500,
+  // Raised by `toBucket` while a route or an action is being projected, never on the request.
+  X_RATE_LIMIT_INVALID: 500,
+  // The shared store did not answer, so nothing decided. An operator's fault, never the caller's.
+  X_RATE_LIMIT_STORE_UNAVAILABLE: 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.
+  X_DRAINING: 503,
+  X_OVERLOADED: 503,
+  // Core's flight gate refusing past `maxQueued` is the same answer one tier down: it carries
+  // `retryAfterSeconds` in `meta`, which `stages.ts` renders onto `Retry-After`, so a caller that
+  // already handles a shed request needs no second branch for a refused one.
+  X_FLIGHT_GATE_OVERLOADED: 503,
+  // 403 and never 401: the caller IS authenticated — that is what makes the forged write work —
+  // so a 401 would send a signed-in user to a sign-in page they are already past.
+  X_CSRF_BLOCKED: 403,
+  // 401 for both, and never 400: an inbound webhook is well formed and carries a CREDENTIAL — a
+  // timestamped hmac over its own bytes — so what failed is authentication, not the request. Never
+  // 403 either, which means an authenticated caller was refused, and there is no authenticated
+  // caller here. Two codes rather than one because the repairs differ and a sender's dashboard
+  // shows the status: `INVALID` is the wrong secret or a rewritten body, `STALE` is a skewed clock
+  // or a delivery being replayed off a capture. Neither triggers `signInRedirect`, which keys on
+  // `X_UNAUTHENTICATED` alone — a webhook sender is not a browser and has no session to go get.
+  X_WEBHOOK_SIGNATURE_INVALID: 401,
+  X_WEBHOOK_SIGNATURE_STALE: 401,
+  // Boot refusals of the app's HTTP declaration (a bearer mount, an action's pinned path or the
+  // app's path style or a path derived before it, the openapi block, the MCP oauth block or an
+  // idempotent tool shadowing its key argument, a page's `post` or `navigation`) — never a request's
+  // answer; 500 if one ever escaped into a response (`x dev` re-evaluating an edited route module):
+  // the deployment is wrong, the caller is not.
+  X_BEARER_MOUNT_INVALID: 500,
+  X_ACTION_HTTP_PATH_INVALID: 500,
+  X_ACTION_PATH_STYLE_INVALID: 500,
+  X_ACTION_PATH_DERIVED_EARLY: 500,
+  X_OPENAPI_CONFIG_INVALID: 500,
+  X_MCP_OAUTH_INVALID: 500,
+  X_MCP_PATH_DUPLICATE: 500,
+  X_MCP_IDEMPOTENCY_KEY_SHADOWED: 500,
+  X_ROUTE_POST_INVALID: 500,
+  X_ROUTE_NAVIGATION_INVALID: 500,
+} satisfies Readonly<Record<string, number>>;

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

@@ -0,0 +1,62 @@
+// One slice of the status table `error-map.ts` composes: tier 0 — `core`, `schema`.
+// A row here is a code owned by a tier-0 package; `bun run new-error-code` appends to the slice its
+// `--package` belongs to, so no one file grows with every code the framework adds.
+
+export const TIER_0_ERROR_STATUS = {
+  // @ultimat3/core (declared beside `assertLocale`; `@ultimat3/time` owned it until 16.x) — the
+  // sibling of the row above, and strictly more the caller's fault: not a tag at all. It was
+  // pinned as unable to reach a request because the `locale` stage negotiates and never throws,
+  // which is true of that stage and irrelevant to `?locale=`, a path segment or an action input
+  // reaching `formatDate` / `formatMoney` / `describeCron`. Those raised it and answered 500,
+  // paging the on-call for a string the caller typed.
+  X_LOCALE_INVALID: 400,
+  // @ultimat3/core — `seal()` / `open()`. All three are reachable from a request (a sealed column
+  // read inside an action) and none is the caller's doing: the deploy has no key, the ring lost a
+  // retired key, or a stored value did not authenticate. 500, stated rather than defaulted.
+  X_SEAL_INVALID: 500,
+  X_SEAL_KEY_MISSING: 500,
+  X_SEAL_KEY_UNKNOWN: 500,
+  // @ultimat3/core
+  // The caller asked for a format the pipeline cannot produce (`?f=avif`): the request names an
+  // unsupported representation, which is 415 — not a 500, which would blame the server for it.
+  X_IMAGE_UNSUPPORTED: 415,
+  // A page token this server minted and the caller echoed back, and it did not verify — tampered,
+  // or replayed against another read. The caller's value and the caller's repair ("request the
+  // first page again"), so it belongs beside `X_IMAGE_QUERY_INVALID` at 400 and not at 500.
+  X_CURSOR_INVALID: 400,
+  // Raised by `markReady()` while a role STARTS, in a process whose lifecycle already drained — so
+  // no request is ever answered with it, and the row exists for the reason the construction-time
+  // rows above do: this table is the closed one, and a code with no row is a 500 anyway.
+  X_LIFECYCLE_DRAINED: 500,
+  X_NOT_IMPLEMENTED: 501,
+  X_TIMEOUT: 504,
+  X_ABORTED: 499,
+  // The twin of `X_ABORTED`, and it answers the same because the outcome is the same: the caller
+  // went away there, the caller's generation moved on here, and in both cases nobody will act on
+  // the answer. Deliberately not 409 — that spelling asks the client to reconcile and try again,
+  // and a fenced answer has nothing to reconcile against.
+  X_SUPERSEDED: 499,
+  // Plan 101's client seam. A typed call made from a server handler: an upstream that gave no usable
+  // answer is 502, the fence is `X_SUPERSEDED`'s twin. The rest are browser-side or declaration-time
+  // refusals no request carries; their rows keep the table closed.
+  X_CLIENT_TRANSPORT_FAILED: 502,
+  X_CLIENT_RECORD_ENVELOPE_INVALID: 502,
+  X_CLIENT_SCOPE_CHANGED: 499,
+  X_CHANNEL_DECLARATION_INVALID: 500,
+  X_LOCAL_STORE_UNAVAILABLE: 500,
+  X_MUTATOR_CLOCK_MISSING: 500,
+  X_REALTIME_UNINSTALLED: 500,
+  // Boot-time: a realtime config and its environment that disagree refuse before any request.
+  X_REALTIME_TOPOLOGY: 500,
+  // The replicator's own Postgres connection failed TLS. A role that never answers a request, so the
+  // row keeps the table closed at 500, beside `X_REALTIME_TOPOLOGY`.
+  X_REPLICATION_TLS: 500,
+  // A browser page on a foreign origin asked for a socket — refused, not unauthenticated: 403.
+  X_SOCKET_ORIGIN_REFUSED: 403,
+  X_RECORD_KEY_MISSING: 500,
+  X_RECORD_REJECTED: 500,
+  X_SYNC_UNCONFIGURED: 500,
+  X_INTERNAL: 500,
+  // @ultimat3/core — a Set-Cookie value would be dropped, misread or injectable
+  X_COOKIE_INVALID: 500,
+} satisfies Readonly<Record<string, number>>;

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

@@ -0,0 +1,73 @@
+// One slice of the status table `error-map.ts` composes: tier 1 — `i18n`, `money`, `time`, `cache`, `seo`, `db`, `storage`, `flags`.
+// A row here is a code owned by a tier-1 package; `bun run new-error-code` appends to the slice its
+// `--package` belongs to, so no one file grows with every code the framework adds.
+
+export const TIER_1_ERROR_STATUS = {
+  // @ultimat3/db — the constraints a request trips, both 409. db's own `fix:` for the unique
+  // violation says "answer 409, which is what a raced signup is", and `X_ENTITY_DUPLICATE` — the
+  // same event one layer up — is 409 above; a foreign key rides with it because both halves of it
+  // are a conflict with the state that is there (the parent is missing, or the child still points
+  // at it), which 422 describes only for the insert.
+  X_DB_UNIQUE_VIOLATION: 409,
+  X_DB_FOREIGN_KEY_VIOLATION: 409,
+  // @ultimat3/i18n — a well-formed tag outside the set this app ships, asserted on a value the
+  // caller supplied (`assertSupportedLocale`). 400 rather than 406: the http `locale` stage
+  // negotiates `Accept-Language` and never throws, so the tag that reaches here came from a path,
+  // query or body the caller wrote — the same place `X_IMAGE_QUERY_INVALID` comes from.
+  X_LOCALE_UNSUPPORTED: 400,
+  // @ultimat3/money — a well-formed code this process carries no row for. The currency table is
+  // OPEN (`registerCurrency`), and every surface between the wire and the throw accepts any
+  // `^[A-Z]{3}$`: `@ultimat3/schema`'s `CURRENCY_CODE_PATTERN`, the OpenAPI `pattern` emitted from
+  // it, and `@ultimat3/entity`'s `char(3)` CHECK. So `{ minor: 100, currency: 'ZWL' }` parses,
+  // reaches `money()` -> `assertCurrency`, and with no row answered 500 — reporting a value the
+  // framework's own schema had just accepted to the error monitor. 400 rather than 422, beside
+  // `X_LOCALE_UNSUPPORTED`: the same shape of mistake, a well-formed value naming something
+  // outside the set this process carries, and money's `fix:` already instructs the caller.
+  X_CURRENCY_UNKNOWN: 400,
+  // @ultimat3/seo — a transform query the caller wrote, so the caller is the one who can fix it.
+  X_IMAGE_QUERY_INVALID: 400,
+  // @ultimat3/storage — every one of these is reachable from a route: `/media/*` already serves
+  // objects, and a mounted `/_storage` serves signed reads and takes signed writes. Without a row
+  // a missing image answers 500, which reads as an outage instead of a 404.
+  X_STORAGE_NOT_FOUND: 404,
+  X_STORAGE_PATH_UNSAFE: 400,
+  X_STORAGE_TOO_LARGE: 413,
+  X_STORAGE_TYPE_REJECTED: 415,
+  X_STORAGE_CHECKSUM_MISMATCH: 422,
+  X_STORAGE_URL_INVALID: 403,
+  X_STORAGE_URL_EXPIRED: 410,
+  // 500, not 403, and the distinction is the whole reason this code exists rather than
+  // reusing X_STORAGE_URL_INVALID: nothing is wrong with the caller's URL. The disk was
+  // built with no way to check a signature, which is the operator's misconfiguration and
+  // not an attacker — reporting it as 403 sends the on-call hunting somebody who is not there.
+  X_STORAGE_URL_UNVERIFIABLE: 500,
+  // 409, not the 500 it fell through to: the object exists and the request is well formed — the
+  // STATE is wrong. A validated upload lands under the quarantine segment and `promoteAttachment`
+  // refuses it until the app's own scanner calls `releaseQuarantine`, which is a thing the caller
+  // can do. A 500 would have read as "the server broke" for a workflow working exactly as built.
+  X_STORAGE_QUARANTINED: 409,
+  // 409 for the same reason: `promoteAttachment` on a key that is not a pending upload — promoted
+  // twice, or never uploaded — is a state the caller can see and fix, not a server fault.
+  X_STORAGE_NOT_PENDING: 409,
+  // 404, deliberately NOT 403: the org check fires before anything is read, so answering
+  // "forbidden" would confirm that a key exists to the one caller who must not learn it.
+  X_STORAGE_ORG_MISMATCH: 404,
+  // @ultimat3/seo — a `meta.links` entry an `ssr` page's `meta()` built from data: an unsafe href,
+  // a preload with no `as`. Thrown while that request renders its head, so it reaches the caller —
+  // an authoring defect, never the visitor's, hence 500 with the cause naming the link intact.
+  X_SEO_LINK_INVALID: 500,
+  // @ultimat3/db — the server rolled the transaction back
+  X_DB_TRANSACTION_ABORTED: 500,
+  // @ultimat3/db — the connection was lost while COMMIT was in flight
+  X_DB_COMMIT_UNKNOWN: 500,
+  // @ultimat3/db — a nested transaction scope waited too long for its sibling
+  X_DB_SIBLING_SCOPE_TIMEOUT: 500,
+  // @ultimat3/storage — the key collides with another key on the local disk
+  X_STORAGE_KEY_CONFLICT: 409,
+  // @ultimat3/storage — the object could not be written
+  X_STORAGE_PUT_FAILED: 500,
+  // @ultimat3/storage — the object could not be read
+  X_STORAGE_READ_FAILED: 500,
+  // @ultimat3/storage — the object is under retention or a legal hold
+  X_STORAGE_OBJECT_LOCKED: 409,
+} satisfies Readonly<Record<string, number>>;

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

@@ -0,0 +1,120 @@
+// One slice of the status table `error-map.ts` composes: tier 2 but `http` itself — `entity`, `policy`, `auth`.
+// A row here is a code owned by `entity`, `policy` or `auth`; `bun run new-error-code` appends to the slice its
+// `--package` belongs to, so no one file grows with every code the framework adds.
+
+export const TIER_2_ERROR_STATUS = {
+  // @ultimat3/auth — every one of these is reachable from a request: the OAuth route descriptors
+  // are mounted by the app, and `authenticate` throws the session codes inside the pipeline. Without
+  // a row each fell to 500, so a user pressing Cancel on a consent screen paged the on-call and a
+  // provider this app never enabled read as an outage. `packages/auth/src/oauth-route.ts` answers
+  // from this table's values when its descriptors are driven OUTSIDE a pipeline; the pin that keeps
+  // the two identical is `scripts/oauth-route-status.test.ts`, since auth is this tier and cannot
+  // import this package.
+  X_SESSION_EXPIRED: 401,
+  X_MFA_REQUIRED: 401,
+  X_ACCOUNT_LOCKED: 429,
+  X_API_KEY_INVALID: 401,
+  X_OAUTH_STATE_INVALID: 400,
+  X_OAUTH_TOKEN_INVALID: 400,
+  X_OAUTH_PROVIDER_UNKNOWN: 404,
+  X_OAUTH_DENIED: 403,
+  // 502, not 500: the conversation that failed is with the provider's server, and the on-call
+  // question "is it us or them?" is the one a status is read for.
+  X_OAUTH_EXCHANGE_FAILED: 502,
+  // 422 and not 400: the body parsed, the field is a string, and a policy rejected its CONTENT —
+  // the same class as `X_BODY_INVALID` and `X_INVARIANT_VIOLATED` above. Unmapped, a visitor
+  // choosing "password" at a signup form was reported to the on-call monitor as a server fault.
+  X_PASSWORD_WEAK: 422,
+  // 422 for the same reason as the row above, and deliberately not 500: `enrolTotp` throws it for a
+  // secret the CALLER supplied — an import from another MFA system, or a value off a form — and
+  // what failed is that value's content, not the server. `verifyTotp` never throws it (an
+  // unreadable stored secret is a non-verdict there, the rule `verifyAgainst` follows for a hash
+  // Bun cannot read), so a login checking a broken row cannot reach this status at all.
+  X_MFA_SECRET_INVALID: 422,
+  // @ultimat3/entity
+  X_NOT_FOUND: 404,
+  X_ENTITY_DUPLICATE: 409,
+  X_INVARIANT_VIOLATED: 422,
+  X_TENANCY_UNSCOPED: 500,
+  X_DB_DRIFT: 500,
+  // Both are the server's verdict on a statement the app wrote, which is the app's fault and not
+  // the caller's: a request cannot repair a missing migration or a wrong column list.
+  X_DB_SCHEMA_STALE: 500,
+  X_DB_STATEMENT_FAILED: 500,
+  // Logged at boot, never thrown into a request; the row exists so the table stays closed.
+  X_MCP_APP_UNMOUNTED: 500,
+  // The three tenancy refusals, all 403, and all deliberately NOT the 404 `X_STORAGE_ORG_MISMATCH`
+  // takes: that one answers 404 because a 403 on a KEY the caller supplied confirms the key exists.
+  // These three name no resource and read no row — the comparison is the actor against an argument
+  // (`X_TENANCY_ACTOR_MISMATCH`), the actor against nothing at all (`X_TENANCY_ACTOR_ORG_REQUIRED`),
+  // or the actor's scopes at `crossTenant()` (`X_TENANCY_CROSS_DENIED`) — so the answer is the same
+  // whether or not the other tenant's row exists, and a 404 would buy no secrecy for the lie.
+  X_TENANCY_ACTOR_MISMATCH: 403,
+  // 403 and never 401, for the reason `X_CSRF_BLOCKED` is one: the actor may be fully
+  // authenticated and merely carry no org — a service actor minted without one — so a 401 sends a
+  // signed-in caller to a sign-in page that cannot give them a tenant.
+  X_TENANCY_ACTOR_ORG_REQUIRED: 403,
+  X_TENANCY_CROSS_DENIED: 403,
+  // The three aggregate refusals, all 500 and all deliberately NOT a 4xx, for the reason
+  // `X_QUERY_NOT_PAGEABLE` below is one: nothing the caller sends changes the answer, and the fix
+  // is an edit to the read itself. They earn ROWS rather than a pin in `scripts/error-map-backlog.ts`
+  // because each carries an instruction the app's author needs and an unmapped 5xx is blanked —
+  // `toProblem` replaces an undeclared code's cause with `INTERNAL_CAUSE`, so pinning them would
+  // answer "the server failed while handling this request" for a fault whose own `fix:` names the
+  // exact call to write instead. A row costs no extra page: `stages.ts` reports every `status >= 500`
+  // either way.
+  //
+  // Reached with a request waiting, all three, which is why they are not in the backlog's entity
+  // group ("misuse a handler's author makes") — the mixed-currency and the ±2^53 refusals are
+  // decided by the ROWS, so a read that answered for two years starts failing on the day the data
+  // crosses the line, and `approximateCount()` on a chain whose predicates came from the caller's
+  // own optional filters is one query string away.
+  X_AGGREGATE_UNSUPPORTED: 500,
+  X_AGGREGATE_MIXED_CURRENCY: 500,
+  X_APPROXIMATE_COUNT_FILTERED: 500,
+  // The two search refusals, 500 for the reason the three above are: nothing the caller sends
+  // changes either answer. An entity with no searchable column needs a `searchable()` on one, and
+  // a driver that cannot answer a full-text match needs the Postgres one — both are edits to the
+  // app, and both carry a `fix:` that an unmapped 5xx would blank (`toProblem` replaces an
+  // undeclared code's cause with `INTERNAL_CAUSE`).
+  X_SEARCH_UNDECLARED: 500,
+  X_SEARCH_IN_MEMORY: 500,
+  // The three state-machine refusals, and they are deliberately THREE statuses rather than one:
+  // the machine says the transition does not exist, the row says it is somewhere else, or the
+  // column says there is no machine at all — three different readers and three different repairs.
+  //
+  // 422 and not 400: the request is well formed and its schema passed. The transition the caller
+  // named is not one this machine has, which is the same shape as `X_INVARIANT_VIOLATED` above and
+  // takes its status. Refused before any statement opens a connection, so nothing was written.
+  X_STATE_TRANSITION_ILLEGAL: 422,
+  // 409, the lost update caught. The row moved between the read the caller decided on and the
+  // write it asked for — nothing is wrong with either, and the repair is re-read and retry, which
+  // is precisely what a 409 tells a client to do. A 422 would say "your request is unusable",
+  // which is false: the identical request succeeds a moment later.
+  X_STATE_CONFLICT: 409,
+  // 500, the same shelf as `X_SEARCH_UNDECLARED`: a column with no machine is a declaration the
+  // app has not written, and no request changes that.
+  X_STATE_UNDECLARED: 500,
+  // A sealed column named where the database would compare it, or in a view. Both are the app's
+  // own declaration or call, never the caller's input — the same shelf as the two above.
+  X_ENTITY_SEALED_PREDICATE: 500,
+  X_ENTITY_SEALED_IN_VIEW: 500,
+  // @ultimat3/policy
+  X_POLICY_MISSING: 500,
+  // A declaration fault raised at module evaluation, the same shelf as the line above. The row is
+  // not a claim it reaches a request — an unmapped code already answers 500 — it is the answer
+  // being REVIEWED instead of accidental, which is why this table is closed.
+  X_POLICY_CLAUSE_EMPTY: 500,
+  X_PERMISSION_UNKNOWN: 500,
+  // 500, and the page IS the point — deliberately not a 4xx to keep this table quiet.
+  // `enforce()` was handed a surface no adapter answers to, which reaches a request only through a
+  // config-driven route table, a surface name off the wire or a JS host; none of those is a value
+  // the caller can correct, and a 400 would tell them to fix a request that is not the problem.
+  // It is the third authz-dispatch fault beside the two rows above and takes their status for the
+  // same reason: the declaration is wrong, not the call.
+  X_POLICY_SURFACE_UNKNOWN: 500,
+  // @ultimat3/auth — a stored totp secret is not sealed, so it is never read as one
+  X_MFA_SECRET_UNSEALED: 500,
+  // @ultimat3/entity — an append-only entity was asked to rewrite or remove a row
+  X_ENTITY_APPEND_ONLY: 409,
+} satisfies Readonly<Record<string, number>>;

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

@@ -0,0 +1,100 @@
+// One slice of the status table `error-map.ts` composes: tier 3 — `action`, `query`, `jobs`, `realtime`.
+// A row here is a code owned by a tier-3 package; `bun run new-error-code` appends to the slice its
+// `--package` belongs to, so no one file grows with every code the framework adds.
+
+export const TIER_3_ERROR_STATUS = {
+  // @ultimat3/action — the code every primitive throws when the CALLER's input fails the schema
+  // the primitive declared. 400 because that is what the published OpenAPI operation promises for
+  // it, and because a missing row made a typo'd uuid a 500: the caller was told the server broke,
+  // and the `error-map` stage reported the caller's mistake to the on-call monitor.
+  X_INPUT_INVALID: 400,
+  // The one way a SERVER answers this code: a POST to the path an action has under a path style
+  // this app does not serve (`hooks.explainMiss`). 404 because it is still a miss — nothing is
+  // routed there and nothing ran, so the status a proxy or a monitor counts is the one the plain
+  // `X_ROUTE_NOT_FOUND` had; the code and the `fix:` are what changed. Every other raise of it is
+  // client-side or a contract test, and never reaches this table.
+  X_CONTRACT_DRIFT: 404,
+  // A retried `Idempotency-Key` naming a different payload, or one still in flight. 409 because
+  // that is what the action's own OpenAPI operation publishes for it — the runtime answered 500
+  // while the document promised 409, and a client written against the spec read the framework
+  // working exactly as designed as an outage.
+  X_IDEMPOTENCY_CONFLICT: 409,
+  // A blank or over-long `Idempotency-Key` HEADER, refused before the handler runs. 400 and not
+  // the 422 a body gets: what failed is a parameter the OpenAPI operation publishes a `maxLength`
+  // for, which is the same thing `X_INPUT_INVALID` is 400 for.
+  X_IDEMPOTENCY_KEY_INVALID: 400,
+  // 500, and deliberately not the 409 above. `IdempotencyReplayedFailureError` re-throws the FIRST
+  // attempt's own code whenever the store recorded one, so this literal code is reached only when
+  // that attempt failed carrying no code at all: an unclassified throw whose commit state nobody
+  // knows. That is the server's to explain, and it is worth reporting.
+  X_IDEMPOTENCY_REPLAYED_FAILURE: 500,
+  // Same shape as the line above and 500 for the same reason: the store holds a record this
+  // build cannot turn into a result. Deliberately NOT 503 — a rolling deploy is the usual
+  // cause, so a retry may well reach a newer pod and succeed, but this code carries no
+  // `retry-after` and the two 503s above are the only ones that do. Telling a caller to come
+  // back without saying when is the load-shedding mistake, one layer up.
+  X_IDEMPOTENCY_STATUS_UNKNOWN: 500,
+  // @ultimat3/jobs — the ONE jobs code with a row here, and the reason the rest are pinned in
+  // `scripts/error-map-backlog.ts` does not cover it. That pin says "a job runs with no socket
+  // attached; `ROLE=worker` opens no HTTP port at all" — true of `X_JOB_TIMEOUT` and every other
+  // worker-runtime code, and NOT true of a decode failure: `toJobRecord` runs wherever a row is
+  // READ, which includes the admin dashboard's job panel and `x jobs show` served over HTTP.
+  // 500, and it should page: a queue holding rows this build cannot read is an operator's
+  // problem, and nothing the caller sent is wrong.
+  X_JOB_ROW_STATUS_UNKNOWN: 500,
+  // A requeue of a job that is still live — the admin panel's retry, `x jobs retry` over HTTP. The
+  // job's STATE is wrong, not the server: 409, like `X_STORAGE_QUARANTINED`.
+  X_JOB_NOT_REQUEUEABLE: 409,
+  // Thrown by `job()` at declaration, while modules load; no request is answered with it. The row
+  // exists for `X_ACTION_JOB_UNBRIDGED`'s reason: the table is closed, and it is a 500 anyway.
+  X_JOB_DECLARATION_INVALID: 500,
+  // Thrown by `registerJobs()` while the app's modules load, so no request is ever answered with
+  // it either — the row exists for the reason `X_CORS_CONFIG_INVALID`'s does: this table is the
+  // closed one, and a code with no row is a 500 anyway.
+  X_ACTION_JOB_UNBRIDGED: 500,
+  // Every `X_WEBHOOK_*` below is OUTBOUND and is thrown inside a worker: `ROLE=worker` opens no
+  // HTTP port, so none of them ever answers a request. The rows exist for the reason
+  // `X_ACTION_JOB_UNBRIDGED`'s does — this table is the closed one, and a code with no row is a
+  // 500 anyway. The INBOUND pair (`X_WEBHOOK_SIGNATURE_*`, 401) is @ultimat3/http's and sits with
+  // the rest of this package's codes above; these are the ones a delivery ends on.
+  X_WEBHOOK_ENDPOINT_UNKNOWN: 500,
+  X_WEBHOOK_ENDPOINT_INVALID: 500,
+  X_WEBHOOK_ENDPOINT_DISABLED: 500,
+  X_WEBHOOK_EVENT_UNKNOWN: 500,
+  X_WEBHOOK_EVENT_INVALID: 500,
+  X_WEBHOOK_DELIVERY_FAILED: 500,
+  X_WEBHOOK_DELIVERY_THROTTLED: 500,
+  X_WEBHOOK_DELIVERY_REJECTED: 500,
+  // Same class again: an export pass runs in a worker, and both codes refuse the DECLARATION —
+  // a `row()` that answers columns nobody declared, and a page too big to hold. Neither is
+  // anything a caller sent.
+  X_EXPORT_ROW_INVALID: 500,
+  X_EXPORT_PART_TOO_LARGE: 500,
+  // @ultimat3/query — the read declares no id, so no cursor can name a position in it. The one
+  // paging failure that is NOT the caller's: the fix is an edit to the read's own select, nothing
+  // the client sends changes the answer, and the report to the on-call monitor is the point.
+  X_QUERY_NOT_PAGEABLE: 500,
+  // A read filtering or sorting on a column its loader never selected: the fix is the loader's
+  // `select`, nothing the caller sends changes it — the same server-side decision as the row above.
+  X_QUERY_COLUMN_UNSELECTED: 500,
+  // @ultimat3/jobs — the job is running and cannot be removed
+  X_JOB_NOT_REMOVABLE: 409,
+  // @ultimat3/jobs — the job is not waiting on its run time
+  X_JOB_NOT_PROMOTABLE: 409,
+  // @ultimat3/jobs — a job list page was asked for outside its bounds
+  X_JOB_PAGE_INVALID: 400,
+  // @ultimat3/action — a mutator is declared without idempotent: true
+  X_MUTATOR_NOT_IDEMPOTENT: 500,
+  // @ultimat3/action — an idempotent action's reservation was taken over before its transaction could settle it
+  X_IDEMPOTENCY_RESERVATION_LOST: 409,
+  // @ultimat3/jobs — the queue holds no job with this id
+  X_JOB_NOT_FOUND: 404,
+  // @ultimat3/realtime — one principal holds too many sockets on this node
+  X_SOCKET_LIMIT: 429,
+  // @ultimat3/action — an idempotent replay would return a field redacted at rest
+  X_IDEMPOTENT_REPLAY_REDACTED: 409,
+  // @ultimat3/query — a query declares audit: true and no audit sink is installed
+  X_QUERY_AUDIT_SINK_MISSING: 500,
+  // @ultimat3/query — an audited read was refused because the audit sink rejected its record
+  X_QUERY_AUDIT_SINK_FAILED: 503,
+} satisfies Readonly<Record<string, number>>;