hq/03-DESIGN/01-to-be/29-what-a-module-declares.md

layer, status, code, updated, decisions

layer	status	code	updated	decisions
to-be	proposed		2026-09-26	02-DECISIONS/0118-a-module-declares-its-own-seats.md 02-DECISIONS/0117-the-bus-is-the-only-broker.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 02-DECISIONS/0083-one-push-leaves-the-mesh-consistent.md

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.

This document is the declaration model. Design 25 is the bus itself — subjects, streams, accounts, enrolment — and stays the authority on the wire. Design 19 is the specification an SDK implements, and is rewritten onto this in step 3 of ADR 0116.

1. A module names locally; the mesh derives the subject

This is the load-bearing rule. ADR 0112 says a module definition names no node, mesh or path. A transport address is the same class of thing: if manifests held literal subjects, reorganising the subject space would mean editing every module in the catalogue, and the mesh would have hundreds of copies of a decision it made once.

declared	derived
emits: order.placed	publish on mesh.mod.<module>.event.order.placed
consumes: billing.order.placed	durable consumer on mesh.mod.billing.event.order.placed
serves: status	queue-group subscription on mesh.mod.<module>.tool.status
seat telegram-sender, accepts: send	work-queue consumer on mesh.seat.telegram-sender.accept.send
uses: telegram-sender	publish on that seat's accept subjects, and nothing else

The event / tool / accept token is load-bearing, not decoration. Revision, found while defining the streams: a stream is defined by a subject filter, so a namespace holding both a module's events and its tool calls cannot be filtered into an events stream without capturing every tool invocation in the mesh — and a tool call must never be persisted (design 25 §3 keeps tools on core NATS, where a lost call is a timeout the caller already handles). The kind token is what makes mesh.mod.*.event.> a safe filter. The first draft of this table had no token, which reads better and cannot be implemented.

The test this must pass: the manifest survives the wire changing. Reorganise the subject space and every manifest in the catalogue is still correct. That is the property ADR 0039 gave the sdk, applied to declarations.

2. Three namespaces, and nothing else

Its own — mesh.mod.<module>.>. Its events and its tools. Nothing else may publish into it, so an event's source is a fact the bus enforces rather than a claim in the body.

Seats it holds — mesh.seat.<seat>.>. Full participation: consume what the seat accepts, publish what it emits, serve what it serves.

Seats it uses — publish only, and only on the accepts half. A sender cannot subscribe to a seat's inbound subject and watch other modules' traffic, and cannot publish the seat's outbound events and lie about outcomes.

A module naming anything outside these three is refused at registration. The whole permission set is derivable from the declaration; nobody writes an access rule.

3. Queues are derived, never declared

A module says what it reacts to, not how delivery works. Each consumes becomes one durable consumer; a seat's accepts becomes one work-queue consumer with a queue group named for the seat. The module does not name them, does not know their names, and cannot misconfigure them — and the controller stays the only writer of stream and consumer definitions (design 25 §3).

Retention belongs to whoever owns the namespace, not to a consumer. A seat declares how long its inbound backlog survives, because that is a property of the service:

seat: telegram-sender
  scope: mesh
  accepts: send        retain 7d
  emits:   delivered, failed
  serves:  status

If each consumer could tune it, the mesh's durability would be an emergent property of whichever manifest was edited last.

Scope gives per-node workers without a new concept. A module running on three nodes that each need their own queue declares a node-scoped seat: one holder per node, three queues, same machinery. Mesh-scoped and node-scoped seats already exist; here they do the work of "one shared service" versus "one worker per machine".

4. Five relationships

	provision	event	job	state	tool
shape	1:1 resource	1:many	N:1	1:1	1:1
addressed to	a provider	the emitter's own namespace	a seat	one node	a module or seat
who must act	the provider	nobody	exactly one holder	that node	the server
credential	sealed, per consumer	none	none	none	none
reply	—	none	none, or an event later	a report	awaited
retention	—	age and size	work queue, explicit ack	last per subject	none
declared	provides/requires	emits/consumes	seat accepts / uses	the mesh's own	serves

Job is the one ADR 0041 had no room for. Its table has events at 1:many and provisions at 1:1; a module submitting work to a service is neither. It is not an event, because an event is a broadcast nobody is obliged to act on and a second holder would do the work twice. It is not a provision, because there is no resource and no credential. What makes it safe is not cleverness in the subscribe call but the seat: exactly one holder, so exactly one worker, by construction.

State is the shape the deploy path needs and nothing else uses. A declaration is not an event — replaying yesterday's is actively harmful — and not a job. Only the newest matters, which is last-per-subject retention, and a node that has seen sequence n refuses n−1 by construction. That is the wire-level answer to issue 107.

5. Seats

A module declares a seat with its protocol, and the mesh enforces one holder at its scope (ADR 0118). A caller declares that it uses the seat, never the module, so the implementation can be replaced under it.

