agentic-dev/docs/decisions/adr-027-domain-error-matching-by-name.md

ADR-027 — Domain errors match by canonical name, not class identity

Status: Accepted · 2026-07-31

Context

defineErrorMiddleware (core-shared) translates feature domain errors to tRPC codes from feature-owned [Ctor, "CODE"] maps. It originally matched result.error.cause instanceof Ctor — class identity.

A downstream app built from this template hit the failure in production: a use case threw UnauthenticatedError, whose [UnauthenticatedError, "UNAUTHORIZED"] mapping exists, yet the client received a raw 500. Root cause: web-next starts through the template's custom server (node --import tsx server.ts — the Socket.IO-ready entry). The DI container binds feature modules loaded by tsx, while the tRPC route handler executes inside the Next/webpack-compiled bundle. Two module graphs, two copies of every error class. The thrown instance and the registered constructor are different objects, instanceof is false, and every mapped error falls through to tRPC's default INTERNAL_SERVER_ERROR.

The failure is doubly deceptive: the HTTP status lies (500 for an expected domain condition), and a routine domain signal presents as a server fault — in the downstream incident an expected UNAUTHORIZED was debugged as an infrastructure crash.

Constraints on any fix:

• Feature-owned maps stay. core-shared must not enumerate feature error classes (existing rule), and the [Ctor, "CODE"] call-site API is used across features/cores — churn there multiplies the diff.
• Server minification. Next minifies server bundles; class identifiers (Ctor.name) may be mangled, so a fix keyed on the static class name is not reliable. String literals survive minification.
• Existing convention. Every domain error class in the template already sets this.name = "<ClassName>" from a string literal in its constructor.

Decision

1. Match by canonical error name, with identity as a fast path. At middleware-definition time, probe one instance per registered constructor (new Ctor("__probe__")) and record its .name — the value assigned from the string literal, which survives both module-graph duplication and minification. At request time an error matches an entry when cause instanceof Ctor or cause.name === canonicalName.
2. Nameless classes match by identity only. A class that never sets a custom name probes as the inherited "Error"; name-matching is disabled for that entry, otherwise every unmapped plain Error would translate.
3. this.name from a string literal becomes a load-bearing convention. Every domain error class MUST assign this.name = "<ClassName>" in its constructor (string literal, matching the class name), and error constructors MUST be side-effect-free and callable with a single message argument (the probe relies on it). This was already universal practice; it is now the matching key.
4. Call sites unchanged. All existing defineErrorMiddleware([[Ctor, "CODE"], ...]) usages keep working verbatim.

Alternatives considered

• Ctor.name comparison (no probe) — rejected: minified server bundles can mangle class identifiers while leaving the constructor-body string literal intact; the probe reads the literal.
• Shared DomainError base class with a code discriminator — rejected (for now): touches every feature's error classes and public contracts to achieve the same runtime behavior name-matching gets with a one-file change. Revisit if error metadata beyond a code is ever needed.
• Unify the module graphs (make the webpack bundle resolve the same module instances the tsx DI graph holds) — rejected: depends on Next bundling internals and externals configuration, fragile across upgrades, and would silently regress the day either toolchain changes resolution.
• Serialize errors at the feature boundary (throw plain objects with a code) — rejected: reshapes the whole error architecture (capture, __sentryReported flag, .cause chains) for a problem the name check solves locally.

Consequences

• Domain errors now surface with their mapped codes regardless of which module graph constructed them; 500 again means "actual server fault".
• Within one feature's map, two classes sharing a name would both match the first entry. Maps are feature-scoped and small, and names conventionally equal the class name, so collisions indicate a naming bug — acceptable.
• The regression test encodes the failure mode (structurally identical class, same name, different identity) so the cross-graph scenario stays covered even where local test runs use a single module graph.
• Any generator or new feature emitting error classes must keep the this.name string-literal assignment — it is no longer cosmetic.