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.
ZacharyZhang-NY