Research 024: the composed grants, checked against a server once built

Events miss a machine that joins after them and replay history where only the
latest matters. A module now declares state it owns and reads; the controller
creates the buckets, the runtime serves them on the bundle's channel. Designs 32
and 25 amended; grants measured against a running server.

01-RESEARCH/024-state-a-module-keeps-on-the-bus/00-overview.md

@@ -0,0 +1,152 @@
+---
+status: graduated
+initiated: 2026-10-04
+touches: [the bus, what a module declares, the tool runtime, the SDK, the bus grants, 03-DESIGN/01-to-be/25-the-bus-on-nats.md, 03-DESIGN/01-to-be/32-what-a-module-declares.md]
+became: [02-DECISIONS/0201-a-module-keeps-its-current-state-in-key-value-buckets-it-declares-and-reaches-through-the-runtime.md, 03-DESIGN/01-to-be/32-what-a-module-declares.md, 03-DESIGN/01-to-be/25-the-bus-on-nats.md]
+---
+
+# 024 — State a module keeps on the bus
+
+## What is investigated
+
+A place on the bus where a module's own code keeps **current state** — not history — that every
+machine sees, including a machine that joins after the state was written: put, get, delete, list and
+watch, reached through the node's runtime the way a bundle already publishes, asks and subscribes
+([ADR 0198](../../02-DECISIONS/0198-a-modules-long-running-code-is-launched-by-the-node-runtime-and-reaches-the-bus-through-it.md)).
+On NATS that is a key-value bucket. The questions are what a module declares, who creates the
+bucket, what the grants are, what the runtime's verbs are, and what may never be stored.
+
+## Why
+
+The mesh carries two kinds of module traffic and a third is missing.
+
+- **Events** land in the EVENTS stream: limits retention, seven days, ten thousand messages per
+  subject, a durable consumer per consuming module that replays what it missed. Never a secret
+  ([design 32](../../03-DESIGN/01-to-be/32-what-a-module-declares.md) §10).
+- **Requests** are core request/reply — tool calls, a bundle's `mesh/ask` — and are kept nowhere.
+
+Neither is *the current value of something*. Two cases from the first module that needs it, the
+operator's agent on a machine ([design 36](../../03-DESIGN/01-to-be/36-the-operators-agent-on-a-machine.md)):
+
+1. **An MCP server registered for every machine.** Registering emits an event every machine's copy
+   of the module consumes. A machine the module is assigned to *after* the registration has no
+   durable consumer yet — the consumer is created at assignment — so it never hears of it. Wanted
+   instead: one entry per server, for every machine or for one; every machine reads the whole current
+   set when it starts and watches for changes; unregistering is a delete; any machine can list it.
+2. **Which licence a machine is bound to** ([design 39](../../03-DESIGN/01-to-be/39-the-anthropic-licence-manager.md)).
+   As events, a machine that was off for a day replays every rotation since and asks for a token
+   after each. It needs only the latest binding and its generation. The token itself stays on
+   request/reply and is never stored.
+
+The design already expects this. [Design 25](../../03-DESIGN/01-to-be/25-the-bus-on-nats.md) §1:
+"conditions and observed state in key-value buckets that anything may watch".
+[Research 017](../017-a-mesh-that-heals-itself/01-the-intended-behaviour.md) wants a provisioner's
+"what I applied" and a rotation's step kept in one rather than in memory. Nothing implements it.
+
+## What exists, measured 2026-10-04
+
+| | fact | where |
+|---|---|---|
+| streams | five kinds of mesh stream: CONTROL (work queue), NODES and ASSIGNMENTS (last per subject), EVENTS (limits: 7 days, 10 000 per subject), one work queue per seat that accepts | the controller's broker streams |
+| the state relationship | [design 32](../../03-DESIGN/01-to-be/32-what-a-module-declares.md) §4 already names *state* — 1:1, last per subject — and says it is "declared: the mesh's own". Two streams use it, both written by the controller. No module can declare it | design 32, the controller |
+| key-value buckets | none, anywhere | all four code repositories |
+| the runtime's bus verbs | `mesh/publish`, `mesh/ask`, `mesh/subscribe`; delivery back to the bundle is `mesh/event` | the runtime's launcher |
+| the runtime's principal | one bus user per machine carries every assigned module; its grant is the union of theirs. That one module's code does not act as another is the runtime's to keep: it publishes under the module's own name by construction | the controller's grant composition, the runtime's bus |
+| what a bundle is issued | a membership per assignment, last per subject, read directly by the runtime: where it serves, where it emits, what it reaches | ADR 0160 |
+| who creates bus objects | the controller only — mesh streams on every raise, a seat's stream at registration, a module's consumer at assignment. No module reaches the JetStream API | design 25 §3 |
+
+### What a key-value bucket needs from a grant, against a real server
+
+Measured against nats-server 2.10 with the Go client the runtime already uses, a bucket created by
+an unrestricted user and used by two users holding only the subjects below (`B` is the bucket):
+
+| operation | subject published | writer | reader |
+|---|---|---|---|
+| bind to the bucket | `$JS.API.STREAM.INFO.KV_B` | yes | yes |
+| get | `$JS.API.DIRECT.GET.KV_B.>` | yes | yes |
+| put, delete | `$KV.B.>` | yes | **refused** |
+| list keys, watch | `$JS.API.CONSUMER.CREATE.KV_B.>` — an ordered, ephemeral consumer | yes | yes |
+| stop a watch cleanly | `$JS.API.CONSUMER.DELETE.KV_B.>` | yes | yes |
+| answers | its own inbox, which every principal already subscribes | — | — |
+
+*Checked again once built, 2026-10-04:* the grants the controller composes for two machines' runtimes —
+one carrying the owner, one only a reader — were loaded into a server as composed, and each operation
+was run as each runtime's user. The owner's did all of them; the reader's read, listed and watched,
+and its put and delete were refused by the server.
+
+Three things the measurement showed that reading the documentation would not have:
+
+1. **A refused put is not an error to the caller; it is a timeout.** The server reports the
+   permission violation asynchronously, on the connection, and the client waits out its deadline
+   for an acknowledgement that never comes. So a runtime that relies on the grant alone tells a
+   bundle "timed out" for "you may not write this" — it must refuse first, from what the module was
+   issued, with the reason.
+2. **A watch's current values include deletions.** A key deleted earlier arrives among the initial
+   values as a delete marker, before the end-of-current marker. A bundle asking "what is there now"
+   must not be handed those.
+3. **Without the consumer-delete grant, stopping a watch hangs** until its deadline, and the
+   ephemeral consumer lingers on the server until it times out by itself.
+
+### Whether the events shape is enough instead
+
+Honestly compared, because a new primitive is a cost:
+
+- **EVENTS cannot be made last-per-subject for some subjects.** Retention is per stream, and
+  JetStream refuses a second stream overlapping the first (verified and recorded in design 32 §3).
+  A state subject inside `mesh.mod.*.event.>` keeps EVENTS' seven days: a licence binding unchanged
+  for a week disappears.
+- **A separate last-per-subject stream per module** is possible — it is exactly what a key-value
+  bucket *is* on the server: a stream with one message per subject, a rollup for purge, and direct
+  reads. Building it by hand gives up the client's get, list, delete and watch, which are the
+  operations both cases need, and would be the mesh writing NATS's own key-value layer again.
+- **Consumers are the wrong reader.** A durable consumer per reading module is created at
+  assignment and replays from where it is; state wants "everything current, now, then changes",
+  which an ordered ephemeral consumer from the last value per subject gives and a durable does not.
+
+So key-value is not a convenience over events; it is the state relationship design 32 already
+names, opened to modules.
+
+## Questions, and what this effort proposes
+
+1. **What a manifest says.** `state` names the buckets a module owns, by local name — every
+   instance of the module may write them and read them. `reads` names another module's bucket as
+   `<module>.<name>`, read-only. Names only, never a bucket or subject (design 32 §1). A bucket's
+   options — how many past values it keeps, how long a value lives — are the owner's to declare,
+   the way a seat declares its own retention (design 32 §3).
+2. **Scope.** One bucket per module per name, mesh-wide. A key may carry a machine by the module's
+   own convention (`all.<server>`, `<machine>.<server>`). A bucket per machine was considered and
+   not proposed: "list every server for every machine" becomes a walk over buckets, and the grant
+   could only narrow writes, which nothing asked for — every instance of the owner already writes.
+3. **Who creates the bucket.** The controller, from the catalogue, on every raise — a bucket exists
+   from registration, like a seat's stream, so a reader can watch before the owner is assigned
+   anywhere. Never a module.
+4. **The runtime's verbs.** `mesh/state.get`, `mesh/state.put`, `mesh/state.delete`,
+   `mesh/state.keys`, `mesh/state.watch`, each naming the bucket as the module named it. A watch
+   is answered once the current values are on their way, then each change is delivered to the
+   bundle as a `mesh/state` request it answers — current values first (no deletions among them), an
+   end-of-current marker, then changes. A child that restarts watches again, as it subscribes
+   again. The runtime refuses, with the reason, a bucket the module was not issued, and a write to
+   one it only reads.
+5. **Secrets.** None in a bucket, sealed or not: a bucket is a stream (design 32 §10). Sealed values
+   are plain base64 and cannot be recognised, so the mechanical check is partial and said to be: the
+   runtime refuses a value carrying a field whose name says it is a credential (`password`,
+   `secret`, `token`, `authorization`, …), which catches the ordinary mistake and not a determined
+   one. For the first consumer this has a concrete consequence: an MCP server registered with an
+   authorisation header keeps that header out of the bucket.
+6. **History, lifetime, size.** One value per key unless the owner says more; no expiry unless it
+   says one; a value at most 256 KiB and a bucket at most 64 MiB, the mesh's caps rather than a
+   module's. **A bucket outlives its module's assignment** — what a module stored is data, and data
+   outlives what declared it ([ADR 0030](../../02-DECISIONS/0030-data-outlives-the-mesh-that-declared-it.md));
+   unassigning is not cleaning up. A bucket whose declaration is gone is reported, never removed.
+7. **Events or state.** State (above).
+
+## The work, once decided
+
+1. A decision record, then design 32 (*state* becomes a relationship a module declares) and design
+   25 (key-value buckets are part of the bus) amended.
+2. The controller: the manifest's two words and their registration check; buckets asserted on every
+   raise; the grants for owners' and readers' runtimes; the buckets issued in each membership.
+3. The runtime: the five verbs, the watch delivery, the refusals; tested against a real server.
+4. The SDK, TypeScript and Go: a small state surface over the verbs.
+5. Proved on a running mesh with one small module, then handed to the operator's agent, whose
+   registered servers move from events to a bucket.

