jschoubben
1111bd84d7
Settles the design repository now that the self-upgrade build is on main: - Records the two decisions that shipped without a record — ADR 0077 (the controller/foundation/node vocabulary) and ADR 0078 (the store and broker are ordinary modules); accepts ADR 0075 and 0076, which shipped work rests on. - Fills issue 051's amended-design and wires ADR 0078 into 07-the-foundation. - Sweeps the repo rename (mesh-control -> mesh-controller) into the mutable docs now that the forge repo is renamed; updates the glossary note and repos.md. - Fixes the six broken links from the design-doc renames, indexes the glossary, regenerates the decisions reading order. Both checks (records.py, index.py) are green. Statuses stay honest: the build is on main and lab-proven but not deployed as the production mesh, so the to-be docs remain in-progress and the as-is layer (the hal mesh) is unchanged — graduation to implemented + as-is belongs to deployment, not merge. https://claude.ai/code/session_01D6qtiYU3P9jk3pnAXyAFyx
3.0 KiB
topic, status, date, deciders, reconstructed, extends
| topic | status | date | deciders | reconstructed | extends |
|---|---|---|---|---|---|
| the mesh | accepted | 2026-09-16 | jochen | false | 0006-the-substrate-and-the-control-plane.md |
77. The parts are named controller, foundation, node — not control plane, substrate, master
Context
The words drifted. In conversation and in code the same thing was called control plane, controller, master, and hub; the store-and-broker pair was called substrate and foundation; a machine was a node, a worker-node, a peer, a slave. A mesh named differently by two people is a mesh they describe differently, and the drift was worst on the parts talked about most.
Three of the terms carried wrong ideas. Control plane is borrowed from networking's control-plane/data-plane split and means nothing here. Master/slave and hub/peer imply a subordinate — but no node is: a node applies its own declaration and keeps running when the control-node dies, so it is as much its own machine as any other. Substrate is a biology metaphor that landed for no one.
Considered Options
- Keep the inherited words. Rejected: they are the source of the drift, and two of them (control plane, substrate) are metaphors that teach the wrong shape to anyone reading them cold.
- master / slave, or hub / peer, for the nodes. Rejected: both name a hierarchy the mesh does not have. The control-node owns no other node; lose it and the rest keep running what they were last told.
- controller / foundation / node + control-node. Chosen.
Decision
The component that decides what each node should be, holds the mesh's records, and tells nodes is
the controller — the module mesh-controller, which claims the mesh-scoped the-controller
seat. The store and broker raised at genesis are the foundation. Machines are nodes;
there are 0..n of them, and exactly one — the one running the controller — is the control-node.
Retired: control plane, substrate, master/slave, hub/peer, worker-node.
00-META/glossary.md is the authority, and a new name for an existing
thing lands there in the change that introduces it in code.
Consequences
mesh-control became mesh-controller across the module, container, image, binary, cmd/ dir and
the git repository; substrate became foundation in the embedded base bundles, the default
template and the example lock; the seat the-control-plane became the-controller. The 03-DESIGN
prose and 00-META follow the new words.
What got harder: the records under 02-DECISIONS/ are immutable, so they keep the words they were
written with — this record included, whose own title names what it retires. A term retired here
still appears there, and the glossary is how to read it. The git repository on the forge was
renamed mesh-control → mesh-controller.
References
00-META/glossary.md— one name per thing, and the words retired.- The rename shipped across all six code repositories and hq (main).