novox/hq
3
0
Fork 0
Code Issues 3 Pull Requests 5 Releases Wiki Activity

Consolidate: 65 decision records to 23

Browse Source 
Every remaining cluster merged. Each was one design that had been split across
several records because it was worked out over days rather than at once.

  the node host          8 -> 1    applies not decides, depends on nothing,
                                   per operating system, root service, the
                                   launcher, episodic, what a declaration is,
                                   actions from the bundle only
  a node and how it joins 4 -> 1   what a node is, joining, the link as
                                   security boundary, the enrolment token
  modules and the graph   7 -> 1   everything is a module, no domain modules,
                                   three edges, provisioning, the core library
  substrate and control   6 -> 1   the test, seven contexts, one control plane,
    plane                          the authority is not a database, the named
                                   products, the pinned bundle
  connectivity            3 -> 1   a route is a grant, reachability declared,
                                   filter rules
  delivery                5 -> 1   reconciliation not a pipeline, artifacts,
                                   the three silos, a failed step, the verdict
  the lab                 5 -> 1   (earlier)
  how this repository     10 -> 1  (earlier)
    works

Nothing was dropped. Each consolidated record carries the reasoning of the ones
it absorbs -- the measurements, the incidents, the alternatives rejected --
because that reasoning is the only reason to keep a record at all. What is gone
is the fragmentation: eight files to read to understand tier 0, when tier 0 is
one component.

The four superseded records went too. They existed to point at their
successors, and the successors now contain what they said.

