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 node-engine. A node is
  just a machine that has joined; being one implies nothing about what it runs.
- **operator account** — the login name of the person who works on a node, stated on the node
  record; empty for a machine nobody logs into. Everything the mesh places under a person's home is
  resolved against this account's home and owned by it
  ([ADR 0181](../02-DECISIONS/0181-the-operator-account-is-a-node-fact-and-a-home-is-a-placement-root.md)).
  Not "the user" (ambiguous with a module's own account) and not a name a definition carries.
- **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`**.
- **node-engine** — the program on every node that applies what the controller declares: it receives the
  node's declaration, writes the files, runs the services and containers, and reports what it did. It
  is the engine, not a module: it owns no file's content, and every file it writes belongs to the module
  that declared it. Replaces **"host agent"**, **"the host"** and **`mesh-host`**. *Agent* is avoided
  because the word already means two other things here, the build agent and the operator's coding
  agent. The code still carries the old name (the `mesh-host` repository, its binary and service
  unit) until the rename is made there; a record written before the rename keeps the old name.
  (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 0128](../02-DECISIONS/0128-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 0127](../02-DECISIONS/0127-amqp-is-a-provision-not-the-bus.md) (superseded by [ADR 0131](../02-DECISIONS/0131-everything-on-the-mesh-speaks-to-the-broker-seat.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** — anything a build produces and the mesh delivers to a machine by **digest**: an
  `image`, a mirrored `upstream` image, a `bundle` of the module's own code, an `archive`. Served by
  the **artifact-store**, an OCI registry that holds every kind as content-addressed blobs
  ([ADR 0156](../02-DECISIONS/0156-an-artifact-is-what-a-build-produces-and-the-store-is-named-for-its-scope.md)).
  Every node pulls from it. An image is one kind of artifact, and a module is not an image.
- 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 0126](../02-DECISIONS/0126-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). The first bench is `mesh-dns-resolver`, a *replicated* mesh seat: one holder per machine,
  each on record and each answering the same names ([ADR 0223](../02-DECISIONS/0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md)).
- **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)).
- **depends on a seat** — a module needing a seat held on its node by some module, without holding
  it. Derived from the resources it declares, never stated: a `service` depends on
  `node-service-manager`, a `package` on `node-package-manager`, a `container` on
  `node-container-runtime` ([ADR 0207](../02-DECISIONS/0207-a-module-depends-on-the-node-seats-that-apply-its-resources.md)).
  Not a claim: a module **claims** a seat it holds and **declares** resources. Nothing claims a
  package.
- **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.

## The surfaces

- **console** — the module (`mesh-console`) that puts the mesh's tools in front of whoever is on a
  machine: an MCP endpoint on the machine's loopback for an agent, the same endpoint for a person. It
  is assigned like any module, holds a credential the mesh minted, and calls tools under a grant its
  manifest declares (`invokes`). Loopback is the authority boundary: whoever is on the machine owns the
  mesh there ([ADR 0152](../02-DECISIONS/0152-the-operators-surface-is-a-module-the-console.md)).
  Not "the tool bridge", "the brain" or "the MCP server" — those name the predecessor's program or a
  protocol, and the console is a module.
- **invokes** — the manifest word for the tools a module calls, `<module>.<tool>` each or `*` for
  every one. A grant on the publish side and nothing else; a module that declares none calls nothing.

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

## The operator's machine

- **node tools** — the one tool runtime per node, a host-side process the host supervises, that loads
  every assigned module's tools bundle and serves every tool and held seat's verb on the subjects the
  memberships issue; its serving mode on loopback is what was called **the console**
  ([ADR 0175](../02-DECISIONS/0175-one-tool-runtime-per-node-serves-every-modules-tools-on-the-host-side.md)).
  Replaces **"console"** as the module's name; *console* remains the word for the person's end of it.
- **bundle** — the artifact a module's own code is built into — its tools, a seat's implementation, a daemon — in any language the mesh has a toolchain for, interpreted or compiled; never an image. One module may declare several ([ADR 0188](../02-DECISIONS/0188-a-modules-own-code-is-bundles-in-any-language-and-a-tools-bundle-speaks-mcp-to-the-runtime.md)).
- **kept region** — a marked block in a managed file the mesh writes *into*, where the operator's own
  lines survive every push and are given back when the module goes
  ([ADR 0174](../02-DECISIONS/0174-a-node-varies-a-module-through-settings-and-kept-regions-never-an-edit.md)).
  One of the two ways a node varies a module; the other is a **setting**.
- **installed / holding** — a module may be assigned (its package installed, its files placed) without
  holding the seat its family declares; *holding* is being the one — the login shell, the display
  session — on that node ([ADR 0176](../02-DECISIONS/0176-the-login-shell-is-a-node-seat-and-execute-is-its-contract.md)).
- ~~flavor~~ — not used. What a flavor varied is a setting or a separate module.