The mesh bus is required, not ambient

Design 29 said no module requires the bus. The catalogue disagrees: 49 of
72 modules take a broker credential and 23 do not, so an ambient connection
mints an account for a third of the catalogue that never speaks — and the
49 each hand-write the path it lands at, which is provisioning done badly
by hand.

The bootstrap argument that made it ambient was narrower than it looked.
"A provisioner needs an account before it can run" is true of a provisioner
process and says nothing about a provision the controller answers, and the
controller is not waiting on a bus account to compose one.

So: the mesh-broker seat delivers mesh-bus; a module requires it and gets an
address, a sealed credential and the trust to verify the server; a module
that requires nothing has no account at all. The requirement delivers the
connection, the declarations shape the authority, and declaring a subject
without requiring the bus is refused as incoherent.

mesh-bus and nats are deliberately two names: a module may run its own NATS
as a backing service exactly as one provides amqp, and a manifest saying
"nats" would otherwise mean either the mesh's nervous system or a private
queue.

The seat's Delivers was wrong twice today — amqp, then empty — and the
comment says so rather than reading as though it were always right.
This commit is contained in:
2026-09-26 21:17:21 +02:00
parent 85f972749a
commit 86a084b7ff
4 changed files with 150 additions and 5 deletions
+2 -1
View File
@@ -11,6 +11,7 @@ code:
updated: 2026-09-26
decisions:
- 02-DECISIONS/0118-a-module-declares-its-own-seats.md
- 02-DECISIONS/0120-the-mesh-bus-is-required-not-ambient.md
- 02-DECISIONS/0111-a-build-source-is-on-the-git-seat-or-external.md
- 02-DECISIONS/0109-a-package-registry-seat-is-one-per-ecosystem.md
---
@@ -64,7 +65,7 @@ convention, which later seats departed from.
|---|---|---|---|
| `mesh-controller` | — | mesh | — | the controller |
| `mesh-store` | — | mesh | — | the store the mesh's own records live in |
| `mesh-broker` | — | mesh | — | the broker carrying the mesh's own bus |
| `mesh-broker` | — | mesh | `mesh-bus` | the broker carrying the mesh's own bus |
| `mesh-vault` | — | mesh | `secret`, reserved | the vault |
| `mesh-artifact-store` | `the-artifact-store` | mesh | `artifact-store` | the artifact registry |
| `mesh-catalog` | `the-catalogue` | mesh | — | the catalogue |
@@ -6,6 +6,7 @@ updated: 2026-09-26
decisions:
- 02-DECISIONS/0118-a-module-declares-its-own-seats.md
- 02-DECISIONS/0119-amqp-is-a-provision-not-the-bus.md
- 02-DECISIONS/0120-the-mesh-bus-is-required-not-ambient.md
- 02-DECISIONS/0106-the-bus-is-nats.md
- 02-DECISIONS/0041-events-are-a-relationship.md
- 02-DECISIONS/0112-a-module-definition-names-no-node-mesh-or-path.md
@@ -14,10 +15,22 @@ decisions:
# 29. What a module declares, and what the bus makes of it
**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. What a module declares are
*relationships*; subjects, streams, consumers and permissions are all derived from those, and a
manifest never contains one.
**A module that speaks to the mesh requires the bus, and receives what it needs to connect**
([ADR 0120](../../02-DECISIONS/0120-the-mesh-bus-is-required-not-ambient.md)). What a module
declares are *relationships*; subjects, streams, consumers and permissions are all derived from
those, and a manifest never contains one.
> **Revised 2026-09-26.** This document opened by calling the bus *ambient* — "no module requires
> it, the way no module requires a filesystem". Two counts say otherwise: of 72 modules in the
> catalogue, **49 take a broker credential and 23 do not**, so an ambient connection would mint an
> account for a third of the catalogue that never speaks; and the 49 each hand-write the path it
> lands at, which is provisioning done badly by hand. The bus is required, and a module that does
> not require it has no account at all.
**The requirement delivers the connection; the declarations shape the authority.** `requires:
mesh-bus` says *this module talks to the mesh* and grants no subject by itself. `emits`,
`consumes`, `serves`, `uses` and a declared seat say what it may say and hear. Declaring a subject
without requiring the bus is incoherent and refused at registration.
This document is the declaration model. [Design 25](25-the-bus-on-nats.md) is the bus itself —
subjects, streams, accounts, enrolment — and stays the authority on the wire.
@@ -254,6 +267,20 @@ What stays different, and must not be unified away: a provision has a **per-cons
a sealed credential**, created and destroyed per consumer. A seat protocol has neither — it is a
role you send to. Collapsing them would mean pretending a database is a subject.
### `mesh-bus` and `nats` are two interfaces, never one name
The mesh's own bus is **`mesh-bus`**, delivered by the `mesh-broker` seat and answered by the
controller — because the bus's accounts are configuration rather than something a provisioner
creates, so there is no provisioner process in the path and nothing waiting on a bus account in
order to make bus accounts. A module that runs a NATS server of its own and offers it as a
backing service provides **`nats`**, exactly as the AMQP broker provides `amqp`
([ADR 0119](../../02-DECISIONS/0119-amqp-is-a-provision-not-the-bus.md)).
They are never the same name. A manifest saying `nats` could otherwise mean either the mesh's
nervous system or a private queue, and the difference between those is the whole architecture.
0119's rule decides which is legitimate: a private bus is a backing service, never a channel to
another module.
### Where addresses survive
"Where is it?" is two different problems, and the bus solves one of them completely and the other