02-DECISIONS/0200-genesis-pivots-to-the-controller-as-a-container-and-the-first-push-hands-it-to-a-process.md

@@ -0,0 +1,78 @@
+---
+topic: building it
+status: accepted
+date: 2026-10-04
+deciders: jochen
+reconstructed: false
+extends: 02-DECISIONS/0067-genesis-is-a-pivot.md
+---
+
+# 200. Genesis pivots to the controller as a container, and the first push hands it to a process
+
+## Context
+
+The controller is Go, compiled to one static binary, and is the last of the mesh's own programs a
+machine runs from an image ([issue 213](../04-ISSUES/213-the-controller-is-a-go-program-run-in-a-container/00-report.md)).
+[ADR 0188](0188-a-modules-own-code-is-bundles-in-any-language-and-a-tools-bundle-speaks-mcp-to-the-runtime.md)
+§1 says a module's own code is bundles, never an image, and §3 that a service bundle is a `process` the
+host runs. The handover exists: a process may name the container it `replaces`, and the host removes
+that container only after the process has stayed up across two checks; two controllers are safe
+together for that moment, the second standing by on the controller's consumers and every plan held by
+one lock.
+
+What stands in the way is genesis ([ADR 0067](0067-genesis-is-a-pivot.md)), which
+[issue 223](../04-ISSUES/223-a-new-mesh-installs-its-controller-as-a-container/00-report.md) found
+assumes an image and a container at every step from its third: it builds the controller's image,
+starts a temporary controller from it, publishes it, finds the controller's container in the pivot
+declaration, and from then on talks to the controller through it. A process's bundle is fetched from
+the artifact store, and genesis raises the artifact store only after the pivot.
+
+## Considered Options
+
+1. **Raise the artifact store before the pivot**, publish the controller's bundle to it, and talk to
+   the controller from the host's side. Rejected for now: it reorders genesis around a store that is
+   itself a module the controller deploys, and rewrites the steps that talk to the controller — a
+   larger change to the one path that is exercised least, to remove a container that exists for
+   minutes.
+2. **Pivot to the controller as a container, as today, and let the first push hand it over to the
+   process**, through the handover that already exists. Chosen.
+3. **Keep the controller a container.** Rejected: it is the exception to ADR 0188 that every other
+   module's code has now left, and it costs a container runtime on the control machine and a
+   container recreation in the middle of a plan.
+
+## Decision
+
+**Genesis raises the controller as a container, under the resource the controller's process
+`replaces`, and the first declaration the controller composes for its own machine hands it over.**
+The container is genesis's own shape, built from the controller's repository, and is recorded on the
+control machine exactly as the manifest's `replaces` names it, so the first apply after the pivot
+finds a replacement for it and removes it once the process is up. The controller's manifest declares
+only the process; the image form exists for genesis alone and is not a second way to run the
+controller on a live mesh.
+
+This is the one bounded exception to ADR 0188 §1: a module's own code in an image, for the minutes
+between the pivot and the first push, on a mesh being created.
+
+## Consequences
+
+- A new mesh ends where a running one is: the controller a process, no controller container.
+- Genesis keeps its steps; what changes is that it no longer reads the controller's container from the
+  manifest, and that it records the container under the name the handover expects.
+- The controller's repository keeps its image build for genesis and the lab.
+- The handover is now on genesis's path too: a process that fails to stay up leaves the genesis
+  container serving, and the apply says so — the same rule as on a live mesh.
+
+## How it is checked
+
+The installer's test raises a mesh whose controller manifest is the process form, and asserts that the
+container genesis recorded is exactly what the process `replaces`, so the first apply hands over and
+leaves one controller. Live, on the running mesh: after the manifest change is pushed, the control
+machine runs the controller as a process and no controller container, and the controller's seat
+answers throughout.
+
+## References
+
+- [Issue 213](../04-ISSUES/213-the-controller-is-a-go-program-run-in-a-container/00-report.md),
+  [issue 223](../04-ISSUES/223-a-new-mesh-installs-its-controller-as-a-container/00-report.md)
+- mesh-host#86 (the handover), mesh-controller#252 (two controllers safe together),
+  mesh-controller#253 (the controller's manifest as a process)

