Merge pull request 'ADR 0132: a seat carries the tools its holder must serve' (#158) from decision/0132-a-seat-carries-the-tools-its-holder-must-serve into main

A role's tools belong to the role, not to whichever module holds it today: the seat declares them
with their schemas, serving them is a condition of occupying the seat, and what the mesh can do
becomes a read of its own records rather than a question nothing answers. A module keeps its own
tools — the same module may run without the seat, and then only its own name is true.

Design 33 follows: the three families, addressing a node-scoped seat, discovery, and what serves
this to an agent.

02-DECISIONS/0132-a-seat-carries-the-tools-its-holder-must-serve.md

@@ -0,0 +1,150 @@
+---
+topic: the mesh
+status: accepted
+date: 2026-09-28
+deciders: jochen
+reconstructed: false
+extends: 02-DECISIONS/0129-a-seat-carries-the-protocol-of-its-role.md
+---
+
+# 132. A seat carries the tools its holder must serve
+
+## Context
+
+[ADR 0129](0129-a-seat-carries-the-protocol-of-its-role.md) gave a seat the protocol of its role in
+three parts: the work it accepts, the events it emits, and the verbs it **serves** — request and
+reply, awaited. The bus already derives authority from all three: a holder subscribes
+`mesh.seat.<seat>.tool.<verb>`, and a module that uses the seat may publish it and nothing else.
+
+**The serving third has never been used.** The mesh defines 14 seats, 8 mesh-scoped and 6
+node-scoped. Exactly one carries a protocol at all — the build machine, which accepts `build` and
+emits `built`. Not one seat declares a single verb it serves. The mechanism is built, enforced, and
+empty.
+
+Meanwhile every tool on the mesh is addressed to a module. Of 72 modules in the catalogue, 45 serve
+tools, about 203 of them, each on `mesh.mod.<module>.tool.<name>`. So a caller binds to the module
+that happens to hold a role rather than to the role, and replacing that module breaks every caller —
+which is the thing seats exist to prevent everywhere else.
+
+**Nothing can say what tools exist.** Measured on 2026-09-28, with the bus carrying the whole mesh: a
+workstation client holding an operator credential connected, the bus accepted the account, and
+`mesh call gitea.gitea_list_repos` answered with real repositories. The same client's `mesh tools`
+found nothing, because it asks `mesh-catalog.catalog_tools` and no module serves that: the catalogue
+serves `catalog_modules`, `catalog_module`, `catalog_provides`, `catalog_dependents` and
+`catalog_stale`. An agent can therefore call any tool it already knows the name of and discover none.
+MCP's `tools/list` is that same question, so the MCP surface is a working transport over an empty
+catalogue.
+
+**And there is nowhere for a tool's definition to live.** A manifest has a `tools` field: 0 of the 45
+modules that serve tools fill it. That is not neglect, it is the arrangement failing — the field was
+the bus grant's source for what a module may subscribe, and because nothing filled it every module
+that served a tool was refused its own subscription on the new bus, live, until the grant was changed
+to the module's own namespace. Today a tool's name, description and argument schema exist only in the
+module's code.
+
+Two facts about the machinery matter for what follows. A seat's protocol is not in the store: the seat
+rows lack the ADR 0129 columns, so the protocol comes from compiled defaults and is merged in when a
+row is read. And `seatSubject` is flat — `mesh.seat.<seat>.<kind>.<verb>` with no node in it — so a
+node-scoped seat's tool call would reach every node's holder at once, and the holders' queue group
+would hand it to whichever answered first.
+
+## Decision
+
+**A seat's protocol carries its tools in full**: the verb, what it does, and the schema of its
+arguments and of its answer. The seat is the definition of the role's interface; the holder is an
+implementation of it.
+
+**Serving the seat's tools is a condition of holding the seat.** A module that does not serve every
+verb the seat declares may not occupy it. This is checked where the other conditions of holding are
+checked — registration and handover — and refused by naming the verbs that are missing.
+
+**A role's tools are addressed to the role.** `mesh.seat.<seat>.tool.<verb>` mesh-wide. A node-scoped
+seat carries the node in the address, because one subject reaching six machines' holders is not an
+address, and the queue group that made it look like one would silently pick a winner.
+
+**A module keeps its own tools, and both exist.** `gitea_list_repos` stays, because gitea can run
+without holding the `git` seat — a second forge, an instance kept for one purpose. The module's name
+answers *this gitea*; the seat's verb answers *whoever is the forge*. Which of the two a caller wants
+is a decision in the running session, not one the mesh makes for it.
+
+**What answers "what tools exist" follows where the definition lives.** A seat's tools are read from
+the mesh's own records. A module's own tools are answered by the module, from the code that defines
+them. Discovery is therefore a read for the durable half and a question to the running mesh for the
+free half.
+
+**A seat's tools are an interface, and change like one.** Additive within a version; a change that
+would break a caller takes the version token the subject already has room for (design 29 §8), and the
+two run side by side until nothing is bound to the old one.
+
+**The mesh's own verbs are the `mesh-controller` seat's tools.** `status`, `push`, `build`, `assign`
+and the rest are a role's interface, not a container's, and the audit point [ADR 0095](0095-the-control-plane-is-the-way-to-ask-a-module.md)
+asks for is the seat's holder.
+
+## Options considered
+
+1. **The manifest declares each module's tools.** Rejected. The list is then written twice — in the
+   manifest and in the code — and a schema in a manifest goes stale silently, which is the worst kind
+   of wrong for something an agent reads to decide what to call. It is also the arrangement that has
+   already failed once: the field exists, 0 of 45 modules fill it, and the grant that depended on it
+   refused every tool subscription on the mesh.
+2. **Every runtime answers an introspection call, and something aggregates them.** Rejected as the
+   shape for a role's tools, kept for a module's own. An aggregator needs permission to publish into
+   every module's namespace, which is a widening the mesh otherwise gives only to the control plane;
+   and the answer is only as available as the modules are, so a mesh whose catalogue cannot say what a
+   role answers while its holder is down cannot plan against it.
+3. **The control plane answers everything.** Rejected. It puts a tool surface on the control plane for
+   tools it does not implement, and makes discovery depend on the one component that must stay
+   answerable while it is itself being replaced. The mesh's own verbs are its to answer, and it answers
+   them as the holder of a seat.
+4. **Seats only; no module tools.** Rejected. Most modules hold no seat, and inventing a seat per
+   module to give its tools a home would dilute what a seat is: one holder of a role the mesh needs
+   exactly one of.
+
+## Consequences
+
+**One capability can have two names, deliberately.** A forge that holds the `git` seat answers both
+`mesh.seat.git.tool.list_repos` and `mesh.mod.gitea.tool.gitea_list_repos`. This is the one place the
+mesh accepts two names for one thing, because they are answers to different questions and the second
+one survives the module not holding the seat. The glossary rule stands everywhere else.
+
+**A seat becomes a contract to implement.** Adding a verb to a seat is a change every holder must
+make, and a claim that was valid becomes invalid until it does. That is the point, and it is also the
+reason a seat's tools should be few and durable while a module's own stay free.
+
+**Three prerequisites, none of them in place.** The seat's protocol must be in the store rather than in
+compiled defaults, or discovery reads a binary rather than the mesh. The protocol must become richer
+than a list of verbs, because a verb without a schema is not something an agent can call. And a
+node-scoped seat needs the node in its subject before any of its tools can exist.
+
+**Discovery becomes cheap for the half that matters.** What roles the mesh has and what each answers is
+a query, with no fan-out and nothing to be up. An agent's authority can then be role-shaped — *the
+forge's tools* — rather than a list of module-specific names that changes when a module is replaced.
+
+**The MCP surface belongs inside the mesh.** Once the tools are the mesh's own records, the thing that
+serves them to an agent is a module the mesh assigns to the machine where the agent sits, with a
+credential the mesh minted and authority derived from what it may call — not a program started by hand
+with a credential printed to a terminal.
+
+## How this is checked
+
+- **Holding is refused without the verbs.** The condition sits with the other conditions of holding a
+  seat, so registration and a handover both refuse a module that does not serve what the seat declares,
+  and the refusal names the missing verbs. A test per condition, as the other seat conditions have.
+- **The grant is derived from the seat, and already is.** A holder's subscription and a user's publish
+  come from the seat's protocol, so a verb nobody declared is a subject nobody may use, and a verb the
+  seat declares reaches exactly its holder. The golden composition of the bus's user list is the test
+  that keeps it honest.
+- **Discovery is a read, and is tested as one.** What the mesh answers for a seat's tools equals what
+  the seat's records declare — no call to a module in the path, so the test needs no running module.
+- **A node-scoped seat's subject carries its node**, checked by the same test that checks the subject
+  table: two nodes holding one node-scoped seat derive two addresses.
+
+## References
+
+- [ADR 0129](0129-a-seat-carries-the-protocol-of-its-role.md) — the protocol this widens
+- [ADR 0121](0121-a-system-seat-is-named-for-its-scope-and-modules-define-their-own.md) — the role, its work and its events
+- [ADR 0095](0095-the-control-plane-is-the-way-to-ask-a-module.md) — a tool call passes one process where an audit belongs
+- [ADR 0126](0126-a-module-declares-its-own-seats.md) — an event is addressed to its emitter, for the same reason a role's verb is addressed to its role
+- [`03-DESIGN/01-to-be/26-the-seats.md`](../03-DESIGN/01-to-be/26-the-seats.md) — how a seat is held and handed over
+- mesh-controller #116, #117, #118 — the grants as they now stand: a module serves its own namespace, the control plane may ask any tool
+- Measured 2026-09-28 on the live mesh: an operator credential calling a module's tool over the bus answers; `tools/list` finds nothing

02-DECISIONS/README.md

@@ -140,6 +140,7 @@ python3 00-META/checks/index.py            fail if stale
 - **0129** — [A seat carries the protocol of its role](0129-a-seat-carries-the-protocol-of-its-role.md)
 - **0130** — [The predecessor is ending, and its broker goes with it](0130-the-predecessor-is-ending-and-its-broker-goes-with-it.md)
 - **0131** — [Everything on the mesh speaks to the broker seat, and AMQP is not a provision](0131-everything-on-the-mesh-speaks-to-the-broker-seat.md)
+- **0132** — [A seat carries the tools its holder must serve](0132-a-seat-carries-the-tools-its-holder-must-serve.md)
 
 ### Its tiers, from the bottom up
 

03-DESIGN/01-to-be/28-building-the-bus.md

@@ -5,7 +5,7 @@ code:
   - mesh-catalog modules/nats
   - mesh-controller internal/catalogue
   - mesh-lab scenarios
-updated: 2026-09-27
+updated: 2026-09-28
 decisions:
   - 02-DECISIONS/0116-the-bus-is-built-in-five-steps.md
   - 02-DECISIONS/0106-the-bus-is-nats.md
@@ -535,7 +535,7 @@ it, and the beds that need a mesh living on NATS can finally run.
       The outcome carries the module name, because only the manifest says what was built and one
       message now has three readers. A failed build names none: it produced no module version, and
       the catalogue would otherwise place something that was never made.
-- [~] 4.3 an installation completes over the bus, with the same outcome as the path it replaces —
+- [x] 4.3 an installation completes over the bus, with the same outcome as the path it replaces —
       **the installer can raise it**: a foundation template that stands up the server, writes the
       server's own settings and the mesh's first user list beside them, and starts a controller
       reaching the new bus. What remains is running it, which is 4.1's bed.
@@ -655,42 +655,35 @@ healthy while reacting to nothing.
 - [ ] 5.1 the cutover bed: a mesh on AMQP with a predecessor stand-in on the deprecated broker
       moves its bus in one rollout, every node reporting on NATS afterwards, the stand-in's own
       client still connected throughout
-- [~] 5.2 the rollout: accounts composed, then the controller, every host and every runtime
+- [x] 5.2 the rollout: accounts composed, then the controller, every host and every runtime
       together; every node confirmed heard before AMQP stops.
 
-      **The readiness half is in and is the half worth having.** The move takes every node at once, so
-      there is nothing to inspect afterwards and no half to roll back — either the mesh was ready or it
-      was not. `rollout check` answers that from records, with one dial: is a bus answering, does a
-      machine hold the seat, has it been sent the composed user list, does every machine and every
-      module that speaks have a credential. Each missing thing names its own next step, because "not
-      ready" that cannot be acted on is not an answer at the point where the next step is irreversible.
+      **Done 2026-09-28, 02:25.** Every machine reports on the new bus, the seat is held by the
+      module that provides it, the old broker is unassigned and forgotten, and every credential was
+      minted afresh at the end because two had been printed on the way. What it took, in the order
+      it was found, each fixed on the trunk before the next step: the control plane's `serve` and
+      `push` never selected the new transport (task 4.3, open until then); a machine's user was
+      granted neither the asking nor the delivery of its own consumer; the account had no JetStream
+      of its own; the control plane's client verified the bus's certificate by name instead of
+      pinning it; the seat table's rows carried no protocol, so no role's work queue was raised; the
+      build machine decided its bus from a variable its container never received; and a rotation
+      put new hashes on the bus before three machines had received their new memberships — which
+      is why there is now `rollout hand <node>` and a host adopts a delivered membership at start.
+      The bootstrap loop — a bus that can only be raised by a declaration that can only arrive
+      over that bus — was broken once, by hand: the mesh's own composed configuration started the
+      server, and the controller binary was run on the node directly until the managed container
+      could be rebuilt over the bus it was on.
 
-      **A machine with no credential is what must stop it.** It keeps running, cannot come back, and
-      afterwards there is no bus to tell it anything over.
-
-      The move itself is deliberately not written yet, and the command says so rather than pretending:
-      it waits on the check having been run against a real mesh. Writing the irreversible half before
-      the question it depends on has ever been asked of something real is how the plan's own rule about
-      beds gets broken by another route.
-
-      > **What this costs if it goes wrong, measured rather than assumed.** Nothing in a served
-      > request's path goes over the mesh's own bus: modules serve from their own containers. What a
-      > failed move costs is the mesh's ability to *change* anything — pushes, tool calls, new
-      > provisioning — until it is finished or undone. That is worth knowing before rather than
-      > after, and it is why the operator's "as long as my services keep running" is a reasonable
-      > position rather than a gamble. **Measured on 2026-09-27**, when a seat emptied itself
-      > mid-change: 52 containers stayed up and the broker never stopped; the control plane
-      > crash-looped for two hours and nothing could be deployed until it was repaired by hand.
-      > An earlier version of this note said the old broker stays as an ordinary provider of
-      > `amqp` ([ADR 0127](../../02-DECISIONS/0127-amqp-is-a-provision-not-the-bus.md)); that is withdrawn by [ADR 0131](../../02-DECISIONS/0131-everything-on-the-mesh-speaks-to-the-broker-seat.md) — see 5.4.
-- [ ] 5.3 **the seat changes hands as one act.** A command takes a seat and the assignment taking it
+- [x] 5.3 **the seat changes hands as one act.** A command takes a seat and the assignment taking it
       over, and the seat is never empty in between — the emptiness is the outage of 2026-09-27, when
       the control plane, which finds its own bus through this seat, lost the address and looped.
-      Today only `seat rename` exists. This is what 5.2 uses to move `mesh-broker` from the old
+      **Built 2026-09-27** (`seat_holding`, migration 0039; design 26 says how it is checked), and used
+      live the next night to hand `mesh-broker` from the old broker's assignment to the new one's. This
+      is what 5.2 uses to move `mesh-broker` from the old
       broker's assignment to the new one's, and it is built first ([ADR 0131](../../02-DECISIONS/0131-everything-on-the-mesh-speaks-to-the-broker-seat.md)).
-- [ ] 5.4 **the old broker and everything that named AMQP leave the mesh** ([ADR 0131](../../02-DECISIONS/0131-everything-on-the-mesh-speaks-to-the-broker-seat.md),
+- [x] 5.4 **the old broker and everything that named AMQP leave the mesh** ([ADR 0131](../../02-DECISIONS/0131-everything-on-the-mesh-speaks-to-the-broker-seat.md),
       superseding [ADR 0127](../../02-DECISIONS/0127-amqp-is-a-provision-not-the-bus.md)): the two modules that
-      required `amqp` are removed, the broker's module is unassigned and removed, registration refuses
+      required `amqp` are removed, the broker's module is unassigned and removed (**done 2026-09-28**; the predecessor's own tooling, which rode the same adopted broker, went dark with it, as [ADR 0130](../../02-DECISIONS/0130-the-predecessor-is-ending-and-its-broker-goes-with-it.md) accepted), registration refuses
       a manifest that provides or requires `amqp`, and a whole-catalogue check asserts none does. Not
       a retirement condition — a decision, taken, with the operator's "I don't care if the predecessor
       breaks" on record ([ADR 0130](../../02-DECISIONS/0130-the-predecessor-is-ending-and-its-broker-goes-with-it.md)).
@@ -701,8 +694,27 @@ healthy while reacting to nothing.
       > shutting it down ends the path that reaches this installation's machines from a workstation.
       > The rollout is driven from the node, or before the broker stops — a sequencing constraint on
       > 5.2, not an afterthought.
-- [ ] 5.5 **the AMQP transport is deleted from the control plane and the hosts**, and the variable
-      that selected a transport is refused at start as unknown. One bus, nothing to select ([ADR 0131](../../02-DECISIONS/0131-everything-on-the-mesh-speaks-to-the-broker-seat.md)).
+- [x] 5.5 **the AMQP transport is deleted from the control plane and the hosts**. One bus, nothing
+      to select ([ADR 0131](../../02-DECISIONS/0131-everything-on-the-mesh-speaks-to-the-broker-seat.md)).
+
+      **Done 2026-09-28.** The control plane's old consume loop, build request, tool call, management
+      API and account scoping went, and the host's old dialling and enrolment paths with them; a
+      membership or token naming any other bus is refused before anything is sent. Nothing selects a
+      transport any more: the variable that once did (`MESH_BUS_NATS`) now only names where the
+      control plane reads its own bus credential, the way any module reads a secret. **Checked by the
+      build**: neither repository's module file names the AMQP client library, so a line that still
+      used it would not compile. The store-window guarantee ([issue 083](../../04-ISSUES/083-other-control-messages-are-lost-while-the-store-restarts/00-report.md))
+      is tested against a bus-less fake rather than the old transport's memory, which is what let
+      that memory go — the one thing it did that the stream does not (superseding a held report) is
+      the staleness check on the message itself (design 25 §3).
+
+      Found on the way: **no build had ever recorded what it stood on.** A recipe reads its base from
+      a build argument, so the digest was never in the file the builder derived edges from, and every
+      order that says *bases first* — `build --on`, `build --behind`, the merge follow-up of
+      [issue 131](../../04-ISSUES/131-nothing-tells-the-mesh-a-source-moved/00-report.md) — walked a
+      graph with no edges. The builder now reports the bases it was handed, the control plane records
+      them by artifact path, and the graph is read from the newest build of each module — a recorded
+      manifest carries no `build.on`, so the edge is derived from the build or it does not exist.
 
 > **The old 5.4 note is history.** It recorded that a retirement *condition* was wrong from
 > [ADR 0127](../../02-DECISIONS/0127-amqp-is-a-provision-not-the-bus.md) onward, which framed the old broker

03-DESIGN/01-to-be/33-the-tools-the-mesh-answers.md

@@ -0,0 +1,137 @@
+---
+layer: to-be
+status: designed
+code: []
+updated: 2026-09-28
+decisions:
+  - 02-DECISIONS/0132-a-seat-carries-the-tools-its-holder-must-serve.md
+  - 02-DECISIONS/0129-a-seat-carries-the-protocol-of-its-role.md
+  - 02-DECISIONS/0095-the-control-plane-is-the-way-to-ask-a-module.md
+---
+
+# 33 — The tools the mesh answers
+
+**An agent can call the mesh's tools and cannot find out what they are.** Both halves were measured
+on the live mesh on 2026-09-28: a client holding an operator credential connected to the bus, asked a
+module for its repositories and got them; the same client's request for the tool list found nothing
+serving it. The transport works, the account model works, the adapter that speaks the agent protocol
+works. What is missing is the mesh being able to say what it can do.
+
+This design is the answer to that question, and it has three families in it, because a tool belongs to
+whoever is accountable for answering it.
+
+## 1. Three families, and why the split is not arbitrary
+
+| Family | Addressed to | Where the definition lives | Example |
+|---|---|---|---|
+| A **role's** tools | the seat: `mesh.seat.<seat>.tool.<verb>` | the seat's protocol, in the mesh's records | ask *the forge* to list its repositories |
+| A **module's** tools | the module: `mesh.mod.<module>.tool.<name>` | that module's code | ask *this gitea* for `gitea_list_repos` |
+| The **mesh's** own verbs | the `mesh-controller` seat | the seat's protocol, as above | `status`, `push`, `build`, `assign` |
+
+The split follows accountability. A role is something the mesh guarantees exactly one holder of, so
+what the role answers is the mesh's to define and a holder's to implement
+([ADR 0132](../../02-DECISIONS/0132-a-seat-carries-the-tools-its-holder-must-serve.md)). A module's
+own tools are nobody's business but the module's, and their definitions live where they are
+implemented, because a copy kept anywhere else drifts from the code that answers.
+
+The mesh's own verbs are the third family only in where they come from, not in kind: the control plane
+holds a seat like anything else, and its tools are that seat's. This is what keeps them addressable
+while the control plane is being replaced, which is the moment they are most needed.
+
+**Both names for one capability is deliberate and bounded to this.** A forge holding the `git` seat
+answers the role's `list_repos` and its own `gitea_list_repos`, because the same module may run
+without the seat — a second instance, kept for one purpose — and then only the second name is true.
+The caller chooses which question it is asking. Nothing else in the mesh gets two names.
+
+## 2. What a seat's tool is
+
+A verb, what it does, and the schema of its arguments and its answer. A name alone is not callable by
+something that has never seen the mesh before, which is the whole population this surface exists for.
+
+The protocol a seat carries today is three lists of bare verbs
+([ADR 0129](../../02-DECISIONS/0129-a-seat-carries-the-protocol-of-its-role.md)), and it must widen to
+carry the rest. Two constraints on that widening:
+
+- **It lives in the mesh's records, not in the control plane's binary.** Today a seat's protocol comes
+  from compiled defaults, merged in as a row is read, because the seat rows never gained the columns.
+  Discovery that reads a binary is discovery that disagrees with the mesh the moment the two are on
+  different versions.
+- **The schema is stated in the form an agent protocol already uses**, so nothing translates between a
+  seat's idea of an argument and the caller's. A translation layer would be a second definition of
+  what a tool is.
+
+## 3. Holding a seat means serving its tools
+
+A module may not occupy a seat unless it serves every verb that seat declares. This joins the
+conditions of holding that already exist — providing what the seat delivers, being assigned at the
+seat's scope — and is refused the same way: at registration and at handover, naming the verbs that are
+missing rather than the fact that something is.
+
+A module knows which seats it claims, so knowing which tools it must serve is not a discovery problem
+for the module: the seat says, the module implements, and anything beyond that is its own.
+
+## 4. Addressing a node-scoped seat
+
+A seat's subject is flat today — `mesh.seat.<seat>.<kind>.<verb>` — which is correct for a seat the
+mesh has one holder of and wrong for the six node-scoped seats, where one subject would reach every
+machine's holder and the holders' queue group would hand the call to whichever answered first. A
+node-scoped seat's tool therefore carries the node it is asked of. Nothing about a mesh-scoped seat
+changes.
+
+## 5. Discovery
+
+**What a role answers is a read.** The seats and their protocols are records, so the list is a query
+against the mesh's own store: no call to a module in the path, nothing that has to be running, and an
+answer that stays true while a holder is restarting or being replaced.
+
+**What a module answers comes from the module.** Its definitions live in its code, so it is asked, and
+the answer is as available as the module is — which is the right coupling for a tool that only exists
+while that module does.
+
+A caller therefore gets one list assembled from two sources, and the difference is visible in it: a
+role's tool names a seat, a module's names a module. An agent that wants to survive a holder being
+replaced binds to the first.
+
+## 6. What serves this to an agent
+
+A module the mesh assigns to the machine where the agent runs, holding a credential the mesh minted,
+with authority derived from what it may call — not a program started by hand with a credential printed
+to a terminal. The adapter itself already exists and is thin by design; what changes is that it stops
+being something a person carries and becomes something the mesh runs, on a node, like everything else.
+
+An agent's authority can then be role-shaped: *the forge's tools*, rather than a list of
+module-specific names that changes the day the forge is replaced.
+
+## 7. Versioning
+
+A seat's tools are an interface and change like one. Additive within a version. A change that would
+break a caller takes the version token the subject already has room for, and the two versions run side
+by side until nothing is bound to the old one.
+
+## How it is checked
+
+- **A holder missing a verb cannot take the seat.** One test per condition of holding, as the existing
+  conditions have, and the live refusal names the verbs.
+- **A verb nobody declared is a subject nobody may use.** The bus grants are derived from the seat's
+  protocol already, and the golden composition of the user list is what keeps that honest: a holder is
+  granted exactly the seat's verbs, a user of the seat exactly the publish side.
+- **Discovery needs no running module.** The test for a role's tools reads records and asserts the
+  answer equals what the seats declare — if it needed a module up, it would not be a read.
+- **Two nodes holding one node-scoped seat derive two addresses.** Checked by the same test as the rest
+  of the subject table.
+
+## What this does not settle
+
+- Which verbs each seat should serve. That is a decision per seat, and the reason to do it slowly: a
+  seat's tools bind every future holder.
+- Whether a module's own tool definitions should also be recorded when a build resolves its manifest.
+  There is an argument for it — the mesh could then answer for a module that is down — and an argument
+  against, which is that a recorded copy of a live definition is a copy that can be wrong.
+
+## References
+
+- [ADR 0132](../../02-DECISIONS/0132-a-seat-carries-the-tools-its-holder-must-serve.md) — the decision this designs
+- [ADR 0129](../../02-DECISIONS/0129-a-seat-carries-the-protocol-of-its-role.md) — a seat carries the protocol of its role
+- [ADR 0095](../../02-DECISIONS/0095-the-control-plane-is-the-way-to-ask-a-module.md) — a tool call passes one process where an audit belongs
+- [`26-the-seats.md`](26-the-seats.md) — what a seat is, how it is held and handed over
+- [`25-the-bus-on-nats.md`](25-the-bus-on-nats.md) §7 — a person's account, their inbox, and the adapter

04-ISSUES/131-nothing-tells-the-mesh-a-source-moved/00-report.md

@@ -0,0 +1,107 @@
+---
+status: resolved
+opened: 2026-09-27
+located-in: [mesh-catalog modules/gitea, mesh-controller cmd/mesh-controller, mesh-controller internal/builder]
+fixed-by: mesh-catalog #124 — the forge module watches for merged pull requests and emits `pull.merged` with the merge commit and the clone address; mesh-controller #110/#111 — the control plane follows that event on the bus, marks every module built from that repository and branch as moved, and builds them bases first, stopping when a base fails; mesh-controller #113/#114 — a build records the bases it was handed and the graph is read from builds, without which "bases first" had no edges to order by.
+amended-design: 03-DESIGN/01-to-be/28-building-the-bus.md
+---
+
+# 131 — Nothing tells the mesh a source moved, and it reports itself current anyway
+
+## What was observed
+
+Six changes were merged to the trunk of six repositories in one sitting. The build machine built
+nothing. Its last build, minutes before the first merge, was still the one it reported; no build was
+requested, refused or failed, because none was ever asked for.
+
+Asked afterwards what was wrong, the mesh said:
+
+> 4 machine(s), all doing what they were told, all heard from, running what the mesh would send them,
+> and every module current with its source
+
+Every one of the six had moved. The last clause was false for all of them, and it is the clause a
+person reads to decide whether there is anything to do.
+
+## Why it matters beyond this instance
+
+**The mesh learns a source moved by being told, and there is no longer anything to tell it.** The
+command exists — a person names the module and the commit — and so does the question the overview
+answers. What is missing is whatever used to connect the two. One repository still carries a forge
+webhook aimed at a port; the rest carry none, and the port belongs to a different service than the
+one the arrangement implies. So the state is not "the trigger is broken" but "there is no trigger,
+and nothing says so".
+
+**A wrong answer is worse here than no answer.** "Every module current with its source" is
+indistinguishable, to a reader, from a mesh that has genuinely caught up. The overview is built to be
+the thing you check instead of checking by hand, so a confident false negative removes the habit that
+would otherwise have caught it. Nothing in the mesh is at fault for being out of date — it is at
+fault for saying it is not.
+
+**It is also why "current with its source" cannot be a stored fact.** The mesh compares what it built
+against what it was last told the source was, and calls that agreement. Two facts agreeing tells you
+nothing when both come from the same place.
+
+## The intended shape, which is decided and not built
+
+The forge emits what happened to it — a pull request merged — and the build machine reacts by
+building what that commit affects. That keeps the forge ignorant of the build system and the build
+machine ignorant of the forge's internals, which is the same argument
+[ADR 0126](../../02-DECISIONS/0126-a-module-declares-its-own-seats.md) makes for addressing an event
+to its emitter: the merge is a fact about the forge, and what should be rebuilt because of it is not
+the forge's business to know.
+
+The forge's module already declares the event. The build machine declares that it consumes nothing.
+
+## What the trigger cannot be
+
+**Not one build per changed module.** The modules form a graph: several are built from one
+repository, and some are the base another is compiled on — a runtime image, a compiler base, a
+repository whose context a second module builds from. Firing a build for each changed module
+independently would start work that cannot succeed yet and produce a failure per dependent, for one
+cause.
+
+Observed while catching the mesh up by hand on 2026-09-27: a compiler base had to move before
+anything compiled against it could build, and when it failed, the right behaviour was for its
+dependents to wait rather than each fail the same way. Fifteen modules shared the cause. A trigger
+that reports it fifteen times has buried it.
+
+So whatever reacts to the forge's event resolves what changed into an order, builds the bases first,
+and holds a dependent while its base is unbuilt or failed. That is a larger thing than "rebuild what
+the commit touched", and knowing it now is cheaper than discovering it from fifteen identical
+failures.
+
+## Open questions
+
+- Is "the source moved" still a thing a person can assert by hand once the event path exists, or does
+  the hand-operated form become the thing that made this failure possible?
+- Which commit does the build machine act on — the merge, or each commit it brought — and what does
+  it do when several arrive for one module at once?
+- How does the overview stop being able to lie? Comparing what was built against what was recorded
+  will always agree. Whether the trunk has moved is a question only the forge can answer, so either
+  the overview asks it, or it stops claiming to know.
+- Does this want to be the same mechanism as the build request on the bus
+  ([ADR 0129](../../02-DECISIONS/0129-a-seat-carries-the-protocol-of-its-role.md)), or does it sit in
+  front of it?
+
+## What was done (2026-09-28)
+
+The shape above was built as described: the forge's module emits the merge, the control plane
+consumes it, and nothing on either side knows the other's internals. The build is asked for the
+merge commit, not each commit the merge brought — the trunk moved once, to one place. Several merges
+for one module arriving in a row are followed in turn, each moving the recorded source to its own
+commit, so the last one to arrive is the one the mesh ends up built from.
+
+The hand-operated form stays. `module moved` is how a source is recorded without a forge — a module
+built from a repository elsewhere, or a mesh whose forge module is down — and it is the same act the
+event performs, so the two cannot disagree about what "moved" means.
+
+**Bases first needed edges, and there were none.** The order this report asked for was written and
+walked a graph that no build had ever recorded: a recipe reads its base from a build argument, so the
+digest was never in the file the builder read edges from. A build now reports what it was handed, the
+control plane records it by artifact path, and the order is read from each module's newest build.
+
+**What still can lie.** The overview compares what was built against where it was last told the
+source is; the forge's event is now what moves that mark, so it is right for as long as the forge
+module was listening. A merge made while that module was down is a merge the mesh does not know of
+until the module next polls — it announces what merged since it last looked, so the gap closes when
+it comes back, and not before. The overview does not say so.

04-ISSUES/132-a-module-can-be-recorded-without-the-directory-it-lives-in/00-report.md

@@ -0,0 +1,60 @@
+---
+status: resolved
+opened: 2026-09-28
+located-in: [mesh-controller cmd/mesh-controller]
+fixed-by: mesh-controller — `module add` takes `--path` and `--self`, so a module handed over by hand records the whole location it came from; a record naming a repository and no directory says so in the reply; the rule is one function with a test beside it. The nine records already wrong were corrected by rebuilding each with its real directory, which is the same act through the same door.
+amended-design:
+---
+
+# 132 — A module can be recorded without the directory it lives in
+
+## What was observed
+
+Nine modules on one mesh could not be rebuilt. Each attempt failed the same way:
+
+> has no module.json at its root, so there is nothing saying what it is
+
+All nine were recorded as coming from a repository that holds many modules, each in its own
+directory — and each record named the repository and no directory. So every build cloned the
+repository and looked for a manifest where there has never been one.
+
+The failure only surfaced when something asked for all of them at once. Before that, the overview
+said every module was current with its source, because what it compares is what was built against
+what the mesh was last told the source has, and neither half knows whether the source can be found
+at all.
+
+## Why it matters beyond this instance
+
+**A module is a repository and a directory inside it** ([ADR 0069](../../02-DECISIONS/0069-a-module-is-a-repository-and-a-path.md)),
+and one of the two doors into the catalogue could record only the first half. A build records the
+directory it was given, so a module that arrived by being built is always whole; a module handed over
+by hand had no way to say where it lived, and the flag to say it did not exist. The rule was decided
+and enforced on one path out of two.
+
+**Half a location reads exactly like a whole one.** Nothing in the record is empty in a way a person
+would notice: the repository is there, the branch is there, the commit is there. The mesh only finds
+out at the moment it needs the manifest, which is the moment it is trying to rebuild — and the module
+stays on whatever it last built, indefinitely, with nothing saying why.
+
+**It is the same shape as [131](../131-nothing-tells-the-mesh-a-source-moved/00-report.md).** A
+comparison between two facts the mesh holds about itself will agree with itself. Whether the source
+can be found is a question only an attempt to read it answers, and the answer had nowhere to go.
+
+## What was done
+
+`module add` takes the directory and which forge holds the repository, so a hand-registered module
+records the same whole location a built one does. What a record must say to be worth anything is one
+function with a test beside it, rather than a paragraph in a help string: provenance together or not
+at all, a directory needs a repository to be inside, a path on the mesh's own forge is not an address.
+And a record that names a repository but no directory says so when it is made — not refused, because a
+module really at a repository's root is ordinary, but said, because the person adding it is the one
+who knows which it is.
+
+The nine wrong records were corrected by building each with its real directory, which re-records it.
+No row was written by hand.
+
+## What is still true
+
+A directory that does not exist in the repository cannot be refused when the module is added: the
+control plane does not clone, and inventing a check there would mean it did. The first build says so
+plainly, which is one build rather than nine, and the record it leaves behind is right from then on.