hq/00-META/glossary.md

# Glossary — the words of the mesh, by domain, and the ones it stopped using

One name per thing. This page is the authority; where an older record says something else, that
record keeps its words and this page says how to read them. It exists because the words kept drifting
in conversation — "control plane", "controller" and "master" for one thing, "substrate" and
"foundation" for another — and a mesh you cannot name precisely is a mesh two people describe differently. The rule and
its check are [ADR 0244](../02-DECISIONS/0244-the-mesh-is-described-in-domains-and-one-word-names-one-thing.md);
the domains are drawn in [to-be 49](../03-DESIGN/01-to-be/49-the-mesh-in-domains.md).

## How to read this page

A **domain** is an area of the mesh that owns a set of concepts: inside it each concept has one word,
and the domain decides what that word means. Other domains use the word as it is defined here and never
change its meaning. Every word is defined once, in the domain that owns it; a section lists the words
it uses from other domains under *Uses*, with no second definition.

Two fixed lines follow an entry where they apply, and `00-META/checks/words.py` reads them:

- *Not:* followed by struck-through words — the words this entry replaced. A struck word with no scope
  is retired everywhere; *(hq)* retires it in this repository's prose only; *(tools)* in the
  descriptions of the mesh's tools and seat verbs only. A retired word may be quoted, never used.
- *Identifier until renamed:* followed by a name in a code span — code that still carries an old name.
  It may stand in a code span and nowhere else until the code is renamed, and then the line goes.

Nothing else on this page is struck through. A word that means different things in different domains
is listed under [Homonyms](#homonyms), with the qualified form each domain uses.

## Words every domain uses

- **mesh** — the whole: the nodes, the modules assigned to them, the controller that decides and the
  records it keeps. One mesh per operator; a second mesh is a second everything.
- **domain** — an area of the mesh that owns a set of concepts and the one word for each, as described
  in the section above ([ADR 0244](../02-DECISIONS/0244-the-mesh-is-described-in-domains-and-one-word-names-one-thing.md)).
  ADR 0006 called seven of them the controller's *contexts*; they carry over as domains under the same
  names, except *observability*, which is now **Health and repair**. Where a domain's records live in
  the controller, the domain owns that store alone ([ADR 0008](../02-DECISIONS/0008-a-context-owns-its-store.md)).
  *Context* in that sense is not used in new writing; the word stays ordinary English, so this is
  checked by review, not by `words.py`.
- **machine** — any computer: hardware, a virtual machine, before, during or outside its membership of
  the mesh. Prose about the computer itself — its disks, its kernel, the network it sits on, what was on
  it before the mesh — says machine.
- **node** — a machine the mesh has adopted and owns. A machine becomes a node when it joins
  ([ADR 0004](../02-DECISIONS/0004-a-node-and-how-it-joins.md)), and from then on it runs the node-engine
  and is either **adopted** (the mesh holds what it found there as found) or **converged** (the mesh made
  it what it is) — [ADR 0100](../02-DECISIONS/0100-a-node-in-use-is-adopted-before-it-is-converged.md).
  Prose about a member of the mesh says node. A node is just a machine that has joined; being one
  implies nothing about what it runs.
- **module** — the unit the mesh assigns: one named thing, defined by its manifest, that a node runs —
  a service, a container, files, packages, its own code — and the tools it serves
  ([ADR 0040](../02-DECISIONS/0040-what-a-module-is.md)). Everything configurable on a node is a module.
- **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)). 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 carries **verbs** — the tools every holder must serve. A verb added to a held seat is first
  promised as optional, then served, then required ([ADR 0246](../02-DECISIONS/0246-a-seats-new-verb-is-promised-before-it-is-required.md)).
- **operator** — the person who runs the mesh, and the one the mesh talks to.
  *Not:* ~~master~~ (hq)
- **person** — any human, as against the mesh acting unattended: *a person's word* releases a held
  delivery, *a person* deletes a consumer's data. The operator is one; the word says that a human, not
  the mesh, acted.

