hq/00-META/glossary.md

Glossary — the words this repository uses, and the ones it stopped using

One name per thing. This page is the authority; where an older record says something else, that record is being superseded, not this page. It exists because the terms kept drifting in conversation — control plane / controller / master / hub for one thing, substrate / foundation for another — and a mesh you cannot name precisely is a mesh two people describe differently.

The mesh and its machines

• node — a machine in the mesh. There are 0..n of them, and each runs the host agent. A node is just a machine that has joined; being one implies nothing about what it runs.
• control-node — the one node that also holds the the-controller seat. There is exactly one per mesh. "control-node" is not a separate kind of machine — it is a node that additionally runs the controller (and, today, the foundation). Lose it and the other nodes keep running what they were last told; they simply cannot be told anything new.
• master / slave, hub / peer — not used. The relationship is controller and nodes, and no node is subordinate: a node applies declarations on its own and survives the control-node dying.

What runs the mesh

• controller — the component that decides what each node should be, holds the mesh's records, and tells nodes over the broker. Replaces "control plane" (borrowed from networking's control-plane/data-plane, and opaque here).
• mesh-controller — the module that runs the controller. It claims the the-controller seat at mesh scope, which is what makes it singular. Replaces the module name mesh-control. (The git repository has been renamed mesh-control -> mesh-controller on the forge; the module, container and image it produces are mesh-controller.)
• foundation — the store and the broker, raised at genesis before any module system exists. Replaces "substrate" (a biology metaphor that landed for no one). The foundation is not a third thing beside the store and broker — it is those two, named together.
• store — the one postgres server. It holds the controller's own context databases (inventory, identity, licences — a context owns its store, ADR 0008) and every module's own database. One server, many databases — never one shared "mesh database".
• broker — the one lavinmq message bus. It carries the mesh bus on the / vhost and a vhost per consumer that requires amqp.

What the mesh stores and serves

• package — what code resolves when it is compiled: an npm/cargo/pypi dependency, by version. Served by the package-registry (gitea). Only a builder talks to it.
• artifact — what the mesh delivers to a machine to install and run: an OCI image, by digest. Served by the artifact-store (distribution). Every node pulls from it.
• These are two protocols, not one store being weak — see ADR 0075.

How modules relate to the mesh

• seat — a named position at a scope (node / site / mesh) with a capacity. A capacity-1 seat is exclusive (one holder); a higher-capacity seat is a bench (several holders coexist).
• claim — a module taking a spot on a seat. claims: [{name, scope}] in a manifest. A mesh-scoped exclusive claim is how the mesh says "there is one of me" — e.g. mesh-controller claims the-controller.
• provision — a service one module provides and others require; the mesh resolves a provider and wires the two with an endpoint and a credential. This is separate from seats: a provision is a service you offer, a seat is a slot you occupy.

How this page is kept

A new name for an existing thing lands here first, in the same change that introduces it in code. A record under 02-DECISIONS/ keeps whatever word it was written with — those are immutable — so a term retired here may still appear there, and the mapping above is how to read it.