---
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).