02-DECISIONS/0201-a-module-keeps-its-current-state-in-key-value-buckets-it-declares-and-reaches-through-the-runtime.md

@@ -0,0 +1,106 @@
+---
+topic: what runs on it
+status: accepted
+date: 2026-10-04
+deciders: jochen
+reconstructed: false
+extends: 02-DECISIONS/0198-a-modules-long-running-code-is-launched-by-the-node-runtime-and-reaches-the-bus-through-it.md
+---
+
+# 201. A module keeps its current state in key-value buckets it declares, and reaches them through the runtime
+
+## Context
+
+A module's code reaches the bus through the node's runtime: it publishes events, subscribes to them
+and asks tools ([ADR 0198](0198-a-modules-long-running-code-is-launched-by-the-node-runtime-and-reaches-the-bus-through-it.md)).
+Events are kept for a week and replayed to a consumer that was away; requests are kept nowhere. What
+neither gives is **the current value of something**, seen by every machine, including one that joins
+after it was written. The first module to need it — the operator's agent on a machine — registers MCP
+servers for every machine as events, and a machine assigned later never hears of them; and it would
+replay a week of licence rotations where it needs only the binding that holds now. Research
+[024](../01-RESEARCH/024-state-a-module-keeps-on-the-bus/00-overview.md) measured the alternatives and
+the grants against a real server.
+
+[Design 32](../03-DESIGN/01-to-be/32-what-a-module-declares.md) §4 already names *state* as one of the
+mesh's relationships — 1:1, last per subject — and reserves it to the mesh's own declarations.
+[Design 25](../03-DESIGN/01-to-be/25-the-bus-on-nats.md) §1 expects key-value buckets on the bus.
+
+## Considered Options
+
+1. **Key-value buckets a module declares, created by the controller, reached through the runtime.**
+   Chosen.
+2. **State as events on EVENTS, read last-per-subject.** Rejected: retention is per stream and EVENTS
+   keeps seven days, so a value unchanged for a week disappears; a second stream over the same subjects
+   is refused by the server (design 32 §3). And events give no get, list or delete.
+3. **A last-per-subject stream per module, written by hand.** Rejected: it is what a key-value bucket
+   is on the server, without the client's get, list, delete and watch — the mesh writing NATS's
+   key-value layer again.
+4. **State in a module's own files or database, shared by asking a tool.** Rejected for state every
+   machine must see: a machine joining later has to know whom to ask and poll, and an owner that is
+   down answers nothing — the property the bus exists to remove.
+
+## Decision
+
+**1. A module declares its state by name.** `state` names the buckets it owns, by local name; every
+instance of the module may write and read them. `reads` names another module's bucket as
+`<module>.<name>`, read-only. A bucket's options are its owner's: how many past values a key keeps,
+and how long a value lives. A manifest names no bucket, stream or subject (design 32 §1).
+
+**2. One bucket per module per name, mesh-wide.** A key may name a machine by the module's own
+convention; the mesh does not scope buckets per machine.
+
+**3. The controller creates the buckets, from the catalogue, on every raise** — from registration,
+like a seat's stream, so a reader can watch a bucket whose owner is not yet assigned anywhere. A module
+never creates one. The runtime's grant on each bucket is the union of what its carried modules may do:
+an owner's instances write and read, a reader's read.
+
+**4. Each assignment is issued its buckets in its membership** ([ADR 0160](0160-the-mesh-issues-an-assignments-subjects-and-a-runtime-serves-what-it-is-issued.md)),
+by the name the module uses for each and whether it may write. The runtime serves `mesh/state.get`,
+`put`, `delete`, `keys` and `watch` on the bundle's channel from that list, and refuses — with the
+reason — a bucket the module was not issued and a write to one it only reads. A watch delivers the
+current values first, without deletions, then an end-of-current marker, then every change, each as a
+`mesh/state` request the bundle answers.
+
+**5. No secret is stored in a bucket, sealed or not.** A bucket is a stream, and design 32 §10 keeps
+every secret off streams. A value that needs a secret names it; the secret travels on request/reply.
+
+**6. The mesh caps size; a bucket outlives its module.** One value per key and no expiry unless the
+owner says otherwise; at most 256 KiB a value and 64 MiB a bucket. Unassigning a module leaves its
+buckets and what is in them ([ADR 0030](0030-data-outlives-the-mesh-that-declared-it.md)); a bucket
+whose declaration is gone from the catalogue is reported, never removed by the mesh.
+
+## Consequences
+
+- A machine that joins reads the current state at once, and every machine sees a change as it
+  happens, with no consumer created per reader and nothing replayed.
+- The runtime's channel has a sixth verb family, and the SDKs a small state surface over it — a
+  contract, which ADR 0039 admits: it changes when the verbs do, rarely, and every module should be
+  rebuilt when it does.
+- What got harder: the runtime must keep each module to its own buckets, because one principal per
+  machine carries all of them and the server enforces only the union. A write the server refuses
+  surfaces to a client as a timeout, not a refusal, so the runtime's own refusal is what a module sees.
+- The secrets rule is only partly mechanical. Sealed values cannot be recognised; the runtime refuses
+  a value with a field whose name says it is a credential, which catches the ordinary mistake and not a
+  determined one. For the operator's agent this means an MCP server's authorisation header stays out of
+  its bucket.
+- Buckets accumulate as modules come and go; that they are reported rather than removed is the price
+  of not deleting data.
+
+## How it is checked
+
+| Rule | Checked by |
+|---|---|
+| A manifest's state names are local, and a read names a bucket its owner declares | the catalogue's registration check, per manifest; a catalogue test that every `reads` whose owner is present names a bucket that owner declares |
+| Buckets exist for every declared state | the controller's raise asserts them idempotently; its test over a real bus |
+| Owners write, readers only read | the composer's test of the grants, per principal kind; the runtime's refusal test over a real bus |
+| A watch hands current values first, without deletions, then changes | the runtime's test over a real bus |
+| No credential-named field in a value | the runtime's refusal test |
+| Live | one module puts on one machine and another machine's watch sees it; a machine assigned afterwards reads it at start |
+
+## References
+
+- Research [024](../01-RESEARCH/024-state-a-module-keeps-on-the-bus/00-overview.md)
+- [Design 32](../03-DESIGN/01-to-be/32-what-a-module-declares.md) §4 and §10, [design 25](../03-DESIGN/01-to-be/25-the-bus-on-nats.md) §1 and §3
+- [ADR 0030](0030-data-outlives-the-mesh-that-declared-it.md), [ADR 0039](0039-what-the-sdk-holds-and-refuses.md),
+  [ADR 0160](0160-the-mesh-issues-an-assignments-subjects-and-a-runtime-serves-what-it-is-issued.md),
+  [ADR 0198](0198-a-modules-long-running-code-is-launched-by-the-node-runtime-and-reaches-the-bus-through-it.md)

02-DECISIONS/README.md