## Module — what a module is and declares

**Purpose.** To say what one module is, in the one document every other domain reads.
**Recorded in** the catalogue, one manifest per module. **Upstream of** every other domain; its words
are a published vocabulary, fixed by the manifest's schema. **Decided by** ADR 0040, 0126, 0174, 0188,
0207, 0236.
**Uses:** module, seat, provision (Provisioning), data class (Data), health (Health and repair).

- **manifest** — the file a module is defined by (`module.json`): what it is, what it provides and
  requires, the seats it claims, the resources it declares, its tools, its data and its health. Say
  manifest in prose, not the file's name.
  *Not:* ~~module definition~~ (hq)
- **resource** — one thing a manifest declares a node must have: a file, a directory, a service, a
  container, a package, a bundle, an archive. A module **declares** resources; the verb *declares* is
  this domain's and means what a manifest states.
- **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 role
  it guards: the `mesh-controller`, `postgres` and `nats` 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),
  [ADR 0116](../02-DECISIONS/0116-the-bus-is-built-in-five-steps.md)).
- **setting** — a value a manifest declares and an assignment gives, one of the two ways a node varies
  a module ([ADR 0174](../02-DECISIONS/0174-a-node-varies-a-module-through-settings-and-kept-regions-never-an-edit.md)).
  What a "flavor" once varied is a setting or a separate module.
  *Not:* ~~flavor~~
- **kept region** — a marked block in a managed file the mesh writes *into*, where the operator's own
  lines survive every send and are given back when the module goes (ADR 0174). The other way a node
  varies a module.
- **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; never an image. A **tools bundle** speaks MCP to
  the tool runner. 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)).
- **tool** — one capability a module serves through the tool runner, addressed `<module>.<tool>`. A
  seat's **verb** is the same thing carried by a seat rather than a module.
- **mesh-sdk** — the library a module's own code is written against, including the harness that serves a
  tools bundle to the tool runner. The harness is part of it, not a library of its own.
  *Not:* ~~tools-sdk~~
- **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.
- **upgrade policy** — how a module's new builds reach its nodes: `roll` (one node first, judged, then
  the rest), `together`, or `record` (register the build, send it nowhere)
  ([ADR 0236](../02-DECISIONS/0236-a-build-is-judged-on-its-first-machine-and-put-back-by-something-other-than-itself-and-so-it-rolls-out-unattended.md)).
  The controller's verb `upgrade` shows it.

## Core — the mesh's own machinery

**Purpose.** To keep the controller, the bus, the store and every node's engine running and agreed, so
every other domain has something to run on. **Recorded by** the controller and the store.
**Upstream of** every domain but Module; the others use the bus and the store as they are.
**Decided by** ADR 0005, 0006, 0067, 0106, 0141, 0175, 0227, 0229.
**Uses:** node, module, seat.

- **controller** — the component that decides what each node should be, holds the mesh's records, and
  tells nodes over the bus. The relationship is *controller and nodes*, and no node is subordinate: a
  node applies its declaration on its own and survives the control-node dying.
  *Not:* ~~control plane~~, ~~slave~~ (hq), ~~mesh-control~~ (hq)
- **mesh-controller** — the module that runs the controller. It claims the `mesh-controller` seat at
  mesh scope, which is what makes it singular.
- **control-node** — the one node that also holds the `mesh-controller` seat. There is exactly one per
  mesh. It is not a separate kind of node — 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.
- **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. *Agent* is avoided because that word means a coding agent here. A record
  written before the rename keeps the old name. "The host" is retired in this repository's prose only:
  in the tools' descriptions it is also an SSH server's or a container runtime's own word, so a
  description that means the node-engine by it is found by review.
  *Not:* ~~host agent~~, ~~the host~~ (hq), ~~node host~~
  *Identifier until renamed:* `mesh-host` — the repository, its binary and its service unit
