# Mission: Error Handling in Software

## Why
Martin wants to make deliberate, defensible error-handling decisions in the applications they
build — frontend and backend — rather than inheriting them from surrounding style. Concretely:
knowing where to throw and where to return, what crosses the wire between server and client,
what the person on the other end sees, and what the system does when something nobody
anticipated goes wrong. A precise, canonical vocabulary is the means, not the end: it is what
lets a review comment name the exact defect and a team convention be argued from the
literature rather than from taste.

## Success looks like
- Can decide, for any given failure site, whether to **throw, return a value, or let it
  propagate** — and say which camp the decision comes from and why.
- Can design the **error envelope** between a backend and its clients: stable machine-readable
  code, developer-facing message, user-safe message, correlation ID — and cite RFC 9457,
  AIP-193 or Stripe when arguing for a shape.
- Can take one backend failure and render it correctly on **two surfaces**: an actionable,
  blame-free message for the end user, and full diagnostic detail in logs and dashboards —
  without leaking internals to the first or losing them from the second.
- Can state what the system does on a **failure nobody anticipated**, at every layer: React
  error boundary, `unhandledrejection`, server error middleware, process exit — and say what
  each does and does not catch.
- Can reason about **state after a failure**: what a half-completed operation left behind, what
  "indeterminate" means for a network call, and when idempotency is the answer.
- Can name the classic anti-patterns in review: swallowing, exception-as-flow-control,
  over-broad catch, log-and-rethrow, retry amplification, shotgun parsing, leaking internals.
- Retains the core taxonomy (bug vs. recoverable error; representation / propagation / handling;
  sentinel / type / opaque) as the vocabulary that makes the above arguable.

## Constraints
- Application code examples in **TypeScript** — React/browser on the frontend, Node service on
  the backend. **Rust, Go and Python** appear as contrast cases, where another language forces a
  discipline TypeScript leaves optional.
- The user-facing surface and the developer-facing surface are **both** in scope; the mapping
  between them is a first-class design object, not an afterthought.
- Glossary-first: introduce the canonical term, then use it.
- Prescription is welcome only when attributable to real literature or a real specification.
  Where the field is genuinely contested — throw vs. Result in TypeScript, for instance — name
  the camps and their arguments instead of adjudicating. Flag synthesis as synthesis.

## Out of scope (for now)
- Internationalisation mechanics of error copy (the *decision* to key messages rather than
  hardcode them is in scope; ICU message syntax is not).
- Formal verification as an alternative to runtime error handling.
- Language-implementation detail of unwinding (DWARF tables, zero-cost EH internals).
- Vendor-specific observability configuration; the *design* questions around correlation IDs
  and error grouping are in scope, the dashboards are not.

## Revision log
- **2026-08-30, session 1–2** — taxonomy-first, examples in Python/Rust/Go, error UX explicitly
  out of scope.
- **2026-08-30, session 3** — refocused on the application level. TypeScript becomes the primary
  language; user-facing presentation moves from out-of-scope to a success criterion; the
  distributed/containment material is promoted from "later" to core.