jschoubben
94fee5d849
The glossary's authority page still named the controller's seat the-controller in two entries, contradicting its own seat section after ADR 0079; issue 058's heading kept the pre-renumber 059; 055's fixed-by named branches that stop existing after merge (now merge commits/PRs) and its located-in listed file paths where the convention wants repos; 056's located-in named mesh-host, which received no fix, instead of mesh-catalog; and the design layer never said the one-store/one-broker property is enforced — 07-the-foundation and the installation table now state the seats. https://claude.ai/code/session_01D6qtiYU3P9jk3pnAXyAFyx
62 lines
4.2 KiB
Markdown
62 lines
4.2 KiB
Markdown
# 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".
|
|
- **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](../02-DECISIONS/0075-two-stores-and-which-provides-what.md).
|
|
|
|
## 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". 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. 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.
|