- **tool runner** — the one program on each node that loads every assigned module's tools bundle and
  serves every tool and every held seat's verb on the subjects the memberships issue; the node-engine
  supervises it as a process beside the services it runs, never a container
  ([ADR 0175](../02-DECISIONS/0175-one-tool-runtime-per-node-serves-every-modules-tools-on-the-host-side.md),
  which called it "node tools"). Its mode on loopback is the mesh MCP server.
  *Not:* ~~node tools~~, ~~tool runtime~~ (hq)
  *Identifier until renamed:* `node-tools` — the module, its unit and its bus account
- **foundation** — the store and the bus, raised at genesis before any module system exists. The
  foundation is not a third thing beside the store and the bus — it *is* those two, named together.
  *Not:* ~~substrate~~
- **genesis** — raising the foundation and the controller on an empty mesh, by the one installation
  done by hand ([ADR 0067](../02-DECISIONS/0067-genesis-is-a-pivot.md)).
- **store** — the one postgres server. It holds the controller's own databases (`inventory`,
  `identity`, `licences`, each owned by one domain, ADR 0008) and every module's own database. One server,
  many databases — never one shared mesh database. Bare *store* means this and nothing else
  (see [Homonyms](#homonyms)).
- **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 `nats`
  module holds it.
- **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 0131](../02-DECISIONS/0131-everything-on-the-mesh-speaks-to-the-broker-seat.md)) — it claims no
  seat, is not foundation, is 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).
- **layer** — one of the four levels the mesh is built in, from the bottom: the node-engine, the
  foundation, the controller, the surfaces. The records' `topic: the tiers` and `repos.md` say *tier* for
  this; new prose says layer (see [Homonyms](#homonyms)).
- **lease** and **epoch** — which controller may send (the lease, held in the bus and renewed), and the
  order of what it sent (the epoch, which a node reads before it accepts a declaration)
  ([ADR 0229](../02-DECISIONS/0229-the-cores-order-is-a-lease-the-store-remembers-and-an-epoch-a-machine-is-sent-once-it-reads-one.md)).

## Placement — what runs on which node

**Purpose.** To decide, send and apply what each node runs, and to say why.
**Recorded by** the controller's `inventory` database. **Upstream of** Provisioning, Connectivity, Data
and Health and repair. **Decided by** ADR 0100, 0126, 0176, 0181, 0207, 0221.
**Uses:** node, machine, module, seat, setting (Module), manifest (Module).

- **assignment** — a module put on a node, with the settings that node gives it.
- **scope** — where a seat or a claim holds: `node`, `site` or `mesh`. `node` is also the scope's
  value in a manifest.
- **capacity** — how many holders a seat takes. A capacity-1 seat is exclusive. A higher-capacity seat
  is a **bench**: several holders coexist. A **replicated** bench has one holder per node, each on record
  and each answering the same, like `mesh-dns-resolver`
  ([ADR 0223](../02-DECISIONS/0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md)). A
  **kinded** bench has holders that are different modules, each claiming one **kind**, and a verb's
  subject carries the kind; `channel` and `intake` are the only ones (ADR 0234).
- **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)).
  The module that holds a seat is its **holder**.
- **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.
- **declaration** — what the controller sends one node: every resource of every module assigned there,
  composed. The noun is this domain's; what a manifest says is that it *declares* (Module), and a manifest
  is never called a declaration. The controller's verb `plan` previews a node's declaration.
