---
status: active
initiated: 2026-09-26
touches:
  - 00-META/mission.md
  - 02-DECISIONS/0106-the-bus-is-nats.md
  - 02-DECISIONS/0010-delivery.md
  - 02-DECISIONS/0083-one-push-leaves-the-mesh-consistent.md
  - 03-DESIGN/01-to-be/06-the-controller.md
  - 03-DESIGN/01-to-be/09-the-node-lifecycle.md
  - 03-DESIGN/00-as-is/09-interfaces-and-observability.md
---

# 017 — A mesh that heals itself

**What.** The behaviour the operator wants: a mesh that runs itself. It notices what is wrong,
repairs what it can, and hands what it cannot repair to someone who can, with the reason. This effort
writes that wish down as intended behaviour, designed for the bus the mesh is moving to
([ADR 0106](../../02-DECISIONS/0106-the-bus-is-nats.md): NATS). It also records what can be done
pragmatically before that move.

**Why.** The mission is *a mesh that controls itself* ([mission](../../00-META/mission.md)). The
mesh can tell whether it is up. It cannot tell whether it is right. The as-is page on observability says so
([as-is 09](../../03-DESIGN/00-as-is/09-interfaces-and-observability.md)). To-be 06 names an
`observability` context in the controller and leaves its store undecided. Nothing routes a condition
the mesh cannot fix to anyone. The cost is measurable: **46 of the 116 issue reports in this
repository describe a failure that was silent.** A mesh that heals itself is, first, a mesh that stops
failing silently.

**What it touches.** The controller's observability context, the node lifecycle's liveness, delivery
([ADR 0010](../../02-DECISIONS/0010-delivery.md), [ADR 0083](../../02-DECISIONS/0083-one-push-leaves-the-mesh-consistent.md)),
the provisioner harness, and rotation, which is proposed alongside to-be 27 as ADR 0114.

**Documents.**

- [01 — The intended behaviour](01-the-intended-behaviour.md): the wish, as principles and as how
  the mesh behaves once the bus is NATS.
- [02 — Now, pragmatically](02-now-pragmatically.md): what is done before NATS, why it does not
  build anything the move would throw away, and what has been done already.

**Next.** Two measurements this effort owes before it can graduate:

1. **Every loop in the mesh**: what it converges, and whether it compares against observed state or
   against its own memory. Issue 120 found the provisioner harness trusting memory. The same pattern is
   expected elsewhere.
2. **The 46 silent failures, classified**: a missing observation, a loop trusting memory, or a missing
   escalation. That shows which mechanism removes the most of them.