Merge pull request 'Issue 244: located — the console drops a mesh seat's node, and a push ran on every machine' (#121) from issues/244-located into main

The same empty schemas recurred for push, plan, assign, pin and settings;
for push the dropped machine became a push of the whole mesh. Record the
evidence, the cause in the console's address form, and the open fixes.

00-META/glossary.md

@@ -7,7 +7,7 @@ another — and a mesh you cannot name precisely is a mesh two people describe d
 
 ## The mesh and its machines
 
-- **node** — a machine in the mesh. There are 0..n of them, and each runs the host agent. A node is
+- **node** — a machine in the mesh. There are 0..n of them, and each runs the node-engine. A node is
   just a machine that has joined; being one implies nothing about what it runs.
 - **operator account** — the login name of the person who works on a node, stated on the node
   record; empty for a machine nobody logs into. Everything the mesh places under a person's home is
@@ -28,6 +28,13 @@ another — and a mesh you cannot name precisely is a mesh two people describe d
   control-plane/data-plane, and opaque here).
 - **mesh-controller** — the module that runs the controller. It **claims** the `mesh-controller`
   seat at mesh scope, which is what makes it singular. Replaces the module name **`mesh-control`**.
+- **node-engine** — the program on every node that applies what the controller declares: it receives the
+  node's declaration, writes the files, runs the services and containers, and reports what it did. It
+  is the engine, not a module: it owns no file's content, and every file it writes belongs to the module
+  that declared it. Replaces **"host agent"**, **"the host"** and **`mesh-host`**. *Agent* is avoided
+  because the word already means two other things here, the build agent and the operator's coding
+  agent. The code still carries the old name (the `mesh-host` repository, its binary and service
+  unit) until the rename is made there; a record written before the rename keeps the old name.
   (The git repository has been renamed `mesh-control` -> `mesh-controller` on the forge; the module,
   container and image it produces are `mesh-controller`.)
 - **foundation** — the store and the broker, raised at genesis before any module system exists.
@@ -73,7 +80,8 @@ another — and a mesh you cannot name precisely is a mesh two people describe d
   The set, with who holds each seat, is the overview of what a mesh has
   ([26 — The seats](../03-DESIGN/01-to-be/26-the-seats.md)). A seat has a **capacity**: a
   capacity-1 seat is exclusive (one holder); a higher-capacity seat is a **bench** (several holders
-  coexist).
+  coexist). The first bench is `mesh-dns-resolver`, a *replicated* mesh seat: one holder per machine,
+  each on record and each answering the same names ([ADR 0223](../02-DECISIONS/0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md)).
 - **claim** — a module taking a spot on a seat. `claims: [{name, scope}]` in a manifest. A
   mesh-scoped exclusive claim is how the mesh says "there is one of me". A foundation seat is
   named after the server it guards: the `mesh-controller`, `postgres` and `lavinmq` modules claim

02-DECISIONS/0082-the-registry-is-reached-by-name-and-trusted-by-the-overlay.md

@@ -51,6 +51,14 @@ the builder) — cost with no new property.
    restarts the runtime when that file changes — the `/etc/hosts` pattern for the content, the
    nftables pattern for the reload. No module author is involved; being on the network is what
    grants the trust, because being on the network is what the trust *is*.
+
+   > **The mechanism changed — 2026-10-05, by [ADR 0222](0222-a-module-is-told-where-a-mesh-seats-holder-is-reached-and-the-controller-writes-no-file-a-seats-holder-owns.md).**
+   > What stands: being on the network grants the trust, the overlay is the transport security, no
+   > module author chooses it, and the trust is written into the runtime's file rather than over it
+   > and reloaded rather than restarted (ADR 0102). What moved: the controller no longer injects the
+   > file or the service. The container runtime's own module writes `insecure-registries`, told where
+   > this machine reaches the store by `${seat:mesh-artifact-store:reach}`, because the controller
+   > writes no file a seat's holder owns ([issue 190](../04-ISSUES/190-the-runtimes-configuration-is-written-by-modules-that-are-not-the-runtime/00-report.md)).
 3. **No accounts (issue 042), recorded as the position it always was.** Reading and pushing
    require presence on the overlay and nothing else. The boundary is enforced, not assumed: the
    registry's `listens` is `from: mesh`, the firewall derives from it, and the overlay admits only

02-DECISIONS/0083-one-push-leaves-the-mesh-consistent.md

@@ -45,6 +45,13 @@ an operator obligation, and an obligation enforced by nothing is issue 057 resta
 declaration is computed from the whole mesh; delivering a mesh that is knowingly inconsistent and
 merely saying so would make "push succeeded" mean less than it says.
 
+> **The mechanism changed — 2026-10-05, by [ADR 0221](0221-a-push-sends-no-build-a-policy-or-a-plan-holds-back-except-to-the-machine-it-names.md).**
+> A named push still flushes every other machine that is behind, compared against what each was last
+> sent. A machine whose modules would move to a build their upgrade policy records, or that an open plan
+> has not sent it yet, is no longer flushed: the push names it and leaves it for `push <node>`. "Behind
+> for an unrelated reason" no longer covers a held upgrade
+> ([issue 259](../04-ISSUES/259-a-named-push-sent-every-machine/00-report.md)).
+
 ## Consequences
 
 - One push is sufficient for a cross-node consumer: the provider's grants arrive from the same

02-DECISIONS/0102-the-mesh-writes-into-a-shared-file-never-over-it.md

@@ -64,6 +64,15 @@ node therefore trusts the mesh's registry as soon as it is on the private networ
 networking no longer touches the runtime. The hosts file networking writes is still written whole
 and stays held until networking is taken; a converge preview names it among the files it replaces.
 
+> **The mechanism changed — 2026-10-05, by [ADR 0222](0222-a-module-is-told-where-a-mesh-seats-holder-is-reached-and-the-controller-writes-no-file-a-seats-holder-owns.md).**
+> Writing into a shared file, adding to a list and reloading rather than restarting all stand. What
+> moved is the writer: the networking module no longer writes the runtime's trust or declares its
+> service. The container runtime's own module writes it into its own file and reloads its own
+> service ([issue 190](../04-ISSUES/190-the-runtimes-configuration-is-written-by-modules-that-are-not-the-runtime/00-report.md)).
+> The controller test named under *How it is checked* below, which held the networking module to
+> declaring the runtime's file, is replaced by one holding the networking module to declaring neither,
+> and by one holding the runtime's module to the trust.
+
 ## Consequences
 
 - The runtime's file on a machine in use keeps its data directory, its logging settings and

02-DECISIONS/0189-the-store-keeps-what-the-records-name.md

