novox/hq

Files

T

jschoubben 784b487bf9 ADR 0131: everything on the mesh speaks to the broker seat, and AMQP is not a provision

Taken during the outage of 2026-09-27, when the protocol leaked into the seat's
contract: to hold mesh-broker a module had to provide amqp, so the module that
will carry the bus could not hold the seat that names the bus, while the module
being retired could. Supersedes 0127. Modules depend on the seat and reach the
bus through the sdk; no manifest provides or requires amqp; the old broker's
module and the two modules that required it leave the catalogue; the AMQP
transport is deleted once every node reports on the new bus.

Design 28 step 5 rewritten under it: the seat handover becomes its own task and
is built first, because the seat the control plane dereferences cannot be empty
in between — that emptiness was the outage. The cost note now carries what was
measured rather than what was assumed.

0128 and 0130 extended 0127; each now rests on 0131 with a dated note and
changes nothing it decided. Every other citation of 0127 names its replacement.
records.py still fails on 0120/0112, which predates this branch.

2026-09-27 23:03:05 +02:00

7.4 KiB

Raw Blame History

topic, status, date, deciders, reconstructed, extends

topic	status	date	deciders	reconstructed	extends
the mesh	accepted	2026-09-26	jochen	false	02-DECISIONS/0131-everything-on-the-mesh-speaks-to-the-broker-seat.md

128. The mesh bus is required, not ambient

Pointer repointed, 2026-09-27. This record was written extending ADR 0127 (superseded by ADR 0131), which ADR 0131 has since superseded — AMQP is not a provision at all. Nothing decided here changes; the frontmatter now rests on the live record, and the citations below are read with that in mind.

Context

Design 29 opened by saying the bus is ambient: "No module requires it, the way no module requires a filesystem. Every module gets a connection and an identity whether it asks or not."

Two counts say that is wrong. Of the 72 modules in the catalogue, 49 declare an own-secret named broker and 23 do not. So the bus is not universal — nearly a third of the catalogue never speaks to it — and an ambient connection would mint an account, a password and a permission set for every one of those 23, each a credential nothing uses and everything must rotate.

And the 49 that do take one each hand-write the path it lands at (own-secrets: { broker: "/var/lib/<module>/broker" }). That is a special case doing badly what provisioning already does well: a consumer names where a credential lands, the mesh seals it there, and rotation and removal follow the same path as every other credential.

The argument that made the bus ambient was narrower than it looked. ADR 0125 reasoned that bus accounts cannot be provisioned because a provisioner is itself a module that needs an account before it can run. That is true of a provisioner process, and it is not true of a provision: the mesh's bus accounts are composed by the controller, into configuration, and the controller is not waiting on a bus account to exist. The circularity is real for one mechanism and absent for the other, and the earlier record applied it to both.

Considered Options

Keep the bus ambient. Rejected on the counts above: it over-grants to 23 modules and keeps a hand-written path in 49.
Derive the requirement from whether a module declares any emits, consumes, serves or uses. Rejected: it is the ambient model with extra inference. A reader of a manifest still cannot see that the module holds a bus credential, and the rule would have to be re-derived every time the set of bus-facing declarations grew.
The mesh bus is a provision a module requires, delivered by the seat that holds it. Adopted.

Decision

A module that speaks to the mesh requires mesh-bus, and receives what it needs to connect. The contract is an address, a credential sealed to the module, and the trust to verify the server. It lands where the module's manifest says, like any provision. A module that does not require it gets no account, no password and no permissions — and 23 modules in the catalogue should get none.

The mesh-broker seat delivers mesh-bus. Its holder is the mesh's own bus, and what holding it delivers is the connection to that bus — which is what a seat delivering a provision has always meant (design 26).

The requirement delivers the connection; the declarations shape the authority. They are two different things and both stay explicit. requires: mesh-bus says this module talks to the mesh; emits, consumes, serves, uses and a declared seat say what it may say and hear, and the permission set is derived from those and nothing else (ADR 0043). Requiring the bus grants no subject; declaring a subject without requiring the bus is refused at registration as incoherent.

The mesh-bus provision is answered by the controller, not by a provisioner. This is the surviving kernel of ADR 0125's bootstrap argument, narrowed to what it actually supports: the bus's accounts are configuration the controller composes and the server reloads (ADR 0106 — never through a management API), so there is no provisioner process in the path and nothing waiting on a bus account to create bus accounts. It is a provision whose provider is the mesh itself.

A module may also provide a NATS server of its own, and that is a different interface. Exactly as the AMQP broker provides amqp (ADR 0127 (superseded by ADR 0131)), a module may run its own NATS and offer it as a backing service. That interface is nats; the mesh's own bus is mesh-bus; the two are never the same name, because a manifest that said nats could mean either and the difference is the whole architecture. The rule from 0119 decides which is legitimate: a private bus is a backing service, never a channel to another module.

Consequences

Design 29's opening is reversed. The bus is not ambient; it is required, and the document's first paragraph says the opposite of this.
The seat's Delivers is mesh-bus — corrected twice in one day, which is worth recording rather than tidying: it read amqp, which was the old broker's interface; ADR 0125 emptied it, on the reasoning that a bus cannot be provisioned; and it is neither. The seat delivers the mesh's bus.
own-secrets: { broker: ... } is retired in favour of the provision's own delivery, across 49 manifests. That is a mechanical change, and it belongs with the conversions in step 4 rather than step 1.
23 modules lose a credential they never used. Not a regression — an over-grant removed, and the smallest honest statement of what this buys.
What got harder: one more line in most manifests. The trade is that the line is true, and its absence is also true.

How it is checked

A module with no requires: mesh-bus has no account. A composition test: the derived user list contains exactly the modules that require it, and the 23 that do not appear nowhere in it.
Declaring a subject without requiring the bus is refused. A registration test on a manifest with emits and no requirement, naming the contradiction.
Requiring the bus grants no subject on its own. A composition test: a module that requires mesh-bus and declares nothing else gets a connection and an empty permission set.
nats and mesh-bus are distinct interfaces. A resolution test: a module requiring nats is answered by a module providing it, never by the seat holder, and vice versa.

References

ADR 0125 — superseded by 0119; its bootstrap argument is narrowed here to the case it supports.
ADR 0127 (superseded by ADR 0131) — a broker as a backing service; this applies the same shape to the mesh's own bus and separates the two names.
ADR 0043 — authority from declarations, which this leaves untouched.
design 26 — a seat delivering a provision.

7.4 KiB Raw Blame History