---
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. |