- **send** — the controller giving a node its declaration. The controller's verb `push` asks for a
  send (of one node, or of every node); prose says send. A git push and a phone's push notification are
  other things (see [Homonyms](#homonyms)).
- **apply** — the node-engine making its node match its declaration; **reconcile** is doing so again
  until nothing differs.
- **operator account** — the login name of the person who works on a node, stated on the node record;
  empty for a node 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 a name a manifest carries.

## Provisioning — one module serving another

**Purpose.** To resolve which module serves a provision for which consumer, and to wire the two.
**Recorded by** the controller. **Upstream of** Data; downstream of Module, Placement and Identity.
**Decided by** ADR 0027, 0084, 0138, 0225, 0230.
**Uses:** module, seat, credential (Identity and access).

- **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.
- **provider** and **consumer** — the module that provides a provision, and the module that requires
  it. Which of several providers serves a consumer is resolved
  ([ADR 0084](../02-DECISIONS/0084-which-provider-serves-a-consumer.md)).
- **pin** — a person's choice of provider for a consumer, which resolution then respects.
- **endpoint** — where a consumer reaches its provider; an assignment binds it and says how far it
  reaches ([ADR 0138](../02-DECISIONS/0138-an-assignment-binds-an-endpoint-and-says-how-far-it-reaches.md)).
- **retire** — a provider stops serving a consumer the mesh no longer asks for; what it kept is deleted
  only by a person ([ADR 0230](../02-DECISIONS/0230-a-consumer-the-mesh-stops-asking-for-is-retired-and-deleted-only-by-a-person.md)).

## Identity and access — who may do what

**Purpose.** To issue, hold, rotate and check the credentials and grants by which modules, nodes, agents
and the operator act. **Recorded by** the controller's `identity` and `licences` databases and the vault.
**Upstream of** Provisioning, Change and delivery, and Operator and conversation.
**Decided by** ADR 0085, 0113, 0183, 0225, 0234.
**Uses:** module, node, operator, consumer (Provisioning).

- **credential** — anything that proves an identity: a password, a key, a token. A **pair credential**
  is the two ends of one credential, the consumer's and the provider's.
- **secret** — a credential or other value the vault keeps sealed and the node-engine unseals into a
  file at apply ([ADR 0085](../02-DECISIONS/0085-a-secret-is-a-provision.md)).
- **vault** — the module that owns every secret (`mesh-vault`,
  [24 — The secrets vault](../03-DESIGN/01-to-be/24-the-secrets-vault.md)).
- **grant** — what an identity may call or reach, bounded by the provisions it requires
  ([ADR 0225](../02-DECISIONS/0225-a-consumers-identity-is-bounded-by-the-provision-it-requires.md)).
- **bus account** and **membership** — a module's or a node's account on the bus, and the subjects it
  is issued. The bus server calls its accounts *users*; the mesh says bus account.
- **rotate** — replacing a credential without a consumer holding one the provider does not know.
- **licence** — a model-access account the licence manager holds and **binds** to a consumer, the
  coding agent on a node ([ADR 0183](../02-DECISIONS/0183-the-anthropic-licence-manager-is-a-module-and-hands-tokens-to-the-agent-over-the-bus.md)).
  Taking a consumer off a licence is **unbinding** it; the licence manager's verb for it is still
  `release`, an identifier to rename.
- **proof** — what an authorising answer carries: a verified sender, a one-time code, a security key's
  touch (ADR 0234). How much proof a kind of ask needs is its **assurance level**.

## Change and delivery — a commit on its way to the nodes

**Purpose.** To take one commit from its pull request to every node that should run it, and to put it
back when it fails. **Recorded by** the `mesh-delivery` module (deliveries) and the controller (the
planner, the walk). **Downstream of** Module, Core, Health and repair and Data.
**Decided by** ADR 0162, 0218, 0236, 0237, 0238, 0239.
**Uses:** module, node, declaration and send (Placement), health (Health and repair), person.

- **merge check** — the two statuses a pull request carries before it may merge: the **merge gate**
  (`mesh/merge-gate`, the build seat's composed check of the modules the change touches) and the
  **repository check** (`mesh/repo-check`, the repository's own `merge-check.sh`)
  ([ADR 0238](../02-DECISIONS/0238-a-commit-is-the-build-at-hand-one-commit-one-change-plan-checked-off-the-trunk-and-published-only-on-it.md)).
- **build seat** — the seat whose holder builds modules, `node-build-agent`; its holder on a node is the
  **builder**. Any node may hold the seat, so there is no build node by nature
  ([ADR 0237](../02-DECISIONS/0237-a-change-is-judged-against-the-mesh-that-runs-before-it-merges-on-the-build-seat.md)).
  *Not:* ~~build machine~~
- **build queue** — the controller's queue of builds to run; one entry in it is a **build request**.
  The queue's verbs still say *ask* for an entry; the conversation's ask is another thing
  (see [Homonyms](#homonyms)).
- **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 node 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)).
  An image is one kind of artifact, and a module is not an image. A package and an artifact are two
  protocols, not one store being weak ([ADR 0075](../02-DECISIONS/0075-two-stores-and-which-provides-what.md)).
- **catalogue** — what the mesh holds of every module, at which commit; and the repository the
  modules live in. `mesh-catalog` and `catalog_modules` are identifiers and keep their spelling.
  *Not:* ~~catalog~~ (hq)
- **delivery** — one commit in one repository on its way to the nodes, from its pull request's head
  being announced to delivered, failed, superseded or stopped: one pull request, one status, one note
  ([ADR 0239](../02-DECISIONS/0239-a-delivery-is-owned-by-the-mesh-delivery-module-and-runs-from-commit-to-delivered.md)).
  Its states are one table (`proposed`, `checked`, `ready` or `rejected`, `published`, `delivering`,
  `held`, and the final four). Not *change* (a diff). *Pipeline* is the predecessor's build-and-deploy
  mechanism, which the as-is designs describe; it is never a word for a delivery.
  *Not:* ~~deployment~~ (hq)
- **delivery group** — two or more deliveries sharing a pull request head branch name across the mesh's
  repositories, delivered as one unit in an order declared (`after:`) or inferred by the planner. One
  level: a group holds deliveries, never groups. Its state is derived from its members, never set.
- **delivery plan** — what a delivery does to the mesh: its **build plan** (the modules it moves and
  their dependents, in tiers), its **deploy plan** (per node, what it receives and what waits for a
  person) and its verdict (the composed nodes, the replays). Computed by the controller's planner from a
  diffset; the controller's verb `delivery-plan` shows it. *Deploy* is used in this one place.
  *Not:* ~~change plan~~, ~~release plan~~
- **mesh-delivery** — the module that owns deliveries and delivery groups, holding the mesh-scoped seat
  of the same name. It records and decides; the controller sends, judges and rolls back when it is asked.
- **walk** — the controller's sending of one trunk commit's builds across nodes, tier by tier, one node
  first and judged at the first-node gate, then the rest (ADR 0236). A primitive the delivering stage
  asks for, not an object anyone manages. A **tier** is one step of a walk: a module, then the modules
  built against it. The controller's verb `plans` lists the walks. Walking is not a noun of its own:
  a module *rolls out* by its `roll` policy.
  *Not:* ~~rollout~~ (hq)
- **first-node gate** — the judgement on a delivery's first node: healthy three times, no witness put it
  back, no condition raised since the send (ADR 0236 §2). Not *the gate* bare (see [Homonyms](#homonyms)).
- **release** — a person's word that a held delivery goes on; the verb `mesh-delivery.release`. Used in
  this sense only.
- **rollback** — putting a node back on the build it ran before, by something other than the build being
  judged (a witness, ADR 0236).
- **the lab**, **scenario**, **replay** — a real mesh raised to run a change against before it reaches
  nodes; what a lab run declares; and a recorded failure run again to prove a fix (ADR 0016, ADR 0237).

## Health and repair — what is wrong, and putting it right

**Purpose.** To notice what is wrong with the mesh, say it once, repair what may be repaired unattended,
and record what was done by hand. **Recorded by** the controller's condition store.
**Upstream of** Change and delivery (the first-node gate) and Operator and conversation (a condition
becomes a message). **Decided by** ADR 0227, 0231, 0240.
**Uses:** node, module, node-engine (Core).

- **health** — a module's or a core component's statement of how it is alive and ready, which the
  node-engine judges ([ADR 0240](../02-DECISIONS/0240-a-module-says-how-it-is-healthy-and-the-node-engine-judges-it.md)).
- **probe** — one look at one thing's health, run by whoever owns the verdict; what a probe returns is a
  **finding**, before it becomes a condition.
- **signal** and **watchdog** — something that must keep happening (a heartbeat, a report after a send),
  and the watcher that raises a condition when it stops (to-be 45 §3).
- **condition** — one open fact about something the mesh owns that is wrong, with a key and a severity;
  raised and cleared only by observation
  ([ADR 0231](../02-DECISIONS/0231-a-healer-acts-on-what-observation-raised-and-only-observation-says-it-worked.md)).
  What a wrapped dashboard raises is its own; the mesh's notion is a condition.
  *Not:* ~~alert~~ (hq)
- **self-check** — the controller's own examination of the mesh, run on demand and on a schedule
  (to-be 45 §4). Its verb is `doctor`, an identifier; prose says self-check.
  *Not:* ~~doctor~~ (hq)
- **healer** — a registered response to one condition kind: its **repair** (the ordinary path again),
  its **budget**, its back-off and its brake. A healer may not withdraw, delete or recreate data.
- **drill** — something broken on purpose to see the mesh raise and clear its condition; a drill is
  never counted as a repair.
- **hand-act** — a repair a person made by hand, recorded so the mesh knows it happened.
- **witness** — what rolls a core component back when its new build does not become healthy: never the
  component itself (to-be 45 §8).

## Data — what the mesh keeps, and getting it back

**Purpose.** To know every item of data a module holds, how precious it is, and to keep it recoverable.
**Recorded by** the manifests' `data` declarations and every node's `node-backup` seat.
**Upstream of** Change and delivery and Health and repair. **Decided by** ADR 0232, 0233, 0235.
**Uses:** module, node, provider and consumer (Provisioning), person.

- **data class** — how precious an item of data is, ranked by the operator: `irreplaceable`,
  `valuable`, `rebuildable`, `cache`; and `none` for a provision that keeps nothing of anybody's
  ([ADR 0233](../02-DECISIONS/0233-a-module-declares-the-data-it-holds-and-the-mesh-protects-and-watches-it-from-that.md)).
- **backup** — a copy kept elsewhere by the node's `node-backup` holder; **restore point** — one backup
  at one moment; **restore** — bringing it back beside the live data, never over it.
- **stream snapshot** — the bus's own backup of each stream, taken by the module holding `mesh-broker`
  ([ADR 0235](../02-DECISIONS/0235-the-bus-is-backed-up-by-its-own-snapshot-of-each-stream.md)).
- **sticky binding** — a consumer's tie to the data a provider keeps for it, which moves only by a
  person ([ADR 0232](../02-DECISIONS/0232-a-binding-to-a-consumers-data-moves-only-by-a-person.md)).

## Connectivity — how nodes and modules reach one another

**Purpose.** To make every node and module reachable by name where it should be, and unreachable where
it should not. **Recorded by** the controller. **Upstream of** Provisioning and Health and repair.
**Decided by** ADR 0007, 0117, 0138, 0223, 0226.
**Uses:** node, machine, assignment and endpoint.

- **private network** — the mesh's own encrypted network between its nodes, on which every node has an
  address and a mesh name ([ADR 0226](../02-DECISIONS/0226-the-private-network-is-assigned-by-its-own-name-and-the-proxy-names-its-public-issuer.md)).
  The network the machine sits on without it is the **underlay**.
  *Not:* ~~overlay~~ (hq)
- **anchor** and **hub** — the roles a node plays for the private network: the anchor is reachable from
  outside and every node reaches it; a hub relays for nodes that cannot reach each other directly.
- **resolver** — a seat holder that answers the mesh's names; a node lists only the mesh's resolvers
  (ADR 0223). **uplink** — a node's connection to the outside network, a seat
  ([ADR 0117](../02-DECISIONS/0117-a-machines-uplink-is-a-seat.md)). **hostname** — a node's own name,
  a seat.
- **proxy** and **public name** — the module that answers a public name and forwards it to an
  endpoint on the private network.
- **packet filter** — what the mesh enforces on a node about which packets pass, the
  `node-packet-filter` seat and its verb `rules`. A **found firewall** is a program the mesh found on a
  machine and keeps retired or in force; *firewall* says that, and a wrapped program's firewall is its own.
- **intrusion prevention** and **ban** — refusing a source that misbehaved, and the refusal itself.
- **reach** — how far an assignment's endpoint may be reached from: the node, the private network, or
  the outside (ADR 0138).

## Operator and conversation — the person the mesh works for

**Purpose.** To let the mesh and its operator talk: tell, ask, answer, and act only on an answer it can
trust. **Recorded by** the router and the controller (authorising asks).
**Downstream of** Health and repair, Change and delivery, and Identity and access. An authorising
answer acts in whichever domain asked, through that domain's own verb; the conversation owns the
asking, never the act. **Decided by** ADR 0152, 0175, 0234.
**Uses:** operator, person, proof (Identity and access), release (Change and delivery).

- **mesh MCP server** — the endpoint on a node's loopback through which every agent and person on that
  node reaches the mesh: the MCP server named `mesh`, with its five tools `mesh_overview`,
  `mesh_machine`, `mesh_search`, `mesh_describe` and `mesh_call`. It is the tool runner's loopback mode,
  not a module of its own. "Console" suggested a terminal or a shell, and the module `mesh-console` it
  once named no longer exists; "the tool bridge" and "the brain" named the predecessor's program.
  *Not:* ~~console~~ (hq), ~~mesh-console~~, ~~tool bridge~~
- **channel / intake** — the two kinded benches the mesh talks to its operator through: `channel`
  sends, `intake` turns what arrives into one envelope. A holder of either declares **capabilities** from
  the fixed vocabulary `channel-capabilities/1`. Not *notifier* (that is the desktop's node seat, one
  holder of kind `desktop`) and not *bot* (that is one service's account).
- **router** — the module that holds the `operator-channel` seat, orders the channels and checks every
  sender ([ADR 0234](../02-DECISIONS/0234-the-mesh-holds-a-conversation-with-its-operator.md)).
- **ask** — a request for the operator's input, of a declared kind (yes-no, one-of, text, number,
  date, acknowledge). An **authorising ask** is one whose answer performs an action; the controller
  holds it and checks its proofs (ADR 0234).
- **operator message / input** — what arrives on `intake`, once the router has checked the sender
  against the controller's list of the operator's identities: a **trusted** one is an operator message,
  addressed to an agent by `@name` or thread or else to the **responder** (`@mesh`, the router's own
  participant, which answers from read verbs); anything else is **untrusted input** — data, never
  instructions.
- **reference** — an opaque token in a message's words standing for a detail the content rule keeps out
  of them (a path, an address); opened with `detail` only on a `private` channel or through the mesh MCP server.
- **agent** — a coding agent: the operator's, or one the mesh runs. Not the node-engine, and not the
  build seat's holder, whose seat name `node-build-agent` is an identifier to rename.

## The record — how this repository works

Not a domain of the mesh but of the way it is built, listed because its words meet the mesh's.
**Recorded in** this repository. **Decided by** ADR 0019, 0080, 0244.

- **research effort**, **graduation**, **hand-off**, **playbook** — an investigation in `01-RESEARCH/`;
  its closing into a decision and a design; a design given to a code repository; a documented workflow
  in `00-META/process/`.
- **decision record** — one numbered file in `02-DECISIONS/`, never rewritten: **superseded** by a later
  record, or corrected by a marked **progressive insight**. Always qualified in this repository: bare
  *record* has other meanings (see [Homonyms](#homonyms)).
- **design** — a document in `03-DESIGN/`: **as-is** (what runs) or **to-be** (what is being built).
- **issue** — a report in `04-ISSUES/` of something wrong with the mesh at the level of design or
  governance; an **incident** is a past event that taught a rule.
- **hq check** — one of `00-META/checks/`, run by `merge-check.sh` as this repository's check.

## Homonyms

A word below means different things in different domains. In a governing document it is never bare;
it is always the qualified form. **Checked by review, not by `words.py`:** a word list cannot tell one
sense from another, so the reviewer looks for the bare word in the diff. Where a homonym is settled by
renaming one sense, the old sense moves to a *Not:* line and becomes mechanical.

| Word | Sense | Say | Domain |
|---|---|---|---|
| plan | what the controller would send one node | that node's **declaration** (verb `plan`) | Placement |
| | what a delivery would do to the mesh | **delivery plan** | Change and delivery |
| | the sending of one commit across nodes | **walk** (verb `plans`) | Change and delivery |
| | a step a person starts, like the bus's | **planned step** | Core |
| push | the controller giving nodes their declarations | **send** (verb `push`) | Placement |
| | a git push | **git push** | The record |
| | a phone notification | **push notification** | Operator and conversation |
| release | a person letting a held delivery go on | **release** | Change and delivery |
| | taking a consumer off a licence | **unbind** (verb `release`, to rename) | Identity and access |
| gate | the judgement on a delivery's first node | **first-node gate** | Change and delivery |
| | the pull request status | **merge gate** | Change and delivery |
| | a failed step stopping its module's later steps (ADR 0136) | *a failed step holds its module* | Placement |
| tier | a level of the mesh | **layer** | Core |
| | a step of a walk | **tier** | Change and delivery |
| | how much proof an ask needs | **assurance level** | Identity and access |
| ask | a request for the operator's input | **ask** | Operator and conversation |
| | an entry in the build queue | **build request** | Change and delivery |
| store | the one database server | **store** | Core |
| | the OCI registry | **artifact store** | Change and delivery |
| | a node's own copy of its last declaration | **last declaration** | Placement |
| record | a numbered decision | **decision record** | The record |
| | the knowledge base agents search first | **the record** (the `records` module) | Operator and conversation |
| | the upgrade policy that sends nowhere | `record` | Module |
| check | a pull request's two statuses | **merge check**, **merge gate**, **repository check** | Change and delivery |
| | a delivery group's verdict | **composed check** | Change and delivery |
| | the controller's own examination | **self-check** | Health and repair |
| | a file in `00-META/checks/` | **hq check** | The record |
| agent | a coding agent | **agent** | Operator and conversation |
| | the build seat's holder | **builder** | Change and delivery |
| the user | an account of a wrapped program, or of the bus server | **its account**, **bus account** | Identity and access |
| | a human | **operator** or **person** | words every domain uses |
| firewall | what the mesh enforces | **packet filter** | Connectivity |
| | what was found on a machine | **found firewall** | Connectivity |
| deploy | the per-node part of a delivery plan | **deploy plan** | Change and delivery |
| | a wrapped program's own deploy | its own word | — |

## How this page is kept

A new word for an existing thing lands here first, in the domain that owns it, in the same change that
introduces it in code. A word moves to another domain only with a decision record. A retired word goes
on a *Not:* line and nowhere else on this page, and `words.py` then fails on it in running prose. A
record under `02-DECISIONS/` keeps whatever word it was written with — those are immutable — so a word
retired here may still appear there, and the *Not:* lines are how to read it.

**How it is checked** ([ADR 0244](../02-DECISIONS/0244-the-mesh-is-described-in-domains-and-one-word-names-one-thing.md)):
`python3 00-META/checks/words.py`, run by `merge-check.sh` on every pull request, fails on a retired
word or a bare identifier in running prose in `00-META/`, `03-DESIGN/`, `AGENTS.md`, `README.md`, and
research and issues dated from 2026-10-07 — code spans, quotations and link targets excepted — and on a
head word that heads two entries or is also retired. The words retired with no scope or with *(tools)*
are copied into the catalogue as `retired-words`, whose own repository check holds the descriptions of
the mesh's tools to them; a change here that retires such a word changes that copy in the same delivery.
Homonyms are checked by review.