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
62 lines
3.0 KiB
Markdown
62 lines
3.0 KiB
Markdown
---
|
|
topic: the mesh
|
|
status: accepted
|
|
date: 2026-09-16
|
|
deciders: jochen
|
|
reconstructed: false
|
|
extends: 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
|
|
|
|
1. **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.
|
|
2. **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.
|
|
3. **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`](../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`](../00-META/glossary.md) — one name per thing, and the words retired.
|
|
- The rename shipped across all six code repositories and hq (main).
|