# 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 `mesh-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 `mesh-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](../02-DECISIONS/0008-a-context-owns-its-store.md))
  and every module's own database. One server, many databases — never one shared "mesh database".
- **bus** — the mesh's own nervous system: NATS, one per mesh, carrying every link the mesh has —
  control, declarations, builds, events, tool calls
  ([ADR 0106](../02-DECISIONS/0106-the-bus-is-nats.md)). A module reaches it by requiring
  `mesh-bus` ([ADR 0120](../02-DECISIONS/0120-the-mesh-bus-is-required-not-ambient.md)); one that
  does not require it has no account on it. Held by the `mesh-broker` seat, which is named after
  the *role* rather than the server, so the server can change without the seat doing so.
- **the deprecated broker** — the lavinmq module. It was the mesh's bus and is not any more. It
  keeps running as an **ordinary provider** of the `amqp` provision, for modules that need a
  message broker of their own the way something needs a database
  ([ADR 0119](../02-DECISIONS/0119-amqp-is-a-provision-not-the-bus.md)) — no seat, not foundation,
  never raised at genesis, and a mesh that never installs it is complete.

  Say *the deprecated broker*, not "the compatibility broker" (it serves the mesh's own modules,
  not only the predecessor's) and not "the AMQP broker" (naming it after a protocol invites
  describing the bus by contrast with it, which is backwards: the bus is the mesh's nervous
  system and this is a module).

## 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](../02-DECISIONS/0075-two-stores-and-which-provides-what.md).

## How modules relate to the mesh

- **seat** — a named role at a scope (node / site / mesh), held by a module assignment, from a
  **closed set** the mesh defines: a claim naming a seat outside the set is refused. A seat may
  **deliver a provision**, and its holder is then the mesh's answer for it when several modules
  provide it ([ADR 0118](../02-DECISIONS/0118-a-module-declares-its-own-seats.md) (superseding [ADR 0110](../02-DECISIONS/0110-a-seat-is-a-module-assignment-from-a-closed-set.md))).
  The set, with who holds each seat, is the overview of what a mesh has
  ([26 — The seats](../03-DESIGN/01-to-be/26-the-seats.md)). A seat has 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". A foundation seat is
  named after the server it guards: the `mesh-controller`, `postgres` and `lavinmq` modules claim
  the `mesh-controller`, `mesh-store` and `mesh-broker` seats ([ADR 0079](../02-DECISIONS/0079-the-foundation-seats-are-named-after-their-servers.md)).
- **provision** — a service one module `provides` and others `require`; the mesh resolves a provider
  and wires the two with an endpoint and a credential. A provision is a service you offer, a seat
  is a role you occupy, and the two meet where a seat delivers a provision: occupying the seat is
  what makes a module *the* provider of it.

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