@ultimat3/http 23.0.0 → 24.0.0

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

@@ -0,0 +1,60 @@
+// 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,
+} satisfies Readonly<Record<string, number>>;

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

@@ -0,0 +1,71 @@
+// 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,
+} satisfies Readonly<Record<string, number>>;

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

@@ -0,0 +1,118 @@
+// 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,
+} satisfies Readonly<Record<string, number>>;

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

@@ -0,0 +1,92 @@
+// 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,
+} satisfies Readonly<Record<string, number>>;

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

@@ -0,0 +1,92 @@
+// One slice of the status table `error-map.ts` composes: tier 4 — `render`, `pwa`, `mcp`, `ai`, `manifest`, `mail`, `ui`, `notify`.
+// A row here is a code owned by a tier-4 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_4_ERROR_STATUS = {
+  // @ultimat3/notify — five 500s and one 502, and the split is who failed.
+  //
+  // The five are the app's own declaration: a notifier with no channels, one channel named twice,
+  // a digest window on a bulk channel, a store nothing installed, and a fan-out past the per-run
+  // ceiling. Every `fix:` on those five names a code edit or a boot call, so nothing a caller
+  // sends changes any of them — `X_NOTIFY_FANOUT_TOO_WIDE` is the only one a request can even
+  // INFLUENCE (an action that notifies a whole org), and the repair is still `bulkChannel()` or a
+  // paged `backfill()`, never the request.
+  X_NOTIFY_CHANNELS_EMPTY: 500,
+  X_NOTIFY_CHANNEL_DUPLICATE: 500,
+  X_NOTIFY_FANOUT_TOO_WIDE: 500,
+  X_NOTIFY_STORE_MISSING: 500,
+  X_NOTIFY_DIGEST_UNSUPPORTED: 500,
+  // 502, and it is the one row on this table that answers for somebody else's server. This code
+  // WRAPS a provider rejection — `NotifyDeliveryFailedError` takes the caught value and renders it
+  // — so the thing that failed is the channel's upstream, not this process. It is thrown inside a
+  // job step today (`x jobs show <notifier> --json` is its own `fix:`), so nothing reaches a
+  // request and the number is unobservable either way; the row is chosen for the day that stops
+  // being true, and the asymmetry decides it. A wrong 502 costs nothing. A wrong 500 pages the
+  // on-call for an email provider's outage, because `stages.ts` reports every `status >= 500` to
+  // the error monitor — which is the failure this whole table exists to stop.
+  X_NOTIFY_DELIVERY_FAILED: 502,
+  // @ultimat3/ui — a form control whose `name` is not a usable field path. The owning slice argued
+  // for NO ROW, on the grounds that this is a render-time developer error that can never reach
+  // HTTP, and the argument is right about the code and wrong about the table.
+  //
+  // `scripts/error-map-backlog.ts` is the only "no row" this table has, and its own header says
+  // what an entry there means: "NOT a claim that the code can never cross HTTP … a claim that
+  // nobody has decided yet", with the ratchet promising only that the undecided set never grows.
+  // This code HAS been decided, so a pin would record the opposite of what is known and grow the
+  // one list that may not grow.
+  //
+  // So it takes the answer every other decided-and-unreachable code takes — `X_CORS_CONFIG_INVALID`,
+  // `X_ACTION_JOB_UNBRIDGED`, `X_RATE_LIMIT_NOT_SHARED`. The row is NOT a claim that it reaches a
+  // request. A code with no row already answers 500 (`DEFAULT_STATUS`); the row changes nothing at
+  // runtime and makes that answer a reviewed one instead of an accident, which is the whole reason
+  // this table is closed.
+  X_UI_FORM_PATH_INVALID: 500,
+  // @ultimat3/ui — `defineTheme()` refused a brand palette whose RESOLVED channels put a pairing
+  // below WCAG 2.2 AA. Declaration-time in the ordinary case, and it takes a row rather than a
+  // backlog entry for the one case that is not: an app that renders a per-tenant brand stylesheet
+  // during a request throws this ON that request. The author's fault and never the caller's, so
+  // 500 is the honest class, and a DECLARED 500 rather than an unclassified one — `toProblem`
+  // blanks the cause of an unclassified failure outside dev, which would hide the one thing that
+  // makes this error actionable: the role and the measured ratio.
+  X_UI_CONTRAST_INSUFFICIENT: 500,
+  // @ultimat3/ui — `<QrCode>` was handed a value past the encoder's version-3 ceiling. The value
+  // is the app's own (a short URL it minted), never the caller's, so 500 is the honest class —
+  // and a declared 500 for the contrast code's reason: `toProblem` blanks an unclassified
+  // failure's cause outside dev, and the cause is where the byte count and the ceiling are.
+  X_UI_QR_CAPACITY: 500,
+  // @ultimat3/render — an island handed props it cannot carry: an undeclared key, a value that is
+  // not JSON, or a bag over `ISLAND_PROPS_MAX_BYTES`. The author's fault and never the caller's,
+  // so 500 is the honest class — and it HAS to be a declared 500. Without a row the code was an
+  // 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.
+  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
+  // unclassified 500 blanks the sentence naming the status and the `redirect()` to use instead.
+  X_ROUTE_STATUS_INVALID: 500,
+  // `asset('assets/…')` named a file that is not on disk. The static build refuses it, but an `ssr`
+  // page calls `asset()` INSIDE the request it renders, so it reaches a caller there — a deploy
+  // defect, never the visitor's, hence 500, declared so the cause naming the missing file survives.
+  X_ASSET_MISSING: 500,
+  // @ultimat3/mail
+  // The deployment configured no transport. It reaches a caller only through an inline
+  // `send(…, { sync: true })` inside a request; the queued path dead-letters instead. A server-side
+  // configuration fault either way, so 500 and never a 4xx — nothing the caller sent is wrong, and
+  // this is exactly the condition somebody should be paged for.
+  X_MAIL_CREDENTIAL_MISSING: 500,
+  // @ultimat3/mcp — the one MCP code that is answered on a REQUEST rather than inside a JSON-RPC
+  // envelope, which is what the rest of that package's backlog group says about the others: the
+  // transport refused before dispatch, so there is no call to answer. 429 because
+  // `mcpHttpRoute` already builds that response by hand (`transport-http.ts`'s `throttled`), with
+  // `retry-after` beside it. The row is what keeps the two surfaces from disagreeing the day the
+  // MCP host is mounted inside this pipeline — a code that renders 429 on one and 500 on the other
+  // is exactly the split this table exists to prevent.
+  X_MCP_RATE_LIMITED: 429,
+  // The second MCP code answered on a request before dispatch, and 413 for the same reason the row
+  // above is 429: `transport-http.ts` already answers it with that status by hand.
+  X_MCP_BODY_TOO_LARGE: 413,
+  // @ultimat3/ai — a vector store was read with no tenant bound inside an org request
+  X_VECTOR_UNSCOPED: 500,
+} satisfies Readonly<Record<string, number>>;