Adopt the glossary's vocabulary in the mutable design docs

"control plane" -> controller and "substrate" -> foundation throughout
03-DESIGN, 00-META and the README, with 06-the-control-plane.md and
07-the-substrate.md renamed to 06-the-controller.md and 07-the-foundation.md.
The immutable 02-DECISIONS records keep their original wording (and links to
them are unchanged) — a term retired here may still appear there, which the
glossary explains how to read.

Claude-Session: https://claude.ai/code/session_01D6qtiYU3P9jk3pnAXyAFyx
This commit is contained in:
2026-09-16 18:48:52 +02:00
parent f9f48fbbf7
commit 33a00d5656
25 changed files with 233 additions and 233 deletions
+15 -15
View File
@@ -142,12 +142,12 @@ nox-mesh-host enrol --token <one-time token>
The token carries **four** things and is carried by a person
([ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md)): the broker's
address, the fingerprint to expect, **the control plane's signing identity**, and the right to
address, the fingerprint to expect, **the controller's signing identity**, and the right to
join once.
**The fourth is the one this document listed three of.** A node connects to the broker and takes
instruction from the control plane behind it, and those are two different identities. Pinning only
the broker would make the control plane's authority *transitive* — a compromised broker could then
instruction from the controller behind it, and those are two different identities. Pinning only
the broker would make the controller's authority *transitive* — a compromised broker could then
forge declarations, which, since the host applies whatever the link delivers, is the whole machine.
So the transport is verified once at connect, and **each declaration is verified by its signature,
every time**.
@@ -158,10 +158,10 @@ What happens, in order:
2. it checks the broker's certificate against the pinned fingerprint — *before* sending anything;
3. it presents the one-time secret **and its own public key**, which the mesh records;
4. it reports its `profile` and `inventory` upward;
5. the control plane decides what this machine should be, and sends a declaration;
5. the controller decides what this machine should be, and sends a declaration;
6. the host applies it, reads back, and reports.
**Step 4 is the one that is easy to miss and is what makes step 5 possible.** The control plane
**Step 4 is the one that is easy to miss and is what makes step 5 possible.** The controller
cannot decide what a machine should run without knowing what it *can* run — a graphical session,
a container runtime, an architecture. The profile is not a diagnostic; it is the input.
@@ -209,7 +209,7 @@ channel, not about network reachability.** What it forbids is a listening thing
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.
The distinction is *who can tell this machine what to be*: only the control plane, only over the
The distinction is *who can tell this machine what to be*: only the controller, only over the
link the node opened, only in declarations of known shape.
---
@@ -219,18 +219,18 @@ link the node opened, only in declarations of known shape.
The same path, with the mesh built in the middle of it.
```
# 1 — raise the substrate and the control plane from the carried bundle
# 1 — raise the foundation and the controller from the carried bundle
nox-mesh-host reconcile
# 2 — the control plane now exists, and issues the first token
# 2 — the controller now exists, and issues the first token
mesh-control token issue
# 3 — the machine joins the mesh it just raised
nox-mesh-host enrol --token <token>
```
Step 1 is the bootstrap from [`07-the-substrate.md`](07-the-substrate.md): a container runtime,
then PostgreSQL, then the database, then the schema, then the control plane. It needs no identity
Step 1 is the bootstrap from [`07-the-foundation.md`](07-the-foundation.md): a container runtime,
then PostgreSQL, then the database, then the schema, then the controller. It needs no identity
because nothing is being asked of anyone — the host is applying a declaration it already
carries, to the machine it is already on.
@@ -238,7 +238,7 @@ carries, to the machine it is already on.
the bootstrap script never had. Its specialness lasted two commands.
**And enrolment is exercised on node one.** The path every other node depends on is walked
immediately, against a control plane on the same machine, rather than being written and first
immediately, against a controller on the same machine, rather than being written and first
used months later on node two.
---
@@ -265,7 +265,7 @@ closes — an authoritative local store, reconcile on start, *last heard from* r
alarm — is what an episodic host needs, at a shorter period.
**It cannot be the first node**, and that is not a limitation to work around. Every step of
raising a substrate is a `package`, a `container` or an `action` against one, and a partial host
raising a foundation is a `package`, a `container` or an `action` against one, and a partial host
refuses the first two. So `mesh-host-android bundle` returns a file that says so rather than an
empty placeholder waiting to be filled in.
@@ -350,7 +350,7 @@ rest. The rule that exists to stop the host lying about what it did also makes i
## Updating what the node holds
An ordinary declaration. Someone assigns a module; the control plane recomputes what that node
An ordinary declaration. Someone assigns a module; the controller recomputes what that node
should be and sends it; the host applies the difference and removes what is no longer declared.
**Removal is not symmetric, and the asymmetry is the design:**
@@ -410,7 +410,7 @@ one binary that has always been the same binary.
Two cases, and they are genuinely different.
**Graceful.** The control plane sends a final declaration that names nothing. The host removes
**Graceful.** The controller sends a final declaration that names nothing. The host removes
what it owns by the table above, reports, and drops its identity. The machine keeps the host
installed and is back to `hosted`. Nothing is left behind that anybody has to remember.
@@ -638,7 +638,7 @@ lets a node verify a mesh it has never spoken to
([ADR 0004](../../02-DECISIONS/0004-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
**On the first node it comes from the controller that was raised two commands ago**, which is
the same command against a mesh that is one machine old.
---