• The set of seats is derived — the mesh's own, plus every registered module's — so it is both closed and extensible, and enumerating it is a query rather than an inventory.
• mesh-* is reserved: the prefix is the reservation rule, and a module declaring one is refused at registration.
• Two modules declaring the same name: the second is refused.
• A module may not claim a seat whose protocol it does not implement.
• Nobody holding a seat is not an error. The stream exists from registration, so work queues until a holder appears. Install the telegram module a week later and the backlog flushes.

6. The lifecycle: build, publish, deploy

Every shape above appears once, in order, and no step knows where the next one runs.

A change lands. The module holding mesh-git emits pushed — repository, ref, commit. An event, because it is a fact about git and git's identity is the meaning.

The change becomes work. The controller consumes pushed, asks the catalogue which modules are built from that repository and path (ADR 0069), and submits one job per affected module to the mesh-build-machine seat. The builder stays simple: it builds what it is handed, and never resolves anything. A builder that dies mid-build has its job redelivered, because a work queue with explicit ack is what that means.

The artifact is published. The builder pushes to the registry seats and emits built — module, version, digest. An event again: a fact about the builder.

The build cascade is that event fanning out through a graph the mesh already has. A module whose image is built on another's artifact declares that in build.on. So built reaches the controller, which walks the declared graph and submits rebuild jobs for everything downstream. A dependency cascade is not special machinery — it is one event, one derived graph, and the same job queue.

Deployment is state, not a message. The controller composes each affected node's declaration and publishes it last-per-subject. A node that was away gets exactly the current one, never a queue of superseded ones, and a replayed older one is refused by sequence.

Applying is reported to a role. The host applies and reports to the mesh-controller seat — not to an address it was given at genesis. Held and retried while the store restarts (ADR 0083).

What disappears across that chain is every address. No webhook URL, no registered callback, no "which node is the builder on", no controller endpoint baked into a joining node. That is the class of bug issue 102 names, dissolved rather than fixed.

7. Modules depending on each other

Three kinds, and conflating them is how deployment ordering goes wrong.

Build-time — A's image is built on B's artifact. Resolved by the cascade above; nothing at runtime cares.

Provision — A requires a database from B. A hard dependency: the credential must exist before A can start, so resolution gates delivery and A is shown as waiting until B has answered (design 27).

Seat — A uses B's seat. A soft dependency, and this is the one the bus changes. A starts whether or not anyone holds the seat, because the stream absorbs the gap. Deployment order stops mattering for everything expressed this way, and a service being restarted, moved or upgraded is not an outage for its callers — it is latency.

That difference is worth choosing on purpose. A dependency expressed as a provision must be ordered; the same dependency expressed as a seat need not be.

8. Versioning a protocol

A seat's protocol is a compatibility surface between modules that do not know each other and are deployed at different times. Four ways it can change, and they are not equally dangerous:

change	example	detectable
additive	a new accepts subject, a new optional field	nothing breaks
removal or rename	send becomes deliver	yes, mechanically
shape	an optional field becomes required	yes, if shapes are specified
semantic	send starts meaning queue for tomorrow	no

Additive is free. A seat may grow without a version, without re-registering a caller, and without ceremony. Most change is this.

A breaking change is refused while anyone is bound. Registration computes a compatibility fingerprint over the seat's protocol — its subjects and the shapes they carry. A registration that alters the fingerprint while callers are bound is refused, and the refusal names them. The mesh already holds the uses graph, so this is derived rather than declared, and it turns a runtime breakage into a registration-time conversation.

When a break is genuinely needed, the version goes in the subject, not the name. The seat stays one thing; mesh.seat.<seat>.v2.<verb> runs beside v1 and the holder serves both. A caller moves when it is ready. Versioning the seat name was considered and rejected: it forks the role, so "one holder" stops meaning one provider of the capability, and every document naming the seat has to be found and changed.

Binding is recorded, not inferred. A caller declares uses: telegram-sender with no version, and resolution binds it to the current one and records that — the same pin machinery design 27 already uses when resolution had a choice to make. Moving to v2 is a deliberate re-pin, so nothing drifts onto a new protocol because it happened to be newest.

Retirement is reported, never automatic. When the uses graph shows nothing bound to v1, the overview says it is retirable. The mesh does not remove it.

And none of this catches a semantic change. Same subject, same shape, new meaning: no fingerprint sees it, and no check proposed here would. The defences are review, and pushing meaning into shape wherever it can go — a required channel field is caught, a changed interpretation of an existing one is not. Saying so is better than implying the fingerprint is complete, because a team that believes it is complete stops reviewing for the case it misses.

9. Provisioning over the bus

Provisioning rides the bus, and the provider stops having an address.

