From f9f48fbbf7a6ed8286aafe11f270bab6663543e9 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 16 Sep 2026 18:22:31 +0200 Subject: [PATCH] Glossary: one name per thing, and the words we retired MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Locks the vocabulary that kept drifting in conversation — controller (not "control plane"), foundation (not "substrate"), node and control-node, seat / bench / claim, package vs artifact. AGENTS.md points at it as the authority. Claude-Session: https://claude.ai/code/session_01D6qtiYU3P9jk3pnAXyAFyx --- 00-META/glossary.md | 60 +++++++++++++++++++++++++++++++++++++++++++++ AGENTS.md | 6 +++++ 2 files changed, 66 insertions(+) create mode 100644 00-META/glossary.md diff --git a/00-META/glossary.md b/00-META/glossary.md new file mode 100644 index 0000000..c8a5178 --- /dev/null +++ b/00-META/glossary.md @@ -0,0 +1,60 @@ +# 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 is still named `mesh-control` until it is renamed 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" — 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. diff --git a/AGENTS.md b/AGENTS.md index 6c1cfbc..313ca77 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,6 +12,12 @@ through them. Thin skills in `.claude/skills/` wrap these playbooks for invocati `hq-handoff`, `hq-sync-constitution`, `hq-status`); each defers to its playbook as authoritative and adds only the mechanical scaffolding. +## Words + +One name per thing. [`00-META/glossary.md`](00-META/glossary.md) is the authority on +vocabulary — *controller* (not "control plane"), *foundation* (not "substrate"), *node* and +*control-node*, *seat* / *bench* / *claim*, *package* vs *artifact*. Use those words. + ## Ground rules - **Markdown only.** No new top-level folders without explicit confirmation.