Introduce AppError taxonomy with 4 kinds (C6.1 part 1/2)

Establishes `src/main/errors/` with:

- `AppError` base + `Recoverable|UserInput|Upstream|Fatal` subclasses
  keyed on a narrow `ErrorKind = "recoverable" | "user_input" |
  "upstream" | "fatal"` union. Four kinds is deliberate: adding a fifth
  is a conscious proposal, not an inline decision at a catch site.
- `classifyUnknownError(e, fallback)` — required-fallback-meta wrapper
  that refuses to invent classification. If `e` is already an
  AppError it is returned untouched; otherwise the call site's
  intent wins and the raw value is preserved via `cause` (for Error
  instances) or `context.raw` (for anything else).
- `logAppError(logger, raw, fallback, level?)` helper emits one
  structured log line and returns the classified AppError so the
  caller can still branch on `err.kind`.

Why this module exists: 248 catch blocks in src/main/ today are
overwhelmingly `} catch {}` or `log.warn(); return default`. Behaviour
is correct case-by-case but the codebase has no machine-readable signal
for "is this recoverable vs fatal", making it impossible to write
graceful-shutdown logic, telemetry buckets, or catch-site audits.

Part 2 migrates the top-20 high-frequency catch sites. Part 3 (tracked
as C6.2 proposal) covers the remaining 228.

No behavioural change in this commit — it only adds the classifier and
exports.
This commit is contained in:
ZacharyZhang-NY committed 2026-04-20 12:14:55 -04:00
1 parent f849efadf5
commit 08427931b6
3 files changed
+285

No files matched your search

+21
View File
@@ -0,0 +1,21 @@
/**
* Error taxonomy entry point (C6.1).
*
* Re-exports the AppError hierarchy and helpers. Import from this path
* everywhere inside src/main/ so the rest of the tree never reaches
* directly into `./taxonomy.ts` or `./handlers.ts`.
*/
export {
AppError,
RecoverableError,
UserInputError,
UpstreamError,
FatalError,
classifyUnknownError,
isAppError,
type AppErrorMeta,
type ErrorKind,
} from "./taxonomy.js";
export { logAppError, type Logger } from "./handlers.js";