hq/02-DECISIONS/0077-the-controller-and-the-foundation.md

topic, status, date, deciders, reconstructed, extends

topic	status	date	deciders	reconstructed	extends
the mesh	accepted	2026-09-16	jochen	false	02-DECISIONS/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 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).