jschoubben
1111bd84d7
Settles the design repository now that the self-upgrade build is on main: - Records the two decisions that shipped without a record — ADR 0077 (the controller/foundation/node vocabulary) and ADR 0078 (the store and broker are ordinary modules); accepts ADR 0075 and 0076, which shipped work rests on. - Fills issue 051's amended-design and wires ADR 0078 into 07-the-foundation. - Sweeps the repo rename (mesh-control -> mesh-controller) into the mutable docs now that the forge repo is renamed; updates the glossary note and repos.md. - Fixes the six broken links from the design-doc renames, indexes the glossary, regenerates the decisions reading order. Both checks (records.py, index.py) are green. Statuses stay honest: the build is on main and lab-proven but not deployed as the production mesh, so the to-be docs remain in-progress and the as-is layer (the hal mesh) is unchanged — graduation to implemented + as-is belongs to deployment, not merge. https://claude.ai/code/session_01D6qtiYU3P9jk3pnAXyAFyx
187 lines
8.2 KiB
Markdown
187 lines
8.2 KiB
Markdown
---
|
|
layer: to-be
|
|
status: proposed
|
|
code:
|
|
- mesh-sdk src
|
|
- mesh-tools src/broker-amqp.ts
|
|
- mesh-controller internal/link
|
|
updated: 2026-09-15
|
|
decisions:
|
|
- 02-DECISIONS/0074-the-wire-is-specified-not-the-types.md
|
|
- 02-DECISIONS/0039-what-the-sdk-holds-and-refuses.md
|
|
- 02-DECISIONS/0043-a-module-broker-account-is-scoped-by-emits-and-consumes.md
|
|
- 02-DECISIONS/0042-the-shape-of-an-event-on-the-wire.md
|
|
---
|
|
|
|
# The module protocol
|
|
|
|
**What a module's code and the mesh say to each other.** An SDK is an implementation of this in one
|
|
language and nothing more ([ADR 0074](../../02-DECISIONS/0074-the-wire-is-specified-not-the-types.md)).
|
|
|
|
This is a specification, so it says what is required rather than how anything is arranged. Where it
|
|
describes current behaviour that is *not yet* specified-and-conformed, it says so.
|
|
|
|
## The shape of it
|
|
|
|
A **floor** every implementation needs, and three **capabilities** that are independent of each
|
|
other. An SDK implements the floor plus whatever capabilities it claims; a module is refused at
|
|
build time if it uses a capability its language's SDK does not implement.
|
|
|
|
| part | a module uses it to |
|
|
|---|---|
|
|
| **connection** | reach the broker as itself |
|
|
| **events** | emit, and react to what others emit |
|
|
| **tools** | answer questions asked of it |
|
|
| **provisioning** | give a consumer an instance of what it provides |
|
|
|
|
---
|
|
|
|
## The floor: connection
|
|
|
|
### The credential
|
|
|
|
A module is given a **sealed credential** as a file, and told where by its declaration. The
|
|
document:
|
|
|
|
| field | is | required |
|
|
|---|---|---|
|
|
| `url` | an `amqps://` URL carrying the account's user and password | yes |
|
|
| `fingerprint` | sha256 of the certificate the broker must present | yes for a scoped account |
|
|
| `node` | the machine this account was issued for | yes for a scoped account |
|
|
| `module` | the module this account was issued for | yes for a scoped account |
|
|
|
|
A plain string rather than a document is a **bootstrap URL** — unscoped, for the moment before a
|
|
mesh can issue anything. An implementation accepts both and must not treat the second as ordinary.
|
|
|
|
### Connecting
|
|
|
|
- The connection **pins the fingerprint**. It does not trust a certificate authority, and it does
|
|
not skip verification. A broker presenting a different certificate is refused, whatever else is
|
|
true of it.
|
|
- A scoped account **does not declare exchanges**. The foundation owns them; an account that may
|
|
declare one is an account that may create a parallel mesh by typo.
|
|
- An implementation **declares its own queue** and nothing else.
|
|
|
|
### Identity
|
|
|
|
**A module's node and module name come from its credential, never from its environment.**
|
|
|
|
This is not a convenience. It is what makes what a module emits match what the mesh authorised: an
|
|
environment variable can be set by anything on the machine, and a module that took its identity
|
|
from one could emit events attributing them to another module. Where an environment variable and
|
|
the credential disagree, the credential wins and the variable is overwritten.
|
|
|
|
---
|
|
|
|
## Capability: events
|
|
|
|
### The exchanges
|
|
|
|
| exchange | carries |
|
|
|---|---|
|
|
| `mesh.events` | every event |
|
|
| `mesh.events.dead` | what could not be handled |
|
|
|
|
### The queue
|
|
|
|
One **durable** queue per consumer, named `<node>.<module>.events`, with as many bindings as the
|
|
module has patterns. Durable because an event emitted while a module is restarting is exactly the
|
|
one that must not be lost.
|
|
|
|
**A message matching two bindings is delivered once**, so an implementation must match the routing
|
|
key against its own patterns locally to decide which handlers run. An implementation that ran every
|
|
handler whose exchange binding matched would run the wrong one.
|
|
|
|
### The envelope
|
|
|
|
Headers ride as AMQP headers. The body is JSON.
|
|
|
|
| header | is | required |
|
|
|---|---|---|
|
|
| `x-event-id` | a unique id, made by the emitter | yes |
|
|
| `x-source` | the module, context or node that emitted it | yes |
|
|
| `x-node` | the machine it was emitted from | yes |
|
|
| `x-time` | emit time, RFC-3339 | yes |
|
|
| `content-type` | always `application/json` | yes |
|
|
| `x-causation-id` | the event or command that caused this one | no |
|
|
| `x-schema` | a version of the body's shape | no |
|
|
|
|
**An unknown `x-` header is ignored, never refused.** An event is observed by parties that need not
|
|
all understand every header, and an implementation that refused one would make adding a header a
|
|
breaking change for everybody.
|
|
|
|
### Delivery
|
|
|
|
At-least-once. **Deduplication is on `x-event-id`**, which only the emitter can produce — a
|
|
consumer cannot tell a redelivery from a second event any other way.
|
|
|
|
### What is true, checked (2026-09-16)
|
|
|
|
Go emits all five required headers; the SDK requires exactly those. `x-causation-id` and `x-schema`
|
|
are **optional** — the SDK sets them when a handler has a causation or a schema, and reads them
|
|
back; a bare event carrying neither is correct. So the envelope agrees across the two
|
|
implementations. `x-schema` is available for versioning a body's shape and is set by whoever has a
|
|
version to declare.
|
|
|
|
---
|
|
|
|
## Capability: tools
|
|
|
|
A module's tools are its operator-facing surface.
|
|
|
|
- A tool is served from a **shared durable queue**, `serve.<key>`. Shared, so several runtimes
|
|
serving one tool compete for a call rather than each answering it.
|
|
- A call is request and reply. The reply returns through the RPC exchange `mesh.rpc`, keyed by the
|
|
caller's own reply queue — **not** through the default exchange, which would let a caller publish
|
|
into any queue on the broker.
|
|
- A caller needs a **reply queue**, and that is what a module's scoped account may not declare
|
|
([issue 049](../../04-ISSUES/049-a-module-can-serve-tools-and-nothing-can-call-them/00-report.md)).
|
|
So a module may serve tools and may not call them, and nothing today issues an account to anything
|
|
that wants to ask.
|
|
|
|
### Not yet true
|
|
|
|
The caller's half has no account. Until that is settled, the only thing that can ask a module a
|
|
question is the foundation's bootstrap admin, which is not a protocol so much as a way in.
|
|
|
|
---
|
|
|
|
## Capability: provisioning
|
|
|
|
A provider ships the provisioner that creates instances of what it offers
|
|
([ADR 0040](../../02-DECISIONS/0040-what-a-module-is.md)).
|
|
|
|
| direction | carries |
|
|
|---|---|
|
|
| **grant, in** | the provision, who is asking — **a module on a machine**, not a machine — and what the consumer contributed |
|
|
| **credential, out** | the fields the provision promises a consumer |
|
|
|
|
**Who is asking is one thing with two parts.** A machine routinely runs several modules wanting the
|
|
same provision, so a grant addressed to a node alone does not name a consumer, and withdrawing one
|
|
would take another's away.
|
|
|
|
### Checked, and it agrees (2026-09-16)
|
|
|
|
This looked like the sharpest disagreement and was not one. The live wire is the contributions file
|
|
— `as`, `secret`, `node`, `at`, `values` — and it is the same on both sides. The types that
|
|
disagreed (`Grant`, `Interface` in the SDK's `contracts`) were dead: exported, imported by nothing,
|
|
describing fields the wire does not carry. They have been removed. The lesson kept: a type beside
|
|
the wire that has drifted from it is worse than none, which is why the wire is specified and
|
|
implementations are checked against it rather than trusted to still match a hand-kept shape.
|
|
|
|
---
|
|
|
|
## How an implementation is checked
|
|
|
|
Per capability, against fixtures rather than prose — a specification nobody can run is a document
|
|
two implementations drift from while both believe they conform.
|
|
|
|
| Rule | Checked by |
|
|
|---|---|
|
|
| The floor is the floor | Every implementation reads the same credential fixture, and refuses one whose fingerprint does not match what the broker presents. |
|
|
| Identity comes from the credential | A fixture sets an environment that disagrees with the credential; the emitted event carries the credential's. |
|
|
| The envelope is the envelope | An emitted event is compared header by header against a fixture; a missing required header fails, an unknown `x-` header is accepted. |
|
|
| Delivery is at-least-once | A fixture delivered twice is handled once. |
|
|
| A grant names a consumer | A grant fixture is read by every implementation and yields the same module and the same node. |
|
|
| A partial SDK is legitimate | An implementation claiming the floor and events passes those suites and is listed for them; a module using tools in that language is refused at build time with the reason. |
|