jochen
7b1dabbce0
The predecessor's agent module was retired and its six files stayed on both workstations telling every session to use tools that no longer exist. This is its successor's design, revised during review on the operator's directions: the host is module-agnostic, the controller has no part, and a real licence manager hands out the correct licence in every situation. - ADR 0181 (reconstructed): the operator account is a node fact stated by the operator; the home is derived unless stated; a resource may be placed under it owned by the account; a node with no account refuses one. What the controller shipped on 2026-09-27 without a record. - ADR 0182: inside a home the module owns the directory and the files it places, writes into the tool's own files for its few keys, never declares a credential's content, and holds everything else as found; a predecessor's leftovers are the operator's to remove once. - ADR 0183: claude-licence-manager holds the mesh seat anthropic-licence-manager and owns the Anthropic licences, grants (encrypted with a key the vault made for it), bindings per touchpoint, usage and audit; one rotation source under a lease; a token travels module to module sealed to each node's module key on request/reply, never as an event; the agent module alone writes what the agent reads; the host delivers package and state and knows nothing else. A bounded exception to ADR 0113; dated mechanism notes on ADR 0050 and 0113. - To-be 36 (claude-code): the mesh's part of the agent's configuration lives in the agent's machine-wide managed directory, owned whole by the module and written by its code; nothing under the home but the credentials file of a subscription licence; the API-key licence through the key-helper; the console as a node-scoped provision (to-be 34 amended); MCP servers as settings with an mcp_configure tool; one agent directory per machine shared by every session. - To-be 39 (claude-licence-manager): store, the two licence kinds, keeping a grant alive, the hand-over, who gets which licence with the predecessor's fallbacks, adoption with the identity guard, the seat's verbs. Numbers taken across main and every open branch at the time of the merge; to-be 14, 29 and 34 carry dated notes; the glossary gains "operator account".
121 lines
9.1 KiB
Markdown
121 lines
9.1 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.
|
|
- **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`**.
|
|
(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).
|
|
- **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.
|
|
|
|
## 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 tools are built into, interpreted or compiled; never an image.
|
|
- **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.
|
|
|