@@ -60,6 +60,14 @@ with the server held still for its duration. Plain collection, not `--delete-unt
 mesh keeps is still a manifest in the store, so it is still referenced, so its blobs stay — the
 dangerous flag is not needed at all once the mesh is the one deciding.
 
+> **Progressive insight — 2026-10-05.** "What the mesh keeps is still a manifest in the store" was true
+> of images and false of archives: the builder published every archive as a bare blob no manifest names,
+> and the store's collector keeps only what a manifest names. Its first night would have deleted every
+> archive the mesh keeps ([issue 253](../04-ISSUES/253-the-stores-collector-would-delete-every-archive-the-mesh-keeps/00-report.md)).
+> The decision stands — the mesh decides, the store reclaims with plain collection. What changes is how an
+> archive is published: with a manifest that holds it, so the sentence becomes true of archives too. Until
+> every kept archive is held, the collector runs as a dry run.
+
 **3. What the mesh keeps, stated as three reasons rather than a number.** A digest is kept because:
 
 - **a definition names it** — every artifact reference in any module's current recorded manifest,

02-DECISIONS/0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md

@@ -11,6 +11,11 @@ extends: 0191-the-meshs-resolver-holds-only-the-meshs-own-names.md
 
 # 194. The mesh has one resolver, and every node asks it for the mesh's names
 
+> **The mechanism changed — 2026-10-05, by [ADR 0223](0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md).** `mesh-resolver` (named `mesh-dns-resolver` in the
+> set) is no longer of capacity one: it is a replicated seat, held on the anchor and on the home
+> server, each holding every node's internal domain from the same roster. One resolving module, the
+> mesh's names held only by its holders, and the retirement of every per-node copy stand.
+
 > **Narrowed, not replaced — 2026-10-03.** How a node asks is decided again by
 > [ADR 0196](0196-a-node-asks-the-meshs-resolver-first-and-a-public-one-only-when-it-is-silent.md): every
 > node and container asks `mesh-resolver` first and a public resolver only when it is silent. There is

02-DECISIONS/0196-a-node-asks-the-meshs-resolver-first-and-a-public-one-only-when-it-is-silent.md

@@ -10,6 +10,13 @@ supersedes-in-part:
 
 # 196. A node asks the mesh's resolver first, and a public one only when it is silent
 
+> **Narrowed, not replaced — 2026-10-05, by [ADR 0223](0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md).** The public resolver listed second goes: musl asks
+> every listed server at once and takes the first reply, so a public "no such name" for a mesh name
+> won it, and every Alpine build on the home server failed. Every machine now lists the mesh's
+> resolvers — two holders of `mesh-dns-resolver`, its own first on a holder — and nothing else. Every
+> node and container asking the mesh's resolver for every name, with no stub and no runtime `dns`,
+> stands. The "fallback" consequence and check below describe what this record decided, not what runs.
+
 ## Context
 
 **[ADR 0194](0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md) gave the

02-DECISIONS/0199-a-module-that-answers-names-declares-its-zone-and-a-nodes-hosts-file-is-one-modules.md

@@ -9,6 +9,10 @@ extends: 0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-nam
 
 # 199. A module that answers names declares its zone, and a node's hosts file is one module's
 
+> **Decided to change — 2026-10-05, by [ADR 0223](0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md), not yet built.** The `hosts` module is renamed `hostname`
+> and its seat `node-hostname`, and it owns `/etc/hostname` as well as `/etc/hosts`; the operator's
+> lines are kept as this record decides. Until that is built, everything below stands as decided.
+
 ## Context
 
 **[ADR 0194](0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md) and

02-DECISIONS/0218-a-plan-sends-grants-before-code-rolls-out-one-machine-first-and-a-newer-merge-takes-over-an-older-plan.md

@@ -0,0 +1,100 @@
+---
+topic: the mesh
+status: accepted
+date: 2026-10-05
+deciders: jochen
+reconstructed: false
+extends: 02-DECISIONS/0162-a-merge-produces-a-tiered-plan-the-mesh-keeps.md
+---
+
+# 218. A plan sends grants before code, rolls a module out one machine first, and a newer merge takes over an older plan
+
+## Context
+
+On 2026-10-05 the delivery path was watched through a day of merges, by several sessions at once. Three
+things went wrong, each recorded as an issue with its evidence.
+
+- **Code arrived before the right to use it** ([issue 249](../04-ISSUES/249-a-modules-new-state-is-refused-until-a-push-the-merge-did-not-make/00-report.md)).
+  A merge gave a module a new key-value state. The plan sent the new bundle to every machine, and only
+  then issued the memberships that grant the state. On three machines the module's new state was refused
+  for two minutes, until a push made by hand. The order is written into the code on purpose: memberships
+  "after the declaration, because the runtime it is for arrives with it". That reason holds only for a
+  first assignment, and even then a membership is kept on the bus for the runtime that connects later
+  ([ADR 0160](0160-the-mesh-issues-an-assignments-subjects-and-a-runtime-serves-what-it-is-issued.md)).
+- **No machine went first.** The module's upgrade policy sends one machine at a time, but a plan's rollout
+  ignores it and sends every machine running the module at once. One at a time also never waited for the
+  first machine to come up healthy: it stopped only if the publish itself failed. A change was therefore
+  everywhere before anything had seen it run.
+- **Plans for successive merges ran over each other** ([issue 254](../04-ISSUES/254-plans-for-successive-merges-run-over-each-other-and-one-was-left-open/00-report.md)).
+  Three merges to the catalogue within four minutes made three plans. Each sent the build agent to every
+  machine and asked for the same builds. One was still "building" hours later, with nothing left for it to
+  wait on. [ADR 0162](0162-a-merge-produces-a-tiered-plan-the-mesh-keeps.md) decides one plan per merge
+  and says nothing about the next merge arriving while one is open. [Issue 219](../04-ISSUES/219-an-older-build-that-finishes-later-replaces-a-newer-one/00-report.md)
+  settled only which build's output wins.
+
+## Considered Options
+
+1. **Debounce merges:** wait a window before planning, so close merges make one plan. Rejected: it only
+   delays the overlap, does nothing for merges further apart than the window, and makes every merge slower.
+2. **Queue plans:** a new plan waits until the older one is done. Rejected: the older plan builds what the
+   newer merge is about to replace, then the newer one builds it again.
+3. **A newer merge's plan takes over the older plan's unfinished work, a plan rolls a module out one
+   machine first, and grants travel before code.** Chosen.
+
+## Decision
+
+**1. Grants before code.** Every send — a plan's rollout and a push alike — issues the memberships for
+the machines it is about to send to before it sends their declarations, after raising the buckets they
+name. When the composed list of bus users changes, the machine that holds the bus is sent first, because
+that list travels in its declaration. A membership that could not be issued fails the send, and the send
+is tried again. It is never reported as done "until the next push".
+
+**2. One machine first.** A plan rolls a module out according to the module's upgrade policy
+([ADR 0162](0162-a-merge-produces-a-tiered-plan-the-mesh-keeps.md) §3). Unless the policy says
+*together*:
+
+- the module is sent to one machine first, the first by name of the machines running it;
+- the rest are sent only once that machine has reported the new declaration applied and current;
+- a first machine that reports a failure, or does not report in time, stops the module's rollout there.
+  The plan names the machine and the reason, and the other machines keep what they ran.
+
+The plan records which machine went first, so a controller replaced mid-rollout resumes from there. A
+policy of *together* keeps today's behaviour.
+
+**3. A newer merge takes over an older plan.** When a merge into a repository's branch makes a plan,
+every open plan for the same repository and branch made before it is superseded, ordered by when each
+plan was made, never by commit:
+
+- the modules the older plan had not yet built join the newer plan's set, before its tiers are computed;
+- the older plan ends in a state of its own, *superseded*, naming the plan that took it over.
+
+Builds the older plan already asked for still finish and register; issue 219's ordering keeps the newer
+one current. A person can also close a plan that waits on nothing, by its id. The plan is marked closed
+by hand and never resumed.
+
+## Consequences
+
+- A module that gains a state, an event or a tool can use it from its first start on every machine.
+- A change reaches one machine before the rest. A change that breaks its first machine stops there, with
+  the reason in the plan.
+- Successive merges build each module once, for the newest commit. The build agent is sent to the
+  machines once per run of merges, not once per merge.
+- **What got harder:** a rollout takes one machine's report longer than before. A module that must change
+  everywhere at once says *together* in its policy. A plan's record now has a superseded state that
+  readers of the plans must know.
+
+## How it is checked
+
+| Rule | Checked by |
+|---|---|
+| grants before code | the controller's test: a send records memberships issued before any declaration; the machine holding the bus is sent first when the user list changes; a failed membership fails the send |
+| one machine first | the controller's test: with a one-at-a-time policy, one machine is sent, the rest only after its applied and current report; a failed first machine stops the module; *together* sends all at once |
+| a newer merge takes over | the controller's test: an older open plan for the same repository and branch is superseded, its unbuilt modules folded in; a plan for another repository is left alone; a superseded plan is not open |
+| live | the next merge to the catalogue that gives a module a new state: no refusal of that state on any machine, the first machine named in the plan, one plan open per repository |
+
+## References
+
+- [Issue 249](../04-ISSUES/249-a-modules-new-state-is-refused-until-a-push-the-merge-did-not-make/00-report.md), [issue 254](../04-ISSUES/254-plans-for-successive-merges-run-over-each-other-and-one-was-left-open/00-report.md)
+- [ADR 0162](0162-a-merge-produces-a-tiered-plan-the-mesh-keeps.md) — plans and tiers, extended here
+- [ADR 0160](0160-the-mesh-issues-an-assignments-subjects-and-a-runtime-serves-what-it-is-issued.md) — memberships, kept on the bus
+- [to-be 30](../03-DESIGN/01-to-be/30-the-mesh-updates-itself-on-a-push.md) — the design this amends

02-DECISIONS/0219-the-build-queue-is-controlled-through-the-controller-and-the-build-seat.md

@@ -0,0 +1,120 @@
+---
+topic: the mesh
+status: accepted
+date: 2026-10-05
+deciders: jochen
+reconstructed: false
+extends: 02-DECISIONS/0190-a-seats-work-is-shared-by-its-holders-and-building-is-the-first-such-role.md
+---
+
+# 219. The build queue is controlled through the controller and the build seat
+
+## Context
+
+The operator asked for tools to control the mesh's builds: see what is queued and running, cancel,
+clear, stop a build immediately, pause and continue, restart and replay. On the day of the request none
+existed. The controller could ask for a build and list finished ones. Nothing could see an ask waiting on
+the build seat's work queue, or one being built. Nothing could take an ask back, and a running build
+could only be stopped by restarting the machine's build agent, which hands the ask to another holder.
+
+How builds run today, read from the code and the bus
+([ADR 0190](0190-a-seats-work-is-shared-by-its-holders-and-building-is-the-first-such-role.md),
+[ADR 0157](0157-a-build-says-what-it-does-on-the-bus-as-it-happens.md)):
+
+- an ask is a message on the seat's work-queue stream;
+- every holder pulls one at a time from one shared worker, and acknowledges after it has announced the
+  outcome;
+- a build says it started, logs its steps, and announces what it built, all on the bus;
+- an ask delivered five times without an answer stays in the stream for a week, with nothing saying so.
+
+Three facts constrain any control:
+
+- **Only the controller may act on the bus's streams and consumers** (design 25 §3, enforced in the bus's
+  user list). Holders may only take from their worker and acknowledge.
+- **A plan waits for a build's outcome and has no timeout.** An ask that disappears without one leaves
+  its plan waiting, said only as late after half an hour.
+- **The bus server in use cannot pause a consumer**; that arrived in a later version.
+
+## Considered Options
+
+1. **Pause and cancel by remaking the worker consumer.** Rejected: a remade worker delivers from now on,
+   so every queued ask would be skipped silently. Issues 206 and 207 are this mistake both ways round.
+2. **Upgrade the bus first and use its consumer pause.** Not now: it gives pause and continue, and
+   nothing else on the list, and upgrading the bus is a change of its own.
+3. **Queue actions are the controller's verbs, process actions are the build seat's verbs, and every
+   action that drops work leaves a failed outcome.** Chosen.
+
+## Decision
+
+**1. The queue is the controller's.** Its verbs act on the work-queue stream, the one thing only it may
+touch:
+
+| verb | what it does |
+|---|---|
+| `queue` | lists every ask: waiting, in flight (with the machine building it, from its started event), and dead (delivered as often as allowed, still in the stream) |
+| `cancel <id>` | takes back a waiting or dead ask; an ask in flight is refused, and `kill` is named instead |
+| `clear` | cancels every waiting ask, and with `--dead` every dead one |
+| `rebuild <module or build>` | asks again for a module's current source, or a past build's source and ref, under a new id |
+| `replay <build>` | asks again for a past build at its commit, as a **dry run** unless told to register |
+| `kill <id>`, `pause [node]`, `resume [node]` | pass the request on to the build seat on the right machine, or on every machine |
+
+**2. The process is the build seat's.** Each holder serves verbs on its own machine:
+
+- `current`: the build running here, its step and how long, and whether this holder is paused;
+- `kill`: stops a running build at once. The build's whole process group is ended, along with every
+  container it started. Its outcome is announced as failed, and the ask is acknowledged, so it is not
+  delivered again;
+- `pause` and `resume`: a paused holder takes nothing new, and a running build finishes. The flag
+  survives the holder's restart.
+
+A holder restarted mid-build keeps today's behaviour: the ask is not acknowledged, and another holder
+takes it.
+
+**3. Nothing dropped is silent.** Cancel, clear and kill each leave a failed outcome for the ask's id,
+taken in like any other. A plan waiting on that build fails, and says why, instead of waiting. A plan keeps
+the id it asked for, so it can match its outcome exactly. A holder checks a cancelled ask before it builds
+it, so an ask taken in the instant it was cancelled is not built.
+
+**4. A plan says what its builds are waiting on, and a failed plan can go on.**
+
+- A plan whose build waits on a paused seat says the seat is paused, and on which machines, and is not
+  counted late while it waits.
+- `plans retry <id>` asks again for the modules a failed plan could not build, under new ids. The plan
+  resumes at that tier and goes on through its later ones. A plan another has superseded, or one
+  already done, is refused.
+- `rebuild` of a module that an open or failed plan has not yet built joins that plan, so the plan and
+  the build are one thing.
+
+**5. Replay does not move the mesh backwards unasked.** A replayed build is a dry run: built, its log
+kept, nothing registered. With `--register` it is registered. If a newer build of the module is already
+registered, that is refused unless `--older` is said as well: registering an older commit makes it the
+current one, and the rollout policy sends it to the machines ([issue 207](../04-ISSUES/207-a-re-made-worker-replayed-every-ask-the-stream-kept/00-report.md)).
+
+## Consequences
+
+- Every build in the mesh can be seen, taken back, stopped or asked again from the console. None of it
+  needs a shell on a machine.
+- A cancelled or killed build shows in the build records as failed, with who stopped it. Its plan fails
+  saying the same.
+- **What got harder:** a holder now serves verbs as well as taking work, and keeps one small flag on
+  disk. Pause is per holder, so "pause the mesh" is the controller asking every holder in turn. A holder
+  away at the time misses it, and the answer names that holder.
+
+## How it is checked
+
+| Rule | Checked by |
+|---|---|
+| the queue is read and classified right | the controller's test: waiting, in flight and dead asks told apart from the stream and the worker; a live test on a throwaway bus |
+| nothing dropped is silent | the controller's test: cancel and clear delete the ask and record a failed outcome; a plan asked for that id fails |
+| a cancelled ask is not built | the holder's test: an ask taken after its cancel is answered failed without building |
+| kill stops everything it started | the holder's test: the build's process group and its labelled containers are ended; the outcome is failed and the ask acknowledged |
+| pause survives a restart | the holder's test: the flag is read back at start, and nothing is taken while it is set |
+| plans follow the queue | the controller's test: a plan waiting on a paused seat says so and is not late; `plans retry` resumes a failed plan and its later tiers are asked; `rebuild` joins the plan that holds the module |
+| replay is safe | the controller's test: a dry run by default, and `--register` over a newer build refused without `--older` |
+
+## References
+
+- [ADR 0190](0190-a-seats-work-is-shared-by-its-holders-and-building-is-the-first-such-role.md) — holders share the seat's work, one at a time
+- [ADR 0157](0157-a-build-says-what-it-does-on-the-bus-as-it-happens.md) — a build's own events are its record
+- [issue 207](../04-ISSUES/207-a-re-made-worker-replayed-every-ask-the-stream-kept/00-report.md) — a remade worker replayed every ask
+- [to-be 18](../03-DESIGN/01-to-be/18-building-a-module.md) — the design this amends

02-DECISIONS/0220-what-a-machine-asks-needs-its-uplink-held-and-the-retired-resolver-pieces-go.md

@@ -0,0 +1,161 @@
+---
+topic: what runs on it
+status: accepted
+date: 2026-10-05
+deciders: jochen
+reconstructed: false
+extends: 02-DECISIONS/0207-a-module-depends-on-the-node-seats-that-apply-its-resources.md
+---
+
+# 220. What a machine asks needs its uplink held, and the retired resolver pieces go
+
+> **Decided to go — 2026-10-05, by [ADR 0223](0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md), not yet built.** `/etc/resolv.conf` becomes the `node-uplink`
+> holder's file, and `resolv-conf`, `node-resolver-config` and this record's dependency of it on
+> `node-uplink` retire with it. Until that is built, everything below stands as decided.
+
+## Context
+
+**Three things about a machine's resolver were left half done when the mesh moved to one resolver.**
+On the production mesh on 2026-10-05, read from the controller's `seats` verb:
+
+- **`node-dns-resolver` has no holder on any node, and no module in the catalogue claims it.**
+  [ADR 0194](0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md) retired it
+  and the controller kept its row deliberately, *"deleted once nothing claims it"*, because removing a
+  seat a machine still holds makes that machine unresolvable. That condition now holds. The row still
+  stands in the controller's compiled set and in the store's seat table, and the overview still lists
+  it, unheld, beside the seats a mesh actually has.
+- **The rule that keeps `/etc/resolv.conf` the mesh's is checked by nothing.**
+  [ADR 0117](0117-a-machines-uplink-is-a-seat.md) found that a network manager rewrites the resolver
+  file on every connectivity change unless it is told not to, and gave that telling to the module
+  holding `node-uplink`. It said the condition *"only if NetworkManager runs"* is expressed by
+  assigning the manager's module. Nothing makes anybody do so: `resolv-conf` can be assigned to a
+  machine with no uplink holder, and the file is then replaced the first time a laptop changes
+  network while every surface of the mesh reads green. Today every node holding
+  `node-resolver-config` also holds `node-uplink` — NetworkManager on the home server, the
+  workstation and the laptop, systemd-networkd on the anchor — by care, not by check.
+- **The catalogue still carries a systemd-resolved split-DNS module**, `resolved-split-dns`, claiming
+  `node-resolver-config`. [ADR 0196](0196-a-node-asks-the-meshs-resolver-first-and-a-public-one-only-when-it-is-silent.md)
+  chose against a stub on every node and says *"There is no `systemd-resolved` module."* It is
+  assigned nowhere. `resolv-conf`'s own resolver file still tells its reader that systemd-resolved or
+  NetworkManager may be assigned *instead* — the opposite of how the roles now divide.
+
+**A dependency mechanism already exists.** [ADR 0207](0207-a-module-depends-on-the-node-seats-that-apply-its-resources.md)
+made a module depend on the node seats that apply its resources, derived rather than stated, judged
+over the node's whole set of assignments, refused at `assign` naming the seat and its possible holders,
+and refused at composition. [ADR 0210](0210-a-tools-configuration-is-its-seat-holders-and-every-other-module-extends-it-through-the-seat.md)
+derived a second kind from contributions. What is missing is a dependency that belongs to a *role*
+rather than to what a module declares.
+
+## Considered Options
+
+**For the retired seat:**
+
+1. **Keep the row until the build seat's retired row goes too, and delete both together.** Rejected:
+   the two have nothing in common but having been retired; one is unclaimed now and the other is not
+   yet known to be.
+2. **Remove it from the compiled set only.** Rejected: seeding adds a seat a release ships and never
+   removes one ([ADR 0122](0122-a-seat-is-data-a-rename-is-a-database-update.md)), so the store's
+   row, which is the live set, would stay.
+3. **Remove it from the compiled set and delete the store's row in a numbered migration**, as the
+   artifact store's rename did for its old row. Chosen.
+
+**For the resolver file and the uplink:**
+
+1. **Leave it to the operator.** Rejected: it is the failure ADR 0117 describes — the file silently
+   replaced — with the one difference that the operator was told.
+2. **`resolv-conf` declares the manager's settings itself.** Rejected by ADR 0117 already: which
+   setting depends on which manager runs, and a resolver module that knew about network managers would
+   be the wrong module knowing the wrong thing.
+3. **A manifest field in `resolv-conf` naming `node-uplink`.** Rejected for the reason ADR 0207
+   rejected its own option 2: a second module claiming the same seat would have to restate it, and
+   one that forgot would pass.
+4. **The seat carries what its holder needs beside it.** `node-resolver-config` names `node-uplink`;
+   any module claiming the former depends on the latter, derived from the claim and judged exactly as
+   ADR 0207 judges a resource's dependency. Chosen.
+
+**For the split-DNS module:** keep it for a machine that wants systemd-resolved in charge, or remove it.
+Kept, it is a second answer to a question ADR 0196 settled, and a claimant the catalogue offers
+without a record allowing it. Removed.
+
+## Decision
+
+**1. `node-dns-resolver` is deleted from the mesh's set.** The controller's compiled set no longer
+carries it, and a numbered migration of the controller's store deletes its row and any alias naming
+it. No alias is kept: nothing was renamed, and a manifest still claiming it should be refused at
+registration, naming the seat. This completes ADR 0194's retirement; nothing it decided changes.
+
+**2. A seat may name the node seats its holder needs held on the same node.** A module claiming such a
+seat depends on each of them. The dependency is a third source beside ADR 0207's resources and ADR
+0210's contributions, and everything ADR 0207 §3 and §4 say of those applies unchanged: met by any
+module assigned to the node, the claimant included; judged over the node's whole set; refused at
+`assign` naming the seat and the catalogue's possible holders; refused at composition; and only said,
+never refused, when no module in the catalogue could hold the needed seat. Unassigning the needed
+seat's last holder beneath a dependent is refused, naming the dependent. What a seat needs is part of
+the mesh's definition of the role: compiled with the set, never stored, as ADR 0212 keeps what a seat
+receives. Adding a need to a seat is a decision, recorded.
+
+**3. `node-resolver-config` needs `node-uplink`.** The holder that writes the resolver file is right
+only while the network manager is told to leave it alone, and that telling is the uplink holder's
+(ADR 0117). Every manager the catalogue knows — NetworkManager, systemd-networkd, dhcpcd — holds
+`node-uplink`, so the refusal always has a remedy to name.
+
+**4. `resolved-split-dns` leaves the catalogue.** `resolv-conf` is the only module claiming
+`node-resolver-config`. Its resolver file's comment says the uplink's holder is required beside it,
+rather than naming alternatives to assign instead.
+
+## Consequences
+
+- **The set reads as the mesh is.** Thirty-seven seats in the compiled set; the overview no longer
+  lists a role nothing can fill.
+- **A machine cannot be given the mesh's resolver file without its network manager being told to keep
+  off it.** A machine with no manager at all — a static configuration — needs the smallest holder,
+  `dhcpcd`, or a new module holding `node-uplink` for its way of configuring the link. That is the
+  point: such a machine has to say what manages its link before the mesh writes a file the manager
+  could overwrite.
+- **Order of assignment on a new machine**: the uplink holder before or with `resolv-conf`, in one
+  `assign` when together. On the production mesh nothing changes: every node already holds both.
+- **The uplink becomes harder to take away.** Unassigning a machine's manager module while
+  `resolv-conf` stays is refused; replacing one manager with another is one act assigning the new and
+  unassigning the old, or the dependent goes first.
+- **A machine wanting systemd-resolved has no module for it.** A future need for one is a new record,
+  not a revival of the removed module.
+- **Changing `resolv-conf`'s comment rewrites `/etc/resolv.conf` on every node once**, with the same two
+  nameserver lines and options; only the comment differs.
+- **The merge order matters.** The controller's tests read the catalogue beside them, and the two
+  changes are judged together: the controller's change and the catalogue's removal merge together,
+  the catalogue's first or in the same window, and the controller rolls out only once its test suite
+  passes against the merged catalogue.
+
+## How it is checked
+
+| Rule | Checked by |
+|---|---|
+| `node-dns-resolver` is not in the set, and the set has thirty-seven seats | mesh-controller's closed-set unit test on the compiled seats |
+| The store's row goes with it | the migration, and after rollout the controller's `seats` verb listing no `node-dns-resolver` |
+| `node-resolver-config` needs `node-uplink`, and a module claiming it depends on the uplink with nothing in its manifest | mesh-controller's seat-dependency tests on the seat definition and on a synthetic claimant |
+| What a seat needs survives loading the set from the store | a unit test loading the store's rows, which carry no such column |
+| `resolv-conf` without an uplink holder is refused at `assign`, naming `node-uplink` and its possible holders; beside one, or with one in the same act, it passes; a composition without one is refused | the same tests, and `assign` live |
+| Unassigning the uplink's last holder beneath `resolv-conf` is refused | an unassign test |
+| In the catalogue, `resolv-conf` depends on the uplink, dhcpcd, NetworkManager and systemd-networkd each hold it, and `resolv-conf` is the only claimant of `node-resolver-config` | a mesh-controller test reading the catalogue beside it |
+| Two modules deciding what a machine asks are still refused on one node | the resolver test, now with a synthetic second claimant |
+| Every node of the live mesh holding `node-resolver-config` also holds `node-uplink` | the controller's `seats` verb, read before this was decided and after it rolls out; `status` reports no unheld dependency |
+
+## References
+
+- [ADR 0194](0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md) — retired
+  `node-dns-resolver`; this record deletes it.
+- [ADR 0196](0196-a-node-asks-the-meshs-resolver-first-and-a-public-one-only-when-it-is-silent.md) — no
+  stub, and so no systemd-resolved module.
+- [ADR 0117](0117-a-machines-uplink-is-a-seat.md) — the uplink's holder keeps the manager off the
+  resolver file; this record makes that a checked dependency.
+- [ADR 0121](0121-a-system-seat-is-named-for-its-scope-and-modules-define-their-own.md) — serving and
+  asking as two seats.
+- [ADR 0207](0207-a-module-depends-on-the-node-seats-that-apply-its-resources.md),
+  [ADR 0210](0210-a-tools-configuration-is-its-seat-holders-and-every-other-module-extends-it-through-the-seat.md) — the dependency mechanism
+  this extends.
+- [ADR 0122](0122-a-seat-is-data-a-rename-is-a-database-update.md) — the set as data, which is why a
+  deletion is a migration.
+- [The seats](../03-DESIGN/01-to-be/26-the-seats.md) and
+  [connectivity §2](../03-DESIGN/01-to-be/08-connectivity.md), amended alongside.
+- mesh-controller `internal/catalogue/seats.go`, `internal/catalogue/seat_dependencies.go`, and the
+  store migration deleting the row; mesh-catalog `modules/resolv-conf`.

02-DECISIONS/0221-a-push-sends-no-build-a-policy-or-a-plan-holds-back-except-to-the-machine-it-names.md

@@ -0,0 +1,122 @@
+---
+topic: the mesh
+status: accepted
+date: 2026-10-05
+deciders: jochen
+reconstructed: false
+extends: 02-DECISIONS/0083-one-push-leaves-the-mesh-consistent.md
+---
+
+# 221. A push sends no build a policy or a plan holds back, except to the machine it names
+
+## Context
+
+[ADR 0083](0083-one-push-leaves-the-mesh-consistent.md) makes a named push finish what it starts. After
+the named machine is sent, every other machine whose declaration differs from what it was last sent is
+sent too. The case it was written for is a grant: assigning a consumer changes the provider's
+declaration on another machine. ADR 0083 accepted that a machine behind *for an unrelated reason* is
+flushed as well, and called that correct rather than a cost.
+
+On 2026-10-05 that reasoning met an upgrade policy
+([issue 259](../04-ISSUES/259-a-named-push-sent-every-machine/00-report.md)). A change to the resolver
+modules was merged with the policy `record`, so that each machine would take it only when pushed, one
+at a time: the anchor first, each checked before the next. `push <anchor>` sent all four machines the
+new build, and so did a later `push <laptop>`. A fault in the change
+([issue 260](../04-ISSUES/260-the-resolver-started-before-its-zones-file-existed/00-report.md)) was met
+on every machine at once.
+
+The cascade compares one digest per machine, and a digest cannot say why a machine differs. Under
+`record`, every machine running the module differs from the merge on, so every machine is flushed. The
+same holds for a plan's rollout under [ADR 0218](0218-a-plan-sends-grants-before-code-rolls-out-one-machine-first-and-a-newer-merge-takes-over-an-older-plan.md):
+while the plan waits on its first machine, the rest differ, and any named push elsewhere sends them the
+build the plan is holding. [Issue 249](../04-ISSUES/249-a-modules-new-state-is-refused-until-a-push-the-merge-did-not-make/00-report.md)
+met the same confusion for the machine holding the bus, which a send adds when its user list changed.
+It narrowed that check to the user list, but the machine, once added, is still sent its whole
+declaration.
+
+So `record` held a change back from nothing but the merge, and "one machine first" held it back only
+from the plan's own sends.
+
+## Considered Options
+
+1. **Report instead of cascade:** list every machine that is behind and send none. Rejected: it is the
+   option ADR 0083 rejected, and for the same reason. [Issue 057](../04-ISSUES/057-a-cross-node-consumer-is-provisioned-only-when-the-provider-is-pushed-again/00-report.md)'s provider would wait for a second push
+   nothing tells anyone to make.
+2. **Send a held machine its consequences and keep its held modules at their last build.** The cascade
+   would compose the machine with each held module pinned at the build it was last sent, so a grant
+   still reaches it and the upgrade does not. Rejected: the catalogue resolves every machine against
+   one manifest per module, the current one. Pinning means resolving a machine's set against a mix of
+   current and older manifests, read back from the build records, beside the current settings, seats
+   and grants. The result matches neither what the machine runs nor what the mesh would send it, so
+   neither `plan` nor `status` could show it. A grant composed for the new build may not fit the old
+   one. It is a second composition path to get one edge case right, and the edge case has a one-word
+   remedy: name the machine.
+3. **Keep, with every send, which build of each module the machine was sent, and leave a machine any
+   of whose modules a policy or a plan holds back.** Chosen.
+
+## Decision
+
+**1. A send records the builds it carried.** With the digest of every declaration it sends, the mesh
+keeps which build of each module the declaration carried: the commit the module's current build was
+made from. A module left out of the declaration keeps the build it was last sent. A declaration sent by
+hand records that what it carried is not known.
+
+**2. A push does not send a machine it did not name a held build.** A machine reached by a named push's
+cascade, or added because it holds the bus, is not sent when any module it runs would move to a build
+that:
+
+- its upgrade policy records rather than rolls out, or
+- an open plan has not yet sent it: the plan is still building the module, or has sent it to its first
+  machine and this is not that machine.
+
+A module the machine was never sent counts as a move. A machine whose last send's builds are not known
+counts as held. It was sent before this was kept, or by hand, so a held upgrade cannot be told apart
+from anything else.
+
+**3. It is named, not hidden.** The push says which machine it left, which module and which builds, why,
+and that `push <node>` sends it. For the machine holding the bus it also says that the bus may refuse
+what this push's machines were newly granted until that machine is sent.
+
+**4. Everything else stays as it is.** A machine with nothing held is flushed exactly as ADR 0083
+decides: a grant, a peer, a setting. The machine a push names is sent everything, held builds included.
+A push that names no machine sends every machine. `push --behind` still sends every machine that is
+behind, held or not. It is the remedy `record` names when an upgrade is announced ("`push --behind`
+when you want them"), and the one command for taking a recorded upgrade everywhere. Narrowing it would
+leave `record` with no way to say "now".
+
+## Consequences
+
+- `record` and "one machine first" hold a change back from every push that does not name the machine.
+  Walking a change through the mesh is `push <anchor>`, check, `push <next>`.
+- **The cost:** a held machine that is also owed a grant from this push waits for its own push. The
+  provider in issue 057's case, if a held upgrade is pending on it, is not sent its new grant, and its
+  consumer is refused until the provider is pushed. The push names that machine and the remedy, so the
+  wait is announced, not silent. When the holder of the bus is held, a new grant may be refused by the
+  bus until it is sent, and the push says so.
+- On the first push after this ships, no machine's last send has its builds recorded yet. Each is held
+  from cascades until it is pushed once: by name, in a whole-mesh push, or by `push --behind`.
+- A manifest handed over by hand does not change the commit a module records, so a cascade still sends
+  its change. Only builds have a commit to compare.
+- ADR 0083's consequence that a machine behind for an unrelated reason is flushed is narrowed. It still
+  holds for every reason except a build held back.
+
+## How it is checked
+
+| Rule | Checked by |
+|---|---|
+| a send records the builds it carried, and "not known" | the controller's test: the builds kept with a send round-trip, an empty send is known and empty, a send by hand reads as not known |
+| a left-out module keeps its last build | the controller's test: a module left out of a declaration records the build it was last sent |
+| a recorded upgrade holds a machine a push did not name | the controller's test: with a module under `record` moved, the cascade of a push naming the anchor leaves the laptop's last send unchanged and names it, the module, both builds and `push laptop` |
+| held and owed something else: not sent, both said | the same test: a newly placed machine changes the laptop's peers while the upgrade is held; the laptop is not sent and the output says why and that what else it is owed waits |
+| a roll-out policy is not held | the same test: with the policy set to roll out, the laptop is sent and its new build recorded |
+| a consequence nothing holds is still sent (issue 057) | the controller's test: a placed machine's peers reach the others by cascade; a machine whose last send is not known is held |
+| a plan waiting on its first machine holds the rest | the controller's test: a machine the plan has not reached is held, the first machine is not; a module sent everywhere, failed, or in a closed plan holds nothing |
+| live | the next change merged under `record`: `push <anchor>` sends the anchor alone and names every other machine running the module |
+
+## References
+
+- [Issue 259](../04-ISSUES/259-a-named-push-sent-every-machine/00-report.md), [issue 260](../04-ISSUES/260-the-resolver-started-before-its-zones-file-existed/00-report.md), [issue 249](../04-ISSUES/249-a-modules-new-state-is-refused-until-a-push-the-merge-did-not-make/00-report.md)
+- [ADR 0083](0083-one-push-leaves-the-mesh-consistent.md): the cascade, narrowed here
+- [ADR 0218](0218-a-plan-sends-grants-before-code-rolls-out-one-machine-first-and-a-newer-merge-takes-over-an-older-plan.md): one machine first, now held from a push as well
+- [ADR 0010](0010-delivery.md): delivery, and what `push --behind` answers
+- [to-be 30](../03-DESIGN/01-to-be/30-the-mesh-updates-itself-on-a-push.md): the design this amends

02-DECISIONS/0222-a-module-is-told-where-a-mesh-seats-holder-is-reached-and-the-controller-writes-no-file-a-seats-holder-owns.md

@@ -0,0 +1,150 @@
+---
+topic: the mesh
+status: accepted
+date: 2026-10-05
+deciders: jochen
+reconstructed: false
+extends: 02-DECISIONS/0082-the-registry-is-reached-by-name-and-trusted-by-the-overlay.md
+---
+
+# 222. A module is told where a mesh seat's holder is reached, and the controller writes no file a seat's holder owns
+
+## Context
+
+[Issue 190](../04-ISSUES/190-the-runtimes-configuration-is-written-by-modules-that-are-not-the-runtime/00-report.md)
+found the container runtime's configuration file written by modules that are not the runtime's. The
+first half is closed: the resolver module no longer writes into that file, and the catalogue's runtime
+module (the holder of `node-container-runtime`) writes `live-restore` and reloads its own service. The
+second half stands. The controller's private network still generates two resources on every machine
+on the network: one writes `insecure-registries`, naming the mesh's artifact store, into the runtime's
+file ([ADR 0082](0082-the-registry-is-reached-by-name-and-trusted-by-the-overlay.md) §2,
+[ADR 0102](0102-the-mesh-writes-into-a-shared-file-never-over-it.md)), and the other declares the
+runtime's service, reloaded on that file. So two parties declare one path and one unit on every
+machine, and nothing refuses it, because the collision check runs over catalogue manifests and the
+private network's resources only exist once its generator has answered for a machine.
+
+On 2026-10-05 the operator made the rule general: **the controller never writes a file a seat's holder
+owns; it tells the owner.** The hosts file had already moved the same way
+([ADR 0199](0199-a-module-that-answers-names-declares-its-zone-and-a-nodes-hosts-file-is-one-modules.md)).
+
+What the runtime's module needs is one fact: the address this machine reaches the mesh's artifact
+store at. The controller already composes that address for every machine at every push. It puts it
+into every image and archive reference the mesh built, and never stores it. Today a module has no way
+to ask for it. A binding gives a consumer the provider's address and a credential. The `${seat:…:<port>}`
+placeholder gives only a port, and only for the store and the broker the controller itself dials.
+
+Two facts about the move itself, read from the host's code:
+
+- The private network writes one member into a list. The host adds a list member and records it per
+  resource, so between the two writers declaring it and one of them going, the member is owned by
+  whichever record added it first.
+- The host removes every resource no longer declared before it applies anything, so in the apply
+  where the private network's record goes and the runtime module's member arrives, the member leaves
+  and comes back with no reload in between.
+
+## Considered Options
+
+1. **Keep the private network writing the trust.** Rejected: it is the defect issue 190 names. Three
+   writers became two, and the second is computed code no check can see.
+2. **An operator setting on the runtime module naming the registry**, as issue 190 first proposed
+   under [ADR 0164](0164-a-setting-is-declared-with-its-default-its-meaning-and-what-changing-it-costs.md).
+   Rejected: where the store is, is a fact the mesh holds, not a choice an operator makes. A setting
+   would be a copy that goes wrong the day the store moves.
+3. **The runtime module requires `artifact-store` and reads the address from its binding
+   (`${bound:…}`).** Rejected. A binding makes the module the store's consumer, and that mints a
+   credential for every machine's runtime, which needs none: reading from the store needs presence on
+   the private network and nothing else (ADR 0082 §3). It also makes a cycle: the store runs as a
+   container in the runtime, and the runtime would require the store before it could be assigned.
+4. **A placeholder that answers where a mesh seat's holder is reached, with no binding.** Chosen. It
+   is the reasoning of `${seat:…:<port>}` taken one step further: nothing is required, nothing is
+   granted, and the answer is an address the mesh already holds in the clear.
+
+## Decision
+
+**1. `${seat:<mesh seat>:reach}` is where this machine reaches the holder of a seat the mesh holds once,
+as host:port.** It is filled where every placeholder is, in a file's content and in an environment
+value, from the address the controller composes for that machine at that push. It requires nothing
+and grants nothing, and no credential comes with it.
+
+- **Only `mesh-artifact-store` is answered.** Another seat is refused by name, never answered with
+  nothing, so a module asking a question the mesh does not answer learns that at composition. A seat
+  is added to what is answered by a record saying why its address is needed.
+- **The answer may be empty**: no machine on the private network holds the seat yet, which is how
+  genesis begins. In a file written into as JSON, an empty member is dropped from its list, and a list
+  left with no members is dropped, so the software is never told an empty name.
+
+**2. The runtime's module states the registry's trust.** Its `daemon` resource writes
+`insecure-registries`, naming `${seat:mesh-artifact-store:reach}`, beside `live-restore`, and it
+reloads its own service. ADR 0082's decision stands: being on the private network is what grants the
+trust, the private network is the transport security, and no module author chooses it. Only who writes
+it moves, from the private network to the runtime's module.
+
+**3. The controller writes no file a seat's holder owns.** The private network generates neither the
+runtime's file nor its service.
+
+**4. What the mesh computes is held to the collision check.** At composition, each computed module's
+resources, as its generator answers for that machine, are checked beside the other modules' resources.
+The check is the same one: no two modules on a machine declare one path, unit, name or package. A
+collision is refused by name. The generator is asked once, and what is checked is exactly what is
+declared.
+
+**5. A unit still held is not given back when another record of it goes.** When the host removes a
+service resource whose unit another declared resource still gives a state, it forgets that record and
+leaves the unit as it is. What the record going had found is not the machine's to restore while
+another resource holds the unit, and restoring it could stop the runtime only for the remaining
+resource to start it again in the same apply.
+
+## Consequences
+
+- **Rollout has a fixed order, in three steps.**
+  1. The controller learns the placeholder. Nothing uses it yet.
+  2. The catalogue's runtime module uses it. A controller that does not know the placeholder would
+     send it through unfilled, so this waits until step 1 is deployed.
+  3. The controller stops generating the private network's two resources and checks generated
+     resources for collisions. With step 3 before step 2, machines would lose the trust. The host
+     change in Decision 5 is deployed before step 3.
+
+  This replaces issue 190's single push. That was needed when two writers of one scalar key would
+  have been refused. A list member written by two records is tolerated by the host.
+- **In the apply of step 3**, the private network's records go first: the member leaves the list and
+  the service record is forgotten. Then the runtime module's file is applied, and the member is added
+  back, recorded as the runtime module's. The runtime is reloaded once. The address is unchanged, so
+  the trust never lapses for a pull.
+- **A machine holding the store, before any network exists**, is answered with the loopback address
+  it reaches the store at. A runtime already trusts loopback, so this adds a redundant member, not a
+  wrong one.
+- **A second writer cannot return through generated code.** It is refused at composition, naming
+  both modules and what they share.
+- **A module can now learn where the artifact store is without being its consumer.** That is a
+  capability, and it is bounded: one seat today, and widened only by a record.
+
+## How it is checked
+
+| Rule | Checked by |
+|---|---|
+| `${seat:mesh-artifact-store:reach}` is filled with this machine's address for the store, in a file and in an environment value | mesh-controller `TestASeatsReachIsWhereThisMachineReachesItsHolder`, and through the whole composition `TestTheRuntimesTrustIsComposedFromTheSeatsReach` |
+| An empty answer adds nothing to a list, and other members stay | mesh-controller `TestAnUnansweredReachAddsNothingToAList` |
+| Any other seat is refused by name | mesh-controller `TestAReachTheMeshDoesNotAnswerIsRefused` |
+| The catalogue's runtime module writes `live-restore` and the trust, and writes no trust when no store is reachable | mesh-controller `TestTheRuntimesModuleTrustsTheMeshsRegistry`, which composes the catalogue's manifest beside it |
+| The private network declares neither the runtime's file nor its service | mesh-controller `TestTheNetworkWritesNothingOfTheRuntimes` |
+| A generated resource colliding with a module's is refused by name; disjoint ones compose; the generator is asked once | mesh-controller `TestAGeneratedResourceCollidingWithAModulesIsRefused`, `TestAGeneratedResourceBesideAModulesOwnIsComposed`, `TestAComputedModuleIsAskedAboutTheNodeItIsFor` |
+| The member moves between records in one apply without leaving the list; one reload; a unit still held is forgotten, never stopped or disabled; the plan says so | mesh-host `TestTheRegistryMovesToTheRuntimesModuleWithoutLeavingTheList`, `TestThePlanForgetsARecordOfAUnitStillHeld` |
+| After rollout, every machine's runtime trusts the store's address | the runtime module's `docker_daemon_config` tool on each machine, read before step 3 and after it |
+
+## References
+
+- [Issue 190](../04-ISSUES/190-the-runtimes-configuration-is-written-by-modules-that-are-not-the-runtime/00-report.md),
+  steps 2 and 5.
+- [ADR 0082](0082-the-registry-is-reached-by-name-and-trusted-by-the-overlay.md): the trust and why it
+  is plain HTTP; its mechanism moves here.
+- [ADR 0102](0102-the-mesh-writes-into-a-shared-file-never-over-it.md): writing into a shared file;
+  its writer of the runtime's trust moves here.
+- [ADR 0079](0079-the-foundation-seats-are-named-after-their-servers.md): a mesh seat names the
+  server, which is what lets a placeholder ask about it.
+- [ADR 0166](0166-the-container-runtime-is-a-node-seat-and-the-host-creates-containers-through-its-holder.md):
+  the runtime module given the registry as a value.
+- [ADR 0199](0199-a-module-that-answers-names-declares-its-zone-and-a-nodes-hosts-file-is-one-modules.md):
+  the hosts file left the controller the same way.
+- mesh-controller `internal/catalogue/seat_into.go`, `internal/catalogue/declaration.go`
+  (`generatedHere`), `internal/overlay/generator.go`; mesh-catalog `modules/docker`; mesh-host
+  `internal/apply/apply.go` (orphan removal).

02-DECISIONS/0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md

@@ -0,0 +1,204 @@
+---
+topic: the tiers
+status: accepted
+date: 2026-10-05
+deciders: jochen
+reconstructed: false
+supersedes-in-part:
+  - 0196-a-node-asks-the-meshs-resolver-first-and-a-public-one-only-when-it-is-silent.md
+extends: 02-DECISIONS/0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md
+---
+
+# 223. The mesh has two resolvers, and a machine lists only them
+
+## Context
+
+**[ADR 0196](0196-a-node-asks-the-meshs-resolver-first-and-a-public-one-only-when-it-is-silent.md) wrote
+every machine's `/etc/resolv.conf` as the mesh's resolver first and a public resolver second.** Its
+reasoning is the C library's: servers are asked in order, the next only when one does not answer, and
+an answer from the first — "no such name" included — is final. That holds for glibc. It does not hold
+for musl, the C library of every Alpine image: musl sends the query to every listed server at once
+and takes the first reply.
+
+**On the production mesh on 2026-10-05 that made the anchor's own name unresolvable from the home
+server's builds.** The build agent on the home server runs its steps in Alpine containers on the host
+network, so they read the machine's `resolv.conf` as it is. Asked for `<anchor>.internal`, the public
+resolver — which has no such name and is the nearer of the two — answered NXDOMAIN first, and musl
+took it. Reproduced six times out of six inside the build agent's own container; every build on that
+machine failed fetching from the anchor. The same lookup from glibc on the same machine answered every
+time. [Issue 262](../04-ISSUES/262-an-alpine-container-could-not-find-a-machine-by-its-mesh-name/00-report.md)
+was the same library failing on a different answer (NXDOMAIN for a missing IPv6 record); fixing that
+did not touch this one, because here the wrong answer comes from a server that should never have been
+asked.
+
+**The public line was there for one case: the mesh's resolver unreachable.** ADR 0196 kept public
+names resolving with the anchor down, the tunnel down, or a laptop behind a captive portal. That case
+is real and rare; the musl case is every lookup of a mesh name from every Alpine container on any
+machine that is not the anchor.
+
+**A seat's work can already be shared by several holders.** [ADR 0190](0190-a-seats-work-is-shared-by-its-holders-and-building-is-the-first-such-role.md)
+made the build role node-scoped with every holder pulling from one queue. A mesh-scoped seat has
+always had exactly one holder: by derivation, or on record since
+[ADR 0131](0131-everything-on-the-mesh-speaks-to-the-broker-seat.md), where a handover replaces the
+holder in one write and every other eligible assignment stands beside it, silent.
+
+## Considered Options
+
+1. **The mesh's resolver alone.** Every mesh name and every public name answered consistently, by one
+   server. Rejected alone: with the anchor down, no machine resolves anything — the reason ADR 0194
+   gave against it, and still true.
+2. **A local forwarder on every machine** — a small resolver on loopback that asks the mesh's resolver
+   for the mesh's suffix and public resolvers for the rest, with `resolv.conf` naming only it. Rejected:
+   it is ADR 0194's per-node stub again, which ADR 0196 removed — a daemon and a module on every node,
+   and a container cannot use a loopback resolver, so containers would need a second configuration.
+   Every resolution fault found on 2026-10-03 was a per-node copy disagreeing with the truth.
+3. **Split by kind of machine** — servers list the mesh's resolver alone, laptops keep a public
+   fallback. Rejected: a laptop runs Alpine containers too, and a rule that differs by machine is a
+   rule nobody can state about the mesh.
+4. **Two mesh resolvers, and nothing else listed.** The same module, the same roster and the same zones
+   on two machines, and every machine lists both. Whichever answers first gives the same answer, so
+   musl's race is harmless; a public name still resolves through either. Chosen.
+
+## Decision
+
+**1. Now: the mesh has two resolvers.** The seat `mesh-dns-resolver` may be held on more than one
+machine — the anchor and the home server — each holder answering the same mesh names: the same
+module, the same machine list, the same zones, rendered by the controller into each.
+
+- **A seat may be replicated.** It is an attribute of the seat in the mesh's definition, compiled with
+  the set and never stored, as what a seat needs ([ADR 0220](0220-what-a-machine-asks-needs-its-uplink-held-and-the-retired-resolver-pieces-go.md))
+  and what it receives are. `mesh-dns-resolver` is the only replicated seat. Making another one is a
+  decision, recorded. In the glossary's words it is the mesh's first **bench** — a seat whose
+  holders coexist — and *replicated* says what kind: every holder answers the same thing.
+- **Every holder is on record, and each is added by an act**: `seat mesh-dns-resolver --add
+  <node>/<module>` records one more holder beside those on record. Assigning the module is not enough:
+  an assignment not on record stands beside the holders, eligible and silent, exactly as ADR 0131 says,
+  and two claimants with nothing on record are refused as for any mesh seat. `--to` still hands the
+  seat over, leaving exactly one holder. `--add` on a seat held once is refused, naming `--to`.
+- **One per machine still**: two modules on one machine claiming it are refused. And a seat held once
+  stays held once: a second claimant on another machine is refused while nothing is on record, and a
+  store recording two holders of such a seat is refused, naming the seat.
+- **Every machine's `/etc/resolv.conf` lists every holder's private address, the holder on the machine
+  itself first if it is one, then the rest in name order, and no public resolver.** The controller
+  gives a module's roster template the holders of each replicated seat, ordered so; the module holding
+  `node-resolver-config` writes the file from it. On a holder, its own private address is first: the
+  resolver listens there and on loopback, and the private address is the one a container on that
+  machine can reach.
+- **The requirement stays.** What writes the file still requires `wildcard-resolution`, so a machine is
+  refused when nothing in the mesh resolves, rather than given a file listing nothing. A holder answers
+  its own requirement; any other machine is bound to the first holder by name. Nothing reads that
+  binding's address any more — the file lists every holder — and the binding is kept for the refusal
+  and the order of delivery.
+
+**2. Next, decided and not yet built: `/etc/resolv.conf` belongs to the uplink's holder.** The program
+that manages the machine's network already has to be told to keep off the file
+([ADR 0117](0117-a-machines-uplink-is-a-seat.md)); instead, the `node-uplink` holder writes it, given
+the resolvers by the mesh: NetworkManager through its global DNS configuration, dhcpcd through static
+nameservers, and systemd-networkd's module declaring the file itself. `resolv-conf` and the seat
+`node-resolver-config` then retire, and ADR 0220's dependency of `node-resolver-config` on `node-uplink`
+goes with them. One owner for the file, and it is the program that would otherwise rewrite it.
+
+> **Progressive insight — 2026-10-05.** Built, the managers' own mechanisms turned out not to write
+> the mesh's file: NetworkManager's global DNS configuration and dhcpcd's resolv.conf hook each write
+> `/etc/resolv.conf` in their own form — their own header, their own options line — and dhcpcd reads
+> its configuration only at its next start, so a change of resolvers would wait for one. The record
+> said NetworkManager and dhcpcd would be given the resolvers "through its global DNS configuration"
+> and "through static nameservers"; instead every one of the three modules declares the file itself,
+> from one template, and keeps its manager off it as before (`dns=none`, `nohook resolv.conf`, and
+> nothing for systemd-networkd). The decision — the uplink's holder owns the file, and `resolv-conf`,
+> `node-resolver-config` and ADR 0220's dependency retire — stands. How parts 2 and 3 are checked is
+> in [connectivity §2](../03-DESIGN/01-to-be/08-connectivity.md).
+
+**3. Next, decided and not yet built: a machine's names are one seat's.** `/etc/hosts` and
+`/etc/hostname` belong to one seat for the machine's identity. The `hosts` module, holding
+`node-hosts-file` ([ADR 0199](0199-a-module-that-answers-names-declares-its-zone-and-a-nodes-hosts-file-is-one-modules.md)),
+is renamed **`hostname`** and holds the seat renamed **`node-hostname`**; it writes `/etc/hostname`
+and the machine's own `127.0.1.1` line, and keeps every operator's line as ADR 0199 does today.
+
+- **Why one seat for both files**: the mesh's only content in `/etc/hosts` is the machine's own name,
+  and nothing owns `/etc/hostname` today. Two files saying one fact belong to one owner.
+- **Why `node-hostname`**: a system seat is named `node-` for its scope and then for its role
+  ([ADR 0121](0121-a-system-seat-is-named-for-its-scope-and-modules-define-their-own.md)), and the role
+  is the machine's name. `node-identity` was considered and rejected: a machine's identity in the mesh
+  already means its key and certificate. `node-host` was rejected for the reason the module name
+  `host` was: "the host" is what the [node-engine](../00-META/glossary.md) was called until now, and
+  its repository and binary still carry `mesh-host`.
+- **Why a module and not part of the node-engine**: the node-engine applies every module's resources
+  and owns no file's content; every file it writes belongs to the module that declared it. A file's
+  content belongs to a seat's holder, and a seat's holder stays replaceable — another module can hold
+  `node-hostname` on a machine that names itself another way, and the node-engine does not change.
+- The rename goes through the seat set's rename (an alias keeps `node-hosts-file` resolving,
+  [ADR 0122](0122-a-seat-is-data-a-rename-is-a-database-update.md)), so nothing claiming the old name
+  breaks in between.
+
+## Consequences
+
+- **musl and glibc agree.** Every listed server answers a mesh name the same way, so the race musl
+  runs has one possible outcome; a public name resolves through either holder's upstreams.
+- **Accepted cost: with no mesh resolver reachable, a machine has no DNS at all** until it can reach
+  one. The anchor is the hub of the private network, so with it down the private network is down too,
+  and the second resolver is reachable only on its own machine and from machines on its own LAN. The
+  mesh assumes the anchor is up about 99.9% of the time. The same holds for a laptop behind a captive
+  portal that keeps the tunnel down: it resolves nothing, the portal's own name included, until the
+  tunnel is up.
+- **The resolver's options change from one attempt to two**, one second each. With no public resolver
+  to fall back to, a single dropped datagram would otherwise fail a lookup on a machine that reaches
+  only one resolver.
+- **Holdings are keyed by seat and assignment.** The store's holding table takes a numbered migration;
+  every existing row is one per seat and satisfies the new key. A handover replaces every holder in one
+  transaction.
+- **Unassigning a holder takes its own row only**: the other resolver keeps holding. Removing the
+  second resolver is unassigning it, then `push --behind`.
+- **The rollout order matters.** The controller that knows replicated seats and renders the holders
+  rolls out first; the catalogue's `resolv-conf`, which reads the holders, second — a controller without
+  them cannot render it; and only then is the second holder added, because an older `resolv-conf`
+  reading its one binding would name the first holder by name order, which may be the new one, and
+  still list the public resolver.
+- **A container keeps the resolvers it started with.** A container on the default bridge copies its
+  machine's `resolv.conf` when it starts; one on a user-defined network is answered by the runtime's
+  embedded resolver, which forwards to the servers it read at start. Either keeps the public resolver
+  until restarted.
+- **Parts 2 and 3 change who writes two files on every machine**, each a handover between modules on
+  the same path; they wait for their own build handoff.
+
+## How it is checked
+
+| Rule | Checked by |
+|---|---|
+| `mesh-dns-resolver` is replicated, and no other seat is; it survives loading the set from the store | mesh-controller unit test over the compiled set and over a store row without the attribute |
+| Two holders on record compose on both, with no refusal, and each lists itself first | mesh-controller resolution and composition test with the catalogue's `dnsmasq` and `resolv-conf` |
+| A machine holding no resolver lists both holders, by name, and no public resolver | the same test on a third machine, asserting no public address appears |
+| A holder answers its own requirement although another holder sorts first | a resolution test on the second holder (issue 258's case kept) |
+| A seat held once still refuses a second claimant, and refuses two holders on record | resolution tests on `mesh-store` |
+| Two claimants of the replicated seat with nothing on record are refused, naming the handover | a resolution test |
+| Every consumer is bound to the same holder whatever order the mesh was resolved in | a unit test on the holder among providers |
+| The store keeps several holders of one seat, once each; a handover leaves one; unassigning takes only its own row | a store test against a live database, through the migration |
+| `seat --add` is refused for a seat held once | the controller's `seat` command |
+| The resolver's machine list has one host record per machine (issue 262's missing check) | a mesh-controller composition test counting host records |
+| `resolv-conf` lists only the seat's holders, with two short attempts | a mesh-controller test reading the catalogue's `resolv-conf` |
+| Live: every machine's `/etc/resolv.conf` lists both holders' private addresses, its own first on a holder, and nothing else; an Alpine container on the host network of the home server resolves `<anchor>.internal` every time | after rollout, read through each machine's tools, and `getent hosts` in an Alpine container repeated ten times |
+| Parts 2 and 3 | not yet built; their checks are written with their handoff |
+
+## References
+
+- [ADR 0194](0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md) — the
+  mesh's resolver; now held on two machines, each holding every node's internal domain.
+- [ADR 0196](0196-a-node-asks-the-meshs-resolver-first-and-a-public-one-only-when-it-is-silent.md) —
+  replaced in part: its public resolver second goes. Every node and container asking the mesh's
+  resolvers for every name, with no stub and no runtime `dns`, stands.
+- [ADR 0190](0190-a-seats-work-is-shared-by-its-holders-and-building-is-the-first-such-role.md) —
+  several holders sharing a role, for a node seat.
+- [ADR 0131](0131-everything-on-the-mesh-speaks-to-the-broker-seat.md) — holders on record, handover,
+  eligible and silent.
+- [ADR 0220](0220-what-a-machine-asks-needs-its-uplink-held-and-the-retired-resolver-pieces-go.md) — the
+  uplink's dependency, which part 2 retires.
+- [ADR 0117](0117-a-machines-uplink-is-a-seat.md), [ADR 0199](0199-a-module-that-answers-names-declares-its-zone-and-a-nodes-hosts-file-is-one-modules.md),
+  [ADR 0121](0121-a-system-seat-is-named-for-its-scope-and-modules-define-their-own.md),
+  [ADR 0122](0122-a-seat-is-data-a-rename-is-a-database-update.md).
+- [Issue 258](../04-ISSUES/258-every-machine-bound-the-resolver-to-itself/00-report.md),
+  [issue 262](../04-ISSUES/262-an-alpine-container-could-not-find-a-machine-by-its-mesh-name/00-report.md).
+- [Connectivity §2](../03-DESIGN/01-to-be/08-connectivity.md) and [the seats](../03-DESIGN/01-to-be/26-the-seats.md),
+  amended alongside.
+- mesh-controller `internal/catalogue/seats.go`, `resolve.go`, `roster.go`,
+  `cmd/mesh-controller/seats.go`, `holdings.go`, and the store migration keying a holding by seat and
+  assignment; mesh-catalog `modules/resolv-conf`, `modules/dnsmasq`.

02-DECISIONS/0224-a-provider-that-keeps-failing-a-consumer-is-a-problem-the-controller-reports.md

@@ -0,0 +1,134 @@
+---
+topic: the mesh
+status: accepted
+date: 2026-10-06
+deciders: jochen
+reconstructed: false
+extends: 02-DECISIONS/0040-what-a-module-is.md
+---
+
+# 224. A provider that keeps failing a consumer is a problem the controller reports
+
+## Context
+
+**A provider's provisioner is the only thing in the mesh that knows whether a provision was made.**
+The controller composes a grant, delivers the contributions file and the minted secret, and the node
+reports that it applied every resource. Whether the provider then made the consumer's database, client
+or bucket is known to the provisioner loop alone ([ADR 0040](0040-what-a-module-is.md),
+[ADR 0048](0048-a-provider-creates-the-credential-the-mesh-minted.md)), and until now it
+said so only in its own journal.
+
+**On 2026-10-05 that cost a day.** The identity provider's database was moved that morning. Its
+realm's administrator kept the password it had before, the module's minted one was inert, and its
+provisioner failed every consumer every five seconds — about 31,000 refused logins from shortly after
+midnight until it was repaired by hand that night. Every surface the mesh has said the mesh was well:
+the machines applied what they were sent, the modules were current, `status` printed its all-well
+sentence. The same fault had been found and repaired by hand four days earlier
+([issue 179](../04-ISSUES/179-an-adopted-identity-providers-admin-never-took-the-minted-secret/00-report.md)).
+
+[Issue 145](../04-ISSUES/145-a-machine-reads-healthy-while-its-modules-cannot-reach-each-other/00-report.md)
+already taught that "the mesh and the machines agree" is not "it works", and `status` says so under its
+all-well line. This is the narrower, checkable half of that gap: not whether a consumer can reach its
+provider, which only dialling answers, but whether the provider has told the mesh it cannot do its job.
+
+## Considered Options
+
+1. **Leave it to the journal, and to a person reading it.** Rejected: that is what happened, twice.
+2. **The controller dials every provision.** Rejected for now: it is issue 145's open question, it
+   needs the controller to hold or borrow every consumer's credential, and it would still not say
+   *why* a provider fails.
+3. **The provider reports its standing through the node's report.** Rejected: the node-engine applies
+   resources and knows nothing of what a module's code does after it starts; the provisioner runs in the
+   node's tool runtime, which speaks to the bus, not to the host.
+4. **The provider announces, as an event, a consumer it keeps failing; the controller keeps the newest
+   word and `status` names it.** Chosen.
+
+## Decision
+
+**1. A provider announces a consumer it keeps failing.** When a provisioner has failed one consumer —
+its create, its periodic check, or reading the consumer's minted secret — for five minutes without a
+single success in between, it emits `provisioner.failing`, naming the consumer, the consumer's
+machine, the provision, the class of error and the error's first words, since when, and how many
+attempts. It says it again every fifteen minutes while it lasts. The first success after that is
+`provisioner.recovered`; so is a consumer the mesh stopped asking for, and so is the first success
+for each consumer after the provider starts, because a provider restarted after announcing a failure
+has forgotten it.
+
+- **The classes** are `credentials-rejected`, `unreachable`, `secret-unreadable` and `refused` (any
+  other refusal), read from the error's words unless the provider's own code classes it better. They are
+  what a person reading `status` needs before opening the journal.
+- **No secret travels.** The error is the provider's own text with the consumer's password removed, as
+  its log line already is.
+
+**2. Every provider may say it, whatever its manifest lists.** The permission to publish the two events
+is derived for every module that receives contributions; no manifest declares them. A provider whose
+manifest forgot them would otherwise have its announcement refused by the bus and fail as silently as
+before.
+
+**3. The controller follows both events from every module, keeps the newest failing word per provider
+module, its machine and the consumer, and removes it on recovery.** Who said it is read from the subject
+the bus let the provider publish on, never from the body. A recovery that arrives while the store is
+away is held and delivered again, because it is said once. The controller's subscription names the two
+events with a wildcard for the emitter — the one pattern on its list — rather than a list of providers
+somebody would have to extend.
+
+**4. `status` names every consumer a provider still assigned where it ran says it keeps failing**, and
+such a consumer breaks the all-well sentence. Its JSON carries them as `failing`; `node show` lists those
+whose provider or consumer is on that machine. A provider no longer assigned there has nothing running
+to fail anybody, and is not asked about. A standing not said again for thirty minutes is shown with how
+long it has been silent: the provider stopped saying anything, and its last word is all the mesh has.
+
+**5. Where a provider's failure has one known cause it can repair safely, it repairs it.** The identity
+provider's administrator refusing the mesh's secret is the first: the module now checks the
+administrator's login on start, every five minutes and whenever its provisioner is refused, and repairs
+a refusal through the server's own bootstrap command — a temporary administrator, the real one's
+password set to the mesh's, the temporary one removed, nothing printed — then checks again and says
+what it did. A repair that fails is braked, from ten minutes doubling to six hours, and announced; while
+the administrator is refused the provisioner stops asking the server, so a lockout policy is not
+provoked, and its consumers are still announced failing. The mechanism is the module's
+([issue 179](../04-ISSUES/179-an-adopted-identity-providers-admin-never-took-the-minted-secret/00-report.md)),
+the rule is this record's: **detected automatically, repaired where safe, loud where not.**
+
+## Consequences
+
+- **The loop is carried by every Go provider until the Go SDK has one.** The provisioner loop is the
+  SDK's ([ADR 0039](0039-what-the-sdk-holds-and-refuses.md)); the Go SDK has none yet, so the two Go
+  providers carry identical copies and a test in each fails when they differ. A TypeScript provider
+  announces nothing until the TypeScript SDK's loop does the same; until then its consumers fail as
+  silently as before, and the next provider to be ported to Go closes that gap for itself.
+- **The controller's event consumer takes one message at a time**, so a standing can wait behind a
+  build being acted on for some minutes. Fifteen-minute repetition makes that harmless for a failure;
+  a recovery is held, never dropped.
+- **The store keeps one row per provider module, its machine and consumer**, through a numbered
+  migration.
+- **The rollout order matters.** The controller that derives the permission and follows the events
+  first; the catalogue's providers second — an older controller refuses nothing that matters, but
+  every announcement is then refused by the bus and logged by the provider.
+
+## How it is checked
+
+| Rule | Checked by |
+|---|---|
+| A consumer failed for five minutes without a success is announced, again every fifteen, and recovered on the first success | provider loop tests in mesh-catalog, postgres and keycloak (`standing_test.go`) |
+| A failing periodic check and an unreadable secret count, not only a failing create | the same tests |
+| A withdrawn consumer and the first success after a start are announced recovered | the same tests |
+| The two Go providers carry the same loop | `harness_same_test.go` in each, comparing the files |
+| Every module that receives contributions is granted the two events, and no other module is | mesh-controller inventory test over the derived declaration and the bus permissions |
+| The controller may hear the two events from any module, and not every event | the same test over the controller's permissions |
+| The emitter is read from the subject; a failing word is kept, a recovery cleared, and a recovery held while the store is away | mesh-controller link tests with a fake store |
+| One row per provider, machine and consumer; recovered removes only its own | an inventory test against a live database, through the migration |
+| `status` names it and is not all-well; the JSON carries it; `node show` names it on both machines; an unassigned provider's word is not a problem | mesh-controller command tests against a live database |
+| The identity provider repairs a refused administrator, verifies, brakes a failed repair, never puts a secret in a command line, and stops asking the server while refused | keycloak module tests with a fake server and a fake container runtime; a live test against a throwaway server when asked for |
+| Live: after rollout, `status` shows nothing failing on a healthy mesh; a provider made to fail a consumer for five minutes appears, and disappears on its next success | read through the console after rollout |
+
+## References
+
+- [Issue 179](../04-ISSUES/179-an-adopted-identity-providers-admin-never-took-the-minted-secret/00-report.md)
+  — the failure, twice, and the repair this record makes automatic.
+- [Issue 145](../04-ISSUES/145-a-machine-reads-healthy-while-its-modules-cannot-reach-each-other/00-report.md)
+  — the scope of the all-well sentence, which this narrows and does not close.
+- [ADR 0040](0040-what-a-module-is.md), [ADR 0048](0048-a-provider-creates-the-credential-the-mesh-minted.md),
+  [ADR 0039](0039-what-the-sdk-holds-and-refuses.md), [ADR 0042](0042-the-shape-of-an-event-on-the-wire.md).
+- [The module protocol](../03-DESIGN/01-to-be/19-the-module-protocol.md), provisioning, amended alongside.
+- mesh-controller `internal/link/standing.go`, `internal/inventory/standing.go` and its migration,
+  `cmd/mesh-controller/standing.go`; mesh-catalog `modules/postgres` and `modules/keycloak`.

02-DECISIONS/README.md

@@ -194,6 +194,11 @@ python3 00-META/checks/index.py            fail if stale
 - **0207** — [A module depends on the node seats that apply its resources](0207-a-module-depends-on-the-node-seats-that-apply-its-resources.md)
 - **0210** — [A tool's configuration is its seat holder's, and every other module extends it through the seat](0210-a-tools-configuration-is-its-seat-holders-and-every-other-module-extends-it-through-the-seat.md)
 - **0212** — [A seat says what it receives, and the machine's hotkeys are a seat](0212-a-seat-says-what-it-receives-and-the-machines-hotkeys-are-a-seat.md)
+- **0218** — [A plan sends grants before code, rolls a module out one machine first, and a newer merge takes over an older plan](0218-a-plan-sends-grants-before-code-rolls-out-one-machine-first-and-a-newer-merge-takes-over-an-older-plan.md)
+- **0219** — [The build queue is controlled through the controller and the build seat](0219-the-build-queue-is-controlled-through-the-controller-and-the-build-seat.md)
+- **0221** — [A push sends no build a policy or a plan holds back, except to the machine it names](0221-a-push-sends-no-build-a-policy-or-a-plan-holds-back-except-to-the-machine-it-names.md)
+- **0222** — [A module is told where a mesh seat's holder is reached, and the controller writes no file a seat's holder owns](0222-a-module-is-told-where-a-mesh-seats-holder-is-reached-and-the-controller-writes-no-file-a-seats-holder-owns.md)
+- **0224** — [A provider that keeps failing a consumer is a problem the controller reports](0224-a-provider-that-keeps-failing-a-consumer-is-a-problem-the-controller-reports.md)
 
 ### Its tiers, from the bottom up
 
@@ -231,6 +236,7 @@ python3 00-META/checks/index.py            fail if stale
 - **0194** — [The mesh has one resolver, and every node asks it for the mesh's names](0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md)
 - **0196** — [A node asks the mesh's resolver first, and a public one only when it is silent](0196-a-node-asks-the-meshs-resolver-first-and-a-public-one-only-when-it-is-silent.md)
 - **0199** — [A module that answers names declares its zone, and a node's hosts file is one module's](0199-a-module-that-answers-names-declares-its-zone-and-a-nodes-hosts-file-is-one-modules.md)
+- **0223** — [The mesh has two resolvers, and a machine lists only them](0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md)
 
 ### What runs on them, and how it gets there
 
@@ -316,6 +322,7 @@ python3 00-META/checks/index.py            fail if stale
 - **0214** — [Backups guard against mistakes, stay on the machine, and are declared by the module that owns the data](0214-backups-guard-against-mistakes-and-stay-on-the-machine.md)
 - **0215** — [The machine's message bus is a node seat, and it is never restarted live](0215-the-machines-message-bus-is-a-node-seat-and-is-never-restarted-live.md)
 - **0216** — [The agent's configuration is registered through its module, at three scopes, and served as one plugin](0216-the-agents-configuration-is-registered-through-its-module-at-three-scopes-and-served-as-one-plugin.md)
+- **0220** — [What a machine asks needs its uplink held, and the retired resolver pieces go](0220-what-a-machine-asks-needs-its-uplink-held-and-the-retired-resolver-pieces-go.md)
 
 ### How it is built
 

03-DESIGN/01-to-be/08-connectivity.md

@@ -7,14 +7,19 @@ code:
   - mesh-controller internal/identity/authority.go
   - mesh-controller cmd/mesh-controller/plan.go (the names the roster publishes)
   - mesh-controller internal/catalogue/zones.go (the zones a module answers, ADR 0199)
-  - mesh-controller internal/catalogue/seats.go (mesh-dns-resolver, node-hosts-file)
+  - mesh-controller internal/catalogue/seats.go (mesh-dns-resolver, node-hostname, node-uplink)
-  - mesh-catalog modules/dnsmasq (the mesh's one resolver)
+  - mesh-controller internal/catalogue/resolve.go (one owner per path, a rendered fact's included, ADR 0223)
-  - mesh-catalog modules/resolv-conf (what a node asks)
+  - mesh-controller cmd/mesh-controller/holdings.go (the holders of a replicated seat, ADR 0223)
-  - mesh-catalog modules/hosts (a node's /etc/hosts)
+  - mesh-controller internal/catalogue/roster.go (each replicated seat's holders, for a template)
+  - mesh-catalog modules/dnsmasq (the mesh's resolvers)
+  - mesh-catalog modules/networkmanager, modules/systemd-networkd, modules/dhcpcd (what a node asks, written by its uplink's holder)
+  - mesh-catalog modules/hostname (a node's /etc/hostname and /etc/hosts)
   - mesh-host internal/identity/serving.go
-  - mesh-host internal/apply (the service that reflects a rule set)
+  - mesh-host internal/apply (the service that reflects a rule set; a whole file handed to its new owner)
-updated: 2026-10-03
+updated: 2026-10-05
 decisions:
+  - 02-DECISIONS/0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md
+  - 02-DECISIONS/0220-what-a-machine-asks-needs-its-uplink-held-and-the-retired-resolver-pieces-go.md
   - 02-DECISIONS/0199-a-module-that-answers-names-declares-its-zone-and-a-nodes-hosts-file-is-one-modules.md
   - 02-DECISIONS/0196-a-node-asks-the-meshs-resolver-first-and-a-public-one-only-when-it-is-silent.md
   - 02-DECISIONS/0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md
@@ -298,10 +303,10 @@ expensively enough to be worth restating:
 - **A node must not pin its own public name locally.** The duplicate record breaks resolution of
   that name for everything else that needs it.
 
-**What the host receives:** what to ask, not what to answer. The mesh has **one resolver**, holding
+**What the host receives:** what to ask, not what to answer. The mesh has **two resolvers**, each
-every node's internal domain; a node asks it first and a public resolver only when it is silent
+holding every node's internal domain; a node lists both and nothing else
 ([ADR 0194](../../02-DECISIONS/0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md),
-[ADR 0196](../../02-DECISIONS/0196-a-node-asks-the-meshs-resolver-first-and-a-public-one-only-when-it-is-silent.md)).
+[ADR 0223](../../02-DECISIONS/0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md)).
 
 **What goes away:** the `/etc/hosts` floor. It exists because a node had to reach the mesh
 database before its own DNS existed; with [ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md)
@@ -359,36 +364,83 @@ not a list of containers.
 somebody starts by hand is not the mesh's to configure, and reaching into every container on a
 machine — declared or not — is what a nameserver in `resolv.conf` would be for.
 
-### One resolver for the mesh
+### The mesh's resolvers
 
-*2026-10-03.* **The mesh's names live in one place: the module holding `mesh-resolver`**, a mesh-scoped
+*2026-10-03, revised 2026-10-05.* **The mesh's names live in one module, held on two machines: the
-seat of capacity one, placed on the node every tunnel converges on. It holds one wildcard per node —
+holders of `mesh-dns-resolver`**, a mesh-scoped seat that is *replicated* — held on the anchor and on
-`<node>.internal` and everything under it — and listens on the private network only. It answers the
+the home server, each running the same module with the same machine list and the same zones, rendered
-mesh's names from what it holds and forwards every other name, giving the public answer.
+by the controller into each. Each holds one wildcard per node — `<node>.internal` and everything
+under it — and one host record per node, listens on its private address and loopback only, answers
+the mesh's names from what it holds and forwards every other name, giving the public answer
+([ADR 0194](../../02-DECISIONS/0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md),
+[ADR 0223](../../02-DECISIONS/0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md)).
+Each holder is on record, added by `seat mesh-dns-resolver --add <node>/<module>`; an assignment of
+the module not on record stands beside them, eligible and silent, and a seat held once stays held
+once. *Checked by the controller's resolution tests with two holders on record, with two claimants
+and nothing on record, and on a seat held once.*
 
-**Every node asks it for everything, and a public resolver only when it is silent.** The module
+**Every node asks them for everything, and nothing else.** `/etc/resolv.conf` lists every holder's
-holding `node-resolver-config` writes `/etc/resolv.conf` naming `mesh-resolver` first and a public
+private address — the holder on the machine itself first if it is one, then the rest by name — with a
-resolver second, with a short timeout and one attempt: the C library moves to the second only when the
+short timeout and two attempts, and **no public resolver**. ADR 0196 listed a public resolver second,
-first does not answer — the anchor or the tunnel down, a captive portal holding the tunnel back — so
+for the anchor being unreachable; a C library that asks every listed server at once and takes the
-public names keep resolving then, and `.internal` is never asked of a public resolver while the mesh's
+first reply — musl, so every Alpine container — took the public resolver's "no such name" for a mesh
-answers. Containers take the same two from their machine, the runtime copying non-loopback resolvers
+name, and every build on the home server failed. With only the mesh's resolvers listed, whichever
-into every container, so the runtime is given no `dns` of its own
+answers first gives the one answer. The cost is stated: a machine that reaches no mesh resolver has no
+names until it does, and with the anchor down the second resolver is reachable only on its own machine
+and its own LAN. Containers take the same lines from their machine, the runtime copying non-loopback
+resolvers into every container, so the runtime is given no `dns` of its own
 ([ADR 0196](../../02-DECISIONS/0196-a-node-asks-the-meshs-resolver-first-and-a-public-one-only-when-it-is-silent.md),
-replacing ADR 0194's per-node `systemd-resolved` stub).
+replacing ADR 0194's per-node `systemd-resolved` stub). *Checked by the controller's composition tests
+on both holders and on a third machine, for every uplink module, and live by each machine's
+`/etc/resolv.conf` and an Alpine container on the home server resolving the anchor's name every
+time.*
 
-**No node holds a copy.** The per-node resolver, its zones file and the mesh's region of `/etc/hosts`
+**The file is the uplink's holder's** ([ADR 0223](../../02-DECISIONS/0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md)).
-go: every resolution fault found on 2026-10-03 was a copy disagreeing with the truth — a hosts file
+A network manager rewrites `/etc/resolv.conf` on every connectivity change unless it is told not to
+([ADR 0117](../../02-DECISIONS/0117-a-machines-uplink-is-a-seat.md)), so the module holding
+`node-uplink` — the one telling it — writes the file itself, and there is one owner for it, the one
+whose program would otherwise overwrite it. Each of the catalogue's three managers' modules
+(NetworkManager, systemd-networkd, dhcpcd) renders the same template from the resolver's holders and
+requires the mesh's resolver, so a machine is refused when nothing in the mesh resolves rather than
+given a file listing nothing. The managers' own mechanisms were weighed and not used: NetworkManager's
+global DNS and dhcpcd's static nameservers each write the file in their own form — their own header,
+their own options line — so neither can write the mesh's file byte for byte, and dhcpcd reads its
+configuration only at its next start; each manager is told to keep off the file and the module
+declares it. No other module may write that path, as a file or as a rendered fact: two modules on one
+node declaring one path are refused. The module that wrote the file before, its seat
+`node-resolver-config` and that seat's need of the uplink beside it
+([ADR 0220](../../02-DECISIONS/0220-what-a-machine-asks-needs-its-uplink-held-and-the-retired-resolver-pieces-go.md))
+retire. The file changes owner in one apply on each machine: the node-engine hands a whole file to the
+resource declaring its path now rather than removing it first, so a machine is never without it.
+*Checked by the controller's tests that the three modules carry one identical template and that
+nothing else in the catalogue writes the path, a resolution test refusing a second writer, and the
+node-engine's handover test, in which the file is present at every step of the apply.*
+
+**A machine's names are one seat's** ([ADR 0223](../../02-DECISIONS/0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md)).
+The `hosts` module is renamed `hostname` and holds `node-hostname`, the seat once named
+`node-hosts-file`, whose former name resolves to it. It writes `/etc/hostname` from its `hostname`
+setting — with no default: what a machine calls itself is the operator's, and the mesh's name for a
+machine and its own need not agree — and the machine's `127.0.1.1` line, keeping the operator's lines.
+A new name takes effect at the next boot; nothing sets it live, because a graphical session's X
+authority is keyed by the name the session started under. *Checked by a resolution test that a
+module claiming the old name and one claiming the new are one seat on one machine, and a composition
+test that `/etc/hostname` is the setting, left out naming the key when nothing sets it.*
+
+**No node holds a copy of its own.** The two holders hold the same rendering of one roster, never a
+list anyone edits. The per-node resolver, its zones file and the mesh's region of `/etc/hosts`
+go, and the per-node resolver's seat with them, deleted from the set once nothing claimed it
+([ADR 0220](../../02-DECISIONS/0220-what-a-machine-asks-needs-its-uplink-held-and-the-retired-resolver-pieces-go.md)): every resolution fault found on 2026-10-03 was a copy disagreeing with the truth — a hosts file
 read once at start, an operator's old line beside the mesh's, a node's resolver lent to a LAN. No
 member's resolver answers a LAN; a router pointing at one is moved first. *Checked by each node's
-`/etc/resolv.conf` naming `mesh-resolver` then a public resolver, by no node but the holder answering
+`/etc/resolv.conf` listing the resolver's holders and nothing else, by no node but a holder answering
 DNS on any address, and by the router's DHCP DNS option naming the router.*
 
 **Names that are neither a node nor a route.** A module that answers names declares a zone (a
 setting) and the listen that answers it; the controller hands the `mesh-dns-resolver` holder every
-zone with its module's node address and published port, and the holder forwards that zone there and
+zone with its module's node address and published port, and each holder forwards that zone there and
 answers nothing in it itself — the lab answers `<machine>.incus` for its running scenarios this way.
 An operator's own names, unrelated to the mesh, live in `/etc/hosts`'s kept region, held per node by
-the `node-hosts-file` seat's holder and changed through its tools; the controller holds none of them
+the `node-hostname` seat's holder and changed through its tools; the controller holds none of them
 ([ADR 0199](../../02-DECISIONS/0199-a-module-that-answers-names-declares-its-zone-and-a-nodes-hosts-file-is-one-modules.md)).
 *Checked by the holder's configuration carrying one forwarding rule per declared zone, and by a push
 leaving the hosts file's operator region byte for byte.*
@@ -1035,10 +1087,14 @@ The list is worth having in one place, because it is most of the argument:
 
 ## Open
 
-- **One resolver ([ADR 0194](../../02-DECISIONS/0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md)).** Not built: every node still runs
+- **One resolver ([ADR 0194](../../02-DECISIONS/0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md)).** *Correction of fact,
-  `node-dns-resolver`. The migration's four steps are in the record, in order.
+  2026-10-05:* no node holds `node-dns-resolver` any more, and
-  Nor are zones or the hosts file's holder ([ADR 0199](../../02-DECISIONS/0199-a-module-that-answers-names-declares-its-zone-and-a-nodes-hosts-file-is-one-modules.md)): the
+  [ADR 0220](../../02-DECISIONS/0220-what-a-machine-asks-needs-its-uplink-held-and-the-retired-resolver-pieces-go.md) deletes the seat. What stood here before: *"Not built: every node still runs
-  workstation moves to the one resolver only once both exist, its lab and operator names depending on them.
+  `node-dns-resolver`. The migration's four steps are in the record, in order."* Nor did it
+  stay true that *"the workstation moves to the one resolver only once"* zones and the hosts file's
+  holder ([ADR 0199](../../02-DECISIONS/0199-a-module-that-answers-names-declares-its-zone-and-a-nodes-hosts-file-is-one-modules.md))
+  exist: every node, the workstation included, asks the one resolver, and every node holds
+  `node-hosts-file`.
 
 - ~~**What happens when the hub is down.**~~ **Resolved** by
   [ADR 0006](../../02-DECISIONS/0006-the-substrate-and-the-control-plane.md), together with `06`'s

03-DESIGN/01-to-be/18-building-a-module.md

@@ -5,8 +5,9 @@ code:
   - mesh-controller cmd/mesh-builder
   - mesh-controller internal/builder
   - mesh-catalog modules/build-agent
-updated: 2026-10-04
+updated: 2026-10-05
 decisions:
+  - 02-DECISIONS/0219-the-build-queue-is-controlled-through-the-controller-and-the-build-seat.md
   - 02-DECISIONS/0190-a-seats-work-is-shared-by-its-holders-and-building-is-the-first-such-role.md
   - 02-DECISIONS/0157-a-build-says-what-it-does-on-the-bus-as-it-happens.md
   - 02-DECISIONS/0189-the-store-keeps-what-the-records-name.md
@@ -346,6 +347,21 @@ scheduled step with the server held still — which is what `while-stopped` exis
 keeps is still a manifest and so still referenced, and the dangerous flag is not needed once the
 mesh is the one deciding.
 
+**An archive is held by a manifest of its own** (2026-10-05,
+[issue 253](../../04-ISSUES/253-the-stores-collector-would-delete-every-archive-the-mesh-keeps/00-report.md)).
+The sentence above held for images and not for archives: an archive was published as a bare blob that no
+manifest names, and the store's collector keeps only what a manifest names, so a nightly collection
+would have removed every archive the mesh keeps, the current ones included. So:
+
+- an archive is published with a manifest that names it and nothing else, built from the archive's digest
+  and size alone so it can be computed again from the record;
+- the sweep makes sure every archive it keeps is held that way before it lets anything go, and lets go of
+  an archive by removing its manifest first;
+- the reference a machine fetches is unchanged.
+
+The collector runs as a dry run until the controller reports no kept archive unheld; only then does it
+collect for real.
+
 A machine behind by more than five builds of a module, recreating a container, cannot pull what it
 was running. It is already a machine the mesh reports as behind, and the answer is the current
 declaration.
@@ -379,3 +395,26 @@ not of the recipe: one artifact declared per target, one build each.
 A component's version stops being stamped in at link time. It is unpacked into a directory named for
 its version, so it reads its version from its own path, and a build no longer has to know what it will
 be called.
+
+## The build queue is controlled
+
+*2026-10-05 — [ADR 0219](../../02-DECISIONS/0219-the-build-queue-is-controlled-through-the-controller-and-the-build-seat.md).*
+
+What is asked of the build seat can be seen and controlled from the console. The controller holds the
+queue, and each machine's build agent holds its own process.
+
+- **The controller's verbs:**
+  - `queue` lists every ask, waiting, in flight or dead;
+  - `cancel` and `clear` take asks back;
+  - `rebuild` asks again under a new id;
+  - `replay` asks again for a past build at its commit, as a dry run unless told to register, and never
+    over a newer build without saying so;
+  - `kill`, `pause` and `resume` are passed on to the seat on the right machine.
+- **The build seat's verbs, on each machine:**
+  - `current` says what is building here and whether this holder is paused;
+  - `kill` ends the build's whole process group and every container it started;
+  - `pause` and `resume` set a flag the holder reads before it takes the next ask, which survives its
+    restart.
+
+Every action that drops work leaves a failed outcome, so a plan waiting on that build fails and says why
+rather than waiting. A plan keeps the id of every build it asked for. A plan waiting on a paused seat says so and is not counted late; a failed plan can be resumed with `plans retry`, and a `rebuild` of a module a plan holds joins that plan.

03-DESIGN/01-to-be/19-the-module-protocol.md

@@ -5,8 +5,11 @@ code:
   - mesh-sdk src
   - mesh-tools src/broker-nats.ts (and broker-amqp.ts until the rollout)
   - mesh-controller internal/link
-updated: 2026-09-26
+  - mesh-controller cmd/mesh-controller (status)
+  - mesh-catalog modules/postgres, modules/keycloak (the Go provisioner loop)
+updated: 2026-10-06
 decisions:
+  - 02-DECISIONS/0224-a-provider-that-keeps-failing-a-consumer-is-a-problem-the-controller-reports.md
   - 02-DECISIONS/0095-the-control-plane-is-the-way-to-ask-a-module.md
   - 02-DECISIONS/0106-the-bus-is-nats.md
   - 02-DECISIONS/0128-the-mesh-bus-is-required-not-ambient.md
@@ -232,6 +235,17 @@ A provider ships the provisioner that creates instances of what it offers
 same provision, so a grant addressed to a node alone does not name a consumer, and withdrawing one
 would take another's away.
 
+### A provider says which consumer it keeps failing
+
+Whether a provision was made is known to the provider's loop alone. A consumer the loop has failed for
+five minutes without one success — its create, its periodic check, or reading the secret the mesh
+minted for it — is announced as `provisioner.failing`, naming the consumer, its machine, the class of
+error and since when, and again every fifteen minutes while it lasts; the first success, a withdrawal,
+and the first success after the provider restarts are `provisioner.recovered`. Every module that
+receives contributions may publish both, derived and never declared. The controller keeps the newest
+failing word per provider, machine and consumer, and `status` names each one until it recovers
+([ADR 0224](../../02-DECISIONS/0224-a-provider-that-keeps-failing-a-consumer-is-a-problem-the-controller-reports.md)).
+
 ### Checked, and it agrees (2026-09-16)
 
 This looked like the sharpest disagreement and was not one. The live wire is the contributions file
@@ -255,4 +269,5 @@ two implementations drift from while both believe they conform.
 | The envelope is the envelope | An emitted event is compared header by header against a fixture; a missing required header fails, an unknown `x-` header is accepted. |
 | Delivery is at-least-once | A fixture delivered twice is handled once. |
 | A grant names a consumer | A grant fixture is read by every implementation and yields the same module and the same node. |
+| A provider that keeps failing a consumer says so | The loop's tests drive five minutes of failure to one `provisioner.failing` and a success to `provisioner.recovered`; the controller's tests carry it from the bus to `status`. |
 | A partial SDK is legitimate | An implementation claiming the floor and events passes those suites and is listed for them; a module using tools in that language is refused at build time with the reason. |

03-DESIGN/01-to-be/26-the-seats.md

@@ -4,14 +4,21 @@ status: in-progress
 code:
   - mesh-controller internal/catalogue/seats.go
   - mesh-controller internal/catalogue/resolve.go
+  - mesh-controller internal/catalogue/seat_dependencies.go
   - mesh-controller internal/inventory/seats.go
   - mesh-controller internal/inventory/migrations/0039-a-seat-is-held-by-one-assignment-on-record.sql
+  - mesh-controller internal/inventory/migrations/0062-a-replicated-seat-has-several-holders-on-record.sql
+  - mesh-controller cmd/mesh-controller/holdings.go
   - mesh-controller cmd/mesh-controller/seats.go
   - mesh-controller cmd/mesh-controller/source.go
   - mesh-controller internal/inventory/migrations/0032-a-source-may-live-on-a-seat.sql
   - mesh-catalog modules/gitea/module.json
-updated: 2026-10-03
+  - mesh-controller internal/inventory/migrations/0063-a-machines-names-are-one-seats.sql
+  - mesh-controller internal/inventory/migrations/0064-the-resolver-file-is-the-uplinks.sql
+updated: 2026-10-05
 decisions:
+  - 02-DECISIONS/0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md
+  - 02-DECISIONS/0220-what-a-machine-asks-needs-its-uplink-held-and-the-retired-resolver-pieces-go.md
   - 02-DECISIONS/0199-a-module-that-answers-names-declares-its-zone-and-a-nodes-hosts-file-is-one-modules.md
   - 02-DECISIONS/0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md
   - 02-DECISIONS/0161-what-deserves-a-seat.md
@@ -36,7 +43,7 @@ A seat has four properties, fixed by the mesh rather than by any module:
 | property | is |
 |---|---|
 | name | what a definition names and an assignment holds, and what a person reads in the list |
-| scope | node, site or mesh: where its capacity applies. Every seat in the set has a capacity of one, so one holder per scope. A bench, a seat with several holders, is a word the glossary keeps and no seat uses yet |
+| scope | node, site or mesh: where its capacity applies. Every seat in the set has a capacity of one, so one holder per scope — except a *replicated* mesh seat, which may be held on several machines at once, one holder per machine, each on record ([ADR 0223](../../02-DECISIONS/0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md)). `mesh-dns-resolver` is the only one. Replicated is part of the seat's definition, compiled with the set and never stored |
 | delivers | the provision its holder answers for, or nothing |
 | decision | the record that made it a seat |
 
@@ -67,6 +74,17 @@ needs ([28](28-building-the-bus.md), task 5.3). **And a holding is the assignmen
 holder takes the row with it, so a seat never points at something that is not running anywhere, and
 the seat falls back to derivation rather than to nothing.
 
+**A replicated seat has several holders on record** (revision, 2026-10-05,
+[ADR 0223](../../02-DECISIONS/0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md)).
+`seat <name> --add <node>/<module>` records one more holder beside those on record, judged exactly
+as a handover is; `--to` still leaves exactly one. Each holder is added by that act and never by being
+assigned: an assignment not on record is eligible and silent, and two claimants with nothing on record
+are refused, as for any mesh seat. `--add` on a seat held once is refused, naming `--to`, and a store
+recording two holders of a seat held once is refused at resolution, naming the seat. A requirement the
+seat delivers is answered on a holder by itself, and elsewhere by the first holder in name order. What
+the holders are is given to a module's roster template, its own machine first — how every machine's
+resolver file lists both of the mesh's resolvers.
+
 The handover refuses what would make the new holder wrong before anything is written: the seat must
 exist, the assignment must exist, and the module must be able to hold the seat — claim it at its scope
 and provide what it delivers, judged against the store's row and not against anything compiled into a
@@ -128,13 +146,13 @@ convention, which later seats departed from.
 | `mesh-npm-package-registry` | `npm-package-registry` | mesh | `npm-package-registry` | the forge |
 | `mesh-git` | `git` | mesh | `git` | the forge |
 | `mesh-build-machine` | `the-build-machine` | node | — | a builder |
-| `mesh-resolver` | — | mesh | — | the mesh's one resolver, holding every node's internal domain ([ADR 0194](../../02-DECISIONS/0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md)) |
+| `mesh-resolver` | — | mesh | — | the mesh's resolvers, each holding every node's internal domain ([ADR 0194](../../02-DECISIONS/0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md)); replicated, held on the anchor and the home server ([ADR 0223](../../02-DECISIONS/0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md)) |
-| ~~`mesh-dns-port`~~ | `the-dns-port` | node | — | retired by [ADR 0194](../../02-DECISIONS/0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md): the local resolver became the mesh's one |
+| ~~`mesh-dns-port`~~ | `the-dns-port` | node | — | retired by [ADR 0194](../../02-DECISIONS/0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md): the local resolver became the mesh's one; deleted from the set, and from the store's table, once nothing claimed it ([ADR 0220](../../02-DECISIONS/0220-what-a-machine-asks-needs-its-uplink-held-and-the-retired-resolver-pieces-go.md)) |
-| `node-hosts-file` | — | node | — | owns `/etc/hosts`: the machine's own lines and the operator's kept region, changed through its verbs `entries`, `add`, `remove` ([ADR 0199](../../02-DECISIONS/0199-a-module-that-answers-names-declares-its-zone-and-a-nodes-hosts-file-is-one-modules.md)) |
+| `node-hostname` | `node-hosts-file` (renamed by [ADR 0223](../../02-DECISIONS/0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md); the former name an alias) | node | — | owns a machine's names: `/etc/hostname`, written from its holder's `hostname` setting with no default and taking effect at the next boot, and in `/etc/hosts` the machine's own lines and the operator's kept region, changed through its verbs `entries`, `add`, `remove` ([ADR 0199](../../02-DECISIONS/0199-a-module-that-answers-names-declares-its-zone-and-a-nodes-hosts-file-is-one-modules.md)). Held by the module `hostname`, formerly `hosts` |
 | `mesh-intrusion-prevention` | `the-intrusion-prevention` | node | — | an intrusion-prevention service |
 | `mesh-packet-filter` | `the-packet-filter` | node | — | the packet filter |
 | `mesh-private-network` | `the-private-network` | node | — | the private network the mesh runs over |
-| `mesh-resolver-configuration` | `the-resolver-configuration` | node | — | whichever of the alternative resolver configurations is chosen |
+| ~~`mesh-resolver-configuration`~~ | `the-resolver-configuration` | node | — | retired by [ADR 0223](../../02-DECISIONS/0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md): `/etc/resolv.conf` is written by the holder of `node-uplink`, the program that would otherwise rewrite it, and the need of the uplink beside it ([ADR 0220](../../02-DECISIONS/0220-what-a-machine-asks-needs-its-uplink-held-and-the-retired-resolver-pieces-go.md)) goes with it; deleted from the set, and from the store's table, once nothing claims it |
 | `mesh-showcase` | `the-showcase` | node | — | the showcase module |
 
 The controller holds **the mesh's own** entries in code, and a test asserts their size and that
@@ -202,10 +220,28 @@ Nothing reaches that state by accident: an unknown manifest field is refused out
 protocol was written as one. Checked by a registration test accepting a node seat with no protocol
 and by the showcase manifest, which declares one.
 
-Most node seats deliver nothing. They say which module is this machine's packet filter, or which of
+Most node seats deliver nothing. They say which module is this machine's packet filter, or which
-two alternative resolver configurations it runs, and a second holder is refused. That is the whole of
+module writes its resolver file, and a second holder is refused. That is the whole of
 their job, and it is a real one: it is the mesh saying what a machine is, in words a person can read.
 
+## A seat that needs another beside it
+
+*2026-10-05* ([ADR 0220](../../02-DECISIONS/0220-what-a-machine-asks-needs-its-uplink-held-and-the-retired-resolver-pieces-go.md)). **A seat may name the node seats its holder needs held on the
+same node**, because some roles are right only while another is filled beside them. The holder of the
+resolver configuration writes `/etc/resolv.conf`, and that file stays the mesh's only while the
+machine's network manager is told to leave it alone — which is what the uplink's holder does
+([ADR 0117](../../02-DECISIONS/0117-a-machines-uplink-is-a-seat.md)). So the resolver configuration
+needs the uplink.
+
+**A module claiming such a seat depends on each seat it needs**, exactly as a module declaring a
+service depends on the service manager
+([ADR 0207](../../02-DECISIONS/0207-a-module-depends-on-the-node-seats-that-apply-its-resources.md)):
+derived from the claim and never written in a manifest, met by any module assigned to the node, judged
+over the node's whole set, refused at assignment naming the seat and the modules that could hold it,
+and refused at composition. Taking the needed seat's last holder from beneath a dependent is refused
+too. What a seat needs is the mesh's definition of the role, compiled with the set and never stored,
+and adding a need is a decision.
+
 ## The overview
 
 The controller lists every seat in the set with its scope, what it delivers, and its holder as a node
@@ -259,5 +295,8 @@ checked as their tables say:
 | `secret` has one provider, the holder of `mesh-vault` | 0161: a second claimant of the seat is refused by name (`CanHold`); *correction of fact, 2026-10-01: no parser rule ever reserved the word, the seat does the work*. |
 | A singular fact about machines is a placement of capacity one, refused by name | 0161: the overlay command's test for a second hub; the store's unique index. |
 | A holder of `node-uplink` is the dialect the machine runs | 0161: the host reports `uplink-<manager>` in its profile with every report; a resolution test refuses the other holder naming the capability. |
+| A seat's holder has the seats it needs beside it: the resolver configuration is refused at `assign` without the uplink held on its node, and the uplink's last holder cannot be taken from beneath it | 0220: seat-dependency tests on the definition, on a synthetic claimant, at assign, at unassign and at composition, and one reading the catalogue for the uplink's possible holders. |
+| A replicated seat has every holder on record and composes on each; a seat held once still refuses a second holder, on record or not; `--add` is refused for it | 0223: resolution and composition tests with two holders on record and a third machine, with two claimants and nothing on record, and on `mesh-store`; a unit test that only `mesh-dns-resolver` is replicated, surviving the store's rows; store tests keeping several holders once each, a handover leaving one, and unassigning one taking only its row. |
+| A retired seat leaves the set once nothing claims it, from the compiled set and the store's table both | 0220: the closed-set test's count, and the store migration that deletes the row. |
 | Holdings are derived, and the overview lists every seat | 0118: the `seats` command test, including an unheld seat. |
 | A build source on the seat records no address; an unheld seat refuses only self-hosted builds | 0111's tests. |

03-DESIGN/01-to-be/30-the-mesh-updates-itself-on-a-push.md

@@ -2,8 +2,10 @@
 layer: to-be
 status: proposed
 code: []
-updated: 2026-10-01
+updated: 2026-10-05
 decisions:
+  - 02-DECISIONS/0221-a-push-sends-no-build-a-policy-or-a-plan-holds-back-except-to-the-machine-it-names.md
+  - 02-DECISIONS/0218-a-plan-sends-grants-before-code-rolls-out-one-machine-first-and-a-newer-merge-takes-over-an-older-plan.md
   - 02-DECISIONS/0162-a-merge-produces-a-tiered-plan-the-mesh-keeps.md
   - 02-DECISIONS/0157-a-build-says-what-it-does-on-the-bus-as-it-happens.md
   - 02-DECISIONS/0121-a-system-seat-is-named-for-its-scope-and-modules-define-their-own.md
@@ -129,6 +131,40 @@ controller replaced mid-plan resumes from the store. `status` lists open plans a
 has waited too long. The transition discipline for breaking changes in the list above is still
 unwritten, and still the next thing.
 
+## How a plan sends (2026-10-05)
+
+Revision, [ADR 0218](../../02-DECISIONS/0218-a-plan-sends-grants-before-code-rolls-out-one-machine-first-and-a-newer-merge-takes-over-an-older-plan.md). Three rules on how a plan delivers what it built.
+
+- **Grants travel before code.** A send issues the memberships for the machines it is about to send to
+  before their declarations. The machine holding the bus is sent first when the list of bus users changes.
+  A membership that could not be issued fails the send.
+- **One machine first.** Unless a module's upgrade policy says *together*, a plan sends it to one machine,
+  the first by name, and to the rest only once that machine reports the new declaration applied and
+  current. A first machine that fails stops the module's rollout there, with the reason in the plan.
+- **A newer merge takes over.** A merge's plan supersedes every older open plan for the same repository
+  and branch, and takes in the modules they had not yet built. A plan that waits on nothing can be closed
+  by hand, by its id.
+
+What a merge changed is read from the forge whole, page by page
+([issue 252](../../04-ISSUES/252-a-merges-changed-modules-were-read-wrong/00-report.md)). A changed path in a
+module directory the mesh does not hold yet is that module's own, not shared code, when its definition is
+among the changed paths.
+
+## What a push does not send (2026-10-05)
+
+Revision, [ADR 0221](../../02-DECISIONS/0221-a-push-sends-no-build-a-policy-or-a-plan-holds-back-except-to-the-machine-it-names.md).
+A named push still sends every other machine its work left behind, but no longer a build that an upgrade
+policy or a plan is holding back
+([issue 259](../../04-ISSUES/259-a-named-push-sent-every-machine/00-report.md)).
+
+- **A send records the builds it carried**: which build of each module the machine was sent.
+- **A machine a push did not name is left** when a module it runs would move to a build its policy
+  records rather than rolls out, or that an open plan has not sent it yet. A machine whose last send's
+  builds are not known is left too. The push names the machine, the module, the builds and the reason,
+  and says `push <node>` sends it.
+- The machine a push names, a push of every machine, and `push --behind` send held builds as before.
+  Walking a change through the mesh under `record` is one `push <node>` per machine.
+
 ## Why now, and why not yet
 
 **Why it matters:** self-update is the difference between a mesh a person maintains by typing

04-ISSUES/179-an-adopted-identity-providers-admin-never-took-the-minted-secret/00-report.md

@@ -1,9 +1,9 @@
 ---
-status: resolved
+status: located
 opened: 2026-10-01
-located-in: [the identity provider's assignment on the control node (an adopted database whose admin predates the mesh), mesh-catalog modules/keycloak (the minted `admin` own-secret, applied by the server only when it creates its master realm)]
+located-in: [the identity provider's assignment on the control node (an adopted database whose admin predates the mesh, and the same database moved on 2026-10-05), mesh-catalog modules/keycloak (the minted `admin` own-secret, applied by the server only when it creates its master realm), every provider's provisioner loop (a consumer failed for a day said so only in a journal), mesh-controller status (nothing read what a provider could not do)]
-fixed-by: done by hand on 2026-10-01 through the server's own bootstrap command — the admin's password set to the value the mesh minted; no code changed
+fixed-by: twice by hand through the server's own bootstrap command (2026-10-01, 2026-10-05); the safety nets in mesh-controller PR #70, mesh-host PR #28 and mesh-catalog PR #80 (ADR 0224), resolved when they are merged and rolled out
-amended-design:
+amended-design: 03-DESIGN/01-to-be/19-the-module-protocol.md
 ---
 
 # 179 — An adopted identity provider's admin never took the secret the mesh minted
@@ -44,6 +44,60 @@ only the download client's: a credential the mesh cannot make is the operator's
 *How it was checked:* `keycloak_list_realms` through the console answers; `keycloak_list_clients`
 on the realm lists both mesh-named clients; the server's log stops the five-second login error.
 
+## Recurred, 2026-10-05
+
+**The identity provider's database was moved that morning, and the admin's old password came back
+with it.** The record the 2026-10-01 repair wrote lived in the database; the database that came up
+on the new store was taken from before that repair, so the realm's `admin` again held a password that
+predates the mesh, and the server — which applies the minted variable only when it creates its master
+realm — did not touch it. From shortly after midnight the provisioner failed every consumer every five
+seconds with *401 invalid_grant, Invalid user credentials*: about 31,000 refused logins until it was
+repaired by hand, the same way as the first time, at about 23:55. In those twenty-three hours nothing
+anywhere said so except the provider's own journal. The machines applied what they were sent, the
+module was current, and `status` printed its all-well sentence.
+
+**The repair, as done both times**, inside the server's container and with nothing printed: the
+server's `bootstrap-admin user` command creates a temporary administrator, from a password generated
+in the container and handed over in an environment variable, on a management port other than the
+default (the running server holds that one); the admin client logs in as it and sets `admin`'s password
+to the value the mesh minted; the temporary administrator and every temporary file are removed.
+
+## What makes it not happen silently again (ADR 0224)
+
+Twice by hand is a pattern, and the operator's direction was that it never happen again: detected
+automatically, repaired automatically where safe, loud where not, and tested.
+[ADR 0224](../../02-DECISIONS/0224-a-provider-that-keeps-failing-a-consumer-is-a-problem-the-controller-reports.md)
+records the rule; three safety nets implement it.
+
+1. **The identity provider repairs its own admin.** Its code — ported from TypeScript to Go with this
+   change — checks that `admin` logs in with the mesh's secret once the server answers, every five
+   minutes after, and at once whenever the provisioner is refused. A refusal is repaired exactly as
+   above, by the module, inside the server's container through the container runtime it already
+   declares, with the secrets passed on standard input and never on a command line; then the login is
+   checked again and one line and an `admin.repaired` event say what was done and why. A repair that
+   fails is announced as `admin.unrepaired`, said loudly in the journal with a pointer here, and braked —
+   ten minutes, doubling to six hours — and while the admin is refused the provisioner stops asking the
+   server, so a lockout policy is never provoked. `keycloak_admin_check` reports the admin's state and,
+   with `repair`, repairs it now.
+2. **A provider that keeps failing a consumer says so.** The provisioner loop announces a consumer it
+   has failed for five minutes without a success — create, the periodic check or an unreadable secret —
+   as `provisioner.failing`, with the class of error, and again every fifteen minutes; its recovery as
+   `provisioner.recovered`.
+3. **`status` names it.** The controller keeps each provider's newest failing word per consumer, and
+   `status`, its JSON and `node show` list it; it breaks the all-well sentence. On 2026-10-05 the first
+   line of `status` would have been the identity provider failing both consumers with
+   `credentials-rejected`, five minutes after midnight.
+
+The first is specific to this module and is the repair; the second and third are for every provider,
+and are what would have said it on the day even if the repair had not existed.
+
+*How it is checked:* the module's tests drive the repair against a fake server and a fake container
+runtime — repaired and verified on a refusal, never while the server is unreachable, braked after a
+failed repair, no secret on any command line, the provisioner short-circuited while refused; the loop's
+tests drive the announcements; the controller's tests take a failing word from the bus to `status` and
+`node show` and back out on recovery. Live, after rollout: a deliberately wrong admin password on a
+throwaway server is repaired within five minutes, and `status` stays all-well while it is.
+
 ## Open
 
 The manifest still says the admin password is the mesh's to mint, which is true of a fresh install

04-ISSUES/190-the-runtimes-configuration-is-written-by-modules-that-are-not-the-runtime/00-report.md

@@ -1,8 +1,8 @@
 ---
-status: located
+status: resolved
 opened: 2026-10-01
-located-in: [mesh-catalog modules/dnsmasq, mesh-controller internal/overlay/generator.go, mesh-controller internal/catalogue/resolve.go (checkResources)]
+located-in: [mesh-catalog modules/dnsmasq, mesh-catalog modules/docker, mesh-controller internal/overlay/generator.go, mesh-controller internal/catalogue/resolve.go (checkResources), mesh-controller internal/catalogue/seat_into.go, mesh-host internal/apply/apply.go (orphan removal)]
-fixed-by:
+fixed-by: novox/mesh-controller#62 (d84c969), novox/mesh-catalog#72 (5c89eaf), novox/mesh-host#26 (a192bcc), novox/mesh-controller#63 (c34b937)
 amended-design:
 ---
 
@@ -71,6 +71,32 @@ gives that module declared settings with defaults. The fix, once both are accept
 5. The collision check sees a computed module's resources as well, so a second writer cannot come
    back through generated code.
 
+> **Where it stands, 2026-10-05.** Step 1 is done: the resolver module writes nothing into the
+> runtime's file, and the runtime's module (the holder of `node-container-runtime`) writes
+> `live-restore` and reloads its own service. No module writes `dns`
+> ([ADR 0196](../../02-DECISIONS/0196-a-node-asks-the-meshs-resolver-first-and-a-public-one-only-when-it-is-silent.md)).
+> That answers the first two open questions below.
+>
+> Steps 2, 3 and 5 are decided in
+> [ADR 0222](../../02-DECISIONS/0222-a-module-is-told-where-a-mesh-seats-holder-is-reached-and-the-controller-writes-no-file-a-seats-holder-owns.md),
+> and the operator's rule is general: the controller never writes a file a seat's holder owns; it
+> tells the owner. The registry reaches the runtime's module as a value the mesh holds, not as a
+> setting: `${seat:mesh-artifact-store:reach}`, with no binding. The ADR 0082 and ADR 0102 notes
+> step 2 asks for are written.
+>
+> Step 4's single push is replaced by an order. A list member written by two records is tolerated
+> by the host, which a scalar key in two modules was not. Four pull requests, merged in this order:
+>
+> 1. The controller learns the placeholder (mesh-controller #62).
+> 2. The runtime's module states `insecure-registries` with it (mesh-catalog #72).
+> 3. The host leaves a unit alone when another declared service still holds it. It is deployed
+>    before 4. Without it, removing the private network's record of the runtime's service gives back
+>    what that record found (mesh-host #26).
+> 4. The controller stops generating the private network's two resources, and checks generated
+>    resources for collisions (mesh-controller #63).
+>
+> `fixed-by:` is filled when they merge.
+
 ## Open questions
 
 - **How the resolver's address reaches the runtime.** Either the resolver seat (`node-dns-resolver`)
@@ -83,3 +109,10 @@ gives that module declared settings with defaults. The fix, once both are accept
 - **The adopted machine's predecessor values.** The runtime module adopting a file with a
   hand-written `dns` and `live-restore: false` replaces both. That is intended, and is the one
   restart the operator must make on that machine.
+
+## Verified
+
+2026-10-05: on every machine `insecure-registries` is now the runtime's module's own, filled from the
+store's seat; the private network's two generated resources are gone. The handover kept the list
+member throughout, and the old reload record was forgotten, not given back ("docker.runtime still
+holds the unit"), so the runtime was never stopped.

04-ISSUES/224-an-apply-reopens-a-maintenance-window-by-recreating-what-it-held-still/00-report.md

@@ -1,8 +1,8 @@
 ---
-status: open
+status: resolved
 opened: 2026-10-04
 located-in: [mesh-host internal/apply/apply.go, mesh-host internal/apply/schedule.go]
-fixed-by:
+fixed-by: mesh-host PR #23
 amended-design:
 ---
 
@@ -62,3 +62,9 @@ is a hole in something new rather than something that broke.
   at the cost of a second source for "is this container meant to be running".
 - Either way: should the *report* say a window is open, so a machine that looks half-stopped at
   03:31 reads as working rather than broken?
+
+## Resolved — 2026-10-05
+
+An apply that arrives during a window now leaves the containers the window holds alone, and reports them `held-still`, naming the step. The first apply after the window converges them. The window is recorded under the host's state directory, the one place every applier on a machine shares: the daemon, a hand-run apply and the installer. It is released on every path, and lapses after six hours or when its process is gone. The machine's report lists open windows. Live on all four machines the same evening. Of the issue's two options, the narrower was taken: nothing blocks, so a push is never held for the length of a window.
+
+Accepted and said in the change: an apply that inspected a container as running in the instant a window opens can still recreate it.

04-ISSUES/243-a-rebuilt-licence-store-silences-every-node/00-report.md

@@ -1,8 +1,8 @@
 ---
-status: located
+status: resolved
 opened: 2026-10-05
 located-in: [mesh-catalog modules/claude-code, mesh-catalog modules/claude-licence-manager]
-fixed-by:
+fixed-by: mesh-catalog PR #45
 amended-design:
 ---
 

04-ISSUES/243-a-rebuilt-licence-store-silences-every-node/01-diagnosis.md

@@ -31,3 +31,9 @@
 **Ruled out.** The bus delivered every binding: each machine that took the fourth binding did so in the
 same second it was published. The licences themselves were sound. The remaining licence refreshed
 on every attempt, and the second account's login was adopted from its first report.
+
+## Resolved — 2026-10-05
+
+Live on all four machines and the manager the same morning. After the restart every machine reported
+the generation it held, and the manager's bindings matched them. The manager logged no failure while
+moving its sequence past them.

04-ISSUES/244-a-verb-whose-schema-is-empty-cannot-be-called-through-the-console/00-report.md

@@ -1,5 +1,5 @@
 ---
-status: open
+status: located
 opened: 2026-10-05
 located-in: [mesh-tools, mesh-controller]
 fixed-by:
@@ -60,6 +60,26 @@ and it is wrong.
   schema describes — a test that calls each with its schema's required set and asserts the answer
   is not "needs" an argument the schema does not have.
 
+## Seen again, 2026-10-05 and 2026-10-06 — and once it did harm
+
+The same picture for more of the mesh's own verbs, read through the console:
+
+```
+mesh_describe  mesh-controller.push      → {"properties": {}}
+mesh_describe  mesh-controller.plan      → {"properties": {}}
+mesh_describe  mesh-controller.assign    → module only, no node
+mesh_describe  mesh-controller.pin       → provision, from, module — no node
+mesh_describe  mesh-controller.settings  → module, values, clear — no node
+```
+
+`build` and `queue`, which take no machine, described in full. For `plan` this is the refusal above.
+For **`push` it was worse than a refusal**: a push takes no required argument, so a call naming one
+machine arrived empty, ran as a push of every machine behind, and answered "N node(s) told" — an
+operator who believed they had pushed one machine had pushed the mesh. Nothing in the answer said the
+machine had been lost.
+
+The diagnosis is in [`01-diagnosis.md`](01-diagnosis.md).
+
 ## Worked around, for now
 
 Through `<node>/node-login-shell.execute`, running the controller's own command line on the

04-ISSUES/244-a-verb-whose-schema-is-empty-cannot-be-called-through-the-console/01-diagnosis.md

@@ -0,0 +1,63 @@
+# Diagnosis
+
+## 2026-10-06
+
+**The schema is not empty where it is kept.** The controller's verb table declares `node` for every
+verb that acts on a machine, and so does the seat's record: asked through the console,
+`mesh-controller.tools` answers `push`, `plan`, `assign`, `pin` and `settings` each with `node` among
+their properties. The controller's announcement on the bus carries the same schemas. So the
+controller publishes them whole, and the loss is after it.
+
+**The console takes `node` out of every schema and every call.** The console's address grammar
+(ADR 0195) puts the machine in the address for a seat held on every machine (`<node>/<seat>.<verb>`)
+and for a module on one machine (`<node>/<module>.<tool>`), and so describes those tools without a
+`node` argument and deletes one from their calls. It did both for **every** address — including a
+seat held once for the mesh, where there is no machine in the address and `node` is the verb's own
+argument: the machine the verb acts on. That is exactly the set observed: each verb lost `node` and
+nothing else, `push` and `plan` had nothing else and described as empty, and the verbs that take no
+machine (`build`, `queue`) were untouched. The older flat listing of the same console had this right
+(it kept a mesh seat's schema as declared); the address form did not carry the distinction over.
+
+**Why the verb then refused, or did the wrong thing.** The controller's verbs read the arguments they
+know and ignore the rest. Given nothing, `plan` and `node` said they needed `node`; `push`, whose
+`node` is optional, read its absence as "every machine behind" and did that. A verb that ignores what
+it does not read cannot tell "nothing was asked" from "something was lost on the way".
+
+**Ruled out.**
+
+- A stale seat record. The record is older than the controller's current source (some verbs lack
+  arguments added since), but it carries `node` wherever the source does.
+- The controller's announcement. It sends the record's schema per verb, unchanged.
+
+**Located in** `mesh-tools` (the console: the schema it describes and the arguments it sends) and
+`mesh-controller` (verbs that pass over what they are given).
+
+## What the fix does, and how it is checked
+
+Pull requests: novox/mesh-tools#14 and novox/mesh-controller#71 — open, not merged.
+
+- **The console** takes `node` out only where the address names the machine. There, a `node` naming
+  the same machine is redundant and dropped; one naming another machine is refused. A call to a seat's
+  verb carrying an argument the verb does not declare is refused, naming it — the seat's record is the
+  mesh's own description of the verb, so the console can judge it.
+- **The controller** refuses, naming the argument: one the verb does not declare; one it declares but
+  did not use for the command it composed (two arguments where one wins, or half of a two-argument
+  shape); a switch that is neither "true" nor "false". A push that names no machine says, as the
+  first line of its answer, that it is a push of the whole mesh and which machines it is sending, and
+  its last line names the machines told. `plan` gains `files`, `push` gains `behind` (the whole mesh
+  said outright, refused beside `node`), and the listing verbs a `limit`.
+- **Checked by tests that walk every verb the controller announces:** for every combination of a
+  verb's declared arguments, the verb either refuses or every argument given changes the command it
+  runs; every verb refuses an argument it does not declare, and `node` where it takes none; and every
+  flag of the command a verb runs — read from the command's own source — is an argument of the verb's
+  schema or is listed, with the reason, as set by the verb or withheld from it. A verb added later,
+  or a flag added to a command, fails these until its schema says how a caller reaches it.
+
+What the tests do not check is the console's own describe-and-call path against a live bus; its unit
+test covers the choice of when `node` is the address's and when it is the verb's.
+
+## Related
+
+Issue 259 is another way a named push reached every machine: there the machine arrived and the
+controller's flush after it sent the others. Different cause, same reader's harm — the answer of a
+push is the only place that says how far it went, which is why the whole-mesh line is in the answer.

04-ISSUES/245-status-calls-a-module-behind-when-only-its-repository-moved/00-report.md

@@ -0,0 +1,50 @@
+---
+status: open
+opened: 2026-10-05
+located-in: []
+fixed-by:
+amended-design:
+---
+
+# 245 — `status` calls a module behind when only its repository moved
+
+## What was observed
+
+2026-10-05. After three catalogue merges that changed 11 modules, `status` listed **69 modules
+behind their source**, each as `holds <older commit>, source has <newer commit>`, with the advice
+"`build --behind` builds them; `push --behind` sends them on".
+
+Between the two commits, `git diff --name-only` shows changes under 11 module directories only. For
+58 of the 69 modules listed, for example a Bluetooth module, the container runtime's, the forge's,
+the package manager's and the bus's, the diff of the module's own path is empty. Their sources did
+not change; only the repository's commit did.
+
+The merges' plans were right: they rebuilt the changed modules and those that depend on them, by
+tier. Only the report was wrong. An agent following the report's own advice ran `build --behind`,
+which rebuilt all 69. The rebuilt bus module was rolled out, and its container was replaced on the
+control node. Every node's runtime lost the bus for about a minute.
+
+## Why it matters beyond this instance
+
+"Behind" is the word a person and an agent act on, and `status` attaches a command to it. A module
+is held to a commit of its repository, so after any merge almost every module of that repository
+reads behind. The list then says nothing about what needs building: it hides the few modules that
+really are behind among the many that are not, and it invites a rebuild of everything, which is not
+a harmless act (above).
+
+## The operator's direction (2026-10-05)
+
+The only truth is the outcome of the build plan. A plan already decides, from a change, which modules
+it affects: those whose sources changed and those that depend on them, tier by tier. "Behind" means
+a module that a plan has decided to rebuild and has not yet rebuilt or rolled out, and nothing else.
+No second comparison beside the plan is made, whether of commits, of folders or of files, because a
+second answer to the same question is how the two came to disagree.
+
+## Open questions
+
+1. Where does `status` read "behind" from today, and what replaces it: the open plans' remaining
+   tiers?
+2. What does a module's recorded commit mean once a plan that leaves it untouched has run? Does it
+   move forward, or does the record stop carrying a commit that only says when it was last built?
+3. Should `build --behind` and `push --behind` take their lists from the same place, so that they can
+   never act on a module no plan named?

04-ISSUES/246-the-console-says-a-module-runs-nowhere-when-a-runtime-answers-late/00-report.md

@@ -0,0 +1,65 @@
+---
+status: resolved
+opened: 2026-10-05
+located-in: [mesh-tools]
+fixed-by: mesh-tools pull request 13 — discovery waits for every runtime that answered PING, names the ones it missed, and mesh_runtimes says who answered
+amended-design:
+---
+
+# 246 — The console says a module runs nowhere when a runtime answers late
+
+## What was observed
+
+2026-10-05. On the laptop, the console answered `mesh_machine` for the laptop with no modules and no
+seats, and a call to one of the laptop's modules with "nothing in the mesh is called slack". The
+laptop's own runtime said at the same moment that it served 275 tools for 48 modules. A minute
+earlier, a call to another laptop module had been answered with "it does not run on the laptop; it
+runs on the workstation", and a retry of the same call worked. Nothing was logged anywhere.
+
+An agent worked around it by calling the runtime's local MCP port directly, which gives the right
+answer and bypasses everything the console stands for: one way in, one account, one record of what
+was called. The operator asked for a tool instead.
+
+## What was measured
+
+A read-only probe on the laptop's own runtime credential timed the discovery answers over 25 rounds
+against the live bus, whose round trip from the laptop was about 40 ms:
+
+- The laptop's runtime answer was the largest on the mesh, at about 164 kB with 341 endpoints. That
+  is far below the bus's message limit, and it was never shortened.
+- It arrived last in every round: a median of about 365 ms, and once 813 ms. The other runtimes
+  answered within 180 to 275 ms, and the controller within 50 ms.
+- The console gathered discovery answers for a fixed 750 ms. Inside the console, the gather runs
+  beside two controller calls and about 570 kB of answers on the same link, and it is slower still
+  while a runtime re-serves after a restart.
+
+## Root cause
+
+Discovery decided who was there by who answered in a fixed window. A late answer was not a failure
+to anyone, so nobody said it. The index simply lacked that runtime, and every answer built on the
+index then stated as fact that the runtime's modules did not exist, or ran only elsewhere.
+
+Ruled out by measurement or by reading the code: an answer too large for the bus, subscriptions lost
+when the bus reconnects, the console not counting its own machine's answer, and the merge of two
+answers dropping a machine.
+
+## Resolution
+
+- Discovery asks who is there (PING, a hundred bytes, answered at once) beside what each serves
+  (INFO). It waits at least the old window, and then up to five seconds for every instance that said
+  it is there, so a large answer is waited for and a quiet mesh costs nothing extra.
+- A runtime that said it is there and did not say what it serves in time, or that answered recently
+  and not now, is named. While one is unheard, the console never says an address is missing or runs
+  elsewhere: it says which runtime was not heard, and where the controller's records place the module.
+- A new console tool, `mesh_runtimes`, says for every runtime how long its answer took, how large it
+  was, how many modules and tools it announced, whether it was shortened, and when it was last heard,
+  and which runtimes or machines were not heard.
+- An announcement still too large after its descriptions are cut to their first line now leaves the
+  descriptions out, and says so.
+
+## How it is checked
+
+The fix ships with tests against a real bus: a runtime that answers after the old window is found and
+called (the same test fails with the fixed window), a runtime that answers PING and never INFO is
+named, and a restarted runtime, which answers under a new instance, is not reported as missed. Live,
+`mesh_runtimes` shows every machine's answer and its time.

04-ISSUES/247-a-module-cannot-put-the-operators-account-in-a-group/00-report.md

@@ -0,0 +1,52 @@
+---
+status: open
+opened: 2026-10-05
+located-in: []
+fixed-by:
+amended-design:
+---
+
+# 247 — A module cannot put the operator's account in a group
+
+## What was observed
+
+2026-10-05. The module for a peripheral-lighting daemon was assigned to the laptop. Its package
+installs the daemon and creates the daemon's group. The daemon then refuses to start: "User is not a
+member of the openrazer group". The device files are the group's, so the daemon cannot reach the
+devices.
+
+The module's own check names the fix, which is to add the account to the group and log in again. No
+module can declare that fix:
+
+- The account is a `user` resource, and the login-shell module already declares it, to set its shell.
+- A second module that declares the same account, only to add one group, is refused as a duplicate
+  name.
+- There is no resource for one membership on its own. A whole-account declaration that lists groups
+  would also take from the account every group it does not list, including the operator's own.
+
+So the step is done by hand, with `sudo`, outside the mesh, and nothing records why the account is in
+the group.
+
+## Why it matters beyond this instance
+
+More modules need this than this one: input devices (`input`), serial ports (`uucp`), the container
+runtime (`docker`), virtual machines (`libvirt`, `kvm`), and capture or scanner hardware. Each is a
+fact a module knows and the operator's account needs. Today every one is a hand step that survives a
+reinstall only by memory. A membership added by hand is also never taken away when the module that
+needed it is unassigned.
+
+## Open questions
+
+1. Is a membership its own resource (account, group), held by the module that needs it and given
+   back on undeclare? Or is it a contribution to the account's holder, in the way ADR 0212 lets a
+   module contribute to a seat?
+2. A membership takes effect at the next login. How does the module say so: a finding, or a
+   moment the power or session seat already knows?
+3. What does undeclare do with a membership the account already had before any module declared it?
+   The host keeps what it found and gives it back, as it does with a whole file it wrote over.
+
+## How it is checked
+
+When fixed, assigning the lighting module to a machine whose account is not in the group puts the
+account in the group, says that a new login is needed, and leaves the account's other groups as they
+were. Unassigning it removes only a membership the module added.

04-ISSUES/248-the-controllers-event-consumer-replayed-a-week-and-held-every-merge-behind-it/00-report.md

@@ -0,0 +1,58 @@
+---
+status: resolved
+opened: 2026-10-05
+located-in: [mesh-controller internal/broker]
+fixed-by: mesh-controller PR #51
+amended-design:
+---
+
+# 248 — The controller's event consumer replayed a week, and held every new merge behind it
+
+## What was observed
+
+A merge to the catalogue at 15:17 never reached the controller. No plan was made and no build was asked
+for it. Every machine kept running the build from before it. The merge just before, to the record, was
+logged twice.
+
+The bus showed why. The controller's durable consumer on the event stream was set to deliver
+**everything the stream holds**, not from where it last was:
+
+| | |
+|---|---|
+| the stream | a week of events, from message 1 514 to message 356 004 |
+| the consumer delivered to | message 1 517, later 4 898 |
+| acknowledged to | 0, later 1 569 |
+| still to deliver | 6 955 merges and build outcomes, a week old |
+| allowed outstanding | one at a time ([issue 175](../175-an-announcement-behind-a-long-build-comes-back/00-report.md)) |
+
+So the controller was working through a week of past merges and build outcomes, one at a time, slowly. Every
+new one — a merge, a build asked by hand — waited behind them. A build asked by hand finished on its
+machine and was never registered. While this went on, the controller's client dropped messages
+("slow consumer") several times, because heartbeats and reports share the loop with these events. From 15:17
+its event loop did nothing more: no line logged, the one delivered event never acknowledged.
+
+How the consumer came to deliver everything is not certain. The bus and the stores were rebuilt the night
+before ([issue 241](../241-one-unreadable-grants-file-dropped-every-database-on-the-control-node/00-report.md)).
+A consumer that is missing is made again by the controller's own assertion, and that made it with the
+server's default, which is everything. [Issue 207](../207-a-re-made-worker-replayed-every-ask-the-stream-kept/00-report.md)
+closed this for a consumer re-made because its type changed. It did not close it for one that is simply
+not there.
+
+## Why it matters
+
+**Delivery stops, and nothing says so.** Status showed every plan done and no machine behind. The merge
+that was missed is not "behind", because no plan was ever made for it. A replay of past merges can also
+act on them again. Issue 207 records nine modules re-registered from the past the same way.
+
+**The way out was a hand on the bus.** No verb resets a consumer. On the operator's explicit word, the
+consumer was re-made from now with a one-off program run as the controller, otherwise unchanged. The
+controller's loop still held the old event afterwards, so the new consumer's first delivery went
+unacknowledged; the loop needs a restart of the controller to let go of it.
+
+## Noticed alongside, not this issue
+
+- Each merge to the catalogue planned 99 to 100 modules in two tiers and rebuilt modules it did not touch.
+  The output was byte-identical, so nothing was redeployed, but it costs minutes of the build machine
+  per merge.
+- Three plans for three merges ran over each other. Each sent the build agent to every machine and asked
+  for the same builds. Nothing supersedes a plan for an older commit.

04-ISSUES/248-the-controllers-event-consumer-replayed-a-week-and-held-every-merge-behind-it/01-diagnosis.md

@@ -0,0 +1,54 @@
+# 248 — Diagnosis
+
+## 2026-10-05
+
+1. A merge was not in the controller's log. The forge's own log showed nothing about delivering it, so the
+   question moved to the bus.
+2. The bus's backlog tool named the controller's event consumer: 6 955 pending, redeliveries, one
+   unacknowledged. Its configuration was read from the server's monitoring endpoint: deliver policy
+   *all*, one outstanding, 30 seconds to acknowledge, five deliveries.
+3. Sampled three times over a minute it did not move, and over the following hour it crawled forward
+   through week-old events. The controller's log held only its client's warnings: dropped messages,
+   and one refused reply.
+4. The controller's code makes a missing consumer with the configuration it asserts, which sets no
+   deliver policy, so the server's default applies: everything. Issue 207's fix sets *from now* only on
+   the path where an existing consumer's type changes.
+
+**Unblocked**, on the operator's explicit word: the consumer re-made from now with its configuration
+otherwise unchanged (nothing pending afterwards). The controller's loop still held the old event, so
+it takes a restart of the controller to let go of it; that restart waits for the operator's word.
+
+**Fix** (mesh-controller, branch `fix/a-consumer-on-a-history-stream-starts-from-now`):
+
+- a consumer may say it starts **from now** when it is made. The controller's event consumer does. A
+  consumer that exists keeps where it is. The server would refuse a changed start anyway.
+- `broker consumer-reset <stream> <consumer>` re-makes a stuck consumer from now, its configuration
+  otherwise kept, and refuses a work queue, where what is pending is work. It is the person's act, said by
+  a command, rather than a one-off program.
+
+Checked by a live test against a throwaway bus:
+
+- made from now, a consumer holds none of the stream's past and does hold the next announcement;
+- asserted again, it keeps its place;
+- the default replays all of it;
+- a reset leaves nothing pending and keeps every other setting;
+- a work queue's consumer is refused.
+
+**Not fixed here:** the client dropping messages while the loop acts on a long merge. Reports and
+heartbeats are redelivered or replaced, so nothing is lost for good, but the loop holding everything while
+it builds is the shape issue 175 already describes.
+
+## 2026-10-05, after the restart
+
+The consumer re-made from now held nothing, and the restarted controller acknowledged what it was handed.
+Two merges made right after reached it within two seconds, and the fixed controller was built, delivered and
+took over by its own plan within two minutes. The re-asked build of the agent module was registered and
+reached all four machines.
+
+**Not explained by this issue:** the record's merge was still logged twice, with the consumer fresh and
+nothing replayed. The duplication has a cause of its own, still to be found. It may be that the forge
+announces a merge on two paths, or that one event is handled twice.
+
+## Resolved — 2026-10-05
+
+The controller's event consumer is made from now when it is made, and `broker consumer-reset` re-makes a stuck one from now. Live: after the restart, merges reached the controller within seconds. Two tests main then failed, both skipped without a store, were fixed in mesh-controller PR #52. The merge heard twice was a separate cause: [issue 250](../250-a-merge-made-through-the-forges-tool-is-announced-twice/00-report.md).

04-ISSUES/249-a-modules-new-state-is-refused-until-a-push-the-merge-did-not-make/00-report.md

@@ -0,0 +1,37 @@
+---
+status: resolved
+opened: 2026-10-05
+located-in: [mesh-controller cmd/mesh-controller]
+fixed-by: mesh-controller PR #54
+amended-design: 03-DESIGN/01-to-be/30-the-mesh-updates-itself-on-a-push.md
+---
+
+# 249 — A module's new state is refused until a push the merge did not make
+
+## What was observed
+
+A merge gave the agent module a new state, a key-value bucket
+([ADR 0201](../../02-DECISIONS/0201-a-module-keeps-its-current-state-in-key-value-buckets-it-declares-and-reaches-through-the-runtime.md)).
+The module's new bundle reached all four machines within a minute of the build, at once. The machines'
+bus permissions did not include the new state until a push was made by hand afterwards.
+
+On three machines the module's watch of the new state was refused for about two minutes: "claude-code keeps
+and reads no state called config". It recovered only because the module asks again with a back-off, and
+the hand-made pushes issued the permissions.
+
+## Why it matters
+
+**The code arrives before the right to use it.** A module that does not retry stays broken until someone
+pushes. A module whose first act on start is to read its new state fails its start. Nothing in the plan
+says the two must travel together.
+
+**No machine went first.** The bundle reached every machine at the same moment. The rollout the operator
+was told — one machine first, then the rest — could not be followed, because the merge had already
+delivered it everywhere.
+
+## Open questions
+
+- Should a plan send a machine its membership, the grants that come with a module's new
+  declarations, in the same push as the bundle, and before it?
+- Should a merge that changes a module's declarations (state, events, tools) be delivered to one machine
+  first, and to the rest only once that one reports it healthy?

04-ISSUES/249-a-modules-new-state-is-refused-until-a-push-the-merge-did-not-make/01-diagnosis.md

@@ -0,0 +1,30 @@
+# 249 — Diagnosis
+
+## 2026-10-05
+
+**Grants after code.** Both a plan's rollout and a push send every machine its declaration first, and
+issue the memberships afterwards. The order is written into the code on purpose, "because the runtime it is
+for arrives with it". That reason holds only for a first assignment, and a membership is kept on the bus for
+a runtime that connects later anyway. A membership that failed was only printed, and left "until the next
+push". The list of bus users travels in the declaration of the machine that holds the bus, which a module's
+rollout reaches only if that machine runs the module.
+
+**No machine first.** The module's upgrade policy sends one machine at a time, but a plan's rollout ignored
+it and sent every machine at once. One at a time did not wait for the first machine to come up either: it
+stopped only if the publish failed.
+
+**Not answered by the open decision on unseen changes** (a removal, a move or a replacement, shown
+before it takes effect). That decision leaves an add-only change alone on purpose, and a new state is one.
+
+**Decided** in [ADR 0218](../../02-DECISIONS/0218-a-plan-sends-grants-before-code-rolls-out-one-machine-first-and-a-newer-merge-takes-over-an-older-plan.md):
+grants before code, and one machine first unless a module's policy says *together*.
+
+## Resolved — 2026-10-05
+
+[ADR 0218](../../02-DECISIONS/0218-a-plan-sends-grants-before-code-rolls-out-one-machine-first-and-a-newer-merge-takes-over-an-older-plan.md), live the same evening:
+
+- every push now issues memberships before it sends declarations;
+- the bus's machine goes first when its list of users moved;
+- a plan sent the build agent to one machine first and to the rest once that machine reported.
+
+The first live rollout exposed a fault in the tier gate. The first machine's report, made between the two sends, was read as stale ([issue 256](../256-a-first-machines-report-read-as-stale-between-the-two-sends/00-report.md)).

04-ISSUES/250-a-merge-made-through-the-forges-tool-is-announced-twice/00-report.md

@@ -0,0 +1,49 @@
+---
+status: resolved
+opened: 2026-10-05
+located-in: [mesh-catalog modules/gitea]
+fixed-by: mesh-catalog PR #63, PR #66
+amended-design:
+---
+
+# 250 — A merge made through the forge's tool is announced twice
+
+## What was observed
+
+The controller logged the record repository's merges twice, seconds apart, with the same commit, even with
+its event consumer freshly made ([issue 248](../248-the-controllers-event-consumer-replayed-a-week-and-held-every-merge-behind-it/00-report.md)).
+Counted over one day:
+
+- 8 of the record's merges were logged twice, against 4 once;
+- 10 of the catalogue's, against 7 once;
+- 2 of the controller's.
+
+A code repository's second line reads differently — "it changed nothing any module the mesh holds is built
+from" — so it was taken for a different message.
+
+## Diagnosis
+
+The forge's module announces a merge from two places in the same process:
+
+1. its merge tool, the moment it merges;
+2. the poll added for [issue 131](../131-nothing-tells-the-mesh-a-source-moved/00-report.md), which
+   announces every merged pull request it has not recorded as announced.
+
+The tool never records what it announced, so the poll announces it again 0.5 to 16 seconds later.
+Merges made in the forge's web interface or by a plain API call are seen by the poll alone, and those are
+the ones logged once. The module's own header comments still say merges are announced "from the tools …
+one process only".
+
+No harm was done this time, but only by luck. The second event is absorbed because the first one moved
+the controller's record of the source. A repository read only by packaging modules has no such record, so
+it would get a second plan. The record module synced twice for each merge.
+
+## Fix
+
+The poll is the only emitter: it sees every path and carries the clone address. The tool merges and
+answers the merge commit. A merge made through the tool is heard up to thirty seconds later, which the
+module already accepts ("an event a minute late is still an event").
+
+## Resolved — 2026-10-05
+
+The forge module's poll is the only announcer of a merge. It asks only the repositories that moved since its last look, and one pass at a time. Live: three merges were each heard once, and a later merge was planned within a minute.

04-ISSUES/251-the-records-checkout-could-not-sync-after-it-ran-as-another-account/00-report.md

@@ -0,0 +1,36 @@
+---
+status: resolved
+opened: 2026-10-05
+located-in: [mesh-catalog modules/records]
+fixed-by: mesh-catalog PR #64
+amended-design:
+---
+
+# 251 — The record's checkout could not sync after it ran as another account
+
+## What was observed
+
+Every sync of the record module failed, on every merge and every timer: git refused the checkout as
+"dubious ownership". The record tools answered all the while, from the checkout as it last stood, and
+nothing said it was stale.
+
+## Diagnosis
+
+The module ran in a container, as the superuser, until its code moved into the machine's tool runtime
+([ADR 0198](../../02-DECISIONS/0198-a-modules-long-running-code-is-launched-by-the-node-runtime-and-reaches-the-bus-through-it.md)).
+The runtime launches it as the operator account. The checkout's git directory and 2 598 of its files still
+belonged to the superuser. Git refuses a repository owned by another user, and the operator account could
+change none of those files.
+
+The module also still declared that it needs a container runtime, a leftover of the same move.
+
+## Fix
+
+The module, ported to Go as part of the fix, clones into a directory of its own inside the one it is given:
+a directory it makes, and so owns. What the old layout left behind is removed where it is the module's.
+Where it is not, the module names it in its status, with the one command that deletes it. The
+container-runtime capability is dropped. A sync that fails is still said in the status, as before.
+
+## Resolved — 2026-10-05
+
+The record module, ported to Go, clones into a directory it makes and owns. Live: it synced to the newest commit, with 692 documents. It names seven leftovers of the old checkout that it cannot remove, with the command that removes them; that is the operator's act.

04-ISSUES/252-a-merges-changed-modules-were-read-wrong/00-report.md

@@ -0,0 +1,38 @@
+---
+status: resolved
+opened: 2026-10-05
+located-in: [mesh-catalog modules/gitea, mesh-controller cmd/mesh-controller]
+fixed-by: mesh-catalog PR #63, mesh-controller PR #54
+amended-design: 03-DESIGN/01-to-be/30-the-mesh-updates-itself-on-a-push.md
+---
+
+# 252 — A merge's changed modules were read wrong, in both directions
+
+## What was observed
+
+Each of three merges to the catalogue within four minutes planned 99 to 100 modules, and rebuilt modules
+they did not touch. The outputs were identical, so nothing was redeployed. The rebuilds cost the build
+machine minutes for every merge.
+
+## Diagnosis
+
+**Too many.** The controller treats a changed path outside every module directory it knows as shared code,
+and rebuilds every module built from the repository. A new module's directory, or one being removed,
+counts: the module is registered only after the merge is planned. Each of the three merges added or
+removed a module. The build agent, built from the same repository, then joins the set and becomes tier 0.
+
+**Too few.** The forge's module asked for a hundred changed files and was given fifty, the forge's page
+size, and reported the list as whole. A merge of 59 files reached the controller with 50. Had the full
+rebuild not hidden it, a module whose own files changed would have stayed unbuilt.
+
+## Fix
+
+- The forge's module reads every page of a pull request's files.
+- The controller counts a changed path in a sibling of known module directories as that module's own, not
+  shared, when that module's definition is among the changed paths. A sibling without a definition, such
+  as a shared library, still means everything, which is the safe direction. Root files still mean
+  everything.
+
+## Resolved — 2026-10-05
+
+The forge's module reads every page of a pull request's files. The controller counts a new module's own directory as that module's when its definition is among the changed paths. Live: catalogue merges planned one module each.

04-ISSUES/253-the-stores-collector-would-delete-every-archive-the-mesh-keeps/00-report.md

@@ -0,0 +1,55 @@
+---
+status: located
+opened: 2026-10-05
+located-in: [mesh-controller internal/builder, mesh-controller internal/artifacts, mesh-catalog modules/distribution]
+fixed-by: mesh-controller PR #53, mesh-host PR #23, mesh-catalog PR #62
+amended-design: 03-DESIGN/01-to-be/18-building-a-module.md
+---
+
+# 253 — The store's collector would delete every archive the mesh keeps
+
+## What was observed
+
+The store's nightly collector ([ADR 0189](../../02-DECISIONS/0189-the-store-keeps-what-the-records-name.md))
+was installed the same day, its first run due that night. Measured read-only beforehand:
+
+| | |
+|---|---|
+| blobs in the store | 8 186 |
+| blobs a manifest names, kept by the collector | 2 090 |
+| blobs it would delete | 6 096 |
+| repositories holding only archives, none named by any manifest | 105 |
+
+Among the archives it would delete were the current bundles of the agent module, the machine host, the
+controller and the tool runtime. Each was named by no manifest, though the controller's records keep them.
+
+## Why it matters
+
+Machines keep their unpacked copies, so nothing would have stopped at once. But any fresh fetch of an
+unchanged module would have failed: a machine joining, a reinstall, an apply that fetches again, the
+controller's own next rollout.
+
+## Diagnosis
+
+Images are pushed with manifests. Archives were published as bare blobs, which no manifest names. The
+store's stock collector marks only from manifests, so every bare blob is unmarked, kept or not. ADR 0189's
+sentence "what the mesh keeps is still a manifest in the store" was true of images only.
+
+Found alongside: the "five most recent builds" reason kept builds of modules the mesh no longer holds,
+forever.
+
+## Fix
+
+- **That night, before the first run:** the collector was changed to a dry run, in its module's
+  definition, and delivered.
+- **Then:**
+  - every archive is published with a manifest that holds it;
+  - the controller's sweep holds every kept archive before it lets anything go, which backfills those
+    already published;
+  - letting an archive go removes its manifest first;
+  - a forgotten module keeps nothing.
+- Real collection returns once the controller reports no kept archive unheld.
+
+## Where it stands — 2026-10-05
+
+Every kept archive is held: the controller's collection command reports 134 of 134 held, none missing. The window the collector needs is no longer reopened by an apply ([issue 224](../224-an-apply-reopens-a-maintenance-window-by-recreating-what-it-held-still/00-report.md)). The collector still runs as a dry run. Turning it to real collection deletes the layers nothing keeps, which is the operator's word to give; this issue resolves when that change lands.

04-ISSUES/254-plans-for-successive-merges-run-over-each-other-and-one-was-left-open/00-report.md

@@ -0,0 +1,36 @@
+---
+status: resolved
+opened: 2026-10-05
+located-in: [mesh-controller cmd/mesh-controller, mesh-controller internal/inventory]
+fixed-by: mesh-controller PR #54
+amended-design: 03-DESIGN/01-to-be/30-the-mesh-updates-itself-on-a-push.md
+---
+
+# 254 — Plans for successive merges run over each other, and one was left open
+
+## What was observed
+
+Three merges to the catalogue within four minutes made three plans, and all three ran at once:
+
+- each sent the build agent to every machine;
+- each asked for the same tier of builds — one module was asked for 32 seconds apart by two plans;
+- the plan for the middle merge still showed "building" hours later, waiting on nothing.
+
+## Diagnosis
+
+A merge's plan is saved without looking at the open plans
+([ADR 0162](../../02-DECISIONS/0162-a-merge-produces-a-tiered-plan-the-mesh-keeps.md): one plan per merge).
+Each open plan advances on its own. Nothing ends a plan whose work a newer merge has taken over, and
+nothing lets a person close a plan that waits on nothing.
+[Issue 219](../219-an-older-build-that-finishes-later-replaces-a-newer-one/00-report.md) settled only which
+build's output wins.
+
+## Fix
+
+[ADR 0218](../../02-DECISIONS/0218-a-plan-sends-grants-before-code-rolls-out-one-machine-first-and-a-newer-merge-takes-over-an-older-plan.md)
+§3. A newer merge's plan supersedes the older open plans for the same repository and branch, and takes in
+the modules they had not built. A person can close a plan by its id.
+
+## Resolved — 2026-10-05
+
+A newer merge's plan supersedes the older open plans of its repository and branch, and a person can close a plan by its id. Live: the plan left open since the afternoon was closed by hand, and its note said what it had built and never sent. A merge made while the controller's own plan was open took it over: the older plan reads "superseded at tier 0 by" the newer, which planned its three modules again.

04-ISSUES/255-the-journal-verb-read-nothing-for-a-system-service/00-report.md

@@ -0,0 +1,36 @@
+---
+status: resolved
+opened: 2026-10-05
+located-in: [mesh-catalog modules/systemd]
+fixed-by: mesh-catalog PR #65
+amended-design:
+---
+
+# 255 — The journal verb read nothing for a system service
+
+## What was observed
+
+The service manager seat's `journal` verb answered "-- No entries --" for the controller's service on the
+control node, while the service was logging steadily. Twice in one day a session reading the controller's
+log fell back to a shell on the machine: the verb that exists for exactly that question answered nothing.
+On one machine of four the same verb did answer: the only one whose operator account is in the journal's
+group.
+
+## Diagnosis
+
+The module runs as the operator account and escalates the five acts on the system manager with `sudo -n`.
+It ran `journalctl` unescalated. journalctl shows an account outside the journal's group only that
+account's own entries, and says "-- No entries --" for everything else. That reads as a quiet service, not
+as a refusal.
+
+The mesh grants the operator account passwordless escalation on every machine through its own drop-in, as
+the sudo module's check confirms.
+
+## Fix
+
+A read of the system journal escalates like an act does. The account's own journal, in the user scope,
+does not. The module was ported to Go as part of the fix, its tests with it.
+
+## Resolved — 2026-10-05
+
+The journal verb reads a system unit's journal escalated, in the module ported to Go. Live: the controller's and the host's journals read through the verb on the control node.

04-ISSUES/256-a-first-machines-report-read-as-stale-between-the-two-sends/00-report.md

@@ -0,0 +1,31 @@
+---
+status: resolved
+opened: 2026-10-05
+located-in: [mesh-controller cmd/mesh-controller]
+fixed-by: mesh-controller PR #55
+amended-design:
+---
+
+# 256 — A first machine's report read as stale between the two sends
+
+## What was observed
+
+The first plan to roll out under [ADR 0218](../../02-DECISIONS/0218-a-plan-sends-grants-before-code-rolls-out-one-machine-first-and-a-newer-merge-takes-over-an-older-plan.md)
+sent the build agent to one machine first, and to the other two once that machine reported it applied, 27
+seconds later. All three applied it within seconds. The plan then said, for seven minutes, that it was
+"waiting for build-agent" on the first machine to be applied. It went on only when that machine happened to
+report again for another reason.
+
+## Diagnosis
+
+The tier gate asked every machine for a report made after the module's last send. With one machine first,
+a module is sent twice, and the second send is the later one. The first machine's report came between the
+two sends, so it read as older than the build. The plan waited for that machine's next report, one report
+cycle, and never knew why.
+
+## Fix
+
+The gate judges each machine from its own send: the first machine from the first send, the rest from the
+second. A plan's wait is also printed to the second rather than the minute, where it had read "0s", and the
+first send is printed in the machine's own time rather than in UTC. Checked by the controller's test: a first
+machine's report between the two sends opens the gate, and a report from before its send does not.

04-ISSUES/257-a-plan-waited-on-a-declaration-its-first-machine-never-reported/00-report.md

@@ -0,0 +1,49 @@
+---
+status: located
+opened: 2026-10-05
+located-in: [mesh-host]
+fixed-by: novox/mesh-host#24 (89a7796)
+amended-design:
+---
+
+# 257. A plan waited on a declaration its first machine never reported
+
+## Symptom
+
+A merge to the controller's repository produced a plan of three tiers, the controller first. The
+controller was built and sent to its first machine, the anchor, which is also the machine holding the
+bus. The plan then said, for five minutes and with no end in sight:
+
+> tier 1 of 3, tier 0 built; waiting for mesh-controller on the anchor, sent first at 20:22 to report
+> it applied before the rest are sent
+
+The anchor had applied it. Its host's journal said `applied 470 resource(s)` ten seconds after the
+send, the new controller was running, and the controller logged the report.
+
+## Evidence
+
+The plan waits for a report that names the declaration last sent (ADR 0218, one machine first; the
+report's `declared` digest against the machine's recorded `sent` digest). Read from the store:
+
+| | digest | at |
+|---|---|---|
+| recorded as sent to the anchor | `09f4d6…` | 20:22:57.699 |
+| the anchor's report, `declared` | `39b48a…` | 20:23:07.718 |
+
+The anchor applied and reported a declaration that is not the one the controller recorded sending.
+So the report never counted, and the plan would have waited until its bound and then failed the
+rollout at its first machine, for a machine that had applied correctly.
+
+The other three machines' digests matched their reports at the same moment.
+
+## What unblocked it
+
+A push to the anchor, made for another reason (its bus grants), recorded a new send. The anchor's
+next report named it, the digests matched, and the plan moved on at its next tick and finished.
+
+## What it costs
+
+A plan that rolls out the controller itself, to the machine that holds the bus, can stop at its first
+machine with nothing wrong there. The plan's words are true but useless: they name a machine that
+already did what was asked. Merges made close together, from several sessions, are the case the
+plans exist for, and a controller change is among them.

04-ISSUES/257-a-plan-waited-on-a-declaration-its-first-machine-never-reported/01-diagnosis.md

@@ -0,0 +1,60 @@
+# Diagnosis
+
+## 2026-10-05
+
+**What is known.** The digest the controller recorded for the anchor (`09f4d6…`, at 20:22:57.699) is
+not the digest of what the anchor applied (`39b48a…`). The anchor's host logged one apply that
+updated the controller, starting at 20:23:02 and reporting at 20:23:07. The controller that sent it
+was replaced at 20:23:04 by that same apply. Its successor logged two reports from the anchor, both at
+20:23:07.
+
+**Ruled out.**
+
+- The catalogue's catch-up: that is the catalogue asking the controller, not a machine asking for its
+  declaration.
+- The host's five-minute check at 20:22:58: it applied nothing new (only "kept" lines). The apply
+  that moved the controller is the one at 20:23:02.
+- A digest computed differently by the host and the controller: the other three machines matched,
+  and after the push at 20:28:00 the anchor matched too.
+
+**Not yet confirmed: two sends to one machine in one step.** The anchor is both the plan's first
+machine and the machine holding the bus. Issue 249 sends the machine holding the bus before the first
+machine when its user list must change, and this controller change added bus grants. If the anchor
+was sent twice in that step, each with its own digest, then the host applying the later one while the
+earlier one's record landed last would give exactly this picture. The next step is to read
+`sendToEach` for the order of its sends and of their `recordSent` calls, and to check the node's
+sequence numbers for two sends at 20:22:57.
+
+**Whatever the cause, the plan's wait has a second fault.** A first machine that reports `applied` for
+a declaration the controller cannot place says nothing about the build. The plan should say "it
+applied something other than what was recorded as sent" instead of "waiting", so a reader acts in
+minutes rather than at the bound.
+
+## 2026-10-05, later: found
+
+**The lead above was wrong.** It was not two sends. The machine's own five-minute reconcile did it.
+
+The host re-applies what it was last told every five minutes. That reconcile read the kept
+declaration, then waited for any apply in progress. A declaration the link is applying is kept only
+once its apply ends. On the anchor:
+
+- the reconcile was due at 20:22:58;
+- the controller's send arrived at 20:22:57;
+- the reconcile read the declaration kept before that send, waited, and applied it after the link's
+  apply;
+- its report named that older declaration.
+
+That explains every fact above:
+
+- the report's digest matched nothing recorded as sent;
+- the other machines, not due, matched;
+- the next push matched.
+
+**Seen a second time, with a visible effect** (issue 261): a module assigned on the laptop was
+applied and then given back 29 seconds later by the reconcile due during that apply.
+
+**Fixed** in mesh-host: the reconcile reads the kept declaration once it holds the apply lock. A test
+reproduces the interleaving: it fails with the old order and passes with the fix.
+
+The plan's "waiting" wording, raised above as a second fault, is unchanged. With the cause gone, a
+report naming an unrecorded declaration should no longer occur.

04-ISSUES/258-every-machine-bound-the-resolver-to-itself/00-report.md

@@ -0,0 +1,53 @@
+---
+status: resolved
+opened: 2026-10-05
+located-in: [mesh-controller]
+fixed-by: novox/mesh-controller#59 (4b382ce)
+amended-design:
+---
+
+# 258. Every machine bound the mesh's resolver to itself
+
+## Symptom
+
+After the mesh moved to one resolver (ADR 0194, 0196), the seat `mesh-dns-resolver` was recorded as
+held on the anchor, and each other machine was pinned to it for `wildcard-resolution`. Each machine
+was then pushed. The anchor's resolver configuration named its own private address first. Every
+other machine's did too: each named **its own** private address, not the anchor's.
+
+Nothing broke, because each machine still ran a resolver of its own while the move was under way. But
+the mesh had decided on one resolver, recorded who held it and pinned every machine to it, and no
+machine used it.
+
+## Cause
+
+The controller binds a requirement in one of two branches:
+
+- **Answered here**, when a module on the same machine provides it.
+- **Answered elsewhere**, when one on another machine does.
+
+Only the second branch read the seat's holder (ADR 0110) and a pin. The first took the local provider,
+and read a pin only to choose between two local ones. Every machine still had its own resolver
+assigned, so every machine took the first branch.
+
+The seat's own definition says the requirement "resolves to the holder wherever it is placed". The
+code did not.
+
+## Fix
+
+For a mesh-wide provision, a pin naming another machine, or the seat's holder on another machine,
+wins over a provider on this one. With neither, the local provider answers as before.
+
+This is checked by three resolve tests in mesh-controller:
+
+- the holder elsewhere answers;
+- a pin elsewhere answers;
+- a holder here still answers here.
+
+The tests fail without the fix.
+
+## Verified
+
+2026-10-05, after the fix rolled out: all four machines' resolver configuration names the anchor's
+resolver first and the public one second. Each resolves the mesh's machine names, a wildcard name
+under a machine, and a public name.

04-ISSUES/259-a-named-push-sent-every-machine/00-report.md

@@ -0,0 +1,46 @@
+---
+status: resolved
+opened: 2026-10-05
+located-in: [mesh-controller]
+fixed-by: novox/mesh-controller#64 (002d5e5)
+amended-design: 03-DESIGN/01-to-be/30-the-mesh-updates-itself-on-a-push.md
+---
+
+# 259. A push to one machine sent every machine
+
+## Symptom
+
+A change to the resolver modules was merged with the upgrade policy `record`, so that each machine
+would get it only when pushed. The plan was to go one machine at a time: the anchor first, then each
+of the others, each checked before the next.
+
+`push <anchor>` sent all four machines, each a new declaration carrying the change. A later
+`push <laptop>` did the same. A further fault in the change (issue 260) was therefore met on every
+machine at once, not on one.
+
+## Cause
+
+A named push ends by flushing every other machine whose declaration differs from what it was last
+sent (issue 057, ADR 0083). This was meant for consequences of the push, such as a provider's grant
+list after a consumer was assigned. It cannot tell a consequence from a change the upgrade policy is
+holding back. Under `record`, every machine running the module differs, so every machine is flushed.
+
+Issue 249 met the same confusion for the machine holding the bus, and narrowed that check to the user
+list alone. The flush has no such narrowing.
+
+## What it costs
+
+`record` is the policy for a change that must be walked through the mesh by hand. A named push cannot
+do that, so the policy does not hold the change back from anything but the merge. The command's name
+says one machine, and the command's output is the only place that says otherwise.
+
+## Open
+
+- Should the flush send a machine only what changed as a consequence: grants, user lists and bound
+  facts, not module versions held by a policy?
+- Or should it list such machines as behind and leave them, as `push --behind` would find them?
+
+## Verified
+
+2026-10-05: after the fix, a named push sent only the machine named. Upgrades held by a policy were
+then sent with `push --behind`, as ADR 0221 has it.

04-ISSUES/259-a-named-push-sent-every-machine/01-diagnosis.md

@@ -0,0 +1,27 @@
+# 259 — Diagnosis
+
+## 2026-10-05
+
+**Located in the controller's push.** A named push ends with the cascade of
+[ADR 0083](../../02-DECISIONS/0083-one-push-leaves-the-mesh-consistent.md): it sends every other machine
+whose declaration's digest differs from the digest it was last sent. The comparison is the only one the
+mesh can make from what it keeps. It keeps a digest of each send and nothing about what the send
+carried, so a machine behind because a module moved under `record` and a machine behind because of a
+grant read the same.
+
+**Not only `record`.** A plan rolling a module out one machine first
+([ADR 0218](../../02-DECISIONS/0218-a-plan-sends-grants-before-code-rolls-out-one-machine-first-and-a-newer-merge-takes-over-an-older-plan.md))
+leaves the other machines differing while it waits on the first. Any named push elsewhere in that
+window sends them the build the plan is holding.
+
+**And the machine holding the bus.** [Issue 249](../249-a-modules-new-state-is-refused-until-a-push-the-merge-did-not-make/00-report.md)
+narrowed *whether* that machine is added to a push to its user list alone. Once added, it is sent its
+whole declaration, held builds included.
+
+**Ruled out:** composing a held machine with its held modules kept at their last build, so it gets the
+grant and not the upgrade. Reasons in the decision.
+
+**Decided** in [ADR 0221](../../02-DECISIONS/0221-a-push-sends-no-build-a-policy-or-a-plan-holds-back-except-to-the-machine-it-names.md):
+each send records which build of each module it carried, and a push does not send a machine it did not
+name any build a policy or an open plan holds back. It names the machine and the remedy instead. The
+fix is a pull request on mesh-controller; `fixed-by:` is filled when it merges.

04-ISSUES/260-the-resolver-started-before-its-zones-file-existed/00-report.md

@@ -0,0 +1,50 @@
+---
+status: located
+opened: 2026-10-05
+located-in: [mesh-host, mesh-catalog]
+fixed-by: novox/mesh-host#25 (a566add)
+amended-design:
+---
+
+# 260. The resolver was restarted before the file it reads existed
+
+## Symptom
+
+The first apply of the resolver's new configuration failed on every machine. Each host's journal:
+
+> failed dnsmasq.service: restarting dnsmasq.service: starting it again: systemctl exited 1
+
+The resolver's own journal:
+
+> dnsmasq: cannot read /etc/mesh-resolver/zones.conf: No such file or directory
+
+The service manager's automatic restart started it again in the same second, and it answered. The
+host still reported the apply as failed, on every machine.
+
+## Cause
+
+The new configuration names a second file, the mesh's zones. The host wrote the configuration and
+restarted the service on it **before** it created the zones file. The zones file was created next in
+the same apply. The service's `restart-on` names both files, but nothing orders the restart after
+every file it reads has been written.
+
+## What it costs
+
+A configuration that adds a file it reads fails its first start everywhere. Here the service manager's
+restart policy hid it within a second. A service without one would have stayed down, holding the
+machine's name resolution with it.
+
+## Open
+
+- Should the host run every restart and reload after all files of the apply are written?
+- Or should it order each restart after every resource the service names in `restart-on`?
+
+## Fix
+
+The host now orders the apply so that a service comes after every resource it names under
+`restart-on` or `reload-on`. Only services move, and only as far as the last of what they name; every
+other resource keeps its declared place. The first open question above is answered that way, per
+service, rather than by moving every restart to the end. This is checked by mesh-host's
+`restart_order_test.go`: a service restarting on two files, one declared after it, is restarted once
+both exist, and a later change to the second file still restarts it. The test fails without the
+ordering.

04-ISSUES/261-a-module-was-applied-and-given-back-half-a-minute-later/00-report.md

@@ -0,0 +1,40 @@
+---
+status: located
+opened: 2026-10-05
+located-in: [mesh-host]
+fixed-by: novox/mesh-host#24 (89a7796)
+amended-design:
+---
+
+# 261. A module was applied and given back half a minute later
+
+## Symptom
+
+The `hosts` module was assigned to the laptop and pushed. The laptop's host applied it: the module's
+block was written at the start of `/etc/hosts`, its tools were installed, and the host reported the
+declaration it had been sent. Twenty-nine seconds later the same host gave the block and the tools
+back. Nothing on the controller had sent a declaration without the module. Five minutes later the
+module was back.
+
+The host's journal on the laptop, in order:
+
+- `updated hosts.own (/etc/hosts): the mesh's region added at the start`
+- `applied 342 resource(s)`
+- `restored hosts.own (/etc/hosts)`
+- `removed hosts.bundle-tools`
+
+## Cause
+
+The host's five-minute reconcile was due during that apply. It read the declaration kept before the
+push, waited for the push's apply to finish, and then applied the older declaration over it. That
+older declaration did not have the module, so the module was given back. The next reconcile read the
+newer declaration, which had been kept by then, and applied the module again.
+
+This is the same fault as [issue 257](../257-a-plan-waited-on-a-declaration-its-first-machine-never-reported/00-report.md),
+where it showed only as a report naming a declaration nobody had recorded sending.
+
+## Fix
+
+The reconcile reads the kept declaration once it holds the apply lock, so it always applies the
+latest declaration the mesh sent. This is checked by mesh-host's test
+`TestAReconcileAppliesWhatWasKeptWhenItsTurnComes`, which fails with the old order.

