novox/hq

Files

T

jochen dbe100ca96 ADR 0110 and 0111: a seat is a module assignment from a closed set, and a build source may live on the git seat

Seats have been doing two jobs and neither is written down. The mechanism ADR 0009 introduced is
enforced — a second holder is refused — but any well-formed name becomes a seat by being claimed,
and nothing can say which seats a mesh has or who holds them: holdings are assembled while planning
and discarded. The enumeration done while preparing this missed the control plane's own manifest,
because core modules' manifests live in its repository rather than the catalogue.

0110 closes the set. Each seat has a name, a scope, what occupying it delivers, and the record that
made it one; a claim outside the set is refused. A seat is held by a module assignment, and what the
mesh knows about the holder is what it knows about that assignment — nothing is stored beside it. A
seat may deliver a provision, and then its holder answers for it among several providers: pin, then
the holder, then the only provider, then refused. That keeps 0009's "refused, never guessed": the
seat is the choice made once, mesh-wide, instead of a pin per consumer node. The first set is the
eleven seats already claimed plus 0109's npm-package-registry, so nothing in use is refused.

Two concepts — seats for exclusion, a new word for consumable singulars — was rejected: both mean
"this mesh's one X", and the overview a person wants is one list.

0111 gives the mesh a git seat and makes a build source one of two explicit forms: a repository on
the seat's holder, recorded by its path and cloned from wherever the holder runs at build time; or
an external URL, recorded and cloned exactly as given. Recognising self-hosted sources by matching
URLs against the forge's address was rejected — it fails in the one case it exists for, after the
forge moves. Credentials for private repositories are left undecided and said so.

Design: new to-be 26 (the seats); 23 gains the seat step in resolution; 18's source entry names
the two forms; the glossary's seat and provision entries say where they meet. 0109 is carried from
its own branch so every link here resolves.

2026-09-25 20:33:14 +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