jschoubben
605c9fd441
Two corrections and one new decision, all from Jochen catching things. Pushed, not polled. I described updates as landing "on the next reconcile", which reads as polling and is not the design. A declaration arrives as a message on a link that is already open; the host applies it then. Polling over an existing connection would be slower to land AND constant traffic to learn nothing. The timer is for drift and nothing else, and it cannot be replaced by an event for a definitional reason: drift is change the mesh did not make -- somebody edited a managed file, a distribution upgrade replaced a config -- so nothing will ever publish a message about it. Only looking finds it. Separated the heartbeat from the reconcile timer, which I had been conflating. They point in opposite directions and answer different questions: the timer looks at the machine and asks whether it still matches; the heartbeat reports upward and is what makes silence mean something. A node with nothing to do sends nothing, and without a heartbeat that is indistinguishable from a node that stopped. 0059 -- a host that cannot start is rolled back by the service manager. I had left this open on the grounds that recovery meant the host judging its own health. That objection does not survive being asked properly: a keepalive is something else judging the host. The watchdog must be local, because nothing dials a node and a host that cannot start cannot report -- so it is the service manager, which is already there. The failure it prevents is sharper than "the node is down": a host that will not start looks exactly like a machine somebody switched off, which is the one condition this design has deliberately decided not to alarm on. So a bad release reaches every node, each goes quiet, and the mesh reports a fleet of sleeping laptops. Confirmed means started and completed one reconcile -- deliberately not "the link is up", or a laptop on a train would roll itself back. The rollback is a script shipped by the package, not a host subcommand, because a binary that will not start cannot be its own recovery. It rolls back once: a second failure means the machine is the problem, not the binary. Also refined the records checker, which produced a false positive: a proposed record may extend another proposed one, because decisions are drafted in chains and the alternative is marking things accepted to satisfy a check. An accepted document resting on a proposed record still fails, and that was verified. 0057, 0058 and 0059 are all proposed.
03-DESIGN / 01-to-be
The mesh being built toward. Every statement here traces to a record in
02-DECISIONS/; nothing arrives by drafting.
A document here describes an intention. What currently runs is in
00-as-is/, and the two are never merged — when something ships, the as-is
document is written and this one's status becomes implemented.
| Document | Covers | Rests on |
|---|---|---|
00-work-breakdown.md |
How the decomposition gets built, in what order, and where a human must look | ADR 0015 |
01-end-to-end-testing.md |
The lab: a real mesh a change can be run against before it reaches nodes | ADR 0016, 0029 |
02-scenario-declaration.md |
What a scenario declares — the underlay, and what to place on it | ADR 0031 |
03-scenario-lifecycle.md |
What happens to a scenario — raise, snapshot, restore, move, destroy | ADR 0032 |
04-lab-installation.md |
Getting the lab onto a clean machine, and why it verifies capability rather than installation | ADR 0008 |
05-the-node-host.md |
Tier 0 — the one thing installed by hand, and the only thing that changes a machine | ADR 0037 |
06-the-control-plane.md |
Tier 2 — what the term means, and the test for what belongs in it | ADR 0037 |
07-the-substrate.md |
Tier 1 — what the control plane consumes and cannot grant itself | ADR 0038, 0048 |
08-connectivity.md |
One context in full — overlay, resolution, exposure, filtering, certificates | ADR 0049, 0050, 0051, 0055 |
09-the-node-lifecycle.md |
How a machine becomes a node, stays one, and stops being one | ADR 0038, 0051 |
Not yet written
- The remaining six contexts.
ADR 0055
settles the list at seven;
connectivityis the first written in full (08) and the other six do not exist yet. The work breakdown says in what order they are needed. Domain grouping outside the core.Not needed. ADR 0017 is superseded by ADR 0044: there is no domain module to group into, so there is no domain list to settle. Relationships are edges, and grouping is a tag and a query.