04-ISSUES/262-an-alpine-container-could-not-find-a-machine-by-its-mesh-name/00-report.md

@@ -0,0 +1,59 @@
+---
+status: resolved
+opened: 2026-10-05
+located-in: [mesh-catalog]
+fixed-by: novox/mesh-catalog#71 (20603b6), novox/mesh-controller#65 (df9231c), novox/mesh-catalog#73 (b4b86c1)
+amended-design:
+---
+
+# 262. An Alpine container could not find a machine by its mesh name
+
+## Symptom
+
+After the mesh moved to one resolver (ADR 0194, 0196), a workflow container on the home server was
+restarted so that it would ask the mesh's resolver. It then crash-looped every fourteen seconds:
+
+> getaddrinfo ENOTFOUND <anchor>.internal
+
+From the same container, `getent hosts <anchor>.internal` answered correctly. So did the machine
+itself, every time, in about forty-five milliseconds.
+
+## Cause
+
+The mesh's resolver answered a machine's name only through a wildcard rule:
+
+- asked for the IPv4 address, it gave the address;
+- asked for the IPv6 address, it answered NXDOMAIN, "no such name", where the correct answer is
+  NODATA, "the name exists and has no such record".
+
+glibc ignores that. musl, the C library of every Alpine image, asks for both records and takes the
+NXDOMAIN as final, so the whole lookup failed. The per-machine resolvers this one replaced answered
+each machine's name from `/etc/hosts`, which gives NODATA, so nothing had depended on the difference
+before.
+
+Reproduced with a throwaway resolver of the same version, given only the wildcard rule.
+
+## Fix
+
+Each machine's name is now also a host record in the machine list the resolver reads. Asked for an
+IPv6 address, the resolver then answers that the name exists and has none. A name under a machine,
+answered only by the wildcard, still answers NXDOMAIN for IPv6, exactly as it did before the move.
+
+## How it is checked
+
+Ask the mesh's resolver for the IPv6 address of a machine's name. The answer must be NOERROR with no
+records. Today that check is done by hand. A controller test that renders the machine list and
+requires one host record per machine should be added.
+
+*2026-10-05:* that test is added with [ADR 0223](../../02-DECISIONS/0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md)
+— mesh-controller's composition test renders the resolver's machine list and requires exactly one
+host record per machine. The live check stays by hand, on each resolver.
+
+## Verified, and what else was found
+
+2026-10-05: the host record fixed the IPv6 answer, but Alpine programs still failed when they read the
+machine's resolver file directly (host networking, docker's default bridge). They asked the mesh's
+resolver and the public fallback at once and took the public "no such name". ADR 0223 removes the
+public fallback: a machine lists only the mesh's resolvers, now two. Afterwards an Alpine container
+resolved a machine's name ten times out of ten, with host networking and on the default bridge, and
+the build machines built with no hosts-file line.

