novox/hq

Files

T

jschoubben ce6ae943b7 Merge main: renumber this branch's records around the trunk's

Both lines of work numbered from the same point, so four decision records and one design
document existed twice with different content. The trunk keeps its numbers and this branch
yields — the only rule that scales, because the trunk's are already cited by what merged
before them.

0117 the bus is the only broker -> 0125
0118 a module declares its own seats -> 0126
0119 amqp is a provision, not the bus -> 0127
0120 the mesh bus is required -> 0128
0123 a seat carries its role's protocol -> 0129
0124 the predecessor is ending -> 0130
design 29, what a module declares -> design 32

Applied to the code repositories too, because a stale reference is worse when numbers
collide than when they dangle: the reader lands on a real record that decided something
else.

Two reconciliations the merge forced, both real:

**0110 was marked wholly superseded and was not.** Its successor says in as many words that
everything 0110 decided about what a seat *is* stands untouched — and two records that
landed on the trunk rest on exactly that part. So it is accepted again, extended rather than
replaced, with a note saying which of its claims moved and where.

**A seat's protocol becomes columns, not fields.** The trunk moved the seat set out of
compiled code into a table the controller owns. This branch had added what a role accepts,
emits and serves to the Go slice. The decision is unaffected and the mechanism is better for
it: giving a role a protocol is now a write rather than a rebuild, which is the trunk's own
argument applied to what this branch added.

One check still fails and it fails on main too: a record resting on ADR 0112 while that is
still 'proposed'. Left alone — it is not this merge's to answer.

2026-09-27 18:23:41 +02:00

6.0 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".
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). A module reaches it by requiring mesh-bus (ADR 0128); 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) — 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 — 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 0126 (superseding 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.

6.0 KiB Raw Blame History