@@ -298,6 +298,7 @@ python3 00-META/checks/index.py            fail if stale
 - **0195** — [The mesh's tools are found by address, not announced whole](0195-the-meshs-tools-are-found-by-address-not-announced-whole.md)
 - **0197** — [Every tool announces itself on the bus, in the NATS services protocol](0197-every-tool-announces-itself-on-the-bus-in-the-nats-services-protocol.md)
 - **0198** — [A module's long-running code is launched by the node's runtime, and reaches the bus through it](0198-a-modules-long-running-code-is-launched-by-the-node-runtime-and-reaches-the-bus-through-it.md)
+- **0201** — [A module keeps its current state in key-value buckets it declares, and reaches them through the runtime](0201-a-module-keeps-its-current-state-in-key-value-buckets-it-declares-and-reaches-through-the-runtime.md)
 
 ### How it is built
 
@@ -320,6 +321,7 @@ python3 00-META/checks/index.py            fail if stale
 - **0111** — [A build source is on the mesh's git seat, or it is an external repository](0111-a-build-source-is-on-the-git-seat-or-external.md)
 - **0149** — [The live mesh is the test bed](0149-the-live-mesh-is-the-test-bed.md)
 - **0174** — [A node varies a module through settings and kept regions, never through an edit](0174-a-node-varies-a-module-through-settings-and-kept-regions-never-an-edit.md)
+- **0200** — [Genesis pivots to the controller as a container, and the first push hands it to a process](0200-genesis-pivots-to-the-controller-as-a-container-and-the-first-push-hands-it-to-a-process.md)
 
 ### How it is checked
 

03-DESIGN/01-to-be/25-the-bus-on-nats.md

@@ -7,8 +7,10 @@ code:
   - mesh-tools src/broker-amqp.ts (to be replaced)
   - mesh-catalog modules/nats (to be written)
   - mesh-sdk src (the protocol's NATS binding, step 3)
-updated: 2026-10-02
+  - mesh-tools node-tools/internal/bus (a module's state, ADR 0201)
+updated: 2026-10-04
 decisions:
+  - 02-DECISIONS/0201-a-module-keeps-its-current-state-in-key-value-buckets-it-declares-and-reaches-through-the-runtime.md
   - 02-DECISIONS/0167-a-membership-carries-what-its-module-receives-and-who-the-mesh-is.md
   - 02-DECISIONS/0160-the-mesh-issues-an-assignments-subjects-and-a-runtime-serves-what-it-is-issued.md
   - 02-DECISIONS/0157-a-build-says-what-it-does-on-the-bus-as-it-happens.md
@@ -48,6 +50,7 @@ mesh's own state lives, and where what a module may say is decided by what it de
 | **events** — a module says something happened | 1:many | delivered to every consumer that declared it; dead-lettered when it cannot be |
 | **tools** — a module or a person asks another's tool | request/reply | one answer, from one server, or a timeout |
 | **work to a role** — a module submits to a capability without knowing who provides it | job | exactly one holder does it; it queues while nobody does |
+| **state** — a module's current value of something, every machine reading it | key-value | the newest per key, kept until replaced or deleted; read whole by a machine that joins later |
 
 The last two rows are the ones worth dwelling on, because they are not messaging in the sense of
 carrying bytes from A to B. **A role is addressable**, so a caller names the capability and never
@@ -56,7 +59,8 @@ changing ([ADR 0126](../../02-DECISIONS/0126-a-module-declares-its-own-seats.md)
 property of the mesh's architecture that happens to be expressed in subjects.
 
 And more of the mesh lands here as it is built: conditions and observed state in key-value
-buckets that anything may watch, the server's own advisories becoming observations like any other
+buckets that anything may watch — the first of them a module's own declared state, *2026-10-04*
+([ADR 0201](../../02-DECISIONS/0201-a-module-keeps-its-current-state-in-key-value-buckets-it-declares-and-reaches-through-the-runtime.md)) — the server's own advisories becoming observations like any other
 ([research 017](../../01-RESEARCH/017-a-mesh-that-heals-itself/00-overview.md)), and a person's
 client speaking the bus directly rather than through a surface built over it (§7). None of that
 is a message being moved; all of it is the bus being the mesh's centre.
@@ -84,8 +88,16 @@ mesh.seat.<seat>.event.<verb>     a role's own event           (JetStream: EVENT
 mesh.seat.<seat>.tool.<verb>      a role's tool                (core request/reply)
 mesh.ask.<node>.<command>         the controller's command api (core request/reply)
 mesh.assignment.<node>.<module>   an assignment's membership   (JetStream: ASSIGNMENTS, last-per-subject)
+$KV.<module>_<name>.<key>          a module's state             (JetStream: a key-value bucket per declared name)
 ```
 
+**Added 2026-10-04** ([ADR 0201](../../02-DECISIONS/0201-a-module-keeps-its-current-state-in-key-value-buckets-it-declares-and-reaches-through-the-runtime.md)):
+the last row is outside `mesh.` on purpose. A key-value bucket is NATS's own construct and lives
+under NATS's own prefix, which is what lets the server's key-value layer — direct reads, rollups,
+delete markers, watches — do the work instead of the mesh writing it again. The bucket is named for
+the module and the local name joined by an underscore, which neither may contain, so two modules can
+never derive one bucket.
+
 **Revised 2026-10-01** ([ADR 0160](../../02-DECISIONS/0160-the-mesh-issues-an-assignments-subjects-and-a-runtime-serves-what-it-is-issued.md)): the rows above
 for a module's and a seat's tools are the shapes the controller *issues*, not rules a runtime carries.
 Every assignment is published a membership — what it serves and where, in which queue, its seat verbs,
@@ -155,6 +167,7 @@ Core NATS is at-most-once. Everything the mesh must not lose lives in a JetStrea
 | CONTROL | `mesh.control.>` except `alive` (a build's outcome moved to its seat, ADR 0121) | work queue, one consumer (the controller), explicit ack | the store-window guarantee ([ADR 0083](../../02-DECISIONS/0083-one-push-leaves-the-mesh-consistent.md)): the controller `nak`s with a delay while its store is away and the message is redelivered; nothing is dropped |
 | NODES | `mesh.node.>` | last per subject | one declaration per node, always the newest |
 | EVENTS | `mesh.mod.*.event.>` and `mesh.seat.*.event.>` | limits (age, size), durable consumer per subscribing module | a subscriber that was down catches up; after `max-deliver` attempts the advisory feeds `mesh.events.dead` (its own small stream). *2026-10-01:* a build's whole log is here too, as the build-machine seat's `log.<build id>` events ([ADR 0157](../../02-DECISIONS/0157-a-build-says-what-it-does-on-the-bus-as-it-happens.md)) — one subject per build, a week of retention, read back by `builds --log <id>` with a consumer that is gone when the reading is done |
+| `KV_<module>_<name>` | `$KV.<module>_<name>.>` | the newest value per key — as many past values as the owner declared — no age unless the owner declared one; a value at most 256 KiB, a bucket at most 64 MiB | a module's state (ADR 0201): one per name in a manifest's `state`, created from the catalogue on every raise, so it exists before its owner runs anywhere; kept when the module is unassigned, because what it holds is data |
 
 Tool calls and heartbeats stay on core NATS: a lost heartbeat is the next heartbeat; a lost tool
 call is a timeout the caller already handles.
@@ -234,6 +247,14 @@ expresses this exactly, per subject, and better than a vhost could:
   permissions for each consumed event's subject, its tool subjects, and that same inbox prefix.
   Nothing else. A module that tries to publish outside its emits is refused by the server, not by
   convention.
+- **A module's state** (ADR 0201), for whichever principal carries the module — today the machine's
+  runtime, whose grant is the union of its modules': binding to the bucket, reading a key directly,
+  and an ordered consumer for listing and watching, created and deleted on the bucket's own stream
+  and nothing else's; and, for the owner's instances only, publishing under the bucket's own
+  `$KV.<bucket>.>`. *Measured 2026-10-04 against a running server:* without the consumer-delete
+  grant a watch cannot be stopped cleanly, and a write the server refuses reaches the writer as a
+  timeout rather than a refusal — so the runtime refuses first, from the membership, and the grant
+  is the second line.
 - **The controller's user** owns `mesh.control.>`, `mesh.node.>` and the streams, and may submit work
   to the seats the mesh's own flows use — a build, for one (ADR 0121).
   **A host's user** may publish its own `mesh.control.<node>.>` and subscribe its own

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

@@ -11,8 +11,10 @@ code:
   - mesh-host internal/apply/apply.go
   - mesh-tools src/main.ts
   - mesh-catalog modules/mesh-catalog
-updated: 2026-10-02
+  - mesh-tools node-tools/internal/runtime (a module's state, ADR 0201)
+updated: 2026-10-04
 decisions:
+  - 02-DECISIONS/0201-a-module-keeps-its-current-state-in-key-value-buckets-it-declares-and-reaches-through-the-runtime.md
   - 02-DECISIONS/0160-the-mesh-issues-an-assignments-subjects-and-a-runtime-serves-what-it-is-issued.md
   - 02-DECISIONS/0126-a-module-declares-its-own-seats.md
   - 02-DECISIONS/0131-everything-on-the-mesh-speaks-to-the-broker-seat.md
@@ -67,6 +69,8 @@ the catalogue, and the mesh would have hundreds of copies of a decision it made
 | `tools: 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 |
+| `state: servers` | a key-value bucket for the module, created by the controller; its instances write and read it |
+| `reads: billing.orders` | read and watch billing's `orders` bucket, and nothing else of it |
 
 **Wildcards, and they are the mesh's rather than a bus's.** *Added 2026-09-27, from
 [issue 127](../../04-ISSUES/127-a-module-event-derives-a-subject-nothing-publishes/00-report.md).* A
@@ -221,7 +225,7 @@ service" versus "one worker per machine".
 | 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` |
+| declared | `provides`/`requires` | `emits`/`consumes` | seat `accepts` / `uses` | the mesh's own; a module's `state` / `reads` | `serves` |
 
 **Job** is the one [ADR 0041](../../02-DECISIONS/0041-events-are-a-relationship.md) had no room
 for. Its table has events at 1:many and provisions at 1:1; a module submitting work to a service
@@ -236,6 +240,31 @@ last-per-subject retention, and a node that has seen sequence *n* refuses *n−1
 That is the wire-level answer to
 [issue 107](../../04-ISSUES/107-a-declaration-carries-no-order/00-report.md).
 
+**A module declares state too.** *Added 2026-10-04,
+[ADR 0201](../../02-DECISIONS/0201-a-module-keeps-its-current-state-in-key-value-buckets-it-declares-and-reaches-through-the-runtime.md).*
+State was the mesh's alone, and modules had the same need with nowhere to put it: an MCP server
+registered for every machine, sent as an event, never reached a machine assigned afterwards — its
+consumer did not exist yet when the event passed — and a licence binding sent as events replays a
+week of rotations where only the latest matters. So a module names the state it **owns** with
+`state`, and another module's it **reads** with `reads: <module>.<name>`. Each is a key-value bucket
+the controller creates from the catalogue, mesh-wide, existing from registration so a reader can
+watch before the owner runs anywhere ([design 25](25-the-bus-on-nats.md) §3). Every instance of the
+owner writes; a reader reads and watches. A key may name a machine by the module's own convention;
+the mesh keeps one bucket per name, not one per machine, because "every server, for every machine"
+is then one list rather than a walk.
+
+What a module sees is what it named. Its assignment's membership lists its buckets by those names,
+with whether it may write, and the runtime answers `get`, `put`, `delete`, `keys` and `watch` for
+them on the bundle's channel — refusing, with the reason, a name it was not issued or a write to a
+bucket it only reads. A watch hands the current values first, then every change: a bundle that starts
+late, or starts again, has the whole of the state before it has any of the news.
+
+The owner says how many past values a key keeps and how long a value lives, as a seat says how long
+its backlog survives (§3); the mesh caps a value's size and a bucket's. **A bucket outlives its
+module's assignment** — what a module stored is data
+([ADR 0030](../../02-DECISIONS/0030-data-outlives-the-mesh-that-declared-it.md)) — and one whose
+declaration is gone is reported, never removed by the mesh.
+
 ## 5. Seats
 
 A module declares a seat with its protocol, and the mesh enforces one holder at its scope
@@ -454,6 +483,14 @@ sealing key leaks, that stream is an archive rather than a moment. So:
   existing discipline — *fetched from it, not carried* — applied to the one payload where carrying
   it is worst.
 
+**A key-value bucket is a stream, so the same holds for it.** *Added 2026-10-04,
+[ADR 0201](../../02-DECISIONS/0201-a-module-keeps-its-current-state-in-key-value-buckets-it-declares-and-reaches-through-the-runtime.md).*
+No secret is put in a module's state, sealed or not: state is exactly what a machine joining a year
+later reads in full. A value that needs a secret names it, and the secret travels on request/reply.
+Sealed values are plain text to anything inspecting them, so this is checked only partly — the
+runtime refuses a value carrying a field whose name says it is a credential, which catches the
+ordinary mistake and not a determined one.
+
 **The bootstrap, which is circular and has a precedent.** The vault makes every secret
 ([ADR 0113](../../02-DECISIONS/0113-the-vault-makes-every-secret.md)), including the bus's own
 passwords. The vault is a module, and a module needs a bus account, whose password the vault
@@ -523,3 +560,9 @@ billing existing under that name.
   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.
+- **A module reaches only the state it declared.** The composer's test: an owner's runtime may write
+  its buckets, a reader's may only read, and nothing else is granted; the runtime's test over a real
+  bus: a name not issued and a reader's write are refused with the reason.
+- **State is current at once.** The runtime's test over a real bus: a watch hands the current values
+  without deletions, then an end-of-current marker, then changes. Live: a machine assigned after a put
+  reads it at start.

03-DESIGN/01-to-be/38-building-the-operators-machine.md

@@ -2,7 +2,7 @@
 layer: to-be
 status: in-progress
 code: [mesh-tools, mesh-controller, mesh-host, mesh-catalog]
-updated: 2026-10-03
+updated: 2026-10-04
 decisions:
   - 02-DECISIONS/0175-one-tool-runtime-per-node-serves-every-modules-tools-on-the-host-side.md
   - 02-DECISIONS/0173-the-operators-machine-is-the-meshs-and-a-module-is-what-it-declares.md
@@ -309,6 +309,25 @@ nextcloud, minio), the two whose clients exist on no system (mongodb, mssql: a d
 and last the mesh's own (mesh-catalog, mesh-vault, records, gitea, mailu, audit-logger, lab, and the
 three mains).
 
+*Built 2026-10-04.* Thirty-four modules no longer run their own code in a container: the first wave
+(mesh-catalog#245), the mesh's own and the media modules (mesh-catalog#248, mesh-media-catalog#13),
+with a step run where and as it is declared (mesh-host#85) and a process's words filled like a
+container's (mesh-controller#250). **Proven live** on every machine that runs them: each moved
+module's tools answer from the node's runtime, the steps run as their oneshot units, and the forge's
+merge events reach the build pipeline from the runtime — the merge after the move started its own
+plan. **Two corrections the machines taught:** a tool that called a broker's command-line client now
+runs it inside the broker's own container, because a host package may be uninstallable on a machine
+whose package index is stale (mesh-catalog#249); and a module reading its application's own key reads
+it through the application's container, because that directory belongs to the account the application
+runs as there, which is not the runtime's (mesh-media-catalog#14). *Completed 2026-10-04:* the last three — mesh-catalog, mongodb and mssql, whose code imports npm
+packages of its own — moved once the builder installs a bundle's own dependencies before compiling,
+keeping the toolchain's SDK authoritative (mesh-controller#255, mesh-catalog#250). Their database
+clients are now drivers inlined into the bundle, not command-line clients fetched by a container; one
+more correction the machines taught: a driver reaching its server on loopback must give TLS a host
+name, since the runtime's Node refuses an address (mesh-catalog#252). **No module's own code runs in
+a container any more;** every module with tools answers from its node's runtime, proven by calling a
+tool of each.
+
 ## WP5 — The shell, on a server first
 
 *mesh-catalog #224, already written. Half a day to assign and prove.*

04-ISSUES/211-a-bundle-is-built-before-the-toolchain-it-is-compiled-in/00-report.md

@@ -1,9 +1,10 @@
 ---
-status: located
+status: resolved
 opened: 2026-10-03
 located-in:
   - mesh-controller
 fixed-by:
+  - mesh-controller#246
 amended-design:
 ---
 
@@ -45,3 +46,7 @@ have to write — a bundle of language L depends on the module that publishes L'
 bundle lands in the tier after it. A test: a merge touching the toolchain module and a TypeScript
 bundle plans the bundle one tier later. Worked around on the day by building the bundle again once
 the toolchain was built.
+
+## Resolved
+
+Every mesh-tools plan since the fix ran in two rounds: the toolchain and runtime images first, what is built in or on them after. Before it, a merge moving both tiered them together. The planner's test proves the order: a merge moving a bundle and its toolchain plans two rounds.

04-ISSUES/212-a-toolchain-rebuild-keeps-the-sdk-it-cached/00-report.md

@@ -1,10 +1,11 @@
 ---
-status: located
+status: resolved
 opened: 2026-10-03
 located-in:
   - mesh-tools
   - mesh-controller
 fixed-by:
+  - mesh-tools#44
 amended-design:
 ---
 
@@ -42,3 +43,7 @@ install from a lockfile that a release updates, or build the install layer witho
 the build should record which SDK version the image carries, so a bundle's record says what it was
 compiled against. A check: after an SDK release and a toolchain rebuild, a bundle built on it reports
 the released version.
+
+## Resolved
+
+The toolchain now installs the exact SDK version the mesh last published, passed in as a build argument from the SDK module's published package, and the planner orders the toolchain after the SDK. Proven 2026-10-04: the toolchain built with the published SDK, and the six TypeScript bundles built in it serve their tools and seat verbs.

04-ISSUES/213-the-controller-is-a-go-program-run-in-a-container/00-report.md

@@ -1,10 +1,14 @@
 ---
-status: open
+status: resolved
 opened: 2026-10-03
 located-in:
   - mesh-controller
-  - mesh-catalog
+  - mesh-host
 fixed-by:
+  - mesh-host#86
+  - mesh-controller#252
+  - mesh-controller#253
+  - mesh-host#88
 amended-design:
 ---
 
@@ -50,3 +54,27 @@ of a plan today.
 
 Located only by owner; the move is a change of the controller's module and its deployment, not of
 its code.
+
+## Fix prepared (2026-10-04)
+
+Three changes. mesh-host#86, merged: a process may name the container it `replaces`, and the host
+removes that container only once the process has stayed up across two checks. mesh-controller#252,
+awaiting the operator's merge: the controller's composition for a service process, and two
+controllers safe together for the handover — the second stands by on the controller's consumers
+until the first lets go, and all plan work holds one advisory lock. mesh-controller#253, held: the
+controller's manifest as a Go bundle and a process. It waits on
+[issue 223](../223-a-new-mesh-installs-its-controller-as-a-container/00-report.md), because with it a
+new mesh cannot be installed.
+
+## Resolved
+
+Proven 2026-10-04 on the control machine: after the manifest change was merged and pushed, the host
+created the controller's account, ran its preparation step, started the controller as a process,
+found it up across both checks and removed the container. The controller now runs as its own account
+from its bundle, no controller container remains, its seat answered throughout, and the merge's own
+plan finished all three tiers under the new process.
+
+One fault on the way, fixed before it could leave two controllers or none: the host read the account
+not existing yet as a user database that did not answer — it matched the exit as text in a wording
+its own runner did not use — so the first apply stopped at the account and the container kept serving,
+which is the handover's safe failure (mesh-host#88).

04-ISSUES/214-a-plan-loses-track-of-the-controller-it-rebuilds/00-report.md

@@ -1,9 +1,10 @@
 ---
-status: located
+status: resolved
 opened: 2026-10-03
 located-in:
   - mesh-controller
 fixed-by:
+  - mesh-controller#246
 amended-design:
 ---
 
@@ -34,3 +35,7 @@ Owner mesh-controller (the planner). **Fix direction:** on start, and whenever a
 build, the plan settles an `asked` build against the build records — a build recorded as built from
 the plan's commit is that tier's outcome — so a plan resumes after the controller replaced itself.
 A test: a plan whose build outcome was recorded while no controller followed it resumes on start.
+
+## Resolved
+
+A plan settles an asked build from the build records, whoever heard the outcome. Proven 2026-10-03 and 2026-10-04: both controller merge plans since the fix finished all three rounds, including the round that replaced the controller, without being stopped by hand.

04-ISSUES/215-a-module-built-at-a-commit-stops-following-its-branch/00-report.md

@@ -1,9 +1,10 @@
 ---
-status: located
+status: resolved
 opened: 2026-10-03
 located-in:
   - mesh-controller
 fixed-by:
+  - mesh-controller#246
 amended-design:
 ---
 
@@ -33,3 +34,9 @@ Owner mesh-controller. **Fix direction:** a build asked at a commit does not cha
 module follows; or, if pinning is meant, the pin is said — in `module list`, in `status`, and by a
 merge's plan naming the module it leaves out and why. A test: building a module at a commit and then
 merging a change to it plans it.
+
+## Resolved
+
+Proven 2026-10-04: the catalogue merges since the fix rebuilt the module that had been pinned at an
+old commit, at the merge's commit, by an ordinary plan — the same as every other module of the
+catalogue. Nothing was asked for it by hand.

04-ISSUES/216-a-bundle-nothing-loads-is-built-and-never-delivered/00-report.md

@@ -1,9 +1,10 @@
 ---
-status: located
+status: resolved
 opened: 2026-10-03
 located-in:
   - mesh-controller
 fixed-by:
+  - mesh-controller#246
 amended-design:
 ---
 
@@ -28,3 +29,7 @@ Owner mesh-controller (the catalogue's registration check). **Fix direction:** a
 loads, runs or unpacks — no `loads`, no `tools` list on its module, no resource naming it — is refused
 at registration, naming the field that would deliver it. A test: such a manifest is refused; adding
 `loads` admits it.
+
+## Resolved
+
+A bundle nothing would deliver is refused at registration, by name. Proven by the controller's tests; the catalogue's bundles all name what the runtime loads (mesh-catalog#243).

04-ISSUES/217-a-refused-announcement-took-down-every-containers-runtime/00-report.md

@@ -1,9 +1,11 @@
 ---
-status: located
+status: resolved
 opened: 2026-10-03
 located-in:
   - mesh-tools
 fixed-by:
+  - mesh-tools#42
+  - mesh-tools#43
 amended-design:
 ---
 
@@ -50,3 +52,7 @@ announcement subscriptions are allowed for every principal kind.
 
 Recovered on the day without the forge's API: the toolchain images built by the controller straight
 from the fix branch, every module image rebuilt on them, and the machine pushed.
+
+## Resolved
+
+A refused announcement is logged and the runtime serves on, and every runtime subscribes only the discovery subjects its grants allow. Proven 2026-10-04: after rolling out to every machine, no container restarts anywhere, and the discovery console lists no runtime as not answering. A refused tool subscription was made non-fatal the same way afterwards, under issue 218 (mesh-tools#46).

04-ISSUES/218-a-mesh-seat-is-answered-by-a-module-that-does-not-hold-it/00-report.md

@@ -1,9 +1,13 @@
 ---
-status: located
+status: resolved
 opened: 2026-10-03
 located-in:
   - mesh-controller
-fixed-by: mesh-controller#248
+  - mesh-tools
+fixed-by:
+  - mesh-controller#248
+  - mesh-tools#45
+  - mesh-tools#46
 amended-design:
 ---
 
@@ -63,3 +67,26 @@ and memberships come from the same list, so they cannot disagree.
 seats and loses the recorded mesh seat. Live, the discovery console's overview must show each
 mesh-scoped seat announced from exactly the holder the records name. Status moves to `resolved` once
 that holds after the fix is rolled out.
+
+## A second cause, and what the rollout broke (2026-10-04)
+
+With the grants corrected, calls to the store reached only the holder, yet the console still showed
+the seat announced from both machines. The module's runtime added every seat its start-up credential
+claims, even after the mesh issued a membership that left the seat out. Once a membership exists,
+it now alone decides which seat verbs a runtime serves (mesh-tools#45).
+
+The rollout then exposed a third fault. The module on the machine that does not hold the seat was
+still running an image built before #45, so it subscribed to the seat's subject. The corrected grants
+refused that subscription, and the refusal ended the process. Its runtime crash-looped until the
+module was rebuilt on the new runtime image. The database itself kept running. A refused tool
+subscription is now logged and costs only that subject (mesh-tools#46), as a refused announcement
+already did ([issue 217](../217-a-refused-announcement-took-down-every-containers-runtime/00-report.md)).
+
+The module was not rebuilt by the plan that rebuilt the runtime image. This is the ordering gap of
+[issue 211](../211-a-bundle-is-built-before-the-toolchain-it-is-compiled-in/00-report.md) seen
+from a container module.
+
+**Proven 2026-10-04.** The discovery console's overview shows the store seat announced from the
+recorded holder only. Repeated calls to the store are answered by that machine, and the answers
+include the controller's own database. The non-holder still answers its own module tools. No
+container restarts on any machine.

04-ISSUES/219-an-older-build-that-finishes-later-replaces-a-newer-one/00-report.md

@@ -0,0 +1,48 @@
+---
+status: resolved
+opened: 2026-10-04
+located-in:
+  - mesh-controller
+fixed-by:
+  - mesh-controller#249
+amended-design:
+---
+
+# 219 — An older build that finishes later replaces a newer one
+
+## What was observed
+
+2026-10-03. Two merges to the runtime module came minutes apart. Each plan asked for every module
+built on the runtime image to be rebuilt. One module's two builds were of the same source and
+differed only in the runtime image they stood on:
+
+| Build | Requested | Finished | Stood on |
+|---|---|---|---|
+| asked by the first plan | 21:33 | 22:04 | the runtime image before the fix |
+| asked by the second plan | 21:49 | 21:56 | the runtime image with the fix |
+
+The older request finished last, and its image became the module's current artifact. The next push
+deployed it, and the module's runtime crash-looped on a fault the newer image had already fixed
+([issue 218](../218-a-mesh-seat-is-answered-by-a-module-that-does-not-hold-it/00-report.md)).
+
+## Why it matters beyond this instance
+
+Which build is current should follow what it was built from, not which build machine was slowest.
+Whenever two plans overlap, which happens on any busy evening, a fix can be silently reverted by a
+build that started before it existed. Every passing check still passes.
+
+## Where to look
+
+How a finished build is recorded and how a module's current artifact is chosen. **How it is checked:**
+a test in which an older request completes after a newer one for the same artifact, and the newer
+stays current.
+
+## Resolved
+
+A build is ordered by when it was requested, read from the id the controller gives it, and a
+module's registered manifest is replaced only by a build requested at or after the one it came from.
+An older request finishing later is recorded and changes nothing; a plan settles only from builds it
+asked for itself. **How it is checked:** store-backed tests replay the incident — the newer request
+stays what the module is — and fail without the fix. Live since 2026-10-04: the rebuilds of every
+runtime-image module and the three waves of module code moves since then each registered the build
+they asked for.

04-ISSUES/220-a-delivered-bundle-keeps-the-files-of-the-one-before/00-report.md

@@ -0,0 +1,41 @@
+---
+status: resolved
+opened: 2026-10-04
+located-in:
+  - mesh-host
+fixed-by:
+  - mesh-host#84
+amended-design:
+---
+
+# 220 — A delivered bundle keeps the files of the one before
+
+## What was observed
+
+2026-10-04. A tools bundle was rebuilt as one self-contained file per entrypoint
+([ADR 0193](../../02-DECISIONS/0193-every-bundle-the-runtime-serves-is-launched-and-the-runtime-knows-no-language.md)),
+so it no longer carries a package directory. On the machine it was delivered to, its directory still
+held the package directory and a compiled file from the earlier delivery, dated hours before the
+new files. The new files were written over the old directory, and nothing removed what the new
+bundle no longer contains.
+
+## Why it matters beyond this instance
+
+A bundle on disk should be exactly the artifact that was built. Leftover files can be imported by
+code that should no longer find them. A fix that removes a file then works on a fresh machine and
+fails on every machine that ran an earlier version. It also makes "what runs here" impossible to
+read from the artifact.
+
+## Where to look
+
+How the host unpacks a bundle into its directory. **How it is checked:** deliver a bundle, then a
+version without one of its files, and the file is gone.
+
+## Resolved
+
+An archive is unpacked into a fresh directory beside the old one and swapped in by rename; a refused
+or failed unpack leaves the old tree whole. **How it is checked:** a second delivery without a file
+removes it, and nothing is left beside the directory; both tests fail without the fix. Proven
+2026-10-04: a bundle rebuilt and delivered after the fix holds exactly the new build and nothing
+beside it. A bundle that has not changed since keeps its old leftovers until its next version, by
+design: an unchanged archive is not unpacked again.

04-ISSUES/221-a-build-machine-learns-a-new-builder-only-from-a-push/00-report.md

@@ -0,0 +1,52 @@
+---
+status: resolved
+opened: 2026-10-04
+located-in:
+  - mesh-controller
+fixed-by:
+  - policy: `upgrade build-agent roll-out` (2026-10-04)
+amended-design:
+---
+
+# 221 — A build machine learns a new builder only from a push
+
+## What was observed
+
+2026-10-04. A controller merge changed how TypeScript bundles are built: one file per entrypoint
+instead of a package directory. Its plan finished, and six bundles were rebuilt right after. They
+came out in the old shape, because the build machines still ran the previous builder. They got the
+new one only from the next push. Rebuilt after that push, the same six came out right.
+
+The same order showed in the bus grants the same night. A push sent while the controller was still
+the previous build composed grants with the previous code. A second push was needed after the new
+controller had started.
+
+## Why it matters beyond this instance
+
+A merge to the controller is not in effect when its plan says done. Anything built or pushed in the
+gap uses the old code and looks current. Today only the operator knows to push first and build
+second, and even the operator forgot.
+
+## Where to look
+
+Whether a controller plan should end by delivering itself to the build machines and the control
+machine, or whether a build should refuse a builder older than the controller that asked for it.
+**How it is checked:** after a controller merge, a build asked right after its plan finishes runs
+the new builder.
+
+## Located
+
+The mechanism existed: a module whose upgrade policy is `roll-out` is sent to its machines when its
+tier is built, and the plan's next tier waits until it is applied. The build agent's policy was
+`record` — built, never sent — as was that of 76 other modules, which is why every rollout on
+2026-10-03 needed a push by hand. The build agent was set to `roll-out`, one machine at a time,
+stopping at the first failure. **How it is checked:** the next controller merge's plan sends the
+build agent to the build machines before its last tier, and a build asked right after the plan
+finishes runs the new builder; then this moves to resolved. Whether the other modules roll out is
+the operator's policy, not this issue's.
+
+## Resolved
+
+Proven 2026-10-04: the next controller merge's plan logged that its first tier was built and the
+build agent sent to all four build machines, and only then asked its next tier. The builder change
+in that merge reached the build machines without a hand push.

04-ISSUES/222-an-assignment-is-refused-on-the-bus-until-the-bus-machine-is-pushed/00-report.md

@@ -0,0 +1,51 @@
+---
+status: resolved
+opened: 2026-10-04
+located-in:
+  - mesh-tools
+fixed-by:
+  - mesh-tools#47
+amended-design:
+---
+
+# 222 — An assignment is refused on the bus until the bus's machine is pushed
+
+## What was observed
+
+2026-10-04. A module was assigned to the laptop, and the laptop alone was pushed. The module's two
+bundles arrived and the node's runtime launched both, and then the bus refused every one of the
+module's subjects:
+
+```
+nats: permissions violation: Permissions Violation for Subscription to "mesh.mod.<module>.tool.<tool>.<node>"
+```
+
+The tools were unreachable until a later push that included the machine running the bus. Then the
+runtime served them without a restart, because a new membership arrived and it re-subscribed.
+
+## Why it matters beyond this instance
+
+What an account may answer lives in the bus's user list, and the controller writes that list only
+into the declaration of the machine that runs the bus. Assigning anything to any machine changes
+that list, so `push <machine>` after `assign <machine> <module>`, which is what the controller itself
+tells the operator to run, leaves the module running and unreachable, with nothing reporting a fault.
+
+## Where to look
+
+Whether a push to one machine should also send the bus's machine when the user list it would
+compose differs from the one that machine holds. **How it is checked:** assign a module with tools
+to a machine that does not run the bus, push only that machine, and its tools answer.
+
+## Diagnosed and resolved
+
+The push did send the bus's machine: the controller's log shows both machines applying in the same
+second. The fault was the order within that second. The node's runtime subscribed before the bus
+had reloaded its user list, the bus refused, and the bus client marks a refused subscription dead.
+Nothing asked again until a later membership happened to re-serve the module.
+
+A subject the runtime answers on is now asked for again when the bus refuses it, after waits from
+two seconds to two minutes, and given up and said after about five minutes. **How it is checked:**
+a test refuses a subject and finds it asked for again and answering, given up past its attempts,
+and not asked again once stopped; and by hand against a bus whose permissions were reloaded while
+connected, the runtime answered two seconds after the grant arrived, where the runtime before the
+fix never answered.

04-ISSUES/223-a-new-mesh-installs-its-controller-as-a-container/00-report.md

@@ -0,0 +1,60 @@
+---
+status: resolved
+opened: 2026-10-04
+located-in:
+  - mesh-host
+fixed-by:
+  - mesh-host#87
+amended-design:
+---
+
+# 223 — A new mesh installs its controller as a container
+
+## What was observed
+
+2026-10-04. Preparing [issue 213](../213-the-controller-is-a-go-program-run-in-a-container/00-report.md),
+the controller's own manifest was changed to a Go bundle run as a process. The installer that raises a
+new mesh assumes the controller is an image and a container at every step from its third on:
+
+- it requires the controller's build to produce exactly one image;
+- it starts a temporary controller from that image, and publishes the image to the registry;
+- at the pivot, it finds the controller's container in the declaration, reads its environment and
+  volumes, waits for it, and from then on talks to the controller only through the container.
+
+## Why it matters beyond this instance
+
+With the controller's manifest changed, a new mesh cannot be installed: the pivot fails. The deeper
+constraint is ordering. A process's bundle is fetched from the artifact store, and the installer
+raises the artifact store only after the pivot, so the controller's first declaration names a bundle
+nothing can serve yet.
+
+## What a fix has to settle
+
+One of two shapes, and it is a decision, not a repair:
+
+1. raise the artifact store before the pivot, publish the controller's bundle to it, and talk to the
+   controller from the host's side rather than through a container; or
+2. pivot to the image form as today, and let the first push hand over to the process, which
+   requires the controller's manifest to carry both forms.
+
+Until it is settled, the change of the controller's manifest (mesh-controller#253) is held. The
+handover itself is built and merged (mesh-host#86); the controller's half (mesh-controller#252) waits
+on the operator. **How it is checked:** the installer's test raises a mesh whose controller manifest
+is the process form, and the controller answers its seat's verbs at the end.
+
+## Decided (2026-10-04)
+
+Option 2, [ADR 0200](../../02-DECISIONS/0200-genesis-pivots-to-the-controller-as-a-container-and-the-first-push-hands-it-to-a-process.md):
+genesis pivots to the controller as a container recorded under the name the process `replaces`, and
+the first push hands it over.
+
+## Resolved
+
+Built as [ADR 0200](../../02-DECISIONS/0200-genesis-pivots-to-the-controller-as-a-container-and-the-first-push-hands-it-to-a-process.md)
+decided: genesis reads only the controller's process from the manifest, builds the controller's image
+from its repository, and pivots to a container of its own shape recorded under the id the process
+`replaces`; an older controller in the image form still builds as before. **How it is checked:** the
+installer's tests build the genesis form from the controller's real manifest, and apply the
+controller's first process declaration over the recorded container with the host's own apply — the
+process starts, the container is removed, one controller remains. A real install from nothing has not
+been run since; the handover it ends in was proven live on the running mesh (issue 213).