# operations

running and shipping software: what breaks after deploy, how to find out, how
to size what you rent, and why the deploy path itself is the least-tested code
you own.

design patterns live in [systems/](../systems/). the split is roughly "how to
build it" against "what it does to you at 2am".

a recurring theme across these notes: the failures that stay open longest do
not produce errors. they produce silence, a green dashboard, or a confidently
wrong belief.

## topics

### observability and failure

- [masked-failure](./masked-failure.md) — a reliability feature moves failure
  from loud and small to silent and large; watchdogs, heartbeats, staleness
- [health-checks](./health-checks.md) — 200 means "replacing me would not
  help"; heartbeat of work, verdict at read time, supervisor decides what a
  failure does (fly checks route, they do not restart), kill switch first
- [observability-of-absence](./observability-of-absence.md) — absent is not
  zero, a disabled invariant is an open outage, and the signals you must add
  deliberately because nothing emits them

### diagnosis

- [throughput-bottlenecks](./throughput-bottlenecks.md) — bound from outside,
  profile the real workload, read upstream's source; one variable per deploy
- [bounded-scans](./bounded-scans.md) — a bound limits work performed, not work
  read; push the skip check to the cheapest tier, and guarantee the cursor moves

### configuration and policy

- [tangled](./tangled.md) — route repository metadata, Git objects, CI, and
  collaboration records to the component that owns them; Bobbin, knots,
  spindles, PDS records, and the interactive log-viewer trap
- [reconcilers-own-config](./reconcilers-own-config.md) — if a reconciler owns
  a value, a hand edit is temporary; change the source, not the reconciled object
- [policy-enforced-by-accident](./policy-enforced-by-accident.md) — a rule
  enforced by a dependency's implementation detail has no owner; enforce at a
  layer you own, and test the policy rather than the mechanism

### what you rent

- [deploy-path](./deploy-path.md) — untested deploy branches are bug
  reservoirs; use the repository's recipe, verify the launcher ran your command
- [instance-sizing](./instance-sizing.md) — measure the working set at a fresh
  start; start small because disk rescale is one-way; read the whole bill
- [home-infra/](./home-infra/) — the home-box cluster: cost optimization,
  public cost declaration, tailscale