Reference: Runtime Error Registry

Last verified 2026-09-03 against engine v1.0.232.

The runtime error registry is the closed, typed taxonomy of runtime gateway failures: one catalog that every runtime failure resolves a stable machine code against, projected to the frontend and to a generated reference, and read at the boundary that turns a thrown error into a player-safe public code. This page is the contract for its surfaces, invariants, proof surfaces, and limits. It links down to the generated catalog and never restates it; for the codes themselves, their categories and dispositions, and the static copy each carries, read the generated reference.

The model behind this reference (why failures are typed rather than parsed, and which behaviors are the catalog's versus the frontend's) is in the Runtime Error Registry explanation.

Source of truth

The taxonomy is owned in one file and projected, never re-authored:

• The catalog RUNTIME_ERROR_CATALOG in server/src/modules/runtime/errors/runtimeErrorCatalog.ts is the single source of truth. The code union RuntimeGatewayErrorCode, the ordered RUNTIME_ERROR_CODES, the closed RUNTIME_ERROR_CATEGORIES, and the lookup runtimeErrorCatalogEntry all derive from it.
• The frontend registry web_client/spa/src/runtime/generated/runtimeErrorRegistry.gen.ts is generated from the catalog by generateRegistrySource in scripts/generate-runtime-error-registry.mjs.
• The generated reference docs/spec/generated/error-catalog.md is generated from the same catalog by gen-error-catalog-docs.ts.
• The boundary classifier runtimeGatewayPublicCode in server/src/modules/runtime/routes.ts maps a thrown error to a stable public code, and runtimeGatewayPublicMessageForCode maps that code to player copy from the catalog.

Surfaces

Invariants

Each row is backed by a named conformance test or check.

Proof surfaces

• Frontend drift-sync. server/tests/runtimeErrorTaxonomy.test.ts renders the catalog fresh and asserts byte-equality with the committed runtimeErrorRegistry.gen.ts; checkRegistryDrift in the generator pins the same equality as a check.
• Boundary classification. server/src/modules/runtime/runtimeGatewayErrors.test.ts drives runtimeGatewayPublicCode and runtimeGatewayPublicMessage across the alias, authority-recovering, access-denied, admission, and untyped cases, and asserts no internal prose reaches player copy.
• Boundary lint. check:runtime-error-taxonomy (in the root check chain) delegates no-prose-classification to scripts/check-no-prose-error-matching.mjs, runs the generator drift check, and runs analyzeCodedErrorSites over server/src/modules/runtime; check:runtime-error-registry (also in the chain) runs the generator drift check on its own.
• Generated-reference drift. gen-error-catalog-docs.ts --check inside gen-docs:check holds docs/spec/generated/error-catalog.md byte-exact against the catalog.

Numbers

The runtime error code count and category count are carried by the generated reference (its Error code count and Category count lines) and are not restated here; read them from the generated Runtime Error Catalog. They are pinned by gen-docs:check (byte-exact projection) and by the drift-sync and deleted-table-coverage tests in server/tests/runtimeErrorTaxonomy.test.ts.

The retryable and terminal values are per-entry data, not numeric constants; they are pinned by the category and retryability invariants above rather than by a scalar.

Limits

• Terminal-when-disconnected is not catalog data. The first-frame family is retryable and non-terminal in the catalog; the disconnected-terminal promotion lives in TERMINAL_WHEN_DISCONNECTED in web_client/spa/src/runtime/runtimeErrorPresentation.ts.
• The Retry affordance is frontend policy. NO_RETRY_ACTION in runtimeErrorPresentation.ts decides whether a Retry label appears; the catalog does not carry it.
• Two internal codes are not catalog members. RUNTIME_CAPACITY_EXHAUSTED_CODE and RUNTIME_DEPLOYMENT_SUPERSEDED_CODE in server/src/modules/runtime/runtimeGatewayErrors.ts only alias onto game_full and game_updating inside runtimeGatewayPublicCode.
• runtime_origin_forbidden bypasses the catalog. It is emitted directly as a 403 with an inline message in server/src/modules/runtime/routes.ts, is not a catalog member, does not pass through the classifier or runtimeGatewayPublicMessageForCode, and returns nothing from runtimeErrorPresentation on the frontend (generic fallback copy). The catalog is the taxonomy the classifier produces, not every code the gateway can emit.
• The frontend category enum is hand-maintained. feCategoryForCode in runtimeErrorPresentation.ts is distinct from the taxonomy category and falls back to a generic connection category for any unmapped taxonomy value, so a newly added taxonomy category is not surfaced there automatically.
• runtime_connection_unverified is a retained catch-all kept for server-table coverage during migration; new throw sites should use a specific split code (runtime_auth_invalid, runtime_credential_expired, runtime_release_stale_link, or runtime_session_ended).
• Variable-argument codedError(code) sites are out of scope for the taxonomy gate and rely on the TypeScript union check instead of analyzeCodedErrorSites.
• The runtime_internal operator description names a stale logger. The live logger is logRuntimeGatewayUntypedError in server/src/modules/runtime/routes.ts; the operator string recorded on the runtime_internal entry names a different, non-live function and is emitted verbatim into the generated reference. It is operator-facing text only and never reaches a player.
• The unit is not enrolled in the feature-contract registry. server/src/lib/featureContractRegistry.ts carries no entry for it, so the closure gate does not yet force its anchor to resolve; it sits at the internal tier.