novox/hq

Files

T

jochen a7b2db9efc Accept ADR 0110 and ADR 0111; the seats design is in progress

The seats half of to-be 27's review is settled, so the two records it rests on are accepted and
the vocabulary catches up: the glossary's *seat* becomes a named role from a closed set, held by
an assignment and possibly delivering a provision, and 23 — Choosing a provider gains the seat
step in resolution, with ambiguity still refused rather than guessed. Both were held back when
0110 was proposed, because a document may not rest on a record that is not accepted.

26 — The seats moves to in-progress rather than designed: it names the files that implement it,
and naming a file claims implementation, which is only defensible once those files are on the
owning repositories' main branches. It becomes implemented when mesh-controller #63 and
mesh-catalog #69 land.

0112, 0113 and 0114 stay proposed; to-be 27 stays proposed with them.

2026-09-26 14:28:23 +02:00

4.8 KiB

Raw Blame History

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

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 0110). The set, with who holds each seat, is the overview of what a mesh has (26 — The seats). 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).
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.

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.

4.8 KiB Raw Blame History