04-ISSUES/263-every-consumer-pays-for-the-tightest-backends-name-limit/00-report.md

@@ -0,0 +1,61 @@
+---
+status: open
+opened: 2026-10-06
+located-in: []
+fixed-by:
+amended-design:
+---
+
+# 263. Every consumer pays for the tightest backend's name limit
+
+## Symptom
+
+The operator: "the 20 character limit has bitten us multiple times". Most recently, on 2026-10-06:
+
+- A change made the network-manager modules require the mesh's resolver provision.
+- Each machine running them thereby became a consumer of that provision, with an identity
+  `mesh_<machine>_<module>`.
+- `networkmanager`'s identity is 23 to 26 characters, over the 20 the controller allows.
+
+The refusal surfaced as the anchor's whole declaration failing to compose, because the anchor carries
+every consumer's grant as the resolver's holder:
+
+> networkmanager on <home-server> is identified as "mesh_<home-server>_networkmanager", 23 characters
+> where a backend (an S3 access key) keeps 20 — give the module a shorter `slug` or shorten the
+> machine's name
+
+For as long as that lasted, no push to the anchor could go through. The fix was another slug.
+
+## Why it keeps happening
+
+[ADR 0049](../../02-DECISIONS/0049-a-consumers-identity-fits-the-tightest-backend.md) bounds **every**
+consumer's identity by the tightest backend anywhere, an object store's 20-character access key
+([issue 034](../034-mesh-login-exceeds-s3-access-key-limit/00-report.md)), and makes a module `slug`
+the remedy. That has two costs:
+
+- **The limit applies where it means nothing.** The resolver provision mints no credential and keeps
+  no name in any backend, yet its consumers were held to an object store's key length. ADR 0049 named
+  per-provision bounds (its option C) as the refinement for later. It has not been done.
+- **It is found late, and far from its cause.** The catalogue's module check and the controller's
+  tests passed. The refusal came only when a real machine's name met the module's name, and it showed
+  on the provider's machine, not on the consumer's, as a whole node that could not be pushed. ADR
+  0049 says it is refused at assignment. This one was a new requirement on modules already assigned,
+  so assignment never saw it.
+
+## What to look into
+
+1. **Bound each provision by its own backend's limit**, ADR 0049's option C. Only a provision that
+   creates a name in a limited backend carries the limit, and a keyless one carries none.
+2. **Refuse it before merge.** The catalogue check should judge a module's identity against the
+   longest machine name in the mesh (or the bound per provision) for every provision it requires, so
+   the refusal names the module in its own pull request.
+3. **Never refuse a provider's whole declaration** for one consumer's identity. Leave that consumer's
+   grant out, say so in `status`, and keep the provider's machine pushable.
+
+## How it is checked (once fixed)
+
+- A catalogue test: a module requiring a keyless provision composes with a long name.
+- A module check: a module requiring a limited provision is refused when the longest machine's
+  identity overflows.
+- A controller test: an overflowing consumer leaves the provider's declaration composable, and is
+  reported.