part of a provision	shape
the requirement resolving to a provider	the controller's, not the bus's
the grant reaching the provisioner	request/reply to a role
holds — the reconcile question, every minute	the same call, on a timer
provisioned / deprovisioned	events
the credential reaching the consumer	§10 — fetched, never carried

A provisioner's interface is already three calls — create, remove, holds — which is exactly a serves protocol. So a provision interface is a seat whose protocol is those three, which is why design 26 already allows a seat to deliver a provision. The two concepts were converging before this document; here they meet.

What stays different, and must not be unified away: a provision has a per-consumer resource and 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.

Where addresses survive

"Where is it?" is two different problems, and the bus solves one of them completely and the other not at all. Keeping them apart matters, because a reader who thinks the mesh no longer has addresses will believe a class of bug is fixed when it is untouched.

Something that is on the bus: the address disappears. A host reporting in used to need the controller's address — recorded somewhere, at some moment, and wrong as soon as anything moved. Now it publishes to mesh.seat.mesh-controller.report and the bus routes it to whoever holds the seat. Nothing anywhere records where the controller is, so nothing can record it wrongly. The same is true of the builder, the catalogue, the telegram sender. This class is not mitigated; it is gone, because the information is no longer stored.

Something that is not on the bus: the address stays, exactly as before. A module that requires a database does not reach postgres over NATS — it opens a postgres connection, because postgres speaks postgres and is not listening on any subject. Its credential contains a host and a port, and no amount of subject addressing changes that.

So the fix for that second class is unchanged and is not this document's: ADR 0098 — fetch the fact where it is used rather than storing a copy — which is what issue 102 is actually about. The bus makes that class smaller by removing every mesh-internal address from it. It does not make it empty.

And one address is irreducible: the bus's own. A node has to know where the broker is before it can use subjects for anything, so that one cannot be a subject. It is the addressing equivalent of §10's bootstrap — the first thing cannot be found by the mechanism that finds everything else.

10. Secrets, and why they never enter a stream

Everything the vault does is request/reply to the mesh-vault role: mint, fetch, rotate. In that sense it is as much on the bus as anything else.

The bus is not trusted with a secret, and does not need to be. A secret is sealed to its recipient, so what crosses the bus is ciphertext only that recipient can open. The broker sees that a secret moved, and to whom — metadata, which is acceptable — and never a plaintext.

But sealed is not enough on its own, because a stream persists. A sealed secret written into a JetStream stream is a durable ciphertext sitting in the mesh's own storage, and the day a sealing key leaks, that stream is an archive rather than a moment. So:

• A secret travels on core request/reply, never through a stream. No persistence, no replay, nothing to exfiltrate later.
• A declaration names a secret; it does not carry one. Declarations are the state shape, which is a stream — so the host fetches the secret from the vault at apply time, over the core path. That is ADR 0098's existing discipline — fetched from it, not carried — applied to the one payload where carrying it is worst.

The bootstrap, which is circular and has a precedent. The vault makes every secret (ADR 0113), including the bus's own passwords. The vault is a module, and a module needs a bus account, whose password the vault makes. Nothing can go first.

This is the shape ADR 0067 already resolves for the control plane: genesis is a pivot. The controller mints the handful of foundation credentials itself, raises the store, the broker and the vault, and then the vault takes over and mints everything from there — the same move as raising a temporary control plane and reinstalling it as an ordinary module once the registry exists.

So there are exactly two things the normal path cannot make, both at genesis, both ending the moment the mesh can mint for itself: the bus's own accounts (§the bootstrap argument in ADR 0117 — a provisioner is a module and needs an account before it can run) and the vault's own credential. Any third exception is a design failure, and naming these two is what makes a third one visible.

11. Open

Semantic change has no mechanical defence (§8). Recorded as open rather than solved, because it is the residue of a question the rest of §8 answers and the part a fingerprint cannot reach.

Whether a module may declare a seat it does not itself claim — the contract as one thing, the implementation as another, which is how two competing implementations would ever exist.

Whether consumes naming another module couples too tightly. It is kept here deliberately — an event's provenance is its meaning — but a consumer of billing.order.placed does depend on billing existing under that name.

12. How it is checked

• A manifest holds no subject. A catalogue test: no manifest contains a string matching the subject grammar. The rule is worthless if it is followed by convention.
• Permissions are exactly the three namespaces. A composition test per module: the derived permission set equals what its declaration implies, and a hand-written addition to it fails.
• A sender cannot read the queue it writes to. A bed: a module declaring uses is refused subscribe on that seat's inbound subject.
• One holder, one delivery. A bed: a seat's job delivered once with the holder running, and a second claim of the seat refused.
• A queued job survives no holder. A bed: submit with the seat unheld, assign the holder, the job is delivered.
• The cascade rebuilds exactly the dependents. A bed: publish an artifact two modules build on, and exactly those two are rebuilt.
• A stale declaration is refused. A bed: replay sequence n−1 after n, and the node refuses it rather than applying it.