The checker made this safe. Each merge left dangling links -- 38 files after
the host merge alone -- and it named every one. Nothing was found by reading,
and a manual pass would certainly have missed some, including references inside
AGENTS.md which every session loads.
This commit is contained in:
jschoubben
2026-08-28 20:03:24 +02:00
parent 5e83ac2c22
commit 77f3a4cea7
90 changed files with 1041 additions and 4187 deletions
Download Patch File Download Diff File Expand all files Collapse all files
03-DESIGN/01-to-be/09-the-node-lifecycle.md
+39 -39
View File
@@ -4,17 +4,17 @@ status: designed
code: []
updated: 2026-08-27
decisions:
- 02-DECISIONS/0036-a-node-is-a-managed-machine.md
- 02-DECISIONS/0037-the-host-applies-it-does-not-decide.md
- 02-DECISIONS/0038-a-node-joins-by-linking-first.md
- 02-DECISIONS/0039-the-link-is-the-security-boundary.md
- 02-DECISIONS/0043-a-declaration-is-an-ordered-list-of-owned-resources.md
- 02-DECISIONS/0051-the-enrolment-token-carries-the-mesh.md
- 02-DECISIONS/0057-the-host-is-a-root-service-installed-as-a-package.md
- 02-DECISIONS/0058-delivery-ends-in-a-declaration.md
- 02-DECISIONS/0060-the-host-is-built-per-operating-system.md
- 02-DECISIONS/0061-the-host-asks-an-init-for-start-and-restart.md
- 02-DECISIONS/0062-a-host-may-be-episodic.md
- 02-DECISIONS/0036-a-node-and-how-it-joins.md
- 02-DECISIONS/0037-the-node-host.md
- 02-DECISIONS/0036-a-node-and-how-it-joins.md
- 02-DECISIONS/0036-a-node-and-how-it-joins.md
- 02-DECISIONS/0037-the-node-host.md
- 02-DECISIONS/0036-a-node-and-how-it-joins.md
- 02-DECISIONS/0037-the-node-host.md
- 02-DECISIONS/0058-delivery.md
- 02-DECISIONS/0037-the-node-host.md
- 02-DECISIONS/0037-the-node-host.md
- 02-DECISIONS/0037-the-node-host.md
---
# The node lifecycle
@@ -42,11 +42,11 @@ questions that were not being asked live.
**Only `enrolled` and `disconnected` are nodes**, and they are the same node in two situations
rather than two kinds of thing
([ADR 0036](../../02-DECISIONS/0036-a-node-is-a-managed-machine.md)). **`hosted` is not a
([ADR 0036](../../02-DECISIONS/0036-a-node-and-how-it-joins.md)). **`hosted` is not a
node** — it is a machine with a program on it that has not been told which mesh it belongs to.
There is no state for *the first node*. That is the point of
[ADR 0038](../../02-DECISIONS/0038-a-node-joins-by-linking-first.md): the first node walks the
[ADR 0036](../../02-DECISIONS/0036-a-node-and-how-it-joins.md): the first node walks the
same path, in an unusual order.
---
@@ -54,7 +54,7 @@ same path, in an unusual order.
## unmanaged → hosted: installing
In the machine's own idiom, because the package manager and the init file are the system's
([ADR 0060](../../02-DECISIONS/0060-the-host-is-built-per-operating-system.md)):
([ADR 0037](../../02-DECISIONS/0037-the-node-host.md)):
```
# Alpine — the intended first node
@@ -67,7 +67,7 @@ systemctl enable --now nox-mesh-host
```
Two lines each, and the init file behind them is four
([ADR 0061](../../02-DECISIONS/0061-the-host-asks-an-init-for-start-and-restart.md)) — it says
([ADR 0037](../../02-DECISIONS/0037-the-node-host.md)) — it says
*run the launcher at boot* and nothing else, so a third system is transcription rather than a
port.
@@ -103,7 +103,7 @@ WantedBy=multi-user.target
```
**Two lines of policy, and that is deliberate**
([ADR 0061](../../02-DECISIONS/0061-the-host-asks-an-init-for-start-and-restart.md)). The init is
([ADR 0037](../../02-DECISIONS/0037-the-node-host.md)). The init is
asked to *start this at boot* and *start it again if it exits*, and nothing else. Both are
expressible in OpenRC, runit, s6 and an Android `init.rc`, so porting this file is transcription
rather than design.
@@ -135,7 +135,7 @@ nox-mesh-host enrol --token <one-time token>
```
The token carries three things and is carried by a person
([ADR 0051](../../02-DECISIONS/0051-the-enrolment-token-carries-the-mesh.md)): the broker's
([ADR 0036](../../02-DECISIONS/0036-a-node-and-how-it-joins.md)): the broker's
address, the fingerprint to expect, and the right to join once.
What happens, in order:
@@ -153,7 +153,7 @@ a container runtime, an architecture. The profile is not a diagnostic; it is the
**The node computes nothing about the mesh.** It needs one peer to reach; the whole overlay is
derived centrally and pushed down
([ADR 0038](../../02-DECISIONS/0038-a-node-joins-by-linking-first.md),
([ADR 0036](../../02-DECISIONS/0036-a-node-and-how-it-joins.md),
[`08-connectivity.md`](08-connectivity.md)).
### The first declaration is the overlay, and nothing else
@@ -172,7 +172,7 @@ Three reasons, and the third is the one that matters when something goes wrong:
address and peer set are *assigned* — it generates a keypair, publishes the public half, and
receives the rest ([`08-connectivity.md`](08-connectivity.md)). So the overlay is the first
thing the mesh can give it, and it should be.
- **It is what [ADR 0038](../../02-DECISIONS/0038-a-node-joins-by-linking-first.md) already
- **It is what [ADR 0036](../../02-DECISIONS/0036-a-node-and-how-it-joins.md) already
says:** *a joining node does the minimum to be reachable, and nothing else.*
- **It is the way back in.** Once the overlay is up, the node is reachable over it — by SSH, by
anything. If a later declaration breaks the machine, there is a route to it that does not
@@ -188,9 +188,9 @@ Worth stating plainly, because the two rules read as a contradiction and are not
|---|---|
| **every node reaches every other node** | over the overlay — SSH, services, ordinary traffic. This is the point of having one |
| **every node consumes from the broker** | its own queue, over its own outbound connection ([ADR 0001](../../02-DECISIONS/0001-nodes-communicate-over-a-broker.md)) |
| **nothing dials a node to control it** | the host has no inbound control surface ([ADR 0039](../../02-DECISIONS/0039-the-link-is-the-security-boundary.md)) |
| **nothing dials a node to control it** | the host has no inbound control surface ([ADR 0036](../../02-DECISIONS/0036-a-node-and-how-it-joins.md)) |
**[ADR 0039](../../02-DECISIONS/0039-the-link-is-the-security-boundary.md) is about the control
**[ADR 0036](../../02-DECISIONS/0036-a-node-and-how-it-joins.md) is about the control
channel, not about network reachability.** What it forbids is a listening thing that accepts
instructions and changes the machine. A node being reachable on the overlay — the whole purpose
of the overlay — is untouched by it, and so is a person opening a shell on it.
@@ -232,7 +232,7 @@ used months later on node two.
## Two kinds of host
Everything above assumes a machine with an init that runs the host at boot. Not every machine
has one ([ADR 0062](../../02-DECISIONS/0062-a-host-may-be-episodic.md)).
has one ([ADR 0037](../../02-DECISIONS/0037-the-node-host.md)).
| | **resident** | **episodic** |
|---|---|---|
@@ -245,7 +245,7 @@ has one ([ADR 0062](../../02-DECISIONS/0062-a-host-may-be-episodic.md)).
| can be the first node | yes | **no** |
**An episodic host being killed is disconnection, not failure.** That is
[ADR 0036](../../02-DECISIONS/0036-a-node-is-a-managed-machine.md) doing the work it was written
[ADR 0036](../../02-DECISIONS/0036-a-node-and-how-it-joins.md) doing the work it was written
for: reachability is state, not class. Everything the design already does for a laptop that
closes — an authoritative local store, reconcile on start, *last heard from* reported without an
alarm — is what an episodic host needs, at a shorter period.
@@ -258,7 +258,7 @@ empty placeholder waiting to be filled in.
**Two things this changes for anything reading the mesh.** *Last heard from* is a much weaker
signal on an episodic host — a healthy phone looks like a dead server — so a reader has to know
which kind it is looking at. And a declaration may take a long time to land, which makes
[ADR 0058](../../02-DECISIONS/0058-delivery-ends-in-a-declaration.md)'s separation of
[ADR 0058](../../02-DECISIONS/0058-delivery.md)'s separation of
*outstanding* from *failed* load-bearing rather than tidy.
**Still open:** how an episodic host is started in practice — an APK with a foreground service,
@@ -272,7 +272,7 @@ Adoption is not a state. It is what the **first apply** does when it is told to
machine already has ([research 012](../../01-RESEARCH/012-the-minimum-viable-node/00-overview.md)).
A candidate machine is not empty. It has a package manager, probably a container runtime,
configuration somebody chose. [ADR 0043](../../02-DECISIONS/0043-a-declaration-is-an-ordered-list-of-owned-resources.md)
configuration somebody chose. [ADR 0037](../../02-DECISIONS/0037-the-node-host.md)
says the host never touches what it did not create — adoption is the deliberate act of taking
ownership of exactly that, so it is a companion to that rule rather than an exception:
@@ -299,7 +299,7 @@ outcome **derived** from the worst line rather than stated alongside it.
**Changes are pushed, not polled.** A declaration arrives as a message on the link and the host
applies it then. The link is already open and outbound
([ADR 0001](../../02-DECISIONS/0001-nodes-communicate-over-a-broker.md),
[ADR 0039](../../02-DECISIONS/0039-the-link-is-the-security-boundary.md)) — asking it
[ADR 0036](../../02-DECISIONS/0036-a-node-and-how-it-joins.md)) — asking it
repeatedly whether anything has changed would be slower to land *and* constant traffic to learn
nothing.
@@ -326,7 +326,7 @@ So the two periodic things do different jobs and should not be conflated:
without a heartbeat that is indistinguishable from a node that stopped. With one, *last heard
from* is a fact beside every node — which is what
[how long disconnected](#how-long-disconnected-and-who-is-told) reports and what
[ADR 0061](../../02-DECISIONS/0061-the-host-asks-an-init-for-start-and-restart.md) exists
[ADR 0037](../../02-DECISIONS/0037-the-node-host.md) exists
because a stuck node cannot send.
**Rebooting mid-apply is safe by construction.** The store records each resource *after* it
@@ -357,7 +357,7 @@ runtime because a declaration changed would stop every container on the node.
## enrolled ⇄ disconnected
Not a failure. Not degraded. A situation
([ADR 0036](../../02-DECISIONS/0036-a-node-is-a-managed-machine.md)).
([ADR 0036](../../02-DECISIONS/0036-a-node-and-how-it-joins.md)).
A disconnected node **keeps reconciling against its own store**, so it goes on holding its
machine in the last state it was told to hold. A laptop shut for a week comes back and
@@ -365,7 +365,7 @@ reconciles; it does not come back and ask what it is.
What it cannot do: receive new declarations, be granted anything new, or have its certificates
renewed — which is the clock on the whole arrangement
([ADR 0053](../../02-DECISIONS/0053-one-control-plane-and-no-failover.md)).
([ADR 0048](../../02-DECISIONS/0048-the-substrate-and-the-control-plane.md)).
**How long it has been disconnected is a fact the mesh must hold**, and nothing holds it today.
Without it, a node running last month's assignments looks exactly like one that is current.
@@ -384,7 +384,7 @@ nox-mesh-host profile # what can this machine actually do?
`apply FILE` accepts actions, because someone who can write that file and run this binary as
root can already do anything it can. The bound in
[ADR 0047](../../02-DECISIONS/0047-the-bundle-may-carry-actions-the-link-may-not.md) is on what a
[ADR 0037](../../02-DECISIONS/0037-the-node-host.md) is on what a
**remote** party may push, not on what a person at the machine may do.
This replaces the three hand-run scripts that exist today — first node, joining, rescue — with
@@ -401,13 +401,13 @@ what it owns by the table above, reports, and drops its identity. The machine ke
installed and is back to `hosted`. Nothing is left behind that anybody has to remember.
**The node is gone.** Stolen, dead, or simply unreachable. The mesh cannot tell it anything, and
by [ADR 0036](../../02-DECISIONS/0036-a-node-is-a-managed-machine.md) it will go on reconciling
by [ADR 0036](../../02-DECISIONS/0036-a-node-and-how-it-joins.md) it will go on reconciling
its last declaration **forever**.
That is the honest consequence of making disconnection ordinary, and the answer is not to make
the host expire. It is that **the node holds nothing that outlives revocation**: its identity is
its own, and every grant it holds is a per-node credential at the provider
([ADR 0039](../../02-DECISIONS/0039-the-link-is-the-security-boundary.md),
([ADR 0036](../../02-DECISIONS/0036-a-node-and-how-it-joins.md),
[ADR 0045](../../02-DECISIONS/0045-a-context-owns-its-store.md)). Revoking is done at the
database, the broker, the object store — not on the machine.
@@ -438,7 +438,7 @@ remains locally authoritative for *operating*; the copy exists only for this.
## Upgrading the host
The host is delivered like anything else
([ADR 0058](../../02-DECISIONS/0058-delivery-ends-in-a-declaration.md)), and this is worth
([ADR 0058](../../02-DECISIONS/0058-delivery.md)), and this is worth
walking through because tier 0 looks like it should be special and is not.
```
@@ -489,7 +489,7 @@ own apply completes. A node must therefore report the version it is **running**,
installed — otherwise the mesh believes an upgrade landed at step 1.
**A version that crashes on start rolls itself back**
([ADR 0061](../../02-DECISIONS/0061-the-host-asks-an-init-for-start-and-restart.md)).
([ADR 0037](../../02-DECISIONS/0037-the-node-host.md)).
What the init starts is not the host but a **launcher**, and the launcher is where the policy
lives:
@@ -551,7 +551,7 @@ credentials still valid — the case
**The host reports what it owns, and the mesh keeps the last report.**
The store stays locally authoritative — a node operates from its own copy and needs nothing to
do so ([ADR 0036](../../02-DECISIONS/0036-a-node-is-a-managed-machine.md)). What changes is that
do so ([ADR 0036](../../02-DECISIONS/0036-a-node-and-how-it-joins.md)). What changes is that
the mesh holds a **copy for recovery**, refreshed on every apply report.
So a node that loses its state file re-enrols, receives both the declaration *and* the record of
@@ -616,12 +616,12 @@ keeps cataloguing.
### Where the enrolment token comes from
**`mesh-control token issue` prints it once**, to the person running it. Single-use, and it
expires whether used or not ([ADR 0039](../../02-DECISIONS/0039-the-link-is-the-security-boundary.md)).
expires whether used or not ([ADR 0036](../../02-DECISIONS/0036-a-node-and-how-it-joins.md)).
It is carried by hand — read off a screen, pasted into a terminal. That is the design rather than
a gap in it: its authenticity comes from the channel it travelled, which is what
lets a node verify a mesh it has never spoken to
([ADR 0051](../../02-DECISIONS/0051-the-enrolment-token-carries-the-mesh.md)). A token emailed,
([ADR 0036](../../02-DECISIONS/0036-a-node-and-how-it-joins.md)). A token emailed,
committed, or dropped in shared storage has lost the only property that makes it worth carrying.
**On the first node it comes from the control plane that was raised two commands ago**, which is
@@ -632,10 +632,10 @@ the same command against a mesh that is one machine old.
## Still open
- ~~**Automatic rollback of a bad host version.**~~ **Resolved** by
[ADR 0061](../../02-DECISIONS/0061-the-host-asks-an-init-for-start-and-restart.md): a launcher
[ADR 0037](../../02-DECISIONS/0037-the-node-host.md): a launcher
counts failed starts and rolls back — shipped by the package, not the host binary, because a
binary that will not start cannot recover itself. It rolls back once; a second failure means
the machine is the problem, not the binary.
- **How a previous declaration is retained and chosen**, which is what rollback of anything else
would use ([ADR 0058](../../02-DECISIONS/0058-delivery-ends-in-a-declaration.md)).
would use ([ADR 0058](../../02-DECISIONS/0058-delivery.md)).
- **A node returning after months** applies a very large jump in one go. Correct, and untested.