04-ISSUES/264-a-self-updating-engine-lost-the-report-of-the-apply-that-delivered-it/00-report.md

@@ -0,0 +1,72 @@
+---
+status: located
+opened: 2026-10-06
+located-in: [mesh-host]
+fixed-by:
+amended-design:
+---
+
+# 264. A self-updating engine lost the report of the apply that delivered it
+
+## Symptom
+
+One declaration for the anchor carried both a new controller and a new version of the host. The
+host applied it and said, in its journal:
+
+- `host <version> is delivered; standing aside so the launcher runs it`
+- `applied, and could not tell the mesh: reporting: context canceled`
+
+The new host started and said `in the mesh, hearing what this node should be`, and nothing more
+about that declaration. The controller's release plan waits for the first machine to report the
+exact digest of the declaration it was sent. That report never came, so the plan waited until a
+person pushed again by hand.
+
+This is the same family as [issue 257](../257-a-plan-waited-on-a-declaration-its-first-machine-never-reported/00-report.md)
+and [issue 261](../261-a-module-was-applied-and-given-back-half-a-minute-later/00-report.md): the
+machine did what it was sent, and the report the plan waits on did not say so.
+
+## Cause
+
+Standing aside for a successor ([ADR 0141](../../02-DECISIONS/0141-the-host-delivers-its-own-successor.md)) is
+decided inside the apply, once the apply has finished, and it cancels the link's context. The link
+then published the apply's report on that same cancelled context, and the bus refused it before it
+left. The declaration was then acknowledged anyway, so the mesh did not deliver it again, and the
+new host had nothing that told it a report was owed.
+
+A crash or power cut between the apply and the report has the same shape. The declaration is
+delivered again in that case only because it was not yet acknowledged, and nothing on the machine
+records that a report is owed.
+
+## Fix
+
+Two parts, in the host:
+
+1. The report of an apply, and of a declaration set aside for a newer one, is published on a context
+   that standing aside does not cancel. It is still limited by the host's timeout, and it is sent
+   before the connection is closed. After an apply that stood aside, nothing further is applied.
+2. The report of the last apply of a declaration from the mesh is kept beside the node's state until
+   the broker has taken it. When a host links, it first sends any report still kept, before it applies
+   anything newly delivered, so the re-sent report cannot arrive after a newer one. What is re-sent
+   is exactly the report the apply made, with the same digest and the same outcome. It is never a new
+   description of the machine, so it cannot claim that something was applied when it was not. A
+   report that names no declaration, such as a refused one, clears what was kept. A node that never
+   applied anything sends nothing.
+
+## How it is checked
+
+These tests in the host fail without the fix:
+
+- `TestAnApplyThatEndsTheLinkIsStillReported`: an apply that cancels the link still has its report
+  delivered, and its declaration is settled after the report.
+- `TestAReportLostAfterTheApplyIsSaidOnTheNextLink`: a report the broker refused is sent again on the
+  next link, unchanged.
+
+These tests guard the edges:
+
+- `TestNothingIsSaidAgainWhenNothingWasLost`: nothing is re-sent when nothing was lost.
+- `TestTheKeptReportSurvivesTheHost` and `TestNothingKeptWhenNothingWasApplied`: the kept report
+  survives a restart exactly as it was made, and it is cleared only by a report about the same
+  declaration.
+
+Once the fix is rolled out, the live check is the next declaration that carries a new host version.
+The first machine's report should reach the plan without anyone pushing by hand.