Handling failures

REQUIRED BACKGROUND: the principal-engineering skill.

Overview

A swallowed error is a bug with its evidence destroyed. Core contract: every failure path does exactly one of three things, and all three are loud. The system that looks healthy while serving wrong data is worse than the one that crashes, because the crash gets fixed today and the silent wrong output gets discovered in an audit.

The contract

Every catch and failure path either:

1. Logs at WARN or ERROR and rethrows, or
2. Logs and returns a TYPED failure the caller must handle (a result type, a sealed error, a status the compiler or contract forces downstream code to acknowledge), or
3. Logs and enters an explicitly documented degraded mode (the degradation is named in the code and its documentation, and something observable says the system is degraded).

Forbidden, no exceptions: