Merge pull request 'Research 019: a warm twin of the running mesh' (#294 ) from jschoubben/research-019 into main

Research 019: a warm twin of the running mesh in the lab
Merge pull request 'Research 018 graduates: ADRs 0173–0177 and to-be 37, the operator's machine' (#293 ) from feat/the-operators-machine into main
2026-10-02 14:59:44 +00:00 · 2026-10-02 16:59:36 +02:00 · 2026-10-02 14:58:48 +00:00 · 2026-10-02 16:53:15 +02:00 · 2026-10-02 16:34:57 +02:00 · 2026-10-02 14:29:00 +00:00
56 changed files with 2626 additions and 48 deletions
@@ -131,6 +131,22 @@ def main():
        else:
            seen[number] = name
    # And decision records, which 155's fix left out: on 2026-10-02 two ADRs numbered 0169 landed
    # on main from two sessions within the hour, and every check passed.
    seen_records = {}
    for path in sorted(glob.glob(os.path.join(ROOT, "02-DECISIONS", "[0-9]*.md"))):
        name = os.path.basename(path)
        number = name.split("-", 1)[0]
        if not number.isdigit():
            continue
        if number in seen_records:
            bad(os.path.join("02-DECISIONS", name),
                "is numbered %s, and so is %s -- a record's number is how it is cited. Take the next "
                "free number across main AND every open pull request; the branch that lands last "
                "renumbers" % (number, seen_records[number]))
        else:
            seen_records[number] = name
    for path in sorted(glob.glob(os.path.join(ROOT, "04-ISSUES", "*", "00-report.md"))):
        front = frontmatter(path)
        if front is None:
@@ -95,3 +95,21 @@ another — and a mesh you cannot name precisely is a mesh two people describe d
 A new name for an existing thing lands here first, in the same change that introduces it in code. A
 record under `02-DECISIONS/` keeps whatever word it was written with — those are immutable — so a
 term retired here may still appear there, and the mapping above is how to read it.
 ## The operator's machine
 - **node tools** — the one tool runtime per node, a host-side process the host supervises, that loads
  every assigned module's tools bundle and serves every tool and held seat's verb on the subjects the
  memberships issue; its serving mode on loopback is what was called **the console**
  ([ADR 0175](../02-DECISIONS/0175-one-tool-runtime-per-node-serves-every-modules-tools-on-the-host-side.md)).
  Replaces **"console"** as the module's name; *console* remains the word for the person's end of it.
 - **bundle** — the artifact a module's tools are built into, interpreted or compiled; never an image.
 - **kept region** — a marked block in a managed file the mesh writes *into*, where the operator's own
  lines survive every push and are given back when the module goes
  ([ADR 0174](../02-DECISIONS/0174-a-node-varies-a-module-through-settings-and-kept-regions-never-an-edit.md)).
  One of the two ways a node varies a module; the other is a **setting**.
 - **installed / holding** — a module may be assigned (its package installed, its files placed) without
  holding the seat its family declares; *holding* is being the one — the login shell, the display
  session — on that node ([ADR 0176](../02-DECISIONS/0176-the-login-shell-is-a-node-seat-and-execute-is-its-contract.md)).
 - ~~flavor~~ — not used. What a flavor varied is a setting or a separate module.
@@ -0,0 +1,86 @@
 ---
 status: graduated
 initiated: 2026-10-02
 touches:
  - 02-DECISIONS/0040-what-a-module-is.md
  - 02-DECISIONS/0011-managed-files-are-generated-never-edited.md
  - 02-DECISIONS/0132-a-seat-carries-the-tools-its-holder-must-serve.md
  - 02-DECISIONS/0150-a-modules-own-code-runs-as-supervised-processes-under-one-account.md
  - 02-DECISIONS/0152-the-operators-surface-is-a-module-the-console.md
  - 02-DECISIONS/0161-what-deserves-a-seat.md
  - 03-DESIGN/01-to-be/05-the-node-host.md
  - 03-DESIGN/01-to-be/29-a-node-has-operator-accounts.md
  - 03-DESIGN/01-to-be/33-the-tools-the-mesh-answers.md
  - 03-DESIGN/01-to-be/34-the-console.md
  - 03-DESIGN/00-as-is/10-module-catalogue.md
  - 04-ISSUES/160-a-machine-says-little-about-itself-and-only-when-asked/00-report.md
  - 04-ISSUES/168-a-setting-reaches-every-file-and-contribution/00-report.md
 became:
  - 03-DESIGN/01-to-be/37-the-operators-machine.md
  - 02-DECISIONS/0173-the-operators-machine-is-the-meshs-and-a-module-is-what-it-declares.md
  - 02-DECISIONS/0174-a-node-varies-a-module-through-settings-and-kept-regions-never-an-edit.md
  - 02-DECISIONS/0175-one-tool-runtime-per-node-serves-every-modules-tools-on-the-host-side.md
  - 02-DECISIONS/0176-the-login-shell-is-a-node-seat-and-execute-is-its-contract.md
  - 02-DECISIONS/0177-a-unit-may-be-user-scoped-and-the-service-manager-is-a-node-seat.md
 ---
 # 018 — The operator's machine as modules
 **What.** The mesh owns the whole machine, not only the services on it. Everything a person
 configures on a node — the login manager, the display server, the window manager, the shell, the
 terminal, the launcher, the notifier, the audio setup, the boot images, the downloads folder, the
 agent at the terminal — is a module: a package, the files it owns under `/etc` and under the
 operator's home, the seat it holds, the tools it serves. One default configuration per module,
 varied per node only through settings rendered into the file or a kept operator region, never
 through an edit. The servers take the universal modules (shell, prompt, git, the agent); the
 workstations take those and the graphical stack, which a capability the machine reports gates.
 This effort writes that behaviour down, measures what the predecessor's desktop modules actually
 contain, and settles what the mesh must gain before the first of them can be written.
 **Why.** The predecessor is retired on every node. What it still owned on the two workstations —
 about thirty modules' worth of dotfiles, user units and `/etc` files — is now owned by nothing:
 no generator regenerates them, and a fix to one of them is a hand edit that nothing records. The
 migration scoped these modules out as *the workstation's own environment*, and
 [to-be 29](../../03-DESIGN/01-to-be/29-a-node-has-operator-accounts.md) names them as the last
 thing the predecessor was keeping alive. To-be 29 covers one directory, `~/.ssh`, and draws a
 boundary inside it. The operator wants no boundary: the machine is the mesh's, as far as it makes
 sense to configure it. That is a wider scope than any design states, and it reaches three records
 that were written for services: what a module is, where a module's tools run, and what a managed
 file may be.
 **What it touches.** The module definition ([ADR 0040](../../02-DECISIONS/0040-what-a-module-is.md)),
 seats and their contracts ([ADR 0132](../../02-DECISIONS/0132-a-seat-carries-the-tools-its-holder-must-serve.md)),
 where a module's tools run ([ADR 0150](../../02-DECISIONS/0150-a-modules-own-code-runs-as-supervised-processes-under-one-account.md),
 [ADR 0152](../../02-DECISIONS/0152-the-operators-surface-is-a-module-the-console.md),
 [to-be 33](../../03-DESIGN/01-to-be/33-the-tools-the-mesh-answers.md) §6), the host's vocabulary
 ([to-be 05](../../03-DESIGN/01-to-be/05-the-node-host.md)), managed files and settings
 ([ADR 0011](../../02-DECISIONS/0011-managed-files-are-generated-never-edited.md),
 [issue 168](../../04-ISSUES/168-a-setting-reaches-every-file-and-contribution/00-report.md)),
 and the catalogue's shape ([as-is 10](../../03-DESIGN/00-as-is/10-module-catalogue.md)).
 **Documents.**
 - [01 — The intended behaviour](01-the-intended-behaviour.md): the operator's wish, written as
  how the mesh behaves, in the mesh's own words.
 - [02 — What exists, and what is missing](02-what-exists-and-what-is-missing.md): the
  predecessor's desktop modules measured; which records already say what is wanted; the gaps.
 - [03 — One tool executor per node](03-one-tool-executor-per-node.md): where a module's tools
  run. The direction the operator set, the evidence for it, and what it supersedes.
 - [04 — The seats of the environment](04-the-seats-of-the-environment.md): the roles a machine
  has once, their candidate contracts, and what gates each.
 **What it had to settle, and where each landed.** *(Graduated 2026-10-02.)*
 1. A module is one *managed thing*, software or not, and every module may serve tools — or ADR
   0040 already says this and only its examples are narrow.
 2. One tool executor per node, host-side, module-agnostic; which records it supersedes and
   in what form the console continues.
 3. Per-node variation is a setting rendered into the file or a kept region, never an edit —
   ADR 0011 stands — and issue 168 is fixed before any environment module carries a setting.
 4. User-scoped units on the host's `service` shape, and a service-manager seat whose holder
   serves the tools about them.
 5. The operator account stated on every node; today no node record carries one.
 6. The seats of the environment and their verbs, one record per seat, slowly, because a
   seat's tools bind every future holder.
 7. Where the environment modules live: this catalogue, or one of their own as the media chain
   has; and whether a third-party organisation's tooling belongs in a public catalogue at all.
@@ -0,0 +1,99 @@
 # 01 — The intended behaviour
 *Written 2026-10-02 from the operator's words, in the mesh's words. What is wanted, before what
 exists. Where a sentence restates a record, the record is named; where it goes further, that is
 said.*
 ## The machine is the mesh's
 **Everything configurable on a node is declared by a module.** Not only the services the mesh
 runs: the login manager, the display server, the window manager, the bar, the launcher, the
 notifier, the compositor, the lock screen, the terminal emulator, the clipboard, the shell and its
 prompt, the editor, the audio setup, the boot images, the package manager's configuration, the
 agent a person runs at a terminal, and the folders a person works in — a downloads folder that is
 tidied, backed up, distributed to other nodes and asked questions of. System folders and the
 operator's home alike. The operator is the only person on every node, so the mesh manages the
 person's machine, not a machine with a person on it.
 This is [ADR 0040](../../02-DECISIONS/0040-what-a-module-is.md)'s definition applied without
 the service bias its examples carry. A module is one managed thing, named once, described
 completely by its manifest. It may have a package, files, a container, a unit, a binary, a seat it
 holds, and tools it serves — any one of these, or all, or two. There is **no kind of module**: zsh
 has a package, files, a seat claim and the tools that claim obliges it to serve; downloads has a
 folder, a process and tools; nftables has a package, files, a service, a seat and tools. The
 difference is what each declares, not what each is.
 **The home has no boundary.** [To-be 29](../../03-DESIGN/01-to-be/29-a-node-has-operator-accounts.md)
 owns one directory under the home and draws a line inside it between the mesh's and the person's.
 Here the line is drawn only by what the modules declare: every file some module places is the
 mesh's; what no module declares is found and left alone, exactly as the adoption rules already
 say for a machine. The reach is bounded by sense, not by a rule — the mesh configures what can
 be configured, and a person's documents, projects and history are data under
 [ADR 0051](../../02-DECISIONS/0051-shared-data-is-the-operators.md), not configuration.
 **A module names no node and no path.** The operator account is a node fact and the home is
 derived from it ([to-be 29](../../03-DESIGN/01-to-be/29-a-node-has-operator-accounts.md) §1–2,
 shipped in the controller; its record is proposed in an open change). A module places a file
 *under the home, owned by the account*, and the same manifest lands on a server and a laptop.
 ## One default, varied by settings, never by edits
 **One module, one default configuration.** The window manager module ships the configuration
 that is right for every node. There are no flavors: the predecessor's one desktop module carried
 four, one per class of machine, and what differed between them is what settings are for.
 **A node varies a module in exactly two ways.** A **setting**, declared by the module with its
 type, meaning and default (proposed alongside the container-runtime records), set for the mesh
 or for one node, and rendered into the file at composition — the value is in the file, not in an
 environment variable the file reads. Or a **kept region**: a block in a file the mesh writes
 *into*, where the operator's own lines survive every push
 ([ADR 0102](../../02-DECISIONS/0102-the-mesh-writes-into-a-shared-file-never-over-it.md)). An
 edit to a managed file outside such a region is not a third way; it is overwritten, as
 [ADR 0011](../../02-DECISIONS/0011-managed-files-are-generated-never-edited.md) says, and the
 predecessor's habit of adopting disk drift back into its database is not carried over.
 The predecessor's theming — some ninety environment variables substituted into templates at sync
 time, with tools to list and set them — is the same idea with the wrong rendering. The knobs
 become declared settings; the file carries the value.
 ## Roles a machine has once are seats, and seats carry tools
 **A role a machine fills at most once is a node-scoped seat**, declared by a module
 ([ADR 0121](../../02-DECISIONS/0121-a-system-seat-is-named-for-its-scope-and-modules-define-their-own.md),
 [ADR 0126](../../02-DECISIONS/0126-a-module-declares-its-own-seats.md)): the login shell, the
 display session, the display server, the terminal emulator, the launcher, the notifier, the
 compositor, the lock screen, the service manager, the boot loader. Several modules may be able to
 hold one — zsh, fish and bash can all hold the login shell — and the assignment on each node says
 which does. Installing a shell is installing software; holding the seat is being *the* shell.
 **A seat's contract is its tools** ([ADR 0132](../../02-DECISIONS/0132-a-seat-carries-the-tools-its-holder-must-serve.md)).
 Every holder of the login-shell seat serves `execute`, which takes one string, the command, and
 runs it on the node the seat is scoped to. Every holder of the boot seat serves "rebuild the boot
 images", so *"rebuild your boot images"* is a verb addressed to a machine, not a one-off step in
 a hook. Every holder of the service-manager seat answers for the units on the machine, system and
 user scope. A module may serve its own tools beside the seat's
 ([ADR 0170](../../02-DECISIONS/0170-the-firewall-seat-serves-its-verbs.md) §2): show the rendered
 configuration, set a theme value, report status.
 **Any tool may be called from any node.** The operator's statement, and the grant model it
 implies: the executor on each node may call everything, as the console already may. A verb that
 needs root on the machine is the module's concern — the tool escalates, the executor and the
 caller do not know.
 ## Servers and workstations differ by capability, not by catalogue
 The same catalogue serves every node. A module declares what it needs — a graphical session, a
 display server, a container runtime — and the machine reports what it has, as the profile already
 reports eight capabilities today ([issue 160](../../04-ISSUES/160-a-machine-says-little-about-itself-and-only-when-asked/00-report.md)).
 Assignment refuses the wrong placement by name
 ([ADR 0161](../../02-DECISIONS/0161-what-deserves-a-seat.md) §3). So every node takes the shell,
 the prompt, git and the agent; only a node with a graphical session can take the display server,
 and only a node holding the display server can take a window manager. Nothing in a module says
 "workstation".
 ## What the operator would say to the mesh
 *Set the login shell on the build node to fish. Rebuild the laptop's boot images. Show me the
 window manager's effective configuration on the desktop and where each value comes from. Give
 the downloads folder on the laptop to the home server. Run `uptime` on every node.* Each of these
 is a seat verb or a module tool, addressed to a node, answered by whatever holds the role there.
@@ -0,0 +1,91 @@
 # 02 — What exists, and what is missing
 *Measured 2026-10-02 on one installation: two workstations, two servers, all four converged to
 the mesh; the predecessor retired on the last workstation the day before. Numbers are from the
 machines and the repositories, not from memory.*
 ## 1. What the predecessor's desktop looks like
 The predecessor's catalogue on the laptop held **34 modules**, of which **28** are the operator's
 environment rather than services. By what they declare:
 | shape | count | examples |
 |---|---|---|
 | package only | 9 | browser, mail client, process monitor, media player, file manager, chat |
 | package + `/etc` files + system service | 5 | login manager, display server, power and thermal daemons, package manager configuration |
 | package + files under the home | 6 | shell and prompt, the agent at the terminal, scripts, the sync client, a music player |
 | files under the home + user units + hooks | 2 | the desktop environment, audio |
 | third-party organisation tooling | 6 | out of scope here |
 **The desktop module alone** declares **88 files**, **4 flavors** (the window-manager stack, and
 one per class of machine), **2 user units** with a hook to enable them, 8 files under `/etc`, a
 wallpaper shipped as an asset, and reads **about 90 environment variables** as theme knobs,
 substituted into its templates at sync time and set through a theming tool. Its hook exists
 because *shipping a unit file does not run it*: one unit had been deployed for months and ran on
 one machine only, because somebody had enabled it there by hand.
 **The shell module** ships `~/.zshrc`, the prompt configuration, an `~/.ssh/config` that the
 predecessor generated from its registry, and a `LOGIN_SHELL` variable applied with `chsh` by a
 hook. Two flavors: the prompt theme, and autocompletion.
 **Other modules write into the desktop module's files.** The chat client places i3 and notifier
 snippets into `config.d` directories the desktop module owns, and its launch flags, window
 placement and notification colours are each a variable with a default.
 **One-off steps live in hooks** across the set: enable user units, `chsh`, create a swap file,
 `mkinitcpio`, enable a vendor VPN service the package ships disabled. Every one is state the
 host could declare or a verb a seat could serve; none is today.
 ## 2. What the migration did with them
 The migration's module to-do scoped the whole set out as *desktop / workstation ricing — the
 workstation's own environment* and *node/OS tooling — managed on the node, never catalogue*. The
 last workstation's runbook then split the same set three ways: **A**, system scope, which the
 host's vocabulary can express today (the login manager, the display server, the power daemons,
 the package manager, the container runtime); **B**, under a home or a user unit, waiting on
 to-be 29; **C**, package only, the operator's call. The migration log closes the workstation with
 *the operator's desktop awaiting its design*.
 Two things followed from scoping them out. Nothing regenerates those files now, so a fix is a hand
 edit — the login manager's session script was fixed this way on the day of writing, and recorded
 in a repository nothing deploys from. And the one piece of this family written as a mesh module,
 the ssh client, was closed on hold in the catalogue until the controller carried the account fact.
 ## 3. What the records already give
 | wanted | record | state |
 |---|---|---|
 | one module per managed thing; every module may have tools | [ADR 0040](../../02-DECISIONS/0040-what-a-module-is.md) | accepted; examples are services, and the shell is named as a *shared* seat |
 | a module declares its own node-scoped seat | [ADR 0121](../../02-DECISIONS/0121-a-system-seat-is-named-for-its-scope-and-modules-define-their-own.md), [ADR 0126](../../02-DECISIONS/0126-a-module-declares-its-own-seats.md) | accepted |
 | a seat's contract is its tools; a holder may add its own | [ADR 0132](../../02-DECISIONS/0132-a-seat-carries-the-tools-its-holder-must-serve.md), [ADR 0170](../../02-DECISIONS/0170-the-firewall-seat-serves-its-verbs.md) | accepted; one node seat serves verbs live |
 | a capability the machine reports gates a holder | [ADR 0161](../../02-DECISIONS/0161-what-deserves-a-seat.md) §3 | accepted; the profile already reports `graphical-session` |
 | the account as a node fact; a file under the home owned by it | [to-be 29](../../03-DESIGN/01-to-be/29-a-node-has-operator-accounts.md) §1–2 | built in the controller; its record proposed in an open change |
 | inside a home: owned, written into, written by the module, found | proposed in the same change | proposed |
 | a setting declared with type, meaning, default and cost | proposed with the container-runtime records | proposed |
 | a managed file is derived; an edit is overwritten | [ADR 0011](../../02-DECISIONS/0011-managed-files-are-generated-never-edited.md) | accepted |
 | the mesh writes into a shared file, never over it | [ADR 0102](../../02-DECISIONS/0102-the-mesh-writes-into-a-shared-file-never-over-it.md) | accepted |
 | a module names no path; the host resolves the home | [ADR 0112](../../02-DECISIONS/0112-a-module-definition-names-no-node-mesh-or-path.md) | accepted |
 | the `user` shape: a login shell is declared state | [to-be 05](../../03-DESIGN/01-to-be/05-the-node-host.md) | designed; used by no module |
 ## 4. What is missing
 1. **The account is recorded nowhere.** The node record has the column; on all four nodes it
   is empty. Every home-scoped module is unassignable until the operator states it.
 2. **User-scoped units.** The host's `service` shape has no user scope. To-be 29 says it
   plainly: *a workstation's per-user daemons have no form the mesh can send.* The desktop
   module's two units, the audio masks, the power module's memory guard and the thermal
   daemon's profile switcher all need it.
 3. **One-off steps.** `mkinitcpio`, `chsh`, creating a swap file. Each is either declared
   state the host lacks a shape for, or a verb a seat should serve. An action in a declaration
   is refused over the link, and rightly.
 4. **Settings leak** ([issue 168](../../04-ISSUES/168-a-setting-reaches-every-file-and-contribution/00-report.md)):
   a setting reaches every mergeable file and every contribution of its module. Ninety theme
   knobs on that mechanism would reach ninety files. The proposed settings record says a setting
   names the file it lands in; that has to ship first.
 5. **Where tools run.** Every module that serves a tool today does so from its own container
   per node. See [03](03-one-tool-executor-per-node.md).
 6. **A seat's verbs are undecided for every seat but three.** To-be 33 leaves which verbs each
   seat serves as *a decision per seat, slowly*. The environment adds a dozen seats.
 7. **Catalogue placement.** The media chain left this catalogue for its own; whether the
   environment does the same, and whether a third-party organisation's tooling belongs in a
   public catalogue, are unasked.
@@ -0,0 +1,88 @@
 # 03 — One tool executor per node
 *The direction the operator set on 2026-10-02, the evidence it rests on, and what it supersedes.
 A direction, not yet a decision: the record is written when this effort graduates.*
 ## Where tools are served today
 [To-be 33](../../03-DESIGN/01-to-be/33-the-tools-the-mesh-answers.md) names three families — a
 role's tools on the seat, a module's own tools on the module, the mesh's own verbs on the
 controller seat — and [ADR 0160](../../02-DECISIONS/0160-the-mesh-issues-an-assignments-subjects-and-a-runtime-serves-what-it-is-issued.md)
 says a runtime serves the subjects its membership issues. What *runs* that runtime is
 [ADR 0150](../../02-DECISIONS/0150-a-modules-own-code-runs-as-supervised-processes-under-one-account.md):
 one supervised process per module, under the module's own account, carrying that module's
 compiled tools. Measured on the live mesh:
 | who answers | how it runs | count |
 |---|---|---|
 | the mesh's own verbs | the controller binary, on its node | 17 verbs |
 | the store seat | the store's own runtime | 2 verbs |
 | the packet-filter seat | **a container per node**, built on the tool-runtime base image, with the network namespace and `NET_ADMIN`, on all four nodes | 3 verbs and 1 own tool |
 | every module's own tools | the module's container, one per node it runs on | 67 tools across the catalogue |
 | the console | a container per node, loopback MCP, `invokes: *` | serves none, calls all |
 | the host | — | serves nothing; answers no question about the machine |
 **The packet-filter holder is the case to look at.** The module is a package, three files and a
 system service. To serve three verbs it also declares a built image and a container on every
 node whose only job is to answer them. Scaled to the environment — a shell, a prompt, a launcher,
 a notifier, a compositor, a login manager, a service manager, a boot loader, a downloads folder —
 that is one container per module per node for software that is itself not a container, and the
 operator's judgement is that tools should not run inside a container at all.
 ## The direction
 **One tool executor per node, on the host side.** A process the host supervises, the way the
 launcher supervises the host ([ADR 0005](../../02-DECISIONS/0005-the-node-host.md)): not a
 container, one bus credential for the node, module-agnostic. It loads the tool code of every
 module assigned to the node and serves each module's tools and each held seat's verbs on the
 subjects the membership issues — nothing changes in what [ADR 0159](../../02-DECISIONS/0159-a-tool-call-names-the-machine-and-a-holder-serves-its-seats-verbs.md)
 and [ADR 0160](../../02-DECISIONS/0160-the-mesh-issues-an-assignments-subjects-and-a-runtime-serves-what-it-is-issued.md)
 say about subjects, grants and memberships; what changes is that one process subscribes for the
 node instead of one per module.
 - **A module brings its tools as a built artifact**, a bundle the pipeline produces, never an
  image. The executor knows bundles and subjects; it knows nothing of zsh or nftables.
 - **A tool is code the module wrote**, one function behind an MCP verb. `execute` on the shell
  seat is a function with a string argument. The executor does not declare, template or
  interpret tools; it runs them.
 - **Root is the module's concern.** A tool that must change the packet filter or rebuild boot
  images escalates itself. The executor does not run as root for everyone, and the caller does
  not know.
 - **Any node may call any tool on any node.** The executor's credential may call everything,
  as the console's already does; per-module grants on the calling side are not kept.
 - **The mesh's own verbs stay with the controller** ([ADR 0154](../../02-DECISIONS/0154-the-meshs-own-verbs-are-the-controller-seats-tools.md)),
  and a mesh-scoped seat's verbs run on the node that holds it
  ([ADR 0121](../../02-DECISIONS/0121-a-system-seat-is-named-for-its-scope-and-modules-define-their-own.md)).
  No hub is added; the controller's node is already one.
 **The console is the executor, renamed.** It already runs on every node with a credential that
 may call everything, and it already serves the mesh's tools to whoever is on the machine over
 MCP on loopback ([ADR 0152](../../02-DECISIONS/0152-the-operators-surface-is-a-module-the-console.md)).
 It moves out of its container into the host's process tree, gains the serving half, and takes a
 name that says what it is — *the node's tool runtime* or simply *node tools*; "console" names
 the operator's half only.
 ## What it supersedes, and what it keeps
 | record | effect |
 |---|---|
 | [ADR 0047](../../02-DECISIONS/0047-a-module-runs-its-code-as-its-own-process-with-its-own-account.md), [ADR 0150](../../02-DECISIONS/0150-a-modules-own-code-runs-as-supervised-processes-under-one-account.md) | superseded *for tools*: one process per node runs every module's tool code, under one account. A module's long-running service — a daemon, a container — is untouched; the executor runs tools, not services. The record must say why one account for every module's tools is acceptable: every tool may be called from every node anyway, and root is taken by the tool, not granted to the process |
 | [ADR 0152](../../02-DECISIONS/0152-the-operators-surface-is-a-module-the-console.md) | kept in substance — a module, assigned per node, loopback MCP, the machine's login is the authority — changed in form: host-side, not a container; serves as well as calls; renamed |
 | [to-be 33](../../03-DESIGN/01-to-be/33-the-tools-the-mesh-answers.md) §6, [to-be 34](../../03-DESIGN/01-to-be/34-the-console.md) | amended the same way |
 | [ADR 0170](../../02-DECISIONS/0170-the-firewall-seat-serves-its-verbs.md) §3, *a container may ask for a capability* | moot for that holder: the verbs run on the host side and escalate as they need |
 | the container-runtime seat, proposed in an open change: *the holder runs as a supervised process and serves the verbs locally to the host and on the bus* | consistent — a supervised process serving verbs is what the executor is; the open question is whether that holder keeps its own process or serves through the executor like everyone else |
 | the tool-runtime base image | no longer the way tools reach a node; may remain the way a module's *service* is built |
 ## What stays open
 - **The executor's language.** The host is a static Go binary and loads no plugins, so the
  executor is a sibling process, and its language decides the language of every tool bundle.
  One decision, taken once.
 - **How a bundle reaches the node.** An artifact of the module's build, delivered as the host
  delivers everything else; whether it is a file resource in the declaration or a thing the
  executor fetches by digest.
 - **Reload.** A push that adds or upgrades a module's bundle reaches a running executor as a
  reload, not a restart, or every tool on the node blinks on every push.
 - **The host's own questions.** [Issue 160](../../04-ISSUES/160-a-machine-says-little-about-itself-and-only-when-asked/00-report.md)
  wants a machine to say more about itself. With an executor on every node, "what is this
  machine made of" is a seat verb like any other, served there.
@@ -0,0 +1,65 @@
 # 04 — The seats of the environment
 *Candidates, not decisions. To-be 33 says which verbs a seat serves is a decision per seat,
 taken slowly, because a seat's tools bind every future holder. This document lists the roles the
 operator's machine has once, who could hold each, what gates it, and a first verb or two — so
 each record has a starting point.*
 ## The rule for what is a seat here
 A role the machine fills **at most once** is a node-scoped seat, declared by the module family
 that fills it ([ADR 0126](../../02-DECISIONS/0126-a-module-declares-its-own-seats.md)). A thing
 several of which coexist without contention — editors, browsers, media players — is not a seat;
 each is a module with its own tools, and nothing is singular about it. A seat is held by one
 assignment per node; other modules of the same family may be installed beside it without
 holding it ([ADR 0040](../../02-DECISIONS/0040-what-a-module-is.md) §1, read with the sharper
 distinction: *installed* is not *holding*).
 ## Candidate seats
 | seat | holders | gated by | first verbs |
 |---|---|---|---|
 | **login shell** | zsh, fish, bash | nothing: universal | `execute(command)`; `show-config`; the holding itself sets the account's login shell through the host's `user` shape |
 | **service manager** | systemd | the `service-manager` capability the profile reports | units: list, status, start, stop, restart, enable, journal; **user scope** on each |
 | **boot** | grub, systemd-boot | a machine that boots itself (not a container host) | `rebuild-images`; `entries` |
 | **package manager** | pacman, apt | the `package-manager` capability | search, installed, upgrade, orphans; today a capability the host uses, not a seat anyone holds |
 | **display server** | xorg, wayland compositors that are their own server | the `graphical-session` capability | `displays`; `layout` |
 | **display session** | i3, sway | the display server seat held on the node; i3 needs x11, sway needs wayland | `reload`; `workspaces`; `windows`; `move` |
 | **terminal emulator** | xterm, alacritty, foot | display session | `open`; `font` |
 | **launcher** | rofi, dmenu | display session | `show`; `theme` |
 | **notifier** | dunst, mako | display session | `send`; `history`; `rule` |
 | **compositor** | picom | display server (x11 only) | `restart`; `effects` |
 | **lock screen** | i3lock, swaylock | display session | `lock` |
 | **bar** | i3status-rust, waybar | display session | `reload`; `blocks` |
 | **login manager** | lemurs, greetd | graphical session | `sessions`; `default-session` |
 | **audio** | pipewire, pulseaudio | the machine reports a sound device | `sinks`, `sources`, `default`, `volume`, `mute` |
 | **clipboard** | greenclip, cliphist | display session | `history`; `clear` |
 Not seats, modules with their own tools: the editor, the browser, the mail client, the file
 manager, the media player, the chat client, the agent at the terminal, the downloads folder, the
 scripts folder, the sync client, the power and thermal daemons that are specific to one machine's
 hardware.
 ## What the table implies
 **Capabilities come first.** `graphical-session`, `service-manager` and `package-manager` are
 reported today. *A display server is held* is not a capability but a seat being held, and a
 module that needs it declares a dependency on the seat, not on a capability: *i3 needs the
 display server seat held by xorg*. Whether a held seat can gate another's assignment is a
 question for the controller's resolver, and the first environment module after the shell will
 ask it.
 **The service manager comes early.** Four of the predecessor's modules ship user units, and the
 executor itself is a unit. User scope on the host's `service` shape is a host change whichever
 module holds the seat; the seat's holder answers the questions about units, it does not apply
 them — the host does, as it does for every declared resource.
 **The shell comes first.** Universal, no capability, one verb that is immediately useful on
 every node, and the `user` shape already makes the login shell declared state. It is the module
 that proves the pattern: a package, files under the home owned by the account, a seat claim,
 tools served by the executor, settings for the few things that vary per node, and a kept region
 for the operator's own lines.
 **The login manager is the first system-scope one**, because it needs nothing new: a package,
 two files under `/etc`, a service — the same shape the ssh daemon module has today — and the
 session script it owns is the file that was hand-fixed the day this effort opened.
@@ -0,0 +1,55 @@
 ---
 status: active
 initiated: 2026-10-02
 touches: [lab, the lab module, the catalogue, assignments, settings, the controller's store]
 became: []
 ---
 # 019 — A warm twin of the running mesh
 ## What is being investigated
 Whether the lab can keep a **warm twin of the mesh as it actually runs**: the same machines, carrying
 the same catalogue, the same assignments and the same settings as the live mesh, raised once and kept
 ready, so that a change can be tested against the mesh as it is rather than against a scenario
 written to resemble it. A run against the twin would go through the lab module like any other run:
 a branch per repository, the twin restored from its snapshot, the change applied, the beds run.
 ## Why
 The lab's beds raise meshes from declarations written for the bed. They prove the mechanism. They
 do not prove that a change works on the mesh that runs, with its accumulated assignments, its
 operator settings, its adopted machines and its modules in their real combinations. The gap showed
 on 2026-10-02:
 - a change to how a module's settings reach its files was correct in every bed, and would have put a
  setting into the container runtime's configuration on every machine running that module. Only the
  composed plan for a real machine showed it;
 - a firewall change composed cleanly and still left one machine's wired port unfiltered, because
  of a link that machine had and no bed did;
 - a recovery step was needed on every machine at once, after a change that every bed had passed.
 The lab already has a warm mode, a snapshot of a raised scenario restored between attempts. What it
 does not have is a scenario that **is** the running mesh, kept current with it.
 ## What it touches
 - **What a twin is made of.** The catalogue and the assignments are records; settings are records;
  secrets are sealed to machines and cannot be copied. Which of these can be carried to the lab as
  they are, which must be substituted, and how a twin says what it substituted.
 - **Data.** A twin with the real catalogue and no real data proves composition and delivery, not a
  migration. Whether a twin carries data, a sample of it, or none.
 - **Keeping it current.** A twin raised once goes stale with the first merge. Whether it is
  re-derived from the live records on each run, refreshed on a schedule, or rebuilt only when asked.
 - **Machines.** The live mesh has machines of different kinds: a server on the internet, machines
  behind a home router, a laptop that sleeps. Which of their properties a twin must reproduce for a
  test to mean anything (reachability, the private network, the found firewall).
 - **Cost.** The lab machine's memory and disk, and how long a twin takes to raise from cold.
 - **The lab module's tools.** A run against the twin rather than a named bed: one more tool, or an
  argument to the run tool.
 ## Starting point
 The lab module (ADR 0172) runs beds through the mesh, and the lab's warm mode already snapshots and
 restores a raised scenario. The beds that raise a machine shaped like one live machine from the
 catalogue are the nearest existing thing, and the first to compare against.
@@ -78,6 +78,8 @@ capability. The host hardcodes no firewall, supervisor, package manager or runti
 generic apply primitives and platform detection, so it runs where none of those exist — an Android
 phone has no ufw, systemd, pacman or Docker.
 > **The mechanism changed — 2026-10-02, by [ADR 0176](0176-the-login-shell-is-a-node-seat-and-execute-is-its-contract.md).** The shell example above — *bash, zsh and fish all join `shell`; one may be default* — is read as *installed is not holding*: the three may all be installed, and the `login-shell` seat is node-scoped and held by exactly one. The decision — what a module is, and the three relationships — stands; [ADR 0173](0173-the-operators-machine-is-the-meshs-and-a-module-is-what-it-declares.md) applies it to the operator's whole machine.
 ## Consequences
 - **Supersedes the earlier "grouped by domain" decision** (folded in consolidation; see the
@@ -9,6 +9,8 @@ extends: 0043-a-module-broker-account-is-scoped-by-emits-and-consumes.md
 # 47. A module runs its code as its own process, with its own account
 > **The mechanism changed — 2026-10-02, by [ADR 0175](0175-one-tool-runtime-per-node-serves-every-modules-tools-on-the-host-side.md).** A module's *tools* are no longer served by the module's own process under its own account: one tool runtime per node, on the host side, serves every assigned module's bundle. A tool is still served on its own subject and only the module that serves it answers; what moved is the process and the account.
 ## Context
 A module is one self-contained thing ([ADR 0040](0040-what-a-module-is.md)), and it gets a broker
@@ -124,6 +124,32 @@ This corrects a fact, not the decision: one statement per endpoint, three things
 none of them deciding on its own, all stand. The table in the decision should be read with the filter
 column applying to an unrouted endpoint.
 ## Progressive insight — 2026-10-02, from issue 191
 **For a routed endpoint, "the proxy serves the internal name" has to mean "serves it to the private
 network", and only the proxy can make it mean that.** The decision says `internal` means the proxy
 serves the internal name and not the public one. It does not say to whom, and the proxy answered
 every name it routes to any request that carried it, on the same listeners as its public names. A
 name being internal kept nobody out: a request from the internet only had to send it. While every
 routed endpoint also had a public name, nothing showed it. Once an endpoint could be internal alone
 ([issue 191](../04-ISSUES/191-a-route-with-only-an-internal-name-is-dropped/00-report.md)), serving
 its name to everyone would have published exactly what `internal` was chosen to keep private.
 The earlier insight above says the port is not the path for a routed endpoint. This is its other
 half: the proxy is the path, so the proxy is where `internal` is enforced. It serves an internal name
 only to the machines of the mesh and to the machine itself
 ([ADR 0144](0144-anything-on-a-machine-may-call-anything-on-it.md)). Who the mesh is, it is told,
 not left to work out: its membership carries the same list of machine addresses the filter's "from the
 mesh" is rendered from ([ADR 0167](0167-a-membership-carries-what-its-module-receives-and-who-the-mesh-is.md)).
 To anyone else, the name is answered as one never routed, in the handshake and in the request, and not
 listed among the names it serves. This holds for the internal name of a `both` endpoint too, whose
 outsiders have its public name.
 The decision, the options and the consequences stand: one statement per endpoint, three things
 derived from it. Checked in the proxy's own tests: an internal-only name is served to a machine the
 membership names and to loopback, and refused, unlisted and uncertified for any other request; until
 the mesh is issued, it is served to the machine alone.
 ## Consequences
 - **A manifest gains endpoint names, and a route contribution names an endpoint instead of a port.**
@@ -9,6 +9,8 @@ extends: 02-DECISIONS/0047-a-module-runs-its-code-as-its-own-process-with-its-ow
 # 150. A module's own code runs as supervised processes under the module's one account
 > **The mechanism changed — 2026-10-02, by [ADR 0175](0175-one-tool-runtime-per-node-serves-every-modules-tools-on-the-host-side.md).** For a module's *tools*, read that record: one runtime per node, the node's one account, bundles loaded from the memberships. This record still governs a module's long-lived processes — a daemon, a provisioner, a scheduled ingest — and the account invariant for them.
 ## Context
 The repository answers "what runs a module's own code" two ways and reconciles them nowhere
@@ -111,6 +111,8 @@ operator owns; narrowing what it may call is a setting on its assignment, which
 [ADR 0046](0046-a-module-configuration-is-its-assignments-not-its-manifest.md) already provides for
 and nothing here builds.
 > **The mechanism changed — 2026-10-02, by [ADR 0175](0175-one-tool-runtime-per-node-serves-every-modules-tools-on-the-host-side.md).** The surface stays a module assigned per node, on loopback, with the machine's login as the authority. It is no longer a container: it is the node tools runtime's serving mode, host-side, and that runtime also serves every assigned module's tools. The module is renamed `node-tools`.
 ## Consequences
 - **The way a person drives the mesh is inside the mesh.** It is declared, delivered, replaced and
@@ -94,6 +94,13 @@ itself restarts, and the console says so rather than hiding the modules' tools w
 **A grant of `*` reaches a role's tools; `seat:<seat>.<verb>` grants one.** The console's `*` needed no
 change to reach the mesh's verbs, which is what a grant meaning *every tool* should mean.
 > **The mechanism changed — 2026-10-02, by [ADR 0175](0175-one-tool-runtime-per-node-serves-every-modules-tools-on-the-host-side.md).**
 > The seat gains a generic verb beside the named ones: `command`, which takes one command line as the
 > controller's binary takes it and answers what it printed. The named verbs stand and keep their
 > schemas; `command` is the whole binary, added because the operator decided any node may call any
 > tool and a verb per command was the only thing keeping `node account`, `node show` and the rest
 > behind a shell on the control node. Additive within the version, as §"additive" above allows.
 ## Consequences
 - **The console answers the mesh's own questions.** Issue 147's first paragraph closes: what a node
@@ -0,0 +1,99 @@
 ---
 topic: the mesh
 status: accepted
 date: 2026-10-02
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0160-the-mesh-issues-an-assignments-subjects-and-a-runtime-serves-what-it-is-issued.md
 ---
 # 167. A membership carries what its module receives, and who the mesh is
 ## Context
 A provider learns what it is given from a file. The controller composes every consumer's contribution
 to a requirement, and the node's declaration writes them into the provider's received file. The route
 proxy reads its routes that way: one JSON file, re-read every two seconds.
 [Issue 191](../04-ISSUES/191-a-route-with-only-an-internal-name-is-dropped/00-report.md) showed what
 that file leaves out. Since [ADR 0138](0138-an-assignment-binds-an-endpoint-and-says-how-far-it-reaches.md),
 a route whose endpoint reaches only the private network carries an internal name and no public one.
 The proxy dropped it. Serving it was not enough either: the proxy answers public and internal names on
 the same listeners, so an internal name served to every request is public under a guessable name. To
 serve it correctly the proxy needs a second fact, **who the mesh is**, and nothing gave it one.
 The first attempt had the proxy work it out: the mesh's range from an environment variable written by
 the catalogue, and the machine's container bridges read from its own interfaces. That is a second
 definition of "the mesh", kept by one module, beside the one the packet filter already uses. The
 controller resolves "from the mesh" to every machine's address on the private network, and the filter
 is rendered from that list. Two definitions agree until one changes.
 [ADR 0160](0160-the-mesh-issues-an-assignments-subjects-and-a-runtime-serves-what-it-is-issued.md)
 already gives every assignment one document on the bus, its membership, read once at connect and
 followed. It says what the assignment serves and reaches. It does not yet say what it is given.
 ## Considered Options
 1. **Keep the file, add the mesh to it.** The proxy keeps polling a file, and the controller writes the
   mesh's addresses beside the routes. It fixes the definition, but delivery stays a file re-read on a
   timer, written by a separate path from the one every other fact a module is told now takes.
 2. **Have the proxy work it out** from a range in its environment and the machine's interfaces. Rejected:
   it is the second definition this record exists to remove.
 3. **The membership carries it.** What each module receives, from the same composition its received
   file is written from, and the mesh's addresses, from the same list the filter is rendered from. The
   proxy follows its membership and serves exactly that.
 ## Decision
 **Option 3.**
 - **A membership carries what its module receives**, by requirement: the contributions every consumer
  made, exactly as composed for its received file. A requirement nobody contributed to is an empty
  list, never absent, for the reason the file is written empty: "nothing asked" and "never told" want
  different responses.
 - **A membership carries who the mesh is**: every machine's address on the private network, the list
  a rule saying "from the mesh" resolves to. One list, two readers: the filter and any module that
  must tell the mesh from the world.
 - **The route proxy reads its routes and the mesh from its membership**, with the bus account every
  module that speaks on the bus is given. It serves an internal name only to the machines the mesh
  names and to the machine itself, and answers anyone else as it answers a name it never routed: in
  the request, in the handshake, and in the list of names it serves.
 - **The file stays until the bus has spoken.** While a proxy has read no membership that carries routes,
  it serves the file, and an internal name only to its own machine: refused, never opened. A
  membership from a controller that issues no routes changes nothing.
 ## Consequences
 - Every membership grows two fields. A machine joining or leaving republishes every membership, which
  a push already does.
 - A provider that receives something is told it twice for now, in its file and on the bus. The file
  goes when every provider reads its membership; that is its own change.
 - The route proxy needs a bus account. It is issued like any module's, so a machine running the proxy
  cannot be composed between the catalogue declaring the account and the operator issuing it. The
  machine keeps what it runs meanwhile.
 - The internal name of a route that also has a public one is now served to the mesh only. Outsiders
  have the public name.
 - A container on the same machine that calls that machine's own internal name arrives from its
  container network, not from a mesh address, and is refused. Calls between machines are unaffected:
  they leave by the machine's mesh address. Whether the mesh should also issue each machine's container
  networks is left open, because the mesh does not record them today.
 ## How this is checked
 | Rule | Checked by |
 |---|---|
 | What a provider receives on the bus is what its received file says, same-node port fix included | a controller test composing a provider and a consumer on one machine and comparing the two |
 | An internal name is served to the machines the membership names and to loopback, and to nobody else | the proxy's tests: served from a named address and from loopback; refused, unlisted and uncertified from any other |
 | A membership that carries no routes, or a mesh that cannot be read, changes nothing | the proxy's tests |
 | Until the mesh is issued, an internal name is served to the machine alone | the proxy's tests |
 | Live: an internal-only route answers over the mesh and is refused from outside | by hand, after the release |
 ## References
 - [ADR 0160](0160-the-mesh-issues-an-assignments-subjects-and-a-runtime-serves-what-it-is-issued.md) —
  the membership this extends
 - [ADR 0138](0138-an-assignment-binds-an-endpoint-and-says-how-far-it-reaches.md) — reach, and the
  insight of 2026-10-02 that the proxy is where internal reach is kept
 - [ADR 0144](0144-anything-on-a-machine-may-call-anything-on-it.md) — the machine itself is always inside
 - [Issue 191](../04-ISSUES/191-a-route-with-only-an-internal-name-is-dropped/00-report.md) — what
  found it
@@ -0,0 +1,136 @@
 ---
 topic: the mesh
 status: accepted
 date: 2026-10-02
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0100-a-node-in-use-is-adopted-before-it-is-converged.md
 ---
 # 168. A converged machine is filtered by the mesh alone, and the host says what else refuses
 ## Context
 [ADR 0100](0100-a-node-in-use-is-adopted-before-it-is-converged.md) says what converging does to
 the firewall a machine was found with: the mesh's derived filter is loaded in place of the
 refusal-only guard, and the found firewall is retired — disabled, never flushed. Four issues from
 the first two convergences are four ways that sentence was not the machine:
 - the flip reported the found firewall retired and it was active two minutes later; fifty minutes
  on, a reconcile found it disabled by hand and recorded that the mesh had done it
  ([143](../04-ISSUES/143-converging-does-not-retire-the-firewall-it-found/00-report.md));
 - "the firewall found" named one front end, and what filtered the forwarded path on that machine
  was a chain a predecessor had installed in the container runtime's user hook — invisible to the
  mesh, refusing two ports the mesh declared open, and when it was removed, carrying an allowance
  every module reaching another by the machine's own name had been relying on
  ([144](../04-ISSUES/144-the-predecessors-rules-outlive-the-firewall-it-was-found-as/00-report.md),
  [145](../04-ISSUES/145-a-machine-reads-healthy-while-its-modules-cannot-reach-each-other/00-report.md));
 - the forward chain listed address ranges that followed neither the modules nor the machine
  ([141](../04-ISSUES/141-the-forward-chain-does-not-follow-the-modules/00-report.md)), answered by
  [ADR 0140](0140-the-filter-constrains-what-arrives-from-outside.md) before this record;
 - the networking module wrote two machine-wide files whole, so taking it restarted every
  container ([084](../04-ISSUES/084-taking-networking-on-an-adopted-node-restarts-every-container/00-report.md)),
  answered by [ADR 0102](0102-the-mesh-writes-into-a-shared-file-never-over-it.md) and the hosts
  file's marked region ([issue 128](../04-ISSUES/128-the-hosts-file-is-written-whole/00-report.md)).
 Read on the four machines of this mesh on 2026-10-02, after every one had converged: on both
 machines that had a front end it is inactive, and the host's record says the mesh retired it on
 both — true of one, false of the other. On the home server the predecessor's chain is still in
 force on the forwarded path, in the legacy packet filter the mesh's reader of rules does not
 consult once a machine is converged, so that machine is filtered by two things and the mesh says
 one. The host's reader already knows how to tell a table that refuses traffic from the runtime's
 own plumbing and from a ban list; it is asked once, at adoption, and only to refuse a machine
 whose firewall nobody speaks. Nothing asks it afterwards, and nothing reports what it saw.
 The group's exit is one sentence: *a converged machine has exactly one thing filtering it, and
 the mesh says truthfully which.* The first half the mesh can enforce only for what it owns; the
 second half it can always do, and it is the half that was missing.
 ## Decision
 **1. Convergence is a state the host keeps, not a step it takes once.** Every apply of a converged
 declaration reads whether the found firewall is in force. Active — enabled again by a package, a
 boot, a hand — it is retired again and said. The record distinguishes *the mesh disabled it* from
 *it was found inactive*, and a reconcile that finds it inactive never records that the mesh did
 it. When the step is skipped because the apply had failures, the report says the found firewall
 was left in force and why; a step that does nothing is never silent.
 **2. The host reports what filters the machine, with every apply, adopted or converged.** Every
 table of the packet filter, and every chain of the legacy filter, that refuses traffic — a drop or
 a reject, or a base chain whose policy drops — with an owner: the *mesh's*, the *found firewall's*,
 the *container runtime's own*, a *ban* (a refusal that names the sources it refuses, in a chain
 that accepts nothing), or *other*. The runtime's own is its plumbing — its chains, the forward
 policy it sets when it turns forwarding on, its guard against reaching a container's address from
 off its bridge. The user chain the runtime leaves for an administrator is not the runtime's:
 anything refusing in it is *other*, which is where both predecessors' chains lived. Each entry
 says in one line what it refuses. The mesh removes none of it: a rule it did not write is the
 operator's to remove, now that they can see it.
 **3. The mesh says which.** `node show` lists the filters with their owners. `status` names every
 converged machine that something other than the mesh's table, the runtime's plumbing and a ban
 list filters, the way it names strays and untaken modules, and such a machine is not "all well".
 The converge preview lists the filters found and the fate of each: the found firewall retired, the
 runtime's and the bans left, *other* left and named — so a person knows before the flip that the
 machine will not be filtered by the mesh alone until they remove it, and what they would be
 removing. *A converged machine is filtered by the mesh alone* when its list holds nothing but the
 mesh's, the runtime's own and bans.
 **4. Adoption's threshold does not move.** A machine whose front end nobody speaks is still refused
 adoption; a refusing rule in the runtime's user chain still does not refuse it — on both machines
 of this mesh it would have, and the migration would not have happened. It is reported instead,
 from the first report on.
 **5. Two of the group's issues are settled by records already accepted.** The forward chain follows
 the machine's outward links and says nothing about networks ([ADR 0140](0140-the-filter-constrains-what-arrives-from-outside.md)),
 which answers 141 whole. The runtime's file is written into and reloaded, and the hosts file's
 region is the mesh's alone ([ADR 0102](0102-the-mesh-writes-into-a-shared-file-never-over-it.md),
 [issue 128](../04-ISSUES/128-the-hosts-file-is-written-whole/00-report.md)), which answers 084. One
 machine-wide file the mesh still writes whole is its own filter, at the path the distribution's
 packet filter reads; an operator's own rules at that path would be contested, and are held as
 found until the filter module is taken ([ADR 0163](0163-taking-a-module-over-is-a-comparison.md)).
 That is a difference a take shows, not a fault, and is decided when it bites.
 ## Consequences
 - The host's report grows by the filters it found and, for a converged machine, the state of its
  found firewall and who retired it; the controller keeps both on the node's record.
 - `retireFirewall` runs on every converged apply and can disable the found firewall more than
  once; the record's *disabled by the mesh* means exactly that.
 - The reader of rules gains an owner per table and chain; what it refuses adoption for does not
  change. A ban stays what it was: not a firewall.
 - Issues 143 and 144 close on rules 1 to 3 once a machine's record names the predecessor's chain;
  141 closes on ADR 0140 and 084 on ADR 0102, both by reading.
 - Removing what is reported is the operator's act, by hand, with the preview's words in front of
  them. The mesh never flushes and never deletes a rule it did not mark.
 ## How this is checked
 | Rule | Checked by |
 |---|---|
 | Every refusing table and chain is classified, the user chain's refusals as *other* | host tests over rulesets captured from three machines of this mesh: a predecessor's chain in the legacy filter, a ban list and empty front-end chains beside the runtime's, a virtualisation host and an endpoint agent that refuse nothing |
 | The found firewall active again on a converged machine is retired again and said; found inactive is recorded as found, not done; a skipped step is said | host tests over a fake front end |
 | The report carries the filters and the found firewall's state for a converged machine | a host test reading the report |
 | `node show` lists filters with owners; `status` names a converged machine something else filters and is not well; the preview lists filters and fates | controller tests over a fixture report |
 | Live | the home server's record names the predecessor's chain in the runtime's user chain as *other*; `status` names the machine; after the operator removes the chain, the next report drops it and `status` is well |
 ## Built and proven live, 2026-10-02
 > **Progressive insight — 2026-10-02.** The decision stands; these are the facts of its building.
 Built in mesh-host 67 (every refusing table and legacy chain classified with an owner, reported with
 every apply; the found firewall retired on every converged apply, *found inactive* kept apart from
 *disabled by the mesh*, a skipped step said) and mesh-controller 211 (kept per node, shown on `node
 show`, named by `status` and not well, previewed with fates). The live row was read at 10:10Z: the home
 server's record named the predecessor's chain in the legacy filter's user chain as *other*, beside two
 chains a retired front end left in the IPv6 legacy filter; the control node's record named the same two
 leftovers; the laptop and the workstation read *the mesh alone*; `status` named both machines. The five
 rule sets were removed at 12:46Z through the packet filter seat's `remove` verb
 ([ADR 0170](0170-the-firewall-seat-serves-its-verbs.md)), and the next report read *the mesh alone* on
 all four machines. The control node's record still says the mesh retired its front end, which issue 143
 records as a hand's work: the host trusts its record, and from this build on the distinction is kept.
 ## References
 - [ADR 0100](0100-a-node-in-use-is-adopted-before-it-is-converged.md), [ADR 0103](0103-what-an-adopted-node-holds-and-what-its-guard-refuses.md), [ADR 0140](0140-the-filter-constrains-what-arrives-from-outside.md), [ADR 0102](0102-the-mesh-writes-into-a-shared-file-never-over-it.md), [ADR 0163](0163-taking-a-module-over-is-a-comparison.md)
 - [Design 08 — Connectivity](../03-DESIGN/01-to-be/08-connectivity.md), [Design 05 — The node host](../03-DESIGN/01-to-be/05-the-node-host.md)
 - Issues 084, 141, 143, 144, 145
@@ -0,0 +1,89 @@
 ---
 topic: the mesh
 status: accepted
 date: 2026-10-02
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0004-a-node-and-how-it-joins.md
 ---
 # 169. A machine joins through the tunnel, and the bus is never public
 ## Context
 The bus is the one channel every machine depends on: enrolment, every declaration, every tool. The
 `nats` module declares it reachable from the mesh only. The controller still opens it to the whole
 internet on the machine that runs it, as a *foundation* port that no module declares and nothing may
 close ([issue 051](../04-ISSUES/051-the-mesh-cannot-update-what-it-depends-on/00-report.md)).
 The reason is joining. [ADR 0004](0004-a-node-and-how-it-joins.md) has a new machine enrol over the bus
 **before** it has a tunnel. [ADR 0007](0007-connectivity.md) states it as a requirement: the node
 running the broker must be reachable from wherever nodes are, at a stable address.
 So the bus listens on the internet permanently, for an event that happens a few times a year. A
 sweep of every machine on 2026-10-02 found no client using the public path. Every connection arrives
 over the tunnel or from the machine itself. The join token does not use it either: it carries the
 controller's configured broker address, a mesh name with the old broker's port.
 ADR 0004 already says what a joining machine needs: *an identity, an address, and one peer to reach*.
 The tunnel can be that peer, if the hub knows the new machine's key before the machine first knocks.
 WireGuard answers nothing to a key it does not know, which is why the tunnel's own port is safe to
 leave open where the bus's is not.
 ## Considered Options
 1. **Keep the bus public.** It is authenticated and encrypted, but every exposure of it, and of the
   server behind it, is exposure of the one thing everything depends on.
 2. **Open the bus publicly only while a join token is live.** Small, and the hub is open only during a
   join window. But the window is real, the rule is about time rather than about who may reach the
   bus, and the opening and closing are pushes that can fail between them.
 3. **The controller makes the new machine's tunnel key and puts it in the token.** One step for the
   operator, but the private half leaves a machine it does not belong to. ADR 0004 refuses that for
   every key a node holds.
 4. **The machine makes its key first, and the token is issued for it.** The machine prints the public
   half of its tunnel key. The operator issues the token for that key. The controller gives the
   machine its address and adds it as a peer on the hub. The token carries the hub's tunnel endpoint
   and key, the machine's address, and the bus's address on the private network. The machine brings
   up its tunnel and enrols over it.
 ## Decision
 **Option 4.**
 - **A machine makes its own tunnel key before it has a token**, and prints the public half. The private
  half never leaves it, as ADR 0004 says of every key a node holds.
 - **A token is issued for a tunnel key.** Issuing it assigns the machine's address on the private
  network, records the key, and makes the machine a peer of the hub. The hub is sent that before the
  token is shown, so the tunnel answers the moment the machine first uses it.
 - **The token carries the one peer.** It adds the hub's tunnel endpoint and public key and the
  machine's own address. **Where** becomes the bus's address on the private network, which needs no
  name resolution.
 - **The machine joins through the tunnel.** It brings the tunnel up from the token alone, then enrols
  over it exactly as before. The enrolment checks that the key it is offered is the one the token was
  issued for.
 - **The bus is never public.** It is no longer a foundation port. Its reach is what the `nats` module
  declares: the mesh. The tunnel's port stays open, as the one way in.
 This changes three things earlier records say. ADR 0004's *where* is the bus's private address, and the
 token carries the peer. ADR 0007's requirement that the broker be reachable from wherever nodes are
 becomes: **the hub's tunnel is**. Issue 051's broker port stops being a foundation port.
 ## Consequences
 - Joining is two commands on the new machine, with the token issued between them. A token issued for
  the wrong key gives a tunnel that never answers, and the machine says so rather than timing out at
  the bus.
 - An unused token leaves a peer on the hub until it expires. Expiry removes it, the same way it voids
  the secret.
 - A machine already in the mesh is unaffected: it reaches the bus over its tunnel today.
 - The genesis machine, the first one, raises the bus on itself and needs no tunnel to reach it.
 ## How this is checked
 | Rule | Checked by |
 |---|---|
 | A token is refused without a tunnel key, and carries the hub's peer and the machine's address | a controller test |
 | Issuing a token makes the machine a peer of the hub before the token is shown | a controller test over the hub's composed tunnel |
 | An expired, unused token's peer is gone from the hub | a controller test |
 | Enrolment refuses a tunnel key other than the one the token was issued for | a controller test |
 | No machine's filter opens the bus to anywhere | a controller test over the composed filter, and the live sweep from outside the mesh |
 | A new machine joins from outside the hub's network with the bus closed to it | the lab, then by hand |
@@ -0,0 +1,103 @@
 ---
 topic: the mesh
 status: accepted
 date: 2026-10-02
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0168-a-converged-machine-is-filtered-by-the-mesh-alone.md
 ---
 # 170. The firewall seat serves its verbs, and a foreign rule set is removed through one of them
 ## Context
 [ADR 0168](0168-a-converged-machine-is-filtered-by-the-mesh-alone.md) made the mesh say truthfully
 what filters a converged machine, and left the removal of what it did not write to the operator's
 hand. The first time that hand was needed — two machines, five rule sets a predecessor and a
 retired front end had left — there was no mesh way to lend it: the packet filter is a seat
 ([ADR 0121](0121-a-system-seat-is-named-for-its-scope-and-modules-define-their-own.md)), a seat's
 holder serves its verbs ([ADR 0154](0154-the-meshs-own-verbs-are-the-controller-seats-tools.md),
 [ADR 0159](0159-a-tool-call-names-the-machine-and-a-holder-serves-its-seats-verbs.md)), and the
 firewall seat declared none. The only remaining path was a shell on the machine, which is the path
 the mesh exists to replace, and which the operator's own tooling rightly refused to an agent.
 A seat's verbs are the contract every holder implements, whatever filter it speaks. What a person
 asks a machine's packet filter is the same whether nftables, a front end or a legacy filter answers:
 what are the rules, reload the mesh's own, remove this thing the mesh did not write. What differs by
 filter is the holder's own business and may be its own tools beside the seat's.
 ## Decision
 **1. The `node-packet-filter` seat serves three verbs**, and a module that claims it serves all
 three or is refused the claim, as with every seat:
 - `rules` — the packet filter as the machine enforces it now: the nftables ruleset, and the legacy
  filter's listings where that tool exists; narrowed to one table or chain when asked. Read-only.
 - `reload` — load the mesh's own filter again from the file the mesh writes, and answer with the
  mesh's table as loaded. The holder's own act on the holder's own rules.
 - `remove` — remove one rule set the mesh did not write, named exactly as the host reports it under
  ADR 0168 (`chain HAL-MESH-ONLY (iptables-legacy)`, `table ip6 filter, chain DOCKER-USER`), and
  answer with what was done. It refuses the mesh's own tables, the container runtime's own chains,
  a built-in chain other than the runtime's user chain, and any chain of a found firewall that is
  in force. The runtime's user chain is emptied back to its one return; another chain loses the
  jumps into it, is flushed and deleted; a table of the machine's own is deleted whole. Each is an
  operator's act, by name, on one thing the mesh reported — never a flush, never a rule the mesh
  itself marked.
 **2. A holder may serve its own tools beside the seat's.** The nftables module keeps its reading of
 the mesh's table as its own tool, and a holder speaking a filter with specifics of its own may add
 tools for them; the seat's three are what every holder owes.
 **3. A container may ask for a capability.** Serving `remove` and `reload` needs the machine's
 network namespace and the right to change its packet filter; a holder's runtime declares
 `capabilities: ["NET_ADMIN"]` on its container and runs on the machine's network. The host grants
 exactly the capabilities declared, names them in the container's spec so a change recreates it, and
 refuses a name that is not a capability's. A privileged container stays undeclarable.
 **4. ADR 0168's "by hand" is read as "by the operator, through the seat".** Removing what the mesh
 reports as *other* is still the operator's act and is still never the mesh's own doing; the verb is
 how the act reaches the machine, recorded on the bus like every other, instead of a shell.
 ## Consequences
 - The seat's row gains the three verbs; a mesh that already runs widens its row at the next
  controller start. The nftables module claims them and gains a runtime — a tool server with the
  packet filter's tools in its image, on the machine's network, with `NET_ADMIN`.
 - The host's container vocabulary grows by `capabilities`; an older host refuses a declaration that
  carries it, so the host rolls before the module.
 - The two machines of this mesh that ADR 0168 found not filtered by the mesh alone are cleaned
  through `remove`, and read *the mesh alone* afterwards; `status` returns to well without a hand on
  either machine.
 ## How this is checked
 | Rule | Checked by |
 |---|---|
 | The seat declares the three verbs; a claim that serves fewer is refused by name | the catalogue's seat tests |
 | `remove` refuses the mesh's tables, the runtime's chains, a built-in chain and an active front end's chains, and removes a user chain with its jumps, empties the user chain, deletes an own table | the module's tests over a fake command runner, with the shapes the host reported live |
 | A container's capabilities reach the runtime and its spec; an unknown name is refused | host tests |
 | Live | `node-packet-filter.remove@<node>` on the home server and the control node; `node show` reads *the mesh alone* on both; `status` is well |
 ## Built and proven live, 2026-10-02
 > **Progressive insight — 2026-10-02.** The decision stands; these are the facts of its building.
 > Written as 0169 for three hours and renumbered to 0170: another record took 0169 on main first,
 > and the check that refuses a shared number covered issues only (now records too).
 Built in mesh-host 68 (`capabilities` on a container), mesh-controller 212 (the seat's three verbs)
 and 213 (the filter file a module names under `filtering.into` counts as declared for a mount — the
 module's first build was refused without it), mesh-catalog 216 (the nftables module's runtime and
 verbs) and mesh-tools 27 (the console lists a node-scoped seat's verbs with their scope and carries the
 machine; before it, the verbs were live on four machines and unreachable from the console —
 [issue 199](../04-ISSUES/199-a-node-scoped-seats-verb-could-not-be-called-through-the-console/00-report.md)).
 Each machine's holder was issued its bus account with `mesh-controller.issue`, the broker node pushed
 first. At 12:46Z the five rule sets ADR 0168 had named were removed through
 `node-packet-filter.remove`, three on the home server and two on the control node, each answering
 with the commands it ran; the next report read *the mesh alone* on all four machines and `status`
 listed nothing under `filtered`. The live row is read. What it cost on the way is
 [issue 200](../04-ISSUES/200-the-controllers-answer-to-the-console-is-refused-by-the-bus/00-report.md).
 ## References
 - [ADR 0168](0168-a-converged-machine-is-filtered-by-the-mesh-alone.md), [ADR 0154](0154-the-meshs-own-verbs-are-the-controller-seats-tools.md), [ADR 0159](0159-a-tool-call-names-the-machine-and-a-holder-serves-its-seats-verbs.md), [ADR 0121](0121-a-system-seat-is-named-for-its-scope-and-modules-define-their-own.md)
 - [Design 33 — The tools the mesh answers](../03-DESIGN/01-to-be/33-the-tools-the-mesh-answers.md), [Design 08 — Connectivity](../03-DESIGN/01-to-be/08-connectivity.md)
@@ -0,0 +1,59 @@
 ---
 topic: the mesh
 status: accepted
 date: 2026-10-02
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0016-the-lab.md
 ---
 # 172. The lab is a module, and runs a bed when the mesh asks
 ## Context
 The lab raises virtual machines and runs the mesh on them, end to end, before a change reaches a real
 machine ([ADR 0016](0016-the-lab.md)). It runs on one machine of the mesh, the one with the
 virtualisation it needs. Until now the only way to start a bed there was to sign in to that machine and
 run the lab's command line by hand, with a dozen environment variables pointing at sibling checkouts.
 Nothing in the mesh could ask for it. An agent working through the mesh's own tools could build,
 merge and push a change, and could not prove it in the lab first. The operator's direction on
 2026-10-02: work on another machine goes through a mesh tool, not a shell on it.
 ## Considered Options
 1. **Keep the lab a command line on one machine.** Every run is a person, or an agent with a shell on
   that machine, outside the mesh.
 2. **The lab is a module.** Assigned to the machine that can run it, serving tools that run a bed
   against named branches and say how it went.
 ## Decision
 **Option 2.**
 - **A `lab` module, assigned where the lab can run**, serves five tools: whether this machine can run
  beds, run beds against a branch per repository, a run's state, its log, and stopping it.
 - **A run is the lab's own suite**, against fresh checkouts of the named branches from the mesh's forge,
  side by side as the lab expects them. It builds what the beds place from those checkouts, as the suite
  already does. It answers at once with an id, like a build: a bed takes minutes, and a call does not.
 - **Only branches on the forge are run**, never code handed to the tool. What a run tested is what the
  forge holds at the commit it names.
 - **The lab is reached over the mesh only.** Its tools travel the bus, and the module opens no port.
 - **No grant beyond the mesh's own.** Running a bed is root on the lab's machine, but anyone who can call
  the mesh's tools can already do worse. The operator's judgement on 2026-10-02.
 ## Consequences
 - An agent proves a change in the lab through the mesh, the same way it builds and pushes one.
 - The lab's machine carries a module whose runtime holds the virtualisation's and the container
  runtime's sockets, and a toolchain to build the mesh with.
 - A run's checkouts are its own, so two runs never build from each other's tree. Old ones are removed
  when their run ends.
 ## How this is checked
 | Rule | Checked by |
 |---|---|
 | A run checks out exactly the named branches, and reports the commits it tested | the module's tests over a forge fixture, and each run's answer |
 | A run answers at once, and its state and log follow it to the end | by hand, the first run |
 | The module opens no port | the composed filter of the lab's machine |
@@ -0,0 +1,108 @@
 ---
 topic: what runs on it
 status: accepted
 date: 2026-10-02
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0040-what-a-module-is.md
 ---
 # 173. The operator's machine is the mesh's, and a module is whatever it declares
 ## Context
 [ADR 0040](0040-what-a-module-is.md) says a module is *one self-contained piece of software the
 mesh installs and manages*, and every example it gives is a service: a database, an analytics
 server, a forge. The catalogue followed the examples. Of the predecessor's 34 modules on one
 workstation, 28 are the operator's environment — a login manager, a window manager with 88 files
 and four flavors, a shell, a terminal, a launcher, an audio setup, scripts — and the migration
 scoped all 28 out as *the workstation's own environment*, to be managed by nobody
 ([research 018](../01-RESEARCH/018-the-operators-machine-as-modules/02-what-exists-and-what-is-missing.md)).
 Since the predecessor retired, nobody is exactly who manages them: a fix is a hand edit that
 nothing records and nothing regenerates.
 [To-be 29](../03-DESIGN/01-to-be/29-a-node-has-operator-accounts.md) reached under the home for
 one directory and drew a boundary inside it. The operator's statement is wider: *the mesh manages
 my entire machine, all four of them, as far as it makes sense* — system folders and the home
 alike, the servers and the workstations from the same catalogue. And the operator refused a
 distinction this effort first drew between modules that ship code and modules that ship only
 declarations: *a module can have some tools, a seat implementation, some containers, a unit, a
 binary, some config files — one of these, or all, or two.*
 ## Considered Options
 1. **Keep 0040's reading and manage the environment outside the catalogue** — dotfiles in a
   repository, a script that places them. Rejected: that is the predecessor's first two days, the
   origin of every inherited shape [as-is 10](../03-DESIGN/00-as-is/10-module-catalogue.md)
   documents, and it puts the one thing a person looks at outside the one mechanism that is
   checked.
 2. **Add a second kind of module for configuration** — a "config module" with files and no
   process. Rejected by the operator: a kind is a distinction the manifest already makes by what
   it declares, and a second kind is a second set of rules to keep in step.
 3. **One definition: a module is one managed thing, described by what it declares.** Chosen.
 ## Decision
 **1. Everything configurable on a node is declared by a module.** Services, and equally the login
 manager, the display server, the window manager, the shell, the terminal, the launcher, the
 notifier, the audio setup, the boot images, the package manager's configuration, the agent at the
 terminal, and a folder a person works in. The test is *can it be configured on a machine*; if it
 can, some module owns it. What no module declares is found and left alone, as adoption already
 says of a machine ([ADR 0100](0100-a-node-in-use-is-adopted-before-it-is-converged.md)).
 **2. A module is whatever it declares, and there are no kinds of module.** A package, files, a
 container, a unit, a binary, a seat claim, tools — any one, or all. 0040's *one self-contained piece
 of software* stands; its examples were services, and that was the whole of the bias. A downloads
 folder with a process that tidies it, backs it up and answers questions about it is a piece of
 software by 0040's own test, and so is a shell that is a package, three files and a seat.
 **3. The home has no boundary of its own.** A file under the operator's home is placed and owned
 the way [to-be 29](../03-DESIGN/01-to-be/29-a-node-has-operator-accounts.md) §2 built it: by a
 module, resolved against the account's home, owned by the account. Which files are the mesh's is
 decided by what modules declare, not by a line drawn through a directory. A person's documents,
 projects and history are data under [ADR 0051](0051-shared-data-is-the-operators.md) and no module
 declares them.
 **4. One module ships one default configuration.** No flavors. What differed between the
 predecessor's four flavors of one desktop module is what [ADR 0174](0174-a-node-varies-a-module-through-settings-and-kept-regions-never-an-edit.md)
 is for.
 **5. Servers and workstations take the same catalogue.** A module declares what it needs; a
 machine reports what it has; assignment refuses by name
 ([ADR 0161](0161-what-deserves-a-seat.md) §3). The shell, the prompt, git and the agent are universal.
 A display server needs a graphical session; a window manager needs the display server held. Nothing
 in a manifest says *workstation*.
 ## Consequences
 - The catalogue grows by a family of modules that run no service. Each is still built,
  registered, assigned, pushed and reported like every other, and `status` says whether a
  machine has applied them.
 - The account fact becomes load-bearing for every node a person uses. Today it is empty on all
  four node records of this mesh; stating it is the first step of the build.
 - A module that *installs* a thing is distinct from a module that *holds its role*: zsh, fish and
  bash may all be installed, and one holds the login shell
  ([ADR 0176](0176-the-login-shell-is-a-node-seat-and-execute-is-its-contract.md)).
 - The host's `package` shape drives the distribution's package manager only. A module whose
  package is outside the distribution's repositories — the login manager in use is one — needs
  either an official package or a shape the host does not have. Recorded as a gap, not decided.
 - The predecessor's hooks go. What they did becomes declared state the host applies, or a verb a
  seat serves ([ADR 0177](0177-a-unit-may-be-user-scoped-and-the-service-manager-is-a-node-seat.md)).
 ## How it is checked
 | Rule | Checked by |
 |---|---|
 | A manifest with no container, no unit and no binary registers and resolves like any other | the catalogue's registration tests, with a package-and-files manifest |
 | A file resource under the home resolves against the account and is owned by it | the controller's composition tests (to-be 29 §2, built) |
 | A home-scoped module is refused on a node with no account, naming the fact | the same tests |
 | A module needing a capability the machine lacks is refused by name | the resolver's tests (ADR 0161 §3) |
 ## References
 - [Research 018](../01-RESEARCH/018-the-operators-machine-as-modules/00-overview.md), documents
  01 and 02 — the behaviour wanted and the inventory measured.
 - [ADR 0040](0040-what-a-module-is.md), [ADR 0112](0112-a-module-definition-names-no-node-mesh-or-path.md),
  [ADR 0051](0051-shared-data-is-the-operators.md), [ADR 0100](0100-a-node-in-use-is-adopted-before-it-is-converged.md)
 - [To-be 29](../03-DESIGN/01-to-be/29-a-node-has-operator-accounts.md) — the account and the home
  as a placement root, built; the records for them are proposed in an open change.
@@ -0,0 +1,92 @@
 ---
 topic: building it
 status: accepted
 date: 2026-10-02
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0011-managed-files-are-generated-never-edited.md
 ---
 # 174. A node varies a module through settings and kept regions, never through an edit
 ## Context
 [ADR 0011](0011-managed-files-are-generated-never-edited.md) says a managed file is derived and an
 edit to it is overwritten without warning. The predecessor said the same and then undid it twice:
 a `merge` strategy that adopted disk drift back into its database, so a local edit became the
 record; and a theming layer of about 90 environment variables substituted into templates at sync
 time, with tools to list and set them, so that *nearly every value was a variable* — a second
 configuration language laid over the first.
 The operator wants both the variation and the rule. One window-manager module with one default
 configuration, and each node tweaking it; and the file carrying the wanted value rather than a
 variable the file reads. Two mechanisms already exist for exactly this: a **setting**, declared by
 the module and set per mesh or per node, rendered at composition
 (`${setting:…}` is live in the resolver's manifest); and a **kept region**, a block in a file the
 mesh writes *into* where the operator's own lines survive every push
 ([ADR 0102](0102-the-mesh-writes-into-a-shared-file-never-over-it.md), used by the ssh-client module
 for the operator's own `Host` blocks).
 What stands in the way is [issue 168](../04-ISSUES/168-a-setting-reaches-every-file-and-contribution/00-report.md):
 a setting today reaches every mergeable file and every contribution of its module. Ninety theme
 knobs on that mechanism would reach ninety files. The record that fixes it — a setting declared
 with its type, meaning, default and the file it lands in — is proposed in an open change alongside
 the container-runtime records.
 ## Considered Options
 1. **Carry the predecessor's merge strategy.** A local edit is adopted into the node's layer.
   Rejected: two writers and no arbiter, which is the option 0011 removed, and the reason a
   `/model` choice was silently reverted on every node for weeks before anyone found the cause.
 2. **Carry the environment-variable theming.** Rejected by the operator: the value belongs in
   the file; a variable the file reads is a second place for the same fact.
 3. **A per-node file override** — a whole file replaced for one node. Rejected: it is a flavor
   under another name, and a module update then misses that node entirely.
 4. **Settings rendered into the file, and kept regions, and nothing else.** Chosen.
 ## Decision
 **A node varies a module in exactly two ways.**
 - **A setting.** Declared by the module with a default, set for the mesh or for one node, rendered
  into the file at composition. The value is in the file. Asked, the mesh lists every setting
  with its effective value and where it came from.
 - **A kept region.** A marked block in a file the mesh writes into, in which the operator's own
  lines are kept across every push and given back when the module goes (ADR 0102).
 **An edit outside a kept region is overwritten, as ADR 0011 says, and never adopted.** Nothing
 reads a managed file back into the record.
 **The predecessor's theme knobs become settings** of the modules whose files they render — the
 window manager's colours are the window manager's settings, the bar's are the bar's — each
 landing in the file that reads it and no other.
 **Issue 168 is fixed before any environment module declares a setting.** A setting must name the
 file it lands in; until that ships, the environment modules carry their defaults in their files
 and no settings.
 ## Consequences
 - No flavors, no per-node file copies, no environment layer. A module's definition is one set of
  files; a node's difference is data in its layer, visible by asking.
 - The settings record proposed alongside the container-runtime records is on the critical path
  of every module with a knob, and this record depends on it shipping as proposed.
 - A kept region is the only place a person edits a managed file, and the file says where it is.
  The operator's own prompt customisations, aliases and window rules live there.
 - What got harder: a change that is neither a setting the module declared nor the operator's own
  lines has no home, and is refused by the mechanism rather than silently kept. That is the point.
 ## How it is checked
 | Rule | Checked by |
 |---|---|
 | A setting reaches only the file its declaration names | the controller's settings tests, once the proposed record ships; issue 168 closes on it |
 | A kept region survives a push with its content and is given back on undeclare | the host's write-into tests (ADR 0102), with a region declared by an environment module |
 | An edit outside a region does not survive a push | the same tests, asserting the file equals the composed content outside the region |
 | Every effective value names its source | `mesh-controller.settings` and the module's own `show-config` tool |
 ## References
 - [Research 018](../01-RESEARCH/018-the-operators-machine-as-modules/01-the-intended-behaviour.md) §"One default, varied by settings, never by edits"
 - [ADR 0011](0011-managed-files-are-generated-never-edited.md), [ADR 0102](0102-the-mesh-writes-into-a-shared-file-never-over-it.md),
  [issue 168](../04-ISSUES/168-a-setting-reaches-every-file-and-contribution/00-report.md)
@@ -0,0 +1,122 @@
 ---
 topic: what runs on it
 status: accepted
 date: 2026-10-02
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0150-a-modules-own-code-runs-as-supervised-processes-under-one-account.md
 ---
 # 175. One tool runtime per node serves every module's tools, on the host side
 ## Context
 A module's tools are code the module wrote, one function behind each verb, served on the subjects
 the controller issues in the module's membership
 ([ADR 0160](0160-the-mesh-issues-an-assignments-subjects-and-a-runtime-serves-what-it-is-issued.md)).
 What *runs* that code is [ADR 0150](0150-a-modules-own-code-runs-as-supervised-processes-under-one-account.md):
 a supervised process per module under the module's own account, and in the catalogue as built,
 that process is a container per module per node, built on the tool runtime's base image.
 Measured on the live mesh ([research 018](../01-RESEARCH/018-the-operators-machine-as-modules/03-one-tool-executor-per-node.md)):
 67 module tools, each served from its module's container; the packet-filter seat's three verbs
 served by a container with `NET_ADMIN` on every one of four machines, for a module that is
 otherwise a package, three files and a service; and the console, a container per node, calling
 everything and serving nothing. The operator's environment adds a dozen modules of the
 packet-filter shape, and the operator's judgement is plain: *I would never run MCP tools inside
 a container; that is a very bad design.* And: *I don't care about permissions or account per
 module, that just complicates things for no good reason. Just a node-level tool executor. If a
 command needs root, that's the module's concern.*
 The tool runtime itself was written for this. Its own description: *the per-node process that
 makes a module's tools actually serve — imports the assigned modules' compiled tool entrypoints,
 each of which registers its tools as it loads; on a node the host resolves the list and starts it
 like any other supervised workload.* What the catalogue did instead was build one image per module
 around it.
 ## Considered Options
 1. **Keep a process per module.** Rejected: one container per module per node for software that
   is not a container, and the account-per-module invariant it exists to protect is one the
   operator declines to pay for.
 2. **The host executes tools itself.** Rejected: the host is a static Go binary that loads no
   plugins; a module's tools are TypeScript on the SDK, and building a second SDK in Go for the
   host's sake is the cost ADR 0039 refuses.
 3. **One tool runtime per node, a sibling of the host, loading every assigned module's bundle.**
   Chosen. It is what the runtime was written to be.
 ## Decision
 **1. One tool runtime per node, supervised by the host, on the host side — never a container.**
 The host starts it the way the launcher starts the host
 ([ADR 0005](0005-the-node-host.md)): a process on the machine, restarted when it dies. It holds one
 bus credential, the node's. It is module-agnostic: it knows bundles and subjects, nothing of what
 any module does.
 **2. It serves every assigned module's tools and every held seat's verbs** on the subjects the
 memberships issue. ADR 0159 and ADR 0160 are unchanged in what they say about subjects, grants
 and memberships; what changes is that one process on the node subscribes to all of them instead of
 one process per module. A module that runs a long-lived service of its own — a daemon, a
 container — keeps it; this record is about tools.
 **3. A module brings its tools as a bundle**, the artifact kind the catalogue already has for
 interpreted code, built by the pipeline and delivered to the node by the host as it delivers any
 artifact. Never an image. The runtime loads each bundle as the membership names it, and a push
 that adds or replaces a bundle reaches a running runtime as a reload.
 **4. Root is the module's concern.** A tool that must change the packet filter or rebuild boot
 images escalates itself. The runtime does not run as root for everyone's sake; the caller does not
 know and need not.
 **5. Any node may call any tool on any node.** The runtime's credential may call everything, as
 the console's already may. A per-module calling grant is not kept.
 **6. The console is this runtime's serving mode, renamed.** [ADR 0152](0152-the-operators-surface-is-a-module-the-console.md)
 stands in substance — a module assigned per node, MCP on the machine's loopback, the machine's
 login is the authority — and changes in form: host-side, serving as well as calling, and named for
 what it is: **node tools**. The mesh's own verbs stay with the controller
 ([ADR 0154](0154-the-meshs-own-verbs-are-the-controller-seats-tools.md)); a mesh-scoped seat's verbs
 run on the node that holds it ([ADR 0121](0121-a-system-seat-is-named-for-its-scope-and-modules-define-their-own.md)).
 **Where ADR 0047 and ADR 0150 say a module's tools are served by the module's own process under
 the module's own account, read this record.** Everything else they decided stands: a tool is served
 on its own subject, only the module that serves it answers, a module's long-lived processes are the
 machine's to supervise. The invariant 0150 kept — one account per module — no longer holds for
 tools, and the reason is stated above: every tool is callable from everywhere by decision 5, so the
 account no longer scopes anything a caller cannot already reach.
 ## Consequences
 - The packet-filter module's container goes; its verbs run on the host side and escalate as they
  need. [ADR 0170](0170-the-firewall-seat-serves-its-verbs.md) §3's container capability is moot
  for it.
 - The tool runtime's base image stays the way a module's *service* may be built; it is no longer
  the way tools reach a node.
 - The node tools runtime needs an interpreter on the machine. The module that is the runtime
  declares it as a package.
 - The container-runtime seat proposed in an open change says its holder *runs as a supervised
  process and serves the verbs locally to the host and on the bus*. A supervised process serving
  verbs is what this runtime is; whether that holder keeps a process of its own or serves through
  the runtime is for that record's build to say.
 - What got harder: one process carries every module's tool code on a node, so one module's
  faulty bundle can take down the node's tools. The runtime loads each bundle guarded and names
  the one that failed; the others serve.
 ## How it is checked
 | Rule | Checked by |
 |---|---|
 | The runtime loads every bundle its memberships name and serves each tool on its subject | the runtime's tests against a real bus: two bundles, three tools, each answers |
 | A bundle that fails to load is named and the others serve | the same tests, with one bundle that throws on load |
 | The host supervises the runtime and restarts it | the host's tests over the launcher's shape |
 | A push that replaces a bundle reloads it without a restart | the runtime's tests: a bundle replaced on disk, the membership re-read, the new tool answers |
 | No module in the catalogue declares a container whose only purpose is tools | a catalogue check: a manifest with `tools` and an image artifact built on the tool runtime's base is refused once the runtime is live |
 | Live | `login-shell.execute@<node>` answers on every node from the node tools runtime; `docker ps` shows no per-module tool container |
 ## References
 - [Research 018](../01-RESEARCH/018-the-operators-machine-as-modules/03-one-tool-executor-per-node.md)
 - [ADR 0150](0150-a-modules-own-code-runs-as-supervised-processes-under-one-account.md), [ADR 0047](0047-a-module-runs-its-code-as-its-own-process-with-its-own-account.md),
  [ADR 0152](0152-the-operators-surface-is-a-module-the-console.md), [ADR 0159](0159-a-tool-call-names-the-machine-and-a-holder-serves-its-seats-verbs.md),
  [ADR 0160](0160-the-mesh-issues-an-assignments-subjects-and-a-runtime-serves-what-it-is-issued.md), [ADR 0154](0154-the-meshs-own-verbs-are-the-controller-seats-tools.md)
 - [To-be 33](../03-DESIGN/01-to-be/33-the-tools-the-mesh-answers.md), [to-be 34](../03-DESIGN/01-to-be/34-the-console.md)
@@ -0,0 +1,66 @@
 ---
 topic: the mesh
 status: accepted
 date: 2026-10-02
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0168-a-converged-machine-is-filtered-by-the-mesh-alone.md
 ---
 # 175. The found front end is uninstalled once a machine is converged
 ## Context
 [ADR 0100](0100-a-node-in-use-is-adopted-before-it-is-converged.md) retires the firewall a machine
 was found with by disabling it, never flushing it, and keeps its configuration on disk so that
 returning the node to adopted can enable it again. [ADR 0168](0168-a-converged-machine-is-filtered-by-the-mesh-alone.md)
 made the host keep it retired and say so. Both machines of this mesh that had a front end have been
 converged for days; neither is going back. What remained of the front end on each — its package,
 its unit enabled for boot on one, its empty chains still wired into the kernel's hooks, a chain of
 its container integration still dropping traffic on the IPv6 path until the day before this record
 — was not a rollback path. It was software nobody runs, left where a reader finds it and asks
 whether the machine has two firewalls.
 The operator asked on 2026-10-02 that it be disabled and uninstalled. Disabled it already was. For
 uninstalled, the host had no word: a package could be declared present and not absent.
 ## Decision
 **1. A package may be declared absent.** `absent: true` on a package resource has the host remove
 the package when it is installed and leave alone a machine that never had it, through the machine's
 own package manager, dependencies untouched. A declaration that stops saying a package is absent
 installs nothing: there is nothing to undo.
 **2. The module that holds the packet filter seat declares the front end it replaced absent**, after
 its own filter is loaded, so the mesh's table is in force before the front end's package goes. On a
 converged machine the front end is therefore gone, not merely off; on an adopted machine nothing of
 this runs, because the filter module is assigned by the flip and not before.
 **3. Returning such a machine to adopted enables nothing.** A machine with no firewall needs no
 openings ([ADR 0100](0100-a-node-in-use-is-adopted-before-it-is-converged.md)); the host records the
 front end as *removed*, says so once, and asks nothing of a command that is not there. What
 ADR 0100 kept on disk for a return is kept only as far as the package manager keeps a changed
 configuration file; the rollback path it described is given up on purpose.
 ## Consequences
 - The host's vocabulary grows by `absent` on a package; an older host refuses a declaration
  carrying it, so the host rolls before the module.
 - The nftables module's declaration gains one resource; on the two machines of this mesh that were
  found with ufw, the next push removes it.
 - `node show` reads *found firewall: ufw, removed* on those machines from then on.
 - ADR 0100's sentence about a return to adopted restoring the found firewall holds only while the
  front end is installed, which after this record it is not on a converged machine.
 ## How this is checked
 | Rule | Checked by |
 |---|---|
 | An absent package is removed when present, left when not, and read back | host tests over a fake package manager |
 | An uninstalled front end is recorded as removed and nothing is asked of it | a host test with ufw missing on a converged apply |
 | Live | the two machines report ufw gone: `pacman -Q ufw` has no answer, `node show` says removed, `status` is well |
 ## References
 - [ADR 0100](0100-a-node-in-use-is-adopted-before-it-is-converged.md), [ADR 0168](0168-a-converged-machine-is-filtered-by-the-mesh-alone.md), [ADR 0170](0170-the-firewall-seat-serves-its-verbs.md)
 - [Design 08 — Connectivity](../03-DESIGN/01-to-be/08-connectivity.md)
@@ -0,0 +1,81 @@
 ---
 topic: what runs on it
 status: accepted
 date: 2026-10-02
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0132-a-seat-carries-the-tools-its-holder-must-serve.md
 ---
 # 176. The login shell is a node seat held by one shell module, and `execute` is its contract
 ## Context
 [ADR 0040](0040-what-a-module-is.md) names the shell as its example of a *shared* seat: bash, zsh
 and fish all join `shell`, and one may be default. The operator's reading is sharper, and it
 matches [ADR 0126](0126-a-module-declares-its-own-seats.md) better: *installing* a shell is
 installing software, and several may be installed; *holding* the seat is being the login shell,
 which a node has exactly one of. A definition says which seats a module can hold; the assignment
 says which it does.
 A seat carries the tools its holder must serve ([ADR 0132](0132-a-seat-carries-the-tools-its-holder-must-serve.md)),
 and [to-be 33](../03-DESIGN/01-to-be/33-the-tools-the-mesh-answers.md) leaves which verbs each
 seat serves as a decision per seat, taken slowly. This is the first seat of the operator's
 environment, and the one every node has.
 ## Considered Options
 1. **A shared `shell` seat with a default**, as 0040's example reads. Rejected: *default* is a
   second concept beside *holder* for the same fact, and the `user` shape already makes the
   login shell declared state ([to-be 05](../03-DESIGN/01-to-be/05-the-node-host.md)).
 2. **No seat; each shell module sets the login shell for itself.** Rejected: two assigned shell
   modules would fight over `chsh`, and nothing would say which won.
 3. **An exclusive node-scoped seat, `login-shell`, declared by the shell modules, held by one
   per node.** Chosen.
 ## Decision
 **1. `login-shell` is a node-scoped seat declared by the shell modules.** zsh, fish and bash each
 declare that they can hold it; a node's assignment says which does; the controller refuses a
 second holder by name as for every seat. A shell module that is assigned without holding the seat
 is installed and nothing more.
 **2. Holding the seat sets the account's login shell.** The holder's declaration carries the
 `user` shape with the shell it provides, so the login shell is declared state the host applies and
 gives back when the holding moves — `chsh` stops being a hook.
 **3. The seat's contract is `execute`.** One verb, one argument, the command, run on the node the
 seat is scoped to as the operator account, answering with what it printed and how it exited.
 Every holder serves it; a holder may serve its own tools beside it
 ([ADR 0170](0170-the-firewall-seat-serves-its-verbs.md) §2) — show the rendered configuration, list
 the plugins, set a prompt value.
 **4. Any node may call it on any node.** The grant is the node tools runtime's
 ([ADR 0175](0175-one-tool-runtime-per-node-serves-every-modules-tools-on-the-host-side.md) §5):
 *run `uptime` on every node* is five calls to one verb.
 ## Consequences
 - The first environment module is a shell: a package, files under the home owned by the account,
  a seat declaration and claim, a `user` shape, and one tool. It proves the whole pattern on every
  node, servers included, before anything graphical is written.
 - ADR 0040's shell example is read as *installed is not holding*; a dated note in that record says
  so. Its decision is untouched.
 - `execute` is a shell on every machine, addressed over the bus. That is the point, and it is
  the widest verb the mesh serves; it exists because the operator decided every node may call
  every tool, and this record does not narrow that.
 ## How it is checked
 | Rule | Checked by |
 |---|---|
 | Two shell modules assigned to one node, one holding: one `user` shape in the declaration, naming the holder's shell | the controller's composition tests |
 | A second claimant is refused by name | the catalogue's seat tests |
 | `execute` runs as the account and answers output and exit status | the module's tool tests over a fake runner, and live on every node |
 | The seat's verb appears with its scope and machine in the node tools listing | the runtime's tests (to-be 33 §4) |
 ## References
 - [Research 018](../01-RESEARCH/018-the-operators-machine-as-modules/04-the-seats-of-the-environment.md)
 - [ADR 0040](0040-what-a-module-is.md), [ADR 0126](0126-a-module-declares-its-own-seats.md),
  [ADR 0132](0132-a-seat-carries-the-tools-its-holder-must-serve.md), [ADR 0170](0170-the-firewall-seat-serves-its-verbs.md)
@@ -0,0 +1,80 @@
 ---
 topic: what runs on it
 status: accepted
 date: 2026-10-02
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0121-a-system-seat-is-named-for-its-scope-and-modules-define-their-own.md
 ---
 # 177. A unit may be user-scoped, and the service manager is a node seat whose holder answers for the units
 ## Context
 The host's `service` shape puts a system unit into a state. It has no user scope.
 [To-be 29](../03-DESIGN/01-to-be/29-a-node-has-operator-accounts.md) states the gap: *a
 workstation's per-user daemons have no form the mesh can send.* Four of the predecessor's
 environment modules ship user units — the desktop's reload watcher and bar watchdog, the audio
 module's masks, the power module's memory guard, the thermal daemon's profile switcher — and the
 predecessor needed a hook to enable them because *shipping a unit file does not run it*; one unit
 was deployed for months and ran on one machine only.
 [ADR 0040](0040-what-a-module-is.md) says the host hardcodes no supervisor, and a swappable
 machine mechanism is a module implementing a capability — which is what the nftables module is for
 the packet filter ([ADR 0170](0170-the-firewall-seat-serves-its-verbs.md)). The service manager is
 reported today as a capability, `service-manager`, and held by nobody. The operator's proposal: a
 systemd module that holds the seat and serves the tools about units, system and user.
 ## Considered Options
 1. **Keep user units as a module concern** — each module runs `systemctl --user` in a hook.
   Rejected: that is the hook that silently never ran, and an action over the link is refused.
 2. **The service-manager module applies units** on behalf of others, as a provision. Rejected by
   the operator: provisioning is for resources a provider creates for a consumer; a unit is
   declared state the host applies, as every resource is.
 3. **The host's `service` shape gains a user scope; a systemd module holds the service-manager
   seat and serves the verbs about units.** Chosen.
 ## Decision
 **1. The `service` shape gains `scope`: `system` (the default) or `user`.** A user-scoped unit
 is applied as the operator account through the account's own service manager: enabled, started,
 stopped, reloaded on its triggers, exactly as a system unit is, and refused on a node with no
 account, naming the fact. The host applies it; no module does.
 **2. `node-service-manager` is a seat of the mesh's own, node-scoped**, seeded by the controller
 under this record, as ADR 0121 requires of a `node-*` name. The `systemd` module claims it and is
 assigned to every machine whose profile reports `service-manager`.
 **3. The seat's verbs answer for every unit on the machine**, each taking an optional `scope`:
 `units`, `status`, `start`, `stop`, `restart`, `enable`, `disable`, `journal`. The host applies what
 is declared; the holder answers questions and operator acts about it, and says, for a mesh-held
 unit, that the host will restore what its declaration says.
 ## Consequences
 - The host's vocabulary grows by one field on one shape, asserted by its count test
  ([to-be 05](../03-DESIGN/01-to-be/05-the-node-host.md)); an older host refuses a declaration
  carrying it, so the host rolls before the first module that uses it.
 - The predecessor's four user-unit modules become declarable without a hook.
 - The seat's holder is the first system seat held by a module that runs nothing of its own: its
  verbs are served by the node tools runtime ([ADR 0175](0175-one-tool-runtime-per-node-serves-every-modules-tools-on-the-host-side.md)).
 - What got harder: `journal` and `status` on a user unit need the account's manager reachable
  from the runtime's process, which runs as the node's account; the holder's tool escalates or
  switches user as it needs, which is ADR 0175 §4 applied.
 ## How it is checked
 | Rule | Checked by |
 |---|---|
 | A `service` with `scope: user` is enabled and started under the account, and refused with no account | the host's tests with a fake service manager |
 | The seat declares its verbs; a claim serving fewer is refused by name | the catalogue's seat tests |
 | The verbs act on a named unit in the named scope and name the unit's holder when the mesh declares it | the module's tests over a fake runner |
 | Live | the desktop's reload watcher declared `scope: user` on a workstation; `node-service-manager.status@<node>` reports it active |
 ## References
 - [Research 018](../01-RESEARCH/018-the-operators-machine-as-modules/04-the-seats-of-the-environment.md)
 - [ADR 0121](0121-a-system-seat-is-named-for-its-scope-and-modules-define-their-own.md), [ADR 0132](0132-a-seat-carries-the-tools-its-holder-must-serve.md),
  [ADR 0040](0040-what-a-module-is.md), [ADR 0170](0170-the-firewall-seat-serves-its-verbs.md)
 - [To-be 05](../03-DESIGN/01-to-be/05-the-node-host.md), [to-be 29](../03-DESIGN/01-to-be/29-a-node-has-operator-accounts.md)
@@ -177,6 +177,12 @@ python3 00-META/checks/index.py            fail if stale
 - **0161** — [What deserves a seat: a role of a module is a seat, a singular fact about machines is a placement with a capacity of one, and a holder's software is the machine's](0161-what-deserves-a-seat.md)
 - **0162** — [A merge produces a tiered plan the mesh keeps, and a module's dependencies are one relation in the catalogue](0162-a-merge-produces-a-tiered-plan-the-mesh-keeps.md)
 - **0163** — [Taking a module over is a comparison: what it compares, what it refuses, and what it carries](0163-taking-a-module-over-is-a-comparison.md)
 - **0167** — [A membership carries what its module receives, and who the mesh is](0167-a-membership-carries-what-its-module-receives-and-who-the-mesh-is.md)
 - **0168** — [A converged machine is filtered by the mesh alone, and the host says what else refuses](0168-a-converged-machine-is-filtered-by-the-mesh-alone.md)
 - **0169** — [A machine joins through the tunnel, and the bus is never public](0169-a-machine-joins-through-the-tunnel-and-the-bus-is-never-public.md)
 - **0170** — [The firewall seat serves its verbs, and a foreign rule set is removed through one of them](0170-the-firewall-seat-serves-its-verbs.md)
 - **0172** — [The lab is a module, and runs a bed when the mesh asks](0172-the-lab-is-a-module-and-runs-a-bed-when-the-mesh-asks.md)
 - **0175** — [The found front end is uninstalled once a machine is converged](0175-the-found-front-end-is-uninstalled-once-a-machine-is-converged.md)
 ### Its tiers, from the bottom up
@@ -267,6 +273,10 @@ python3 00-META/checks/index.py            fail if stale
 - **0150** — [A module's own code runs as supervised processes under the module's one account](0150-a-modules-own-code-runs-as-supervised-processes-under-one-account.md)
 - **0152** — [The operator's surface is a module the mesh assigns: the console](0152-the-operators-surface-is-a-module-the-console.md)
 - **0155** — [A definition names no installation: how that is checked, and the three ways a value that did gets out](0155-a-definition-names-no-installation-and-how-that-is-checked.md)
 - **0173** — [The operator's machine is the mesh's, and a module is whatever it declares](0173-the-operators-machine-is-the-meshs-and-a-module-is-what-it-declares.md)
 - **0175** — [One tool runtime per node serves every module's tools, on the host side](0175-one-tool-runtime-per-node-serves-every-modules-tools-on-the-host-side.md)
 - **0176** — [The login shell is a node seat held by one shell module, and `execute` is its contract](0176-the-login-shell-is-a-node-seat-and-execute-is-its-contract.md)
 - **0177** — [A unit may be user-scoped, and the service manager is a node seat whose holder answers for the units](0177-a-unit-may-be-user-scoped-and-the-service-manager-is-a-node-seat.md)
 ### How it is built
@@ -288,6 +298,7 @@ python3 00-META/checks/index.py            fail if stale
 - **0107** — [Persistent data is a directory bind, never a named volume](0107-persistent-data-is-a-directory-bind-never-a-named-volume.md)
 - **0111** — [A build source is on the mesh's git seat, or it is an external repository](0111-a-build-source-is-on-the-git-seat-or-external.md)
 - **0149** — [The live mesh is the test bed](0149-the-live-mesh-is-the-test-bed.md)
 - **0174** — [A node varies a module through settings and kept regions, never through an edit](0174-a-node-varies-a-module-through-settings-and-kept-regions-never-an-edit.md)
 ### How it is checked
@@ -1,9 +1,10 @@
 ---
 layer: to-be
 status: in-progress
-code: [mesh-lab]
+code: [mesh-lab, mesh-catalog modules/lab]
-updated: 2026-09-11
+updated: 2026-10-02
 decisions:
  - 02-DECISIONS/0172-the-lab-is-a-module-and-runs-a-bed-when-the-mesh-asks.md
  - 02-DECISIONS/0016-the-lab.md
  - 02-DECISIONS/0010-delivery.md
 ---
@@ -119,7 +120,25 @@ In order, on a machine with nothing:
 6. **Verification**, as above, before anything is raised.
-## Open
+## The lab answers the mesh
 *2026-10-02* ([ADR 0172](../../02-DECISIONS/0172-the-lab-is-a-module-and-runs-a-bed-when-the-mesh-asks.md)).
 Once installed, the lab is also a module: `lab`, assigned to the machine that passed `check`. Its
 tools run there and nowhere else:
 | tool | does |
 |---|---|
 | `lab_check` | the lab's `check`, on this machine |
 | `lab_run` | fresh checkouts of the named branches from the forge, side by side, then the suite on the named beds; answers with an id |
 | `lab_status` | where a run is, and how it ended: the commits it tested, passed and failed |
 | `lab_log` | the run's output so far |
 | `lab_stop` | ends a run |
 The runtime is a container holding the toolchain the suite builds with. It reaches the
 virtualisation daemon and the container runtime through their sockets on the machine, so what it
 raises is what a hand run raises. The prerequisites above stay installed by hand. The module uses
 them, and never installs them.
 - **Whether the lab's bootstrap may install packages at all**, given that the mesh's rules
  forbid installing by hand. The resolution is probably that the lab's bootstrap *is* the
@@ -4,6 +4,7 @@ status: in-progress
 code: [mesh-host]
 updated: 2026-10-02
 decisions:
  - 02-DECISIONS/0168-a-converged-machine-is-filtered-by-the-mesh-alone.md
  - 02-DECISIONS/0163-taking-a-module-over-is-a-comparison.md
  - 02-DECISIONS/0141-the-host-delivers-its-own-successor.md
  - 02-DECISIONS/0100-a-node-in-use-is-adopted-before-it-is-converged.md
@@ -176,6 +177,14 @@ has left to say. *How it is checked:* a host test joins a kept network and refus
 host test keeps a left-out module's record and hold and removes an absent module's; a bootstrap test
 holds the installer's constants to the module's manifest where the catalogue is checked out beside it.
 **What filters the machine, and the found firewall kept retired** — revision, 2026-10-02
 ([ADR 0168](../../02-DECISIONS/0168-a-converged-machine-is-filtered-by-the-mesh-alone.md)). The host
 reports, with every apply, every table and legacy chain that refuses traffic and whose it reads it as —
 the mesh's, the found firewall's, the container runtime's own, a ban, or other — and, converged, whether
 the firewall it was found with is in force and who retired it. It retires that firewall on every
 converged apply, not once, records *found inactive* apart from *disabled by the mesh*, and says when the
 step was skipped. *How it is checked:* ADR 0168's table.
 **Found reaches every kind that can touch what the machine has**
 ([ADR 0103](../../02-DECISIONS/0103-what-an-adopted-node-holds-and-what-its-guard-refuses.md)). For a module not yet taken, a directory present with no record
 keeps its mode and owner, a unit present with no record keeps its state and boot setting, a
@@ -7,8 +7,13 @@ code:
  - mesh-controller internal/identity/authority.go
  - mesh-host internal/identity/serving.go
  - mesh-host internal/apply (the service that reflects a rule set)
-updated: 2026-09-30
+updated: 2026-10-02
 decisions:
  - 02-DECISIONS/0175-the-found-front-end-is-uninstalled-once-a-machine-is-converged.md
  - 02-DECISIONS/0170-the-firewall-seat-serves-its-verbs.md
  - 02-DECISIONS/0169-a-machine-joins-through-the-tunnel-and-the-bus-is-never-public.md
  - 02-DECISIONS/0168-a-converged-machine-is-filtered-by-the-mesh-alone.md
  - 02-DECISIONS/0167-a-membership-carries-what-its-module-receives-and-who-the-mesh-is.md
  - 02-DECISIONS/0148-the-meshs-names-are-resolved-not-copied-into-containers.md
  - 02-DECISIONS/0151-a-routes-internal-name-is-composed-under-the-node-that-serves-it.md
  - 02-DECISIONS/0147-a-module-anchors-the-meshs-authority.md
@@ -171,6 +176,28 @@ the broker's node must be dialable by every node, at a stable address, and so mu
 reachable; on one network it does not. A mesh whose nodes are all behind NAT cannot be raised, and
 a broker node whose address moves invalidates every token issued for it.
 *2026-10-02.* **The order changes at step 1: the tunnel comes first, from the token**
 ([ADR 0169](../../02-DECISIONS/0169-a-machine-joins-through-the-tunnel-and-the-bus-is-never-public.md)).
 The circularity above is real, and it is broken differently. The overlay is configured by the mesh,
 except for the one peer a joining machine needs, and the token carries that peer. So the sequence
 becomes:
 ```
 0  the node has an underlay address     the machine's own
 1  the node makes its tunnel key        before any token; it prints the public half
 2  a token is issued for that key       its address assigned, and the hub sent it as a peer
 3  the tunnel comes up to the hub       from the token alone: the hub's endpoint and key, its address
 4  the node dials the bus               OVER THE TUNNEL, at the bus's private address
 5  it proves itself, and is proved to   enrolment, checking the key is the one the token named
 6  the rest of the overlay              the whole peer set, delivered as files
 7  names, filtering, routes             as before
 ```
 The link no longer stays on the underlay. The bus is reached over the tunnel by every machine,
 including one that is joining, so it is never opened to the internet. The precondition becomes: **the
 hub's tunnel must be dialable by every node, at a stable address.** That port answers nothing to a
 key it does not know.
 **Whether the link should later move onto the overlay, with the underlay as fallback, is
 [open](../../02-DECISIONS/0007-connectivity.md).** It is a decision rather than a derivation: the
 gain is which network carries bytes, not what an attacker can reach, since the link is already
@@ -709,6 +736,48 @@ needs no new filter; a declared port is reachable from off the private network a
 not; no address of a machine's own networks appears in a rendered filter, asserted on the text; and a
 machine reporting no outward link is refused in the control plane with its existing filter left alone.
 ### A converged machine is filtered by the mesh alone, and the host says what else refuses
 *2026-10-02, [ADR 0168](../../02-DECISIONS/0168-a-converged-machine-is-filtered-by-the-mesh-alone.md),
 from [issues 143](../../04-ISSUES/143-converging-does-not-retire-the-firewall-it-found/00-report.md) and
 [144](../../04-ISSUES/144-the-predecessors-rules-outlive-the-firewall-it-was-found-as/00-report.md).*
 Retiring the found firewall was a step the flip took once, and said it had taken whatever happened;
 on the first machine with one it did not take, and a hand's work fifty minutes later was recorded as
 the mesh's. And "the firewall found" named one front end while a predecessor's chain in the container
 runtime's user hook — legacy iptables on one machine, invisible to a reader of nftables — filtered the
 forwarded path, refused ports the mesh declared open, and carried an allowance every module reaching
 another by the machine's own name relied on.
 **Convergence is a state the host keeps.** Every converged apply reads whether the found firewall is in
 force; enabled again, it is retired again and said; the record says whether the mesh disabled it or
 found it inactive, and a skipped step is said. **The host reports what filters the machine**, every
 apply, adopted or converged: every table and legacy chain that refuses, with an owner — the mesh's,
 the found firewall's, the runtime's own plumbing, a ban, or *other*, which is where the runtime's user
 chain's refusals go. **The mesh says which:** `node show` lists them; `status` names a converged machine
 anything *other* filters and is not well; the converge preview lists what filters the machine and the
 fate of each — retired with the front end, left as the runtime's, left as a ban, or *left in force and
 not the mesh's*. The mesh removes none of it; adoption's threshold does not move.
 *How it is checked:* host tests over rulesets captured from three machines of this mesh classify every
 refusing chain (a predecessor's chain in the legacy filter as *other*, a ban list reached through the
 user chain as a ban, a leftover front-end chain as *other*); a fake front end enabled again on a
 converged machine is retired again and said, found inactive is recorded as found; the report carries
 the filters and the found firewall's state and a change in them is worth an unasked report; controller
 tests over a fixture report check the recording, the preview's fates, the status JSON and the well
 predicate. Live: the home server's record names the predecessor's chain as *other* and `status`
 names the machine until the chain is removed by hand.
 *2026-10-02, [ADR 0170](../../02-DECISIONS/0170-the-firewall-seat-serves-its-verbs.md):* removing what
 the host reports as *other* is reached through the packet filter seat's `remove` verb, an operator's act
 by name on the bus; the seat also serves `rules` and `reload`, and its holder's runtime declares the
 `NET_ADMIN` capability on the machine's network. See design 33.
 *2026-10-02, [ADR 0175](../../02-DECISIONS/0175-the-found-front-end-is-uninstalled-once-a-machine-is-converged.md):*
 once a machine is converged, the front end it was found with is uninstalled, not merely disabled — the
 packet filter's holder declares its package absent after the mesh's filter is loaded, and a return to
 adopted then enables nothing. The rollback path ADR 0100 kept on disk is given up on purpose.
 ## 5 — Certificates
 **Two authorities, kept separate on purpose.**
@@ -842,6 +911,18 @@ One value, three readers:
 | `public` | the machine port, to anywhere | the public name | the public authority |
 | `both` | the machine port, to anywhere | both names | each name's own authority |
 *2026-10-02.* **The proxy serves an internal name to the private network only**
 ([ADR 0138](../../02-DECISIONS/0138-an-assignment-binds-an-endpoint-and-says-how-far-it-reaches.md),
 its insight of this date). It answers public and internal names on the same listeners, so the name a
 request carries is the request's own claim, not where the request came from. An internal name is
 served to the machines of the mesh and to the machine itself; to anyone else it is answered as a name
 never routed, in the handshake as well as the request. Without this, an endpoint with reach `internal`
 would be public under a name that is easy to guess
 ([issue 191](../../04-ISSUES/191-a-route-with-only-an-internal-name-is-dropped/00-report.md)).
 The proxy is told who the mesh is, and its routes, in its membership on the bus — the same machine
 addresses the filter's "from the mesh" is rendered from
 ([ADR 0167](../../02-DECISIONS/0167-a-membership-carries-what-its-module-receives-and-who-the-mesh-is.md)).
 **An endpoint that is not routed is reached and never named.** No route contribution means no name is
 composed and no certificate requested, while the filter still acts on it. That is the case the model
 could not express at all, and it is the ordinary case for anything that is not HTTP.
@@ -7,8 +7,9 @@ code:
  - mesh-tools src/broker-amqp.ts (to be replaced)
  - mesh-catalog modules/nats (to be written)
  - mesh-sdk src (the protocol's NATS binding, step 3)
-updated: 2026-10-01
+updated: 2026-10-02
 decisions:
  - 02-DECISIONS/0167-a-membership-carries-what-its-module-receives-and-who-the-mesh-is.md
  - 02-DECISIONS/0160-the-mesh-issues-an-assignments-subjects-and-a-runtime-serves-what-it-is-issued.md
  - 02-DECISIONS/0157-a-build-says-what-it-does-on-the-bus-as-it-happens.md
  - 02-DECISIONS/0106-the-bus-is-nats.md
@@ -94,6 +95,12 @@ list; the account's grant is the same membership read the other way; the console
 tool's subject. The one rule a runtime keeps is the membership's own subject, from the two names in its
 credential.
 **Revised 2026-10-02** ([ADR 0167](../../02-DECISIONS/0167-a-membership-carries-what-its-module-receives-and-who-the-mesh-is.md)):
 a membership also carries **what its module receives**, by requirement — the contributions its
 received file is written from, from the same composition — and **who the mesh is**, every machine's
 address on the private network, the list the filter's "from the mesh" is rendered from. The route
 proxy is the first reader of both.
 **Revised 2026-09-27** ([ADR 0129](../../02-DECISIONS/0129-a-seat-carries-the-protocol-of-its-role.md)):
 **`mesh.build.request`, `mesh.control.built` and the BUILDS stream are gone.** A build is work submitted to a role, and the
 mesh already has a shape for that — a seat's `accept` subjects, on a work queue with a queue group of
@@ -1,8 +1,11 @@
 ---
 layer: to-be
-status: proposed
+status: in-progress
-code: []
+code:
-updated: 2026-09-27
+  - mesh-controller internal/inventory
  - mesh-controller internal/catalogue
  - mesh-controller cmd/mesh-controller
 updated: 2026-10-02
 decisions:
  - 02-DECISIONS/0112-a-module-definition-names-no-node-mesh-or-path.md
  - 02-DECISIONS/0120-a-roster-fact-carries-its-format-as-a-template.md
@@ -14,10 +17,10 @@ decisions:
 # 29 — A node has operator accounts, and the mesh owns what lives under a home
 **The mesh models machines but not the people on them.** A node record holds its name, its
-address, its mode — and nothing about *who a person is* on it: `jochens` on novox, `ace` on ace,
+address, its mode — and nothing about *who a person is* on it: one login name on the build node,
-`jochen` on shanks and g14. That username is not incidental. It decides who a file under `~` is
+another on the home-server, a third on both workstations. That username is not incidental. It
-owned by, who a user service runs as, and — the case that surfaced this — which account `ssh
+decides who a file under `~` is owned by, who a user service runs as, and — the case that surfaced
-<node>` logs in as. The predecessor knew it (its per-node `user:`, and the modules that wrote a
+this — which account `ssh <node>` logs in as. The predecessor knew it (its per-node `user:`, and the modules that wrote a
 person's `~/.ssh/config`, `~/.zshrc`, `~/.config`); the mesh, taking those over, kept the machine
 facts and dropped the human one.
@@ -28,8 +31,9 @@ Several things are missing, and they are one idea.
 A node has one or more **operator accounts**: the human logins on it. At minimum a name; the
 mesh already knows the node and its address, so `<account>@<node>` is then a complete answer to
 "who am I, where." It is the mesh's to hold because everything below is derived from it, and
-because it is exactly the fact that was silently lost — `ssh ace` failed to `ace` because nothing
+because it is exactly the fact that was silently lost — `ssh home-server` logged in under the
-in the mesh said ace's account is `ace`.
+workstation's own name, because nothing in the mesh said the home-server's account is a different
 one.
 ## 2. A resource may live under a home, owned by its account
@@ -65,14 +69,14 @@ create `~/.ssh` at `0700`, chown it to the account, and own the files it places
 **The boundary — and it is the reason this is safe:** `~/.ssh` is the one directory where a wrong
 declaration locks a person out of their own machine. So the mesh's *found-vs-owned* semantics
-([ADR 0126](../../02-DECISIONS/0118-undeclaring-gives-a-unit-back-the-state-it-was-found-in.md),
+([ADR 0118](../../02-DECISIONS/0118-undeclaring-gives-a-unit-back-the-state-it-was-found-in.md),
 adoption) apply *inside* the home directory. The mesh **owns** the directory and the files above; it
 **holds as found — never rewrites, never removes** — the operator's own contents: their **private
 keys** and their **personal drop-ins** (`config.d/personal`, the personal `Host` aliases a
 workstation carries, exactly as `hosts.local` is the home the mesh never rewrites for `/etc/hosts`).
 Reconcile removing an unassigned `config.d/mesh` is fine; the same logic aimed at `id_ed25519` or an
 operator's own `authorized_keys` entry is a lockout. This is the login-channel cousin of the rule
-[ADR 0125](../../02-DECISIONS/0117-a-machines-uplink-is-a-seat.md) draws for the uplink and the sshd
+[ADR 0117](../../02-DECISIONS/0117-a-machines-uplink-is-a-seat.md) draws for the uplink and the sshd
 module draws for the firewall: **the mesh must never be able to arrange the one failure that severs
 its own way back in.** The carve-out is not a convenience; it is that rule, in `~/.ssh`.
@@ -108,12 +112,12 @@ found-vs-owned boundary of §3 is exactly what guarantees nothing already there
 None of this needs a node to discover the mesh, and none of it needs a control-plane module of its
 own. The ssh files are **roster facts**
-([ADR 0128](../../02-DECISIONS/0120-a-roster-fact-carries-its-format-as-a-template.md)): once the
+([ADR 0120](../../02-DECISIONS/0120-a-roster-fact-carries-its-format-as-a-template.md)): once the
 roster view carries a node's **host key** and its **account** beside its name and address, the
 `ssh-client` module ships a template for `known_hosts`, `config` and `authorized_keys`, and the
 controller renders each node's copy from the full roster and pushes it. The mesh owns the data; the
 module owns ssh's format; the control plane gains no ssh syntax. It is the same act as composing a
-peer list or `/etc/hosts` — which is why there is **no novox-only "mesh-ssh" module**: the
+peer list or `/etc/hosts` — which is why there is **no control-node-only "mesh-ssh" module**: the
 centralization is the controller's composition, not a module that runs somewhere. Only non-secret
 facts travel (names, addresses, accounts, host keys, the CA public key); the private key stays the
 operator's, placed as an operator-owned file, referenced by path.
@@ -129,6 +133,44 @@ operator's, placed as an operator-owned file, referenced by path.
 They meet at the account and the CA, not at a bespoke module. The `sshd` server side already exists;
 the client/identity side and the CA are the open pieces.
 ## What has shipped, and what has not
 *Recorded 2026-10-01 from the controller's main branch, not from intent.*
 **Built (mesh-controller, merged 2026-09-27):**
 - **§1, the account as a node fact.** A node record carries an operator account and, optionally,
  its home. Empty is a real state — a freshly enrolled or headless machine has no operator account
  known yet — and an empty home means *derive it* (the superuser's home for the superuser, the
  conventional per-user home otherwise), so the common case needs no entry. The controller's node
  command sets it. One account per node is what exists; "one or several" below is still open.
 - **§2, resources under a home.** The account and its home are offered as machine facts, and a
  resource's *path and owner* resolve placeholders exactly as its content does — so a module places
  a file under a person's home, owned by that person, naming neither. A roster file may say it lives
  under the home: it is rendered per node, placed under that node's account's home, chowned to the
  account, and a node with no account gets none.
 - **§5, the composed ssh config.** The roster rendering carries each node's account, so the
  `ssh-client` template can emit a `Host` block per node with the right login name. Composed
  end-to-end in the controller's tests.
 **Written but not shipped:** the `ssh-client` catalogue module itself exists on a branch of the
 module repository; its pull request was closed with a hold until this design is deployed, and
 nothing has deployed it since. The predecessor's generator still writes every workstation's ssh
 client blocks today — which is where [issue 172](../../04-ISSUES/172-the-ssh-client-block-matches-one-spelling-of-a-machine/00-report.md)
 was found.
 **Not built:** the SSH CA and certificates (§4), `known_hosts` and `authorized_keys` as roster files,
 the found-vs-owned boundary inside `~/.ssh` (§3 — the controller has no rule yet that refuses to
 rewrite a private key), adoption of existing keys, the ssh-agent as a user service, and user-scoped
 services in general. The host vocabulary still has no user-scope unit at all; a workstation's
 per-user daemons (a bar watchdog, a config reloader, an audio service masked per user) have no form
 the mesh can send.
 **A gap this surfaced:** §1 shipped as code before it had a decision record. The account as a node
 fact, the home as a placement root, and what the mesh may and may not do under a home are each a
 decision this document names but no record states. They are the next records to write, before the
 family of §2 modules is built.
 ## Why now, and why not yet
 **Why it matters:** when HAL retires, the generators that keep `~/.ssh`, shell config and the
@@ -137,7 +179,7 @@ alias and its trust, and a fresh machine has no operator dotfiles at all — the
 service and leave the human unable to work on the box.
 **Why not build it reflexively:** it is a real addition to the node model, the resource model, and
-the seat set, and must be gotten right. The mechanism half is now settled — ADR 0128 is what lets
+the seat set, and must be gotten right. The mechanism half is now settled — ADR 0120 is what lets
 the ssh files be templates with no control-plane format — so what remains to decide here is the
 model:
@@ -156,15 +198,22 @@ model:
  unnecessary, and forwarding an agent into a node exposes the operator's keys to that node's root —
  so prefer certificates and `ProxyJump` over forwarding.
-**Not urgent, not blocking.** ssh and dotfiles work today because HAL's generators still run as the
+**Now load-bearing.** The migration of every node to the mesh is complete; what remains of the
-substrate. This becomes load-bearing in the node-by-node retirement phase, not before — which is the
+predecessor is exactly the user environment this design covers — ssh config, dotfiles, the desktop
-right time to build it, once the account and CA model are decided here.
+stack and the per-user services of the two workstations. Those generators are the last thing
 keeping the predecessor running, so the model questions above are no longer deferred: the account
 record, the home as a placement root, user-scoped services and the one-off steps a hook used to run
 each need a decision before the modules that replace the generators can be written.
 ## The family beyond `~/.ssh` — 2026-10-02
 The modules §2 calls *a family* — the shell, the terminal, the desktop, everything under a home that is not `~/.ssh` — are designed in [37 — The operator's machine](37-the-operators-machine.md), under [ADR 0173](../../02-DECISIONS/0173-the-operators-machine-is-the-meshs-and-a-module-is-what-it-declares.md) to [0177](../../02-DECISIONS/0177-a-unit-may-be-user-scoped-and-the-service-manager-is-a-node-seat.md). This document keeps `~/.ssh`, the CA and the roster files. Two things it listed as not built are decided there: user-scoped services (ADR 0177) and the one-off steps a hook used to run (declared state, or a seat's verb).
 ## References
 - The gap was found generating `~/.ssh/config` from the *HAL* registry (`hal/terminal`'s
  postConfigure hook), which the nox mesh has no equivalent for.
- [ADR 0128](../../02-DECISIONS/0120-a-roster-fact-carries-its-format-as-a-template.md) — the roster
+- [ADR 0120](../../02-DECISIONS/0120-a-roster-fact-carries-its-format-as-a-template.md) — the roster
  fact mechanism that renders the ssh files, format owned by the module.
 - [ADR 0112](../../02-DECISIONS/0112-a-module-definition-names-no-node-mesh-or-path.md) — the
  system-path placement this mirrors for home paths.
@@ -173,6 +222,6 @@ right time to build it, once the account and CA model are decided here.
 - [ADR 0113](../../02-DECISIONS/0113-the-vault-makes-every-secret.md) — the CA key is a secret the
  vault makes; [ADR 0114](../../02-DECISIONS/0114-a-shared-credential-rotates-over-two-credentials.md)
  — short-lived certs as rotation.
- [ADR 0125](../../02-DECISIONS/0117-a-machines-uplink-is-a-seat.md),
+- [ADR 0117](../../02-DECISIONS/0117-a-machines-uplink-is-a-seat.md),
-  [ADR 0126](../../02-DECISIONS/0118-undeclaring-gives-a-unit-back-the-state-it-was-found-in.md) —
+  [ADR 0118](../../02-DECISIONS/0118-undeclaring-gives-a-unit-back-the-state-it-was-found-in.md) —
  the never-sever-the-channel rule and the found-vs-owned semantics, applied here to `~/.ssh`.
@@ -2,8 +2,9 @@
 layer: to-be
 status: implemented
 code: [mesh-controller, mesh-tools]
-updated: 2026-10-01
+updated: 2026-10-02
 decisions:
  - 02-DECISIONS/0170-the-firewall-seat-serves-its-verbs.md
  - 02-DECISIONS/0160-the-mesh-issues-an-assignments-subjects-and-a-runtime-serves-what-it-is-issued.md
  - 02-DECISIONS/0159-a-tool-call-names-the-machine-and-a-holder-serves-its-seats-verbs.md
  - 02-DECISIONS/0154-the-meshs-own-verbs-are-the-controller-seats-tools.md
@@ -121,6 +122,8 @@ module-specific names that changes the day the forge is replaced.
 asked of the module, through a `tools` verb every runtime answers) and lists a role's tools when the
 records carry them.
 *Amended 2026-10-02 by [ADR 0175](../../02-DECISIONS/0175-one-tool-runtime-per-node-serves-every-modules-tools-on-the-host-side.md):* the module that serves this to an agent is the node tools runtime — one per node, host-side, serving every assigned module's tools as well as answering the person on loopback. The console is its serving mode, renamed. See [37 — The operator's machine](37-the-operators-machine.md) §3.
 ## 7. Versioning
 A seat's tools are an interface and change like one. Additive within a version. A change that would
@@ -169,6 +172,18 @@ either way.
 What stays as designed and not built: which verbs any *other* seat serves, and §3 for module-declared
 seats' schemas beyond the names their manifests already list.
 ## The firewall seat's verbs, 2026-10-02
 [ADR 0170](../../02-DECISIONS/0170-the-firewall-seat-serves-its-verbs.md). The first node-scoped seat
 to carry verbs: `node-packet-filter` serves `rules` (the filter as the machine enforces it, nftables
 and legacy), `reload` (the mesh's own filter from its file) and `remove` (one rule set the mesh did
 not write, named as the host reports it under ADR 0168; refusing the mesh's tables, the runtime's
 own chains, a built-in chain and an active found firewall's). Every holder serves all three; the
 nftables module does so from a runtime on the machine's network with `NET_ADMIN`, which is the first
 container to declare a capability. Removing a predecessor's rule set is an operator's act reached
 through the seat, recorded on the bus, instead of a shell on the machine. *How it is checked:* ADR
 0169's table.
 ## What this does not settle
 - Which verbs each seat should serve. That is a decision per seat, and the reason to do it slowly: a
@@ -2,7 +2,7 @@
 layer: to-be
 status: implemented
 code: [mesh-catalog, mesh-tools, mesh-controller]
-updated: 2026-10-01
+updated: 2026-10-02
 decisions:
  - 02-DECISIONS/0160-the-mesh-issues-an-assignments-subjects-and-a-runtime-serves-what-it-is-issued.md
  - 02-DECISIONS/0159-a-tool-call-names-the-machine-and-a-holder-serves-its-seats-verbs.md
@@ -20,6 +20,8 @@ An agent reaches them over MCP on the machine's loopback; a person reaches the s
 installed by hand, nothing is configured with an address, and the mesh knows the surface exists because
 it put it there ([ADR 0152](../../02-DECISIONS/0152-the-operators-surface-is-a-module-the-console.md)).
 > **Amended 2026-10-02 by [ADR 0175](../../02-DECISIONS/0175-one-tool-runtime-per-node-serves-every-modules-tools-on-the-host-side.md).** What this document describes stays true in substance and changes in form: the console becomes the serving mode of the node tools runtime, a host-side process the host supervises rather than a container, which also serves every assigned module's tools from their bundles. The module is renamed `node-tools`. [37 — The operator's machine](37-the-operators-machine.md) §3 is where it now lives.
 ## 1. What it is
 A module, `mesh-console`, in the catalogue. Its image is the tool runtime's own — the client that
@@ -0,0 +1,142 @@
 ---
 layer: to-be
 status: in-progress
 code: [mesh-host, mesh-controller, mesh-tools, mesh-catalog]
 updated: 2026-10-02
 decisions:
  - 02-DECISIONS/0173-the-operators-machine-is-the-meshs-and-a-module-is-what-it-declares.md
  - 02-DECISIONS/0174-a-node-varies-a-module-through-settings-and-kept-regions-never-an-edit.md
  - 02-DECISIONS/0175-one-tool-runtime-per-node-serves-every-modules-tools-on-the-host-side.md
  - 02-DECISIONS/0176-the-login-shell-is-a-node-seat-and-execute-is-its-contract.md
  - 02-DECISIONS/0177-a-unit-may-be-user-scoped-and-the-service-manager-is-a-node-seat.md
  - 02-DECISIONS/0040-what-a-module-is.md
  - 02-DECISIONS/0112-a-module-definition-names-no-node-mesh-or-path.md
  - 02-DECISIONS/0126-a-module-declares-its-own-seats.md
  - 02-DECISIONS/0132-a-seat-carries-the-tools-its-holder-must-serve.md
  - 02-DECISIONS/0161-what-deserves-a-seat.md
  - 02-DECISIONS/0102-the-mesh-writes-into-a-shared-file-never-over-it.md
 ---
 # 37 — The operator's machine
 **Every configurable thing on a node is a module, the home included, and the same catalogue serves
 a server and a laptop.** One default configuration per module, varied per node by a setting or a
 kept region; roles a machine has once as node-scoped seats with tool contracts; one tool runtime
 per node serving every module's tools on the host side
 ([ADR 0173](../../02-DECISIONS/0173-the-operators-machine-is-the-meshs-and-a-module-is-what-it-declares.md)
 to [0177](../../02-DECISIONS/0177-a-unit-may-be-user-scoped-and-the-service-manager-is-a-node-seat.md)).
 This is the design [to-be 29](29-a-node-has-operator-accounts.md) §2 called *a family* and
 [research 018](../../01-RESEARCH/018-the-operators-machine-as-modules/00-overview.md) measured.
 ## 1. What a module of the environment looks like
 Worked on the first one, a shell. The `zsh` module declares:
 - a **package**, `zsh`;
 - **files under the home**, owned by the account: the shell's rc file with the module's default
  configuration, carrying a kept region for the operator's own lines, and `${setting:…}`
  placeholders for the few values a node varies; the account and its home are machine facts the
  controller resolves ([ADR 0112](../../02-DECISIONS/0112-a-module-definition-names-no-node-mesh-or-path.md),
  to-be 29 §2);
 - a **seat declaration**, `login-shell`, node-scoped, with its one verb; and a **claim** on it;
 - a **`user` shape** naming the shell, applied only where the module holds the seat;
 - a **tools bundle**, the artifact kind for interpreted code, with `execute` and the module's own
  `show-config`.
 No container, no unit, no service. It is assigned to every node with an operator account. The
 `fish` and `bash` modules are the same with another package and other files; one of the three
 holds the seat on each node.
 The second shape is **system scope**: the login manager declares a package, two files under
 `/etc`, and a service, which is exactly what the ssh daemon module declares today. The third
 shape is **graphical**: the window manager declares a package, files under the home, a
 user-scoped unit or two, a claim on the display-session seat, a dependency on the display server
 being held, and a bundle with its tools. Nothing in any of them says which machine it is for.
 ## 2. Variation
 A node differs from the default in two ways and no other
 ([ADR 0174](../../02-DECISIONS/0174-a-node-varies-a-module-through-settings-and-kept-regions-never-an-edit.md)):
 a **setting** the module declared, set in the node's layer and rendered into the file; or lines in
 a **kept region** the file marks. The predecessor's ninety theme variables become the settings of
 the modules whose files read them. Until the settings record proposed alongside the
 container-runtime records ships — a setting names the file it lands in — environment modules carry
 defaults in their files and declare no setting; that is the order, not a preference.
 ## 3. The node tools runtime
 One per node, started and restarted by the host as a sibling process, never a container
 ([ADR 0175](../../02-DECISIONS/0175-one-tool-runtime-per-node-serves-every-modules-tools-on-the-host-side.md)).
 It is the tool runtime that exists, in the role it was written for: it reads the memberships of
 every module assigned to the node, loads each module's tools bundle, and serves every tool and
 every held seat's verb on the subjects issued. It holds the node's one bus credential and may call
 every tool on the mesh. Its serving mode on the machine's loopback is what the console was
 ([to-be 34](34-the-console.md)); the module is renamed **node-tools** and declares the interpreter
 it needs as a package.
 A bundle reaches the node as any artifact does. A push that adds or replaces one is a reload. A
 bundle that fails to load is named in the node's report and the others serve. A tool that needs
 root escalates itself.
 ## 4. The seats of the environment
 Decided now: **`login-shell`** (module-declared; zsh, fish, bash; verb `execute`) and
 **`node-service-manager`** (the mesh's own; systemd; verbs over units in both scopes). The rest
 are candidates from [research 018](../../01-RESEARCH/018-the-operators-machine-as-modules/04-the-seats-of-the-environment.md),
 one record each when its first holder is written: display server, display session, terminal
 emulator, launcher, notifier, compositor, lock screen, bar, login manager, audio, clipboard, boot.
 Editors, browsers, media players, the agent, the downloads and scripts folders are modules with
 tools and no seat.
 A module that needs a role filled depends on **the seat being held** on the node, not on a
 capability: the window manager needs the display server seat held, by xorg or by a compositor
 that is its own server. Whether a held seat can gate an assignment is the first question the
 resolver is asked by the second graphical module; the display server itself is gated by the
 `graphical-session` capability the profile already reports.
 ## 5. What the host gains, and what it does not
 - `service` gains `scope: user`, applied as the account
  ([ADR 0177](../../02-DECISIONS/0177-a-unit-may-be-user-scoped-and-the-service-manager-is-a-node-seat.md)).
 - The host starts and supervises the node tools runtime as it would any host-side process, and
  delivers bundles as artifacts.
 - Nothing else. No hooks, no actions: `chsh` is the `user` shape, enabling a unit is the `service`
  shape, rebuilding boot images is a verb of the boot seat when that seat is written.
 - A gap, recorded: the `package` shape drives the distribution's package manager and nothing
  outside its repositories. The login manager in use is such a package; it waits on an official
  package or a decision the host does not yet have.
 ## 6. The order of the build
 1. **The operator account on every node** — `mesh-controller node` with the login name; empty on
   all four today. Nothing home-scoped composes before it.
 2. **The node tools runtime** — mesh-host supervises it; mesh-tools serves bundles from memberships
   and reloads; mesh-controller composes the bundle into the declaration and the memberships to one
   runtime per node; the catalogue renames the console. Proven when the packet-filter verbs answer
   from it and its container is gone.
 3. **`zsh`**, the first environment module: seat, `user` shape, home files, `execute`. Proven on a
   server first, then every node.
 4. **`systemd`** and user scope: the host's field, the seat seeded, the module. Proven by the
   desktop's reload watcher declared `scope: user` on a workstation.
 5. **The login manager**, system scope, once its package is installable; then the display server,
   the window manager, and the rest of the graphical stack, each seat its own record.
 6. **Settings** for the theme knobs, after the settings record ships and issue 168 closes.
 ## How it is checked
 | Claim | Checked by |
 |---|---|
 | A module with a package, home files, a seat and a bundle resolves and composes on a node with an account, and is refused on one without | the controller's composition tests |
 | One runtime per node serves every assigned module's tools; a per-module tool container no longer exists | the runtime's tests; `docker ps` on a converged machine |
 | A user-scoped unit is applied as the account | the host's tests |
 | A node's difference from a module's default is visible as a setting with a source or a kept region | `mesh-controller.settings`; the host's write-into tests |
 | The same manifests assign to a server and a workstation; the graphical ones are refused on the server by name | the resolver's tests and the live mesh |
 ## References
 - [Research 018](../../01-RESEARCH/018-the-operators-machine-as-modules/00-overview.md)
 - [To-be 29](29-a-node-has-operator-accounts.md) — the account and the home; this design is the
  family its §2 names, beyond `~/.ssh`.
 - [To-be 33](33-the-tools-the-mesh-answers.md), [to-be 34](34-the-console.md) — the tools and
  the console, amended by ADR 0175.
 - [To-be 05](05-the-node-host.md) — the host's vocabulary, widened by ADR 0177.
@@ -38,9 +38,10 @@ document is written and this one's status becomes `implemented`.
 | [`26-the-seats.md`](26-the-seats.md) | **Proposed.** What a mesh can have one of, who fills each, and a seat's holder answering for the provision it delivers — including the `git` seat a build's source can live on | [ADR 0126](../../02-DECISIONS/0126-a-module-declares-its-own-seats.md) (superseding [ADR 0110](../../02-DECISIONS/0110-a-seat-is-a-module-assignment-from-a-closed-set.md)), [ADR 0111](../../02-DECISIONS/0111-a-build-source-is-on-the-git-seat-or-external.md), [ADR 0109](../../02-DECISIONS/0109-a-package-registry-seat-is-one-per-ecosystem.md) |
 | [`27-a-module-requires-the-mesh-resolves.md`](27-a-module-requires-the-mesh-resolves.md) | **Proposed.** One concept for everything a module needs: a requirement with a contract, answered by one of four kinds of provider, resolved at assignment or refused. Retires settings, placeholders, facts and paths in definitions | [ADR 0112](../../02-DECISIONS/0112-a-module-definition-names-no-node-mesh-or-path.md), [ADR 0113](../../02-DECISIONS/0113-the-vault-makes-every-secret.md), [ADR 0114](../../02-DECISIONS/0114-a-shared-credential-rotates-over-two-credentials.md), [ADR 0126](../../02-DECISIONS/0126-a-module-declares-its-own-seats.md) (superseding [ADR 0110](../../02-DECISIONS/0110-a-seat-is-a-module-assignment-from-a-closed-set.md)) |
 | [`28-building-the-bus.md`](28-building-the-bus.md) | **Proposed.** The five steps of the bus work in the order their dependencies allow, each ending at a bed — with the surface measured, so no step's size is a guess | [ADR 0116](../../02-DECISIONS/0116-the-bus-is-built-in-five-steps.md), [ADR 0106](../../02-DECISIONS/0106-the-bus-is-nats.md), [ADR 0074](../../02-DECISIONS/0074-the-wire-is-specified-not-the-types.md) |
-| [`29-a-node-has-operator-accounts.md`](29-a-node-has-operator-accounts.md) | **Proposed.** The mesh models machines but not the humans on them: a node gains operator accounts, and a resource may live under a home owned by its account — what would own ~/.ssh, dotfiles and ~/.config when HAL retires | [ADR 0112](../../02-DECISIONS/0112-a-module-definition-names-no-node-mesh-or-path.md), [ADR 0051](../../02-DECISIONS/0051-shared-data-is-the-operators.md) |
+| [`29-a-node-has-operator-accounts.md`](29-a-node-has-operator-accounts.md) | **In progress.** A node has an operator account and a resource may live under its home — built in the controller; the ssh-client module, the SSH CA, the `~/.ssh` boundary and user-scoped services are not. The account fact still wants its decision record | [ADR 0112](../../02-DECISIONS/0112-a-module-definition-names-no-node-mesh-or-path.md), [ADR 0051](../../02-DECISIONS/0051-shared-data-is-the-operators.md) |
 | [`32-what-a-module-declares.md`](32-what-a-module-declares.md) | **Proposed.** What a module declares and what the bus derives from it: three namespaces, subjects from local names, queues never declared, the five relationships, and the build-publish-deploy lifecycle on one bus | [ADR 0126](../../02-DECISIONS/0126-a-module-declares-its-own-seats.md), [ADR 0127](../../02-DECISIONS/0127-amqp-is-a-provision-not-the-bus.md), superseded by [ADR 0131](../../02-DECISIONS/0131-everything-on-the-mesh-speaks-to-the-broker-seat.md) (superseding [ADR 0125](../../02-DECISIONS/0125-the-bus-is-the-only-broker.md)), [ADR 0041](../../02-DECISIONS/0041-events-are-a-relationship.md) |
 | [`37-the-operators-machine.md`](37-the-operators-machine.md) | **In progress.** Every configurable thing on a node is a module, the home included; one default per module varied by settings or kept regions; roles a machine has once as seats with tool contracts; one tool runtime per node on the host side | [ADR 0173](../../02-DECISIONS/0173-the-operators-machine-is-the-meshs-and-a-module-is-what-it-declares.md), [0174](../../02-DECISIONS/0174-a-node-varies-a-module-through-settings-and-kept-regions-never-an-edit.md), [0175](../../02-DECISIONS/0175-one-tool-runtime-per-node-serves-every-modules-tools-on-the-host-side.md), [0176](../../02-DECISIONS/0176-the-login-shell-is-a-node-seat-and-execute-is-its-contract.md), [0177](../../02-DECISIONS/0177-a-unit-may-be-user-scoped-and-the-service-manager-is-a-node-seat.md) |
 ## Not yet written
@@ -1,8 +1,8 @@
 ---
-status: located
+status: resolved
 opened: 2026-09-22
 located-in: [mesh-controller internal/overlay, mesh-host internal/apply]
-fixed-by:
+fixed-by: ADR 0102 (mesh-controller internal/overlay: the runtime file written into, reloaded), issue 128 (the hosts file as a region)
 amended-design: 03-DESIGN/01-to-be/05-the-node-host.md
 ---
@@ -56,3 +56,12 @@ and nothing checks for it today.
 - Should an adopted node that cannot trust the registry be refused a module that needs to pull?
  Or should the refusal come earlier, when the node joins?
 ## Resolved, 2026-10-02
 The runtime's file is written into and the runtime reloaded, never restarted
 ([ADR 0102](../../02-DECISIONS/0102-the-mesh-writes-into-a-shared-file-never-over-it.md), the
 diagnosis above); the hosts file is a marked region the mesh owns alone
 ([issue 128](../128-the-hosts-file-is-written-whole/00-report.md)). Neither whole file remains. Read
 into [ADR 0168](../../02-DECISIONS/0168-a-converged-machine-is-filtered-by-the-mesh-alone.md), rule 5,
 which names the one whole machine-wide file the mesh still writes — its own filter at the
 distribution's path — as a difference a take shows, not a fault.
@@ -1,8 +1,8 @@
 ---
-status: located
+status: resolved
 opened: 2026-09-22
 located-in: [mesh-controller cmd/mesh-controller/adoption.go (take previews nothing), mesh-host internal/apply (the comparison and the record)]
-fixed-by:
+fixed-by: mesh-controller 201 (the preview names the narrowing and the port's reach), 206 (`take --yes <digest>` acts on the preview read)
 amended-design:
 ---
@@ -46,3 +46,7 @@ host first, then the controller's `take`.
 mesh-controller 201 and the pull request after it: the preview names it, and `take --yes <digest>`
 acts on the preview that was read. Stays located until a take is read on an adopted machine — every
 machine of this mesh is converged today, so the record's live row has not been run.
 ## Resolved, 2026-10-02
 Closed on the operator's decision of 2026-10-02 with the built and tested code live on every machine (mesh-controller 206, mesh-host 64), not on a take read on an adopted machine: every machine of this mesh is converged, so none holds a found thing to compare, and the record's live row — ADR 0163's last — will be read at the next real adoption rather than staged. Said here so nobody later believes that row was run.
@@ -1,8 +1,8 @@
 ---
-status: located
+status: resolved
 opened: 2026-09-22
 located-in: [mesh-controller cmd/mesh-controller/adoption.go (take previews nothing), mesh-host internal/apply (the comparison and the record)]
-fixed-by:
+fixed-by: mesh-host 64 (genesis raises the forge as `gitea`, on the module's image digest, with the module's data directory at /data; a test holds the installer to the module's manifest)
 amended-design:
 ---
@@ -63,3 +63,7 @@ to the module's manifest where the catalogue is checked out beside it. The netwo
 left: the bootstrap forge runs on the machine's network to reach the store on its loopback, the module
 runs bridged and publishes its ports, and the take says so. Closing waits for group 9's genesis test —
 a mesh raised, the module assigned, and the module found holding rather than raising a second forge.
 ## Resolved, 2026-10-02
 Closed on the operator's decision of 2026-10-02. Name, image and data directory align; the network does not — the bootstrap forge runs on the machine's network to reach the store on its loopback, the module runs bridged — and a take says so rather than hides it. Whether genesis should move the forge onto a bridge, and the test that raises a mesh and finds the module holding rather than raising a second forge, belong to group 9's genesis work and are not owed by this record any more.
@@ -1,8 +1,8 @@
 ---
-status: located
+status: resolved
 opened: 2026-09-23
 located-in: [mesh-controller cmd/mesh-controller/adoption.go (take previews nothing), mesh-host internal/apply (the comparison and the record)]
-fixed-by:
+fixed-by: mesh-host 63 (the kept original's difference), mesh-controller 201 (shown; a differing file refuses unless `--replace <path>`)
 amended-design:
 ---
@@ -74,3 +74,7 @@ host first, then the controller's `take`.
 mesh-host 63 reports the difference between the kept original and the declared content; mesh-controller
 201 shows it in the preview and refuses a differing file unless `--replace <path>` names it, or the
 module declares the file partially. Stays located until a take is read on an adopted machine.
 ## Resolved, 2026-10-02
 Closed on the operator's decision of 2026-10-02 with the built and tested code live on every machine (mesh-controller 206, mesh-host 64), not on a take read on an adopted machine: every machine of this mesh is converged, so none holds a found thing to compare, and the record's live row — ADR 0163's last — will be read at the next real adoption rather than staged. Said here so nobody later believes that row was run.
@@ -1,8 +1,8 @@
 ---
-status: located
+status: resolved
 opened: 2026-09-23
 located-in: [mesh-controller cmd/mesh-controller/adoption.go (take previews nothing), mesh-host internal/apply (the comparison and the record)]
-fixed-by:
+fixed-by: mesh-host 63 (both images' creation dates), mesh-controller 201 (DOWNGRADE said; refused unless `--downgrade`)
 amended-design:
 ---
@@ -71,3 +71,7 @@ host first, then the controller's `take`.
 mesh-host 63 reports the found image and both images' creation dates; mesh-controller 201 says
 DOWNGRADE and refuses unless `--downgrade` is said. Stays located until a take is read on an adopted
 machine.
 ## Resolved, 2026-10-02
 Closed on the operator's decision of 2026-10-02 with the built and tested code live on every machine (mesh-controller 206, mesh-host 64), not on a take read on an adopted machine: every machine of this mesh is converged, so none holds a found thing to compare, and the record's live row — ADR 0163's last — will be read at the next real adoption rather than staged. Said here so nobody later believes that row was run.
@@ -1,8 +1,8 @@
 ---
-status: located
+status: resolved
 opened: 2026-09-23
 located-in: [mesh-controller cmd/mesh-controller/adoption.go (take previews nothing), mesh-host internal/apply (the comparison and the record)]
-fixed-by:
+fixed-by: mesh-controller 201 (`secret accept --provider` reaches a required secret), 206 (a module's secrets listed with origin; a minted one for found data refuses unless `--mint <name>`)
 amended-design:
 ---
@@ -78,3 +78,7 @@ The pull request after it reads every secret a module holds on a machine with it
 of a module whose data was found refuses a minted, unaccepted one — naming the accept that carries
 the existing value in, or `--mint <name>` to let the service take the new one. Stays located until
 a take is read on an adopted machine.
 ## Resolved, 2026-10-02
 Closed on the operator's decision of 2026-10-02 with the built and tested code live on every machine (mesh-controller 206, mesh-host 64), not on a take read on an adopted machine: every machine of this mesh is converged, so none holds a found thing to compare, and the record's live row — ADR 0163's last — will be read at the next real adoption rather than staged. Said here so nobody later believes that row was run.
@@ -1,8 +1,8 @@
 ---
-status: located
+status: resolved
 opened: 2026-09-23
 located-in: [mesh-controller cmd/mesh-controller/adoption.go (take previews nothing), mesh-host internal/apply (the comparison and the record)]
-fixed-by:
+fixed-by: mesh-controller 201 (the neighbours on a found network are named), 206 (the per-machine `networks` setting), mesh-host 64 (the taken container joins the kept network)
 amended-design:
 ---
@@ -73,3 +73,7 @@ The preview names every neighbour on a found network (mesh-controller 201). The
 adds the per-machine setting `networks` — a container id to the found networks it keeps — judged for an
 adopted machine only, and mesh-host 64 has the taken container join each once it runs. Stays located
 until a take is read on an adopted machine.
 ## Resolved, 2026-10-02
 Closed on the operator's decision of 2026-10-02 with the built and tested code live on every machine (mesh-controller 206, mesh-host 64), not on a take read on an adopted machine: every machine of this mesh is converged, so none holds a found thing to compare, and the record's live row — ADR 0163's last — will be read at the next real adoption rather than staged. Said here so nobody later believes that row was run.
@@ -1,10 +1,10 @@
 ---
-status: located
+status: resolved
 opened: 2026-09-28
 located-in:
  - mesh-controller internal/catalogue/filtering.go
  - mesh-host internal/apply
-fixed-by:
+fixed-by: ADR 0140 — mesh-controller (the filter around outward links; no network ranges anywhere)
 amended-design: 03-DESIGN/01-to-be/08-connectivity.md
 ---
@@ -86,3 +86,11 @@ supersedes both 0137 and the first attempt at answering this.
  runtime, or left as the one constant?
 - Should the preview say which of a machine's networks are the mesh's and which are not, so a range
  that exists to protect a leftover is visible as such?
 ## Resolved, 2026-10-02
 By [ADR 0140](../../02-DECISIONS/0140-the-filter-constrains-what-arrives-from-outside.md), built and
 live since 2026-09-29: the forward chain constrains what arrives on the machine's outward links and
 says nothing about networks, so there is no list to derive and nothing for a preview to tell apart.
 Read into [ADR 0168](../../02-DECISIONS/0168-a-converged-machine-is-filtered-by-the-mesh-alone.md),
 rule 5, which closes it.
@@ -1,10 +1,10 @@
 ---
-status: located
+status: resolved
 opened: 2026-09-29
 located-in:
  - mesh-host internal/apply/opening.go (retireFirewall)
  - mesh-host internal/apply/apply.go (the condition it is called under)
-fixed-by:
+fixed-by: mesh-host 67 (retire on every converged apply; found-inactive apart from disabled-by-mesh; a skipped step said), mesh-controller 211 (the found firewall's state on node show)
 amended-design:
 ---
@@ -100,3 +100,21 @@ harmless, but the mesh's belief about which firewall is in force has been wrong
  so". Should it?
 - Why do the host's own detail lines not reach the journal? Everything it decided during the flip is
  unrecoverable, which is why this account has candidates instead of a cause.
 ## Decided, 2026-10-02
 [ADR 0168](../../02-DECISIONS/0168-a-converged-machine-is-filtered-by-the-mesh-alone.md), rule 1:
 convergence is a state the host keeps — the found firewall active again is retired again and said, a
 reconcile that finds it inactive records *found so* and never *done by the mesh*, and a step skipped
 after a failed apply is said. Built in mesh-host on `feat/one-thing-filters-a-converged-machine`; the
 record of both machines of this mesh is corrected by the first report under it.
 ## Resolved, 2026-10-02
 mesh-host 67 and mesh-controller 211, live on every machine at 10:10Z. The step now runs on every
 converged apply and says what it did; a found firewall enabled again is retired again. The record's
 one inherited lie stands as history: on the control node the machine's own record already said the
 mesh had disabled the firewall, and the host trusts its record, so `node show` says "retired by the
 mesh" there. From this build on, a reconcile that finds the firewall inactive records *found inactive*
 and never the other thing. Whether the flip's step took on 2026-09-29 is not recoverable and is not
 owed by this record any more.
@@ -1,10 +1,10 @@
 ---
-status: located
+status: resolved
 opened: 2026-09-29
 located-in:
  - mesh-host internal/apply/opening.go
  - mesh-controller cmd/mesh-controller (the converge preview)
-fixed-by:
+fixed-by: mesh-host 67 (every refusing table and legacy chain classified with an owner; the runtime's user chain is other), mesh-controller 211 (kept, shown on node show, named by status, previewed with fates)
 amended-design:
 ---
@@ -82,3 +82,24 @@ everything reached from within.
 - Is the bus and the registry being reachable from anywhere still what the mesh wants on a machine that
  faces the internet? The design says yes, for enrolment. It deserves asking on its own rather than
  being answered by a leftover.
 ## Decided, 2026-10-02
 [ADR 0168](../../02-DECISIONS/0168-a-converged-machine-is-filtered-by-the-mesh-alone.md), rules 2 and
 3: the host reports every table and legacy chain that refuses, with an owner, and the runtime's user
 chain's refusals as *other*; `node show`, `status` and the converge preview say it. Built on
 `feat/one-thing-filters-a-converged-machine` in mesh-host and mesh-controller. On 2026-10-02 the home
 server still carries the predecessor's chain in its legacy filter; the record's live row is reading it
 there.
 ## Resolved, 2026-10-02
 mesh-host 67 and mesh-controller 211, live at 10:10Z. The live row of
 [ADR 0168](../../02-DECISIONS/0168-a-converged-machine-is-filtered-by-the-mesh-alone.md) was read the
 same hour: the home server's record names the predecessor's chain in the legacy filter's user chain
 as *other*, with what it refuses, beside two chains a retired front end left in the IPv6 legacy filter;
 the control node's record names the same two leftovers; the laptop and the workstation read *the mesh
 alone*. `status` names both machines and is not well until the operator removes what the mesh did not
 write. The allowance the predecessor's chain carried is
 [issue 145](../145-a-machine-reads-healthy-while-its-modules-cannot-reach-each-other/00-report.md)'s,
 and that record is not closed by this one.
@@ -0,0 +1,80 @@
 ---
 status: resolved
 opened: 2026-10-01
 located-in: [mesh-controller examples/route-proxy/main.go (routesFrom requires a route's public `name` and treats `internal-name` only as an alias of it; the handler serves every routed name to any source), mesh-controller internal/broker/membership.go (a membership says nothing of what its module receives or who the mesh is)]
 fixed-by: mesh-controller PR 207 (the membership carries what a module receives and who the mesh is; the proxy follows it and serves internal names to the mesh only), mesh-catalog PR 211 (the proxy's bus account), mesh-controller PR 208 (the issue verb that delivers it), live 2026-10-02
 amended-design: [03-DESIGN/01-to-be/08-connectivity.md, 03-DESIGN/01-to-be/25-the-bus-on-nats.md]
 ---
 # 191 — A route with only an internal name is dropped as naming nothing
 ## What was observed
 A module whose endpoint reaches only the private network could not be reached by its internal name.
 The module ran and answered on its own port. Its route's internal name resolved to the serving node.
 The request failed during the TLS handshake:
 ```
 http: TLS handshake error from …: no public route for "unifi.home-server.internal" in this mesh,
  so no certificate is asked for
 ```
 The proxy's own log said why, every time it re-read its routes:
 ```
 unifi on home-server asked for a route and named nothing; skipped
 ```
 The route it skipped was not empty. The mesh had given it an endpoint, a port, a scheme and an internal
 name, and no public name:
 | route | `name` | `internal-name` | served |
 |---|---|---|---|
 | home-assistant | a public name | `home-assistant.home-server.internal` | under both |
 | unifi | — | `unifi.home-server.internal` | under neither |
 Three other modules on the same node were skipped with the same line on the same pass.
 ## Why it matters
 **Reach is decided in one place, and the proxy reads the old shape of the decision.**
 [ADR 0138](../../02-DECISIONS/0138-an-assignment-binds-an-endpoint-and-says-how-far-it-reaches.md)
 made an endpoint's reach decide which names exist. The controller composes the public name, the
 internal name, or both, and composes no name that nobody asked for
 ([issue 140](../140-an-endpoints-reach-is-not-declared/01-resolution.md)). An endpoint that reaches
 only the private network is the ordinary case for anything that should not face the internet. It is
 exactly the case the proxy drops.
 **The failure is quiet and points the wrong way.** Nothing marks the module unhealthy. The handshake
 error says *no public route*, which reads as a certificate fault on the reader's side. The line that
 gives the real cause is one of four identical lines repeated every few seconds in a log nobody reads
 until they already suspect the proxy.
 **The opposite move is not a workaround.** Giving the endpoint public reach makes the proxy serve it.
 It also publishes an administration interface to the internet to get a name on the private network.
 ## Open questions
 - Should the proxy refuse a route it cannot serve in a way the controller or an operator sees, not
  only in its own log? The same silent skip covers a route with no usable port or an unknown scheme.
 - What checks that what the controller composes and what the proxy serves stay the same shape? ADR
  0138 changed one side and nothing failed on the other.
 ## Resolved (2026-10-02)
 Built as [ADR 0167](../../02-DECISIONS/0167-a-membership-carries-what-its-module-receives-and-who-the-mesh-is.md)
 decided, and live on both machines that run the proxy. Each logs that its routes now come from its
 membership, and serves internal names to the four machines the mesh names. Checked by hand:
 - the internal-only route answers through the proxy from the serving machine and from two other
  machines of the mesh, over a certificate from the mesh's own authority that each verifies;
 - the same name asked from an address outside the mesh is answered as a name never routed, over plain
  HTTP, and refused in the TLS handshake; the list of served names it is shown leaves out every internal
  name.
 Two things the rollout found are their own records: the proxy's bus account could be issued only from
 the controller's command line, until mesh-controller PR 208 added the `issue` verb, and the status line
 counting every module as a bus user without a credential is
 [issue 195](../195-every-assigned-module-is-counted-as-a-bus-user-without-a-credential/00-report.md).
 The serving machine also lacked the certificate-trust module, so it could not verify the mesh's own
 certificates until it was assigned there.
@@ -0,0 +1,75 @@
 # Diagnosis
 *2026-10-01.*
 **Ruled out first: the module itself.** Its container was up and had not restarted. The controller's
 status endpoint answered on its own port with `"up": true`. The tool wrapper beside it was serving
 all its tools.
 **Ruled out: name resolution.** The internal name resolved to the serving node's private-network
 address, which is where the proxy listens. Plain HTTP to the name reached the proxy and got a 404.
 HTTPS failed in the handshake, and the proxy logged that it had no route for the name.
 **The route as the proxy received it.** The mesh-written route file held a complete contribution
 for the module: endpoint `web`, port, scheme `https`, `insecure`, a label, and `internal-name`. It had
 no `name`. That is what the controller composes for an endpoint whose reach stops at the private
 network (ADR 0138, `composeName`). The contribution was correct.
 **Located: `routesFrom` in the proxy.** It reads `name` first and skips the contribution if `name`
 is empty. It reads `internal-name` only at the end, as a second host for a rule that already has a
 public one. So the proxy can serve an internal name only next to a public one. That matched the
 mesh before ADR 0138, when both names were always composed. It has been wrong since then.
 The other half of the proxy already handles the case. Certificates for a host are split by whether it
 is in the public set: hosts outside it go to the internal authority, and only hosts inside it are
 eligible for ACME. A host that is only ever an internal name falls on the correct side of both checks
 without change. For certificates, only reading the route was wrong; who may reach the route is the next section.
 **The fix.** `routesFrom` takes a route that names either host, serves each name it carries, and
 marks only the public one as public. It still skips a route that names neither, with the same log line.
 A test proves an internal-only route is served, certified by the internal authority, and refused by
 the public one. That test fails against the code before the change.
 ## The first fix would have made the name public — 2026-10-02, from review
 Serving the dropped route was not enough. The proxy picks a route from the name a request carries
 and never from where the request came from, and it answers public and internal names on the same
 listeners. Its public names resolve to an address the internet reaches. So once the internal-only
 route was served, any request from the internet carrying `unifi.home-server.internal` — a name of a
 fixed, guessable shape — would have reached an administration interface that reach `internal` was
 chosen to keep private. Before the fix the route was unreachable from everywhere. After it, it would
 have been reachable from everywhere. Two more leaks came with it: the proxy's answer for an unrouted
 name listed every name it serves, internal ones included, and the handshake handed a certificate
 naming the internal host to any client.
 Nothing showed this while every routed endpoint also had a public name: its internal name exposed
 nothing the public one did not. It is a gap in the decision's wording, not only in the proxy — ADR
 0138 says the proxy *serves* the internal name without saying to whom — so it is recorded there as a
 progressive insight and in the to-be connectivity design.
 **Where "inside" is decided: told, not worked out.** The first correction had the proxy work it out
 for itself — the mesh's range from an environment variable the catalogue wrote, and the machine's
 container bridges from its own interfaces. That was a second definition of "the mesh", kept by one
 module beside the one the controller already has: it resolves "from the mesh" to every machine's
 address on the private network, and the packet filter is rendered from that list. Reviewed, it was
 replaced: [ADR 0167](../../02-DECISIONS/0167-a-membership-carries-what-its-module-receives-and-who-the-mesh-is.md)
 has every membership on the bus carry what its module receives and that list, and the proxy follows
 its membership. One composition, read by the filter and by the proxy.
 The proxy reads the source address, where the guard reads the interface, because it cannot see the
 interface a request arrived on. A claimed source does not carry here: a connection needs its replies,
 and replies to a mesh address leave by the tunnel.
 **What changed with it.** The internal name of a route that also has a public one is now served to the
 mesh only, like any other internal name. Outsiders have the public name, so nothing they could reach is
 lost. A container calling its own machine's internal name arrives from its container network and is
 refused; whether the mesh should issue those networks too is left open in ADR 0167.
 **Order of release.**
 1. The catalogue change, which gives the proxy a bus account. A machine running the proxy is not
   composed until its account is issued, so the account is issued straight after
   (`module issue route-proxy --node <machine>`), and then the machine is pushed.
 2. The controller and proxy change. The push after it publishes memberships that carry the routes and
   the mesh, and each proxy takes them. Until then, a proxy serves its file, and internal names to its
   own machine alone.
@@ -0,0 +1,71 @@
 ---
 status: resolved
 opened: 2026-10-02
 located-in: [mesh-host internal/apply (removeOrphan: a former target of a kind with no removal was fatal), mesh-host internal/store (Record keeps a former target for every kind, the host's own archive included)]
 fixed-by: mesh-host 65 — a former target of a kind the host cannot remove is left in place, said and forgotten; a dropped archive still refuses
 amended-design:
 ---
 # 194 — The host's own former archive stops every machine applying anything
 ## What was observed
 2026-10-02, 00:34Z, on all four machines of this mesh, the first time a host carrying former
 targets ([ADR 0163](../../02-DECISIONS/0163-taking-a-module-over-is-a-comparison.md), rule 5,
 built in mesh-host 63) replaced itself with a newer host (mesh-host 64).
 The host delivers its own successor as an archive whose target is a versioned directory
 ([ADR 0141](../../02-DECISIONS/0141-the-host-delivers-its-own-successor.md)): every new version
 is the same resource with a new target. Since mesh-host 63 the record keeps a resource's former
 target so the next apply removes what the host wrote under it
 ([issue 097](../097-a-resource-that-changes-target-leaves-the-old-one-behind/00-report.md)). So
 the new host's first apply found the previous version's directory as a former target of its own
 archive, and asked the removal for an archive — which does not exist
 ([issue 162](../162-an-archive-cannot-be-undeclared/00-report.md)):
 ```
 applying "mesh-host.next@former:/usr/lib/nox-mesh-host/versions/3c906749ad27": no way to remove a "archive"
 0 resource(s) were applied and remain
 ```
 Orphans are removed before any resource is applied on a converged machine, so the refusal ended
 every apply at its first step. Every machine reported `failed`, applied nothing, and would have
 gone on doing so: a host fix is itself an archive the same apply would have to write, and the apply
 never reached it. The machines kept running what they had; nothing new from the mesh could land.
 ## Why it matters beyond this instance
 Two rules that are each right met in the one resource the host cannot afford to stop on. Rule 5
 says a former target is removed and said; issue 162 says an archive has no removal, deliberately,
 so an unassignment nothing can undo is never reported as done. Neither rule was wrong; their
 meeting was never tested, because the bed that would have found it is a host replacing itself
 under the new rule, and the first such replacement was the live one. The fix is narrow: a former
 target of a kind the host cannot remove is left in place, said, and forgotten — never fatal,
 because nobody dropped it. An archive the declaration dropped still refuses, as 162 has it.
 ## What it took to recover
 The broken host cannot apply its own fix: the fix is delivered as an archive, and the apply fails
 before writing anything. On each machine the host's record (`/var/lib/mesh-host/state.json`) had to
 lose the one `@former:` entry by hand, once, so that the next push could write the fixed archive and
 stand aside for it. A manual edit of the host's record is otherwise never done; it is written here
 because the alternative was four machines that could apply nothing.
 ## Open questions
 - Should `Record` keep a former target for a kind the host cannot remove at all? The trace is
  useful; the removal it implies is not. Keeping it and letting the apply forget it is what the fix
  does; not recording it would be quieter.
 - Should the host's own versions directory be cleaned by the launcher rather than by the apply —
  the one archive whose former targets are genuinely removable, by the thing that knows which one
  runs?
 - Is there a bed that replaces a host under the current rules before the live mesh does
  (the proof row of [ADR 0141](../../02-DECISIONS/0141-the-host-delivers-its-own-successor.md) was
  a single crossover, before former targets existed)?
 ## Resolved, 2026-10-02
 mesh-host 65, merged 07:35Z. Recovered as the record above says: the operator dropped the one
 `@former:` entry from each machine's host record and pushed; the fixed host then ran on all four and
 its first apply said `forgotten mesh-host.next@former:… a former target left in place` and applied the
 rest. The open questions stand as questions for the host's own versions, not as faults.
@@ -0,0 +1,62 @@
 ---
 status: open
 opened: 2026-10-02
 located-in: []
 fixed-by:
 amended-design:
 ---
 # 195 — Every assigned module is counted as a bus user without a credential, and the real gaps are lost in the count
 ## What was observed
 `status`, and `plan` for any machine, open with one line before anything else:
 ```
 the bus's user list leaves out 49 user(s) the mesh has minted no credential for: <node>.<module>, …
 Each is a user that cannot connect until one is issued
 ```
 The 49 are spread over four machines and name 26 distinct modules. Checked against the catalogue on
 2026-10-02:
 | what the module's definition says | modules |
 |---|---|
 | declares an own secret named `broker` | 1 — the route proxy, which needed a bus account for issue 191 |
 | declares no `broker` secret, and emits, consumes and serves nothing on the bus | 17 — the packet filter, the intrusion filter, the ssh daemon, the resolver configuration, the certificate authority, the broker itself and others |
 | declares no `broker` secret, and **emits events** | 1 |
 | not in this catalogue, so not checked | 7 |
 So the line counts every module assigned anywhere as a bus user. For almost all of them that is not a
 missing credential. A module with no `broker` secret has nowhere to receive one, and the mesh already
 says an account nothing reads is an orphan ([issue 078](../078-a-delivered-secret-is-accepted-under-any-name/00-report.md)).
 Two real gaps sit inside the count and cannot be told from the noise:
 - **A declared `broker` secret was filled with a value that is not an account.** Before its account was
  issued, the route proxy's plan on both machines already carried a sealed `broker` file, while the same
  status line said no credential had been minted for it. A push had made the declared secret the way it
  makes any own secret. The module would have started with a credential the bus does not know, and
  nothing would have said why. It was found only because the account was being issued by hand.
 - **A module that emits events declares no way to reach the bus.** Its events can go nowhere, and no
  check refuses that.
 ## Why it matters
 **A warning that is always on is read as never on.** The line names 49 users on every `status` and every
 `plan`. An operator, or an agent, learns to scroll past it. The one entry that was a real fault looked
 exactly like the 48 that were not.
 **The fault that was real is the silent kind.** A module whose broker credential is a generated value
 starts, fails to authenticate, and reports that three layers away from the cause. That is the failure
 the composition already refuses for a secret that was never made at all ("declared and not made"). Here
 a value was made, so the refusal never fired.
 ## Open questions
 - Should a bus user be composed for a module that declares no `broker` secret at all? If not, the line
  shrinks to the modules that can actually use an account.
 - Is a `broker` secret ever correctly made by the generic generator? If not, should composition refuse
  a declared `broker` until it is issued, or should the mesh issue it as part of placing the module?
 - Should a module that emits, consumes or serves on the bus be refused when it declares no `broker`
  secret?
@@ -0,0 +1,54 @@
 ---
 status: resolved
 opened: 2026-10-02
 located-in: [mesh-controller internal/catalogue/filtering.go (AsNftables: the forward chain has no rule for the mesh passing through, so a relayed packet is judged by this machine's own published ports)]
 fixed-by: mesh-controller PR 209 (the forward chain relays what comes in and goes out on the tunnel), live 2026-10-02
 amended-design: []
 ---
 # 196 — The hub relays the mesh only on the ports it publishes for itself
 ## What was observed
 A sweep of every listening port on every machine, from every other machine, on 2026-10-02. Two home
 machines, neither of which can be dialled, reach a third home machine through the hub, as
 [ADR 0007](../../02-DECISIONS/0007-connectivity.md) says every path between machines that are not
 co-located does.
 From either of the two, the third answered on **17 of its 55** listening ports over the mesh. The hub
 itself, probing the same machine directly, reached all the ports that machine's rules open to the mesh.
 The result was the same at 40 probes in parallel and at 4, so it was not load.
 The 17 were not a property of the target. They were exactly the ports **the hub** publishes for its own
 containers: ssh, the proxy's two, and the hub's own block of published ports. A capture on the target
 during one probe to a port that answered and one that did not:
 - the answering one: the SYN arrives on the tunnel, reaches the container, and the reply leaves by the
  tunnel;
 - the other: nothing arrives at all, on any interface.
 ## Why it matters
 **ADR 0007's hub carries every path between machines that are not co-located, and the filter breaks
 that path without saying so.** Whether one home machine can reach a service on another depends on
 whether the hub happens to publish the same port number for something of its own. Adding or removing
 a module on the hub silently opens or closes paths between two other machines that it has nothing to
 do with.
 It also hid behind another fault. A missing placement made the same pair look disconnected earlier the
 same day, and that explanation fit well enough that the per-port pattern was not looked for.
 ## Open questions
 - The relaying rule accepts what comes in on the tunnel and leaves on it, and leaves judging to the
  machine it is for. Should the hub also restrict relayed traffic to what that machine opens to the
  mesh? That would duplicate the target's rules on the hub.
 - No test raises two machines behind a hub and checks a port between them that the hub does not
  publish. The lab's beds have one machine per site.
 ## Resolved (2026-10-02)
 Live on all four machines after one push each. The same sweep, from both home machines to the third
 over the mesh: 45 of 55 ports answer, the same 45 the hub reaches directly. The 9 that do not are
 ports the target opens to nobody on the mesh, and one is refused because it listens only on a LAN
 address. Nothing answers that the target's rules do not open.
@@ -0,0 +1,27 @@
 # Diagnosis
 *2026-10-02.*
 **Not the tunnel.** The route from either home machine to the target is the tunnel, and traffic to the
 17 ports travels it in both directions. A placement fault would have stopped every port.
 **Not the target's filter.** The target opens the failing ports to every address of the mesh in its
 input chain and its forward chain, the hub reaches them directly, and the SYN for a failing port never
 arrived at the target to be judged.
 **The hub's forward chain.** A relayed packet comes in on the tunnel and leaves on it, so the hub's
 forward hook judges it. The chain the controller renders (`AsNftables`) has a default of drop, accepts
 established traffic, and accepts what did not arrive on an outward link or the tunnel. That last rule is
 for the machine's own containers reaching outward. After that come the rules for this machine's own
 published ports, each matching the **original destination port** of the connection. None of them names
 an outgoing interface or a destination. So a relayed packet to another machine's port 20000 matched the
 hub's own rule for its own port 20000 and passed. One to port 8080, which the hub does not publish,
 matched nothing and was dropped.
 **The fix.** One rule: in on the tunnel **and** out on the tunnel is accepted. That is the mesh passing
 through to another of its machines, which filters it against its own rules. It does not widen anything
 on the hub. A packet for the hub itself is the input chain's, and one for the hub's own containers
 leaves by a bridge, not the tunnel. Both still meet their rules. WireGuard only accepts a packet from a
 peer whose address that peer is allowed to use, so in-on-the-tunnel means from a machine of the mesh.
 A controller test asserts the rule in the forward chain only, never in the input chain, and absent on a
 machine with no tunnel. It fails without the fix, and the rendered set loads with `nft -c`.
@@ -0,0 +1,43 @@
 ---
 status: resolved
 opened: 2026-10-02
 located-in: [mesh-host internal/outward (Links reported only the links carrying a default route)]
 fixed-by: mesh-host PR 66 (a link backed by a physical device is named outward, up or down), live 2026-10-02
 amended-design: []
 ---
 # 197 — A physical link that is down is not filtered when it comes up
 ## What was observed
 A sweep of every machine's filter on 2026-10-02. A laptop-class machine connected by its radio has a
 wired port that was unplugged. Its filter guarded the radio and the tunnel, and accepted everything
 arriving on any other link:
 ```
 iifname != { "mesh0", "<radio>" } accept
 ```
 The wired port was not in the list. Plugged in, everything arriving on it would have been accepted,
 every port of the machine open to whatever network the cable reached. That would last until the
 machine reported again and was pushed a new filter.
 ## Why it matters
 **The filter's one rule about links fails open.** [ADR 0140](../../02-DECISIONS/0140-the-filter-constrains-what-arrives-from-outside.md)
 has the filter constrain what arrives from outside, and has the machine say which links face outside.
 Everything not named is treated as the machine's own, its containers and bridges. So a link the machine
 fails to name is not filtered at all. The host named only the links carrying a default route at the
 moment it reported. A cable plugged in later is the ordinary case for a laptop. A second wired network
 that never carries the default route, such as a direct link to a storage box, is never named at all.
 ## Open questions
 - A virtual link that faces outside (a VPN client's interface, a USB tether that appears as a virtual
  device) has no physical device behind it. It is named only while it carries the default route. Is
  that enough?
 ## Resolved (2026-10-02)
 Live on the affected machine after the host was delivered and one more push: its filter now guards the
 radio, the tunnel and the unplugged wired port, before anything is plugged into it.
@@ -0,0 +1,14 @@
 # Diagnosis
 *2026-10-02.*
 **Located in `mesh-host` `internal/outward`.** `Links` read the kernel's routing tables and returned the
 interfaces carrying a default route. An unplugged port carries none, so it was never reported, and the
 controller rendered the filter around the links it was given.
 **The fix.** A link faces outside if it carries a default route **or** has a physical device behind it.
 The kernel lists every interface under `/sys/class/net`, with a `device` entry for one backed by
 hardware. A bridge, a veth, the tunnel and the loopback have none, so they stay the machine's own. The
 wired port is now reported up or down, and the filter guards it before anything is plugged in. Tested
 with a radio carrying the default route and an unplugged wired port beside a bridge, a veth, the docker
 bridge, the tunnel and the loopback: the two physical links are reported, nothing else.
@@ -0,0 +1,71 @@
 ---
 status: resolved
 opened: 2026-10-02
 located-in: [mesh-catalog modules/dnsmasq (listens on loopback and the machine's mesh address only), the home-server's DNS (a predecessor's dnsmasq configuration the mesh did not own), the home network's DHCP (hands out the home-server as every device's DNS)]
 fixed-by: mesh-catalog PR 214 (dnsmasq listens on addresses from a setting; docker's file takes no settings), mesh-controller PR 210 (the settings verb), mesh-catalog PR 215 (unifi network DNS tools), live 2026-10-02
 amended-design: []
 ---
 # 198 — The home network's DNS server ran outside the mesh, and the mesh's filter closed it
 ## What was observed
 Every phone on the home Wi-Fi had no internet, while a laptop on the same Wi-Fi did. The router's
 DHCP hands every device the home-server's LAN address as its DNS server. The home-server's DNS daemon
 was listening on that address, and every query to it timed out. The router itself answered the same
 query at once. The laptop worked because it resolves through its own local resolver, not through the
 server DHCP names.
 ## Why it happened
 The DNS daemon on the home-server was not the mesh's. It ran under a configuration file a predecessor
 generated, listening on loopback, the mesh address and the LAN address. The mesh's `dnsmasq` module was
 assigned to the other three machines and not to this one, so no module on the home-server declared
 port 53. Its filter opens only what a module declares, so DNS from the LAN was dropped. It started when
 the home-server applied the filter this morning, after nine hours of applying nothing
 ([issue 194](../194-the-hosts-own-former-archive-stops-every-apply/00-report.md)).
 Nothing said so. The daemon reported running, the filter applied cleanly, and the mesh had no record
 that the home network depended on a service it did not know.
 ## Why it matters
 **A service the mesh does not know is closed by the mesh's filter, by design, and nothing asks whether
 something depends on it.** That is the right default for an unknown port. It is the wrong outcome for
 the one service a whole network was told to use. The gap is that a machine can run something
 important outside the mesh with nothing to show it.
 **The mesh's `dnsmasq` could not have served the LAN either.** It listened on loopback and the mesh
 address only. The reach of its DNS endpoints opens the filter, but the daemon would not have been
 listening on the LAN address anyway.
 ## Open questions
 - Should a machine report the listening services the mesh does not own, the way it reports the links
  that face outside? This one would have been visible before the filter closed it.
 - The LAN address the home-server answers on is now a setting, beside the reach that opens the filter.
  Two statements that must agree. Should reach `public` on a DNS endpoint imply listening beyond the
  mesh?
 ## Resolved (2026-10-02)
 The home network was pointed at the gateway for DNS while the fix was built, which got the phones back
 within minutes. Then:
 - the mesh's `dnsmasq` takes the addresses it listens on beside the machine's from a setting, with
  loopback as the mesh-wide default, so no other machine changed;
 - the home-server's layer adds its LAN address, and its DNS endpoints' reach is `public`. The router
  forwards no DNS, so that means the LAN;
 - the module and its sibling `resolv-conf` were assigned to the home-server, replacing the
  predecessor's daemon and configuration, which were kept aside;
 - the home network was pointed back at the home-server, through a new `unifi` tool.
 Checked live: from another machine on the LAN, public names and mesh names both resolve through the
 home-server's LAN address, and the mesh and the machine itself resolve as before.
 **One fault found on the way, and caught before it reached any machine.** A module's settings are
 merged into every mergeable file the module owns. The first attempt therefore put the new setting into
 docker's `daemon.json` as well as into dnsmasq's config, and dockerd refuses keys it does not know. The
 plan showed it before any push. The change was reverted and redone with docker's file declared to take
 no settings. The general fault, a module's settings reaching files they were not meant for, is still
 there for any module with more than one file.
@@ -0,0 +1,35 @@
 ---
 status: resolved
 opened: 2026-10-02
 located-in: [mesh-tools src/client.ts (toolsOn left node-scoped seats out of the listing), mesh-tools src/mcp.ts (the call resolved the key against that listing)]
 fixed-by: mesh-tools 27 — node-scoped seats are listed with their scope, the verb requires the machine, and the call carries it in the subject
 amended-design:
 ---
 # 199 — A node-scoped seat's verb could not be called through the console
 ## What was observed
 2026-10-02, the first time a node-scoped seat declared verbs
 ([ADR 0170](../../02-DECISIONS/0170-the-firewall-seat-serves-its-verbs.md)). The packet filter's
 holder on every machine served `rules`, `reload` and `remove` on the seat's per-machine subjects, and
 the bus admitted them. The console answered every call with *nothing serves
 node-packet-filter.rules@<machine>*.
 [Design 33 §4](../../03-DESIGN/01-to-be/33-the-tools-the-mesh-answers.md) says a node-scoped seat's
 tool carries the node it is asked of, as `<seat>.<verb>@<node>`. The console's listing left
 node-scoped seats out — the comment said they *wait for a caller naming the node* — but the roles map
 the console resolves a name against is built from that same listing. So the name never resolved as a
 seat's verb, fell through to a module's subject nobody served, and the refusal named the wrong cause.
 ## Why it matters beyond this instance
 A stated behaviour that did not happen, with a refusal that pointed elsewhere: the seat's verbs were
 live on four machines and unreachable from the one surface a person uses. It could only be found by a
 node-scoped seat declaring verbs, which none had.
 ## Resolved, 2026-10-02
 mesh-tools 27: node-scoped seats are listed with their scope, their verbs take a required `node`, the
 call carries it in the subject, and a call without one is refused in words. Tested with a round trip
 asking one machine's holder and being refused without a machine.
@@ -0,0 +1,36 @@
 ---
 status: open
 opened: 2026-10-02
 located-in: []
 fixed-by:
 amended-design:
 ---
 # 200 — The controller's answer to a long console call is refused by the bus
 ## What was observed
 2026-10-02. A `push` of the control node asked through the console came back as *mesh-controller.push
 did not answer in time. Something is serving it, so this is the tool being slow rather than absent.*
 The push had run; the machine applied. The bus's log on the control node, at the same moment:
 ```
 [ERR] 10.10.0.1:56030 - cid:4015 - Publish Violation - User "controller",
      Subject "_INBOX.shanks.mesh-console.WRNO5V9IJ1FX35AU5NRBEB.WRNO5V9IJ1FX35AU5PN1UW"
 ```
 The controller's reply to the console's request was refused: the controller's bus account may not
 publish to the console's reply inbox. Shorter calls (`status`, `node`, `nodes`) answer; the long ones
 (`push` of a large machine, `issue`) time out on the console's side although they succeed.
 ## Why it matters beyond this instance
 A call that succeeds and is reported as a timeout sends a person to retry what already happened — a
 second push, a second issue — and reads as the mesh being slow when it is the mesh refusing itself.
 Whether the inbox prefix the console uses is the one the controller's account is allowed to answer, or
 the request outlives the inbox subscription, is what a diagnosis has to tell apart.
 ## Open questions
 - Which reply inboxes may the controller's account publish to, and which does the console request on?
 - Does a reply after the requester's timeout count as a violation, or is the prefix itself refused?
Author	SHA1	Message	Date
mesh-admin	e1203e5a43	Merge pull request 'Research 019: a warm twin of the running mesh' (#294 ) from jschoubben/research-019 into main	2026-10-02 14:59:44 +00:00
jschoubben	4ce967619a	Research 019: a warm twin of the running mesh in the lab	2026-10-02 16:59:36 +02:00
mesh-admin	6df2cfecd6	Merge pull request 'Research 018 graduates: ADRs 0173–0177 and to-be 37, the operator's machine' (#293 ) from feat/the-operators-machine into main	2026-10-02 14:58:48 +00:00
jochen	73047501f6	ADR 0154: the controller seat gains a generic command verb (dated note, by ADR 0175)	2026-10-02 16:53:15 +02:00
jochen	bf39baf104	Research 018 graduates: ADRs 0173–0177 and to-be 37, the operator's machine Every configurable thing on a node is a module, the home included, and a module is whatever it declares (0173, extending 0040). A node varies a module only through a setting rendered into the file or a kept region, never an edit (0174, extending 0011; issue 168 first). One tool runtime per node serves every module's tools on the host side, never in a container; the console is its serving mode, renamed node-tools (0175, extending 0150; 0047/0150/0152 carry dated notes). The login shell is a node seat held by one shell module with `execute` as its contract (0176). A unit may be user-scoped and the service manager is a node seat held by systemd (0177). To-be 37 is handed off in-progress to mesh-host, mesh-controller, mesh-tools and mesh-catalog, with the build in order: the account on every node, the runtime, zsh, systemd, then the graphical stack. To-be 29 keeps ~/.ssh and points at 37; 33 §6 and 34 are amended; the glossary gains node tools, bundle, kept region, installed/holding, and retires flavor.	2026-10-02 16:34:57 +02:00
mesh-admin	5eadf36937	Merge pull request 'ADR 0175: the found front end is uninstalled once a machine is converged' (#292 ) from feat/the-found-front-end-is-uninstalled into main	2026-10-02 14:29:00 +00:00
jschoubben	8c9a2c7501	ADR 0175: the found front end is uninstalled once a machine is converged; design 08 note	2026-10-02 16:27:33 +02:00
mesh-admin	54213ba90c	Merge pull request 'Research 018: the operator's machine as modules' (#291 ) from research/018-the-operators-machine into main	2026-10-02 14:27:27 +00:00
jochen	7fb59bde98	Research 018: the operator's machine as modules The predecessor is retired on every node and what it still owned on the two workstations — some thirty modules of dotfiles, user units and /etc files — is owned by nothing. To-be 29 covers one directory under the home; the operator wants the whole machine, system folders and home alike, as modules: one default configuration each, varied per node by settings or a kept region, never an edit; roles the machine has once as node-scoped seats with tool contracts; the graphical stack gated by a capability so the same catalogue serves the servers. Four documents: the intended behaviour in the mesh's words; the predecessor's desktop measured (34 modules, one with 88 files, 4 flavors and ~90 theme variables) against what the records already give and what is missing (the account is empty on every node, no user-scoped units, settings leak, tools run in a container per module per node); the direction the operator set for where tools run — one executor per node, host-side, module-agnostic, the console renamed and moved out of its container, superseding 0047/0150 for tools; and the candidate seats of the environment with first verbs, the shell first.	2026-10-02 15:19:25 +02:00
mesh-admin	a4d24d7b65	Merge pull request 'ADR 0168: built and proven live' (#290 ) from decision/0168-built into main	2026-10-02 13:09:22 +00:00
jschoubben	116b2d1793	ADR 0168: built and proven live — the live row read on the home server and the control node, the five rule sets removed through ADR 0170's verb	2026-10-02 15:08:58 +02:00
mesh-admin	68a14493c9	Merge pull request 'ADR 0169 → 0170: the firewall seat's record renumbered after a collision on main; built note; cycle.py refuses two records sharing a number' (#289 ) from decision/0170-renumbered-and-built into main	2026-10-02 12:52:17 +00:00
jschoubben	98eb3aa76f	ADR 0169 → 0170: the firewall seat's record renumbered after a collision on main; its built note; cycle.py refuses two records sharing a number Another session's 0169 landed first. The collision check from issue 155 covered issue folders only; it covers decision records now, and would have refused this.	2026-10-02 14:51:22 +02:00
mesh-admin	91bbe648a8	Merge pull request 'Issues 199 (resolved: a node-scoped seat's verb through the console) and 200 (the controller's answer to a long console call is refused by the bus)' (#288 ) from issues/199-200-console-seat-verbs-and-inbox into main	2026-10-02 12:25:37 +00:00
jschoubben	0e7b85f184	Issues 199 (resolved: a node-scoped seat's verb through the console) and 200 (the controller's answer to a long console call is refused by the bus)	2026-10-02 14:25:03 +02:00
mesh-admin	dac49de6e7	Merge pull request 'ADR 0172: the lab is a module, and runs a bed when the mesh asks' (#287 ) from jschoubben/the-lab-is-a-module into main	2026-10-02 12:17:21 +00:00
jschoubben	0d9208dbbf	ADR 0172: the lab is a module, and runs a bed when the mesh asks	2026-10-02 14:15:44 +02:00
mesh-admin	bf0ee7cb25	Merge pull request 'ADR 0169: the firewall seat serves its verbs, and a foreign rule set is removed through one of them' (#285 ) from feat/the-firewall-seat-serves-its-verbs into main	2026-10-02 11:29:15 +00:00
jschoubben	4567e13071	ADR 0169: the firewall seat serves its verbs, and a foreign rule set is removed through one of them Designs 33 and 08 revised. The first node-scoped seat with verbs: rules, reload, remove; the nftables module holds it from a runtime with NET_ADMIN, the first container to declare a capability.	2026-10-02 13:27:03 +02:00
mesh-admin	aa5d9f1045	Merge pull request 'ADR 0169 (proposed): a machine joins through the tunnel, and the bus is never public' (#284 ) from jschoubben/a-machine-joins-through-the-tunnel into main	2026-10-02 11:17:42 +00:00
jschoubben	79642251a1	ADR 0169 accepted; design 08's join order starts with the tunnel	2026-10-02 13:17:32 +02:00
jschoubben	331cb94c6e	ADR 0169 (proposed): a machine joins through the tunnel, and the bus is never public The bus was public only so a new machine could enrol before it had a tunnel. The machine now makes its tunnel key first, the token is issued for it and makes it a peer of the hub, and enrolment happens over the tunnel.	2026-10-02 13:13:15 +02:00
mesh-admin	78351560f7	Merge pull request 'Issue 198: the home network's DNS server ran outside the mesh, and its filter closed it' (#283 ) from jschoubben/the-lans-dns-is-the-mesh into main	2026-10-02 10:22:51 +00:00
mesh-admin	62cc2f89c7	Merge pull request 'Issue 197: a physical link that is down is not filtered when it comes up' (#280 ) from jschoubben/every-physical-link-faces-outside into main	2026-10-02 10:22:40 +00:00
jschoubben	426f741ad0	Issue 198: the home network's DNS server ran outside the mesh, and its filter closed it	2026-10-02 12:22:31 +02:00
jschoubben	9bed54d3be	Issue 197 resolved: the wired port is guarded before it is plugged in	2026-10-02 12:22:15 +02:00
jschoubben	413daf8ad5	Issue 197: a physical link that is down is not filtered when it comes up	2026-10-02 12:22:15 +02:00
mesh-admin	5c993c09b7	Merge pull request 'Issues 143 and 144 resolved: the live row of ADR 0168 read on the home server and the control node' (#282 ) from issues/143-144-resolved into main	2026-10-02 10:11:37 +00:00
jschoubben	7c3be48db2	Issues 143 and 144 resolved: the live row of ADR 0168 read on the home server and the control node	2026-10-02 12:11:17 +02:00
mesh-admin	b665d06701	Merge pull request 'ADR 0168: a converged machine is filtered by the mesh alone, and the host says what else refuses (group 7)' (#281 ) from feat/one-thing-filters-a-converged-machine into main	2026-10-02 10:03:48 +00:00
jschoubben	1bd13446d4	ADR 0168: a converged machine is filtered by the mesh alone, and the host says what else refuses (group 7) Designs 08 and 05 revised; 141 resolved by ADR 0140 and 084 by ADR 0102 and issue 128, both by reading; 143 and 144 decided, built on the matching branches in mesh-host and mesh-controller, resolved when the home server's record names the predecessor's chain.	2026-10-02 11:58:18 +02:00
mesh-admin	14adaafa53	Merge pull request 'to-be 29: the account fact and home-scoped resources shipped; the ssh-client module, CA and ~/.ssh boundary did not' (#279 ) from design/29-what-shipped into main	2026-10-02 09:49:52 +00:00
mesh-admin	bd673cc6ec	Merge pull request 'Group 6 closed: 086, 090, 098, 099, 100, 101 resolved on the operator's decision' (#278 ) from issues/group-6-closed into main	2026-10-02 09:38:11 +00:00
jschoubben	bd6c55d225	Group 6 closed: 086, 090, 098, 099, 100, 101 resolved on the operator's decision, each saying the live row was not run	2026-10-02 11:37:08 +02:00
mesh-admin	2bbbc56502	Merge pull request 'Issue 194 resolved: the fixed host forgot its former archive on all four machines' (#277 ) from issue/194-resolved into main	2026-10-02 09:31:49 +00:00
jschoubben	c8935aceca	Issue 194 resolved: the fixed host forgot its former archive on all four machines	2026-10-02 11:31:29 +02:00
mesh-admin	29b656f2c0	Merge pull request 'Issue 196: the hub relays the mesh only on the ports it publishes itself' (#276 ) from jschoubben/the-hub-relays-the-mesh into main	2026-10-02 09:23:55 +00:00
jschoubben	d05ac367f1	Issue 196 resolved: the hub relays the mesh, re-swept live	2026-10-02 11:23:37 +02:00
jschoubben	1c0dafb918	Issue 196: the hub relays the mesh only on the ports it publishes itself	2026-10-02 11:17:11 +02:00
mesh-admin	018ee359ae	Merge pull request 'Issue 194: the host's own former archive stops every machine applying anything' (#274 ) from issue/194-the-hosts-own-former-archive-stops-every-apply into main	2026-10-02 09:04:30 +00:00
mesh-admin	c5535eeebd	Merge pull request 'ADR 0163 built: the take digest, the minted-secret refusal, the networks setting, settings judged where stored, genesis raising the forge as declared' (#270 ) from feat/a-take-is-a-comparison-the-rest into main	2026-10-02 09:04:21 +00:00
mesh-admin	dbb9d2bc16	Merge pull request 'Issue 191 and ADR 0167: a membership carries what its module receives, and who the mesh is' (#273 ) from jschoubben/an-internal-only-route into main	2026-10-02 07:49:27 +00:00
jschoubben	28d53dcc28	Issue 191 resolved: internal-only routes are served to the mesh, live on both proxies	2026-10-02 09:49:25 +02:00
jschoubben	df667eb710	ADR 0167: a membership carries what its module receives, and who the mesh is Issue 191's route proxy needs to know who the mesh is to serve an internal name correctly, and the first fix had it work that out alone. The membership on the bus now carries it, from the same list the filter uses. ADR 0138 gains an insight that the proxy is where internal reach is kept; designs 08 and 25 say how.	2026-10-02 09:49:19 +02:00
jschoubben	098a2ca485	Issue 191: a route with only an internal name is dropped as naming nothing	2026-10-02 09:49:19 +02:00
mesh-admin	a34cedeb5d	Merge pull request 'Issue 195: every assigned module is counted as a bus user without a credential' (#275 ) from jschoubben/issue-195 into main	2026-10-02 00:44:29 +00:00
jschoubben	db5ff5a5ee	Issue 195: every assigned module is counted as a bus user without a credential The status warning names 49 users; 48 are modules that never speak on the bus, and the one real fault, a declared broker secret filled with a generated value, looked the same as the rest.	2026-10-02 02:44:24 +02:00
jschoubben	780c2b6e58	Issue 194: the host's own former archive stops every machine applying anything Rule 5 of ADR 0163 (a former target is removed) met issue 162 (an archive has no removal) in the host's own archive, the first time a host carrying former targets replaced itself; every machine applied nothing from then on.	2026-10-02 02:42:19 +02:00
jochen	8c231102f8	to-be 29: the account fact and home-scoped resources shipped; the ssh-client module, CA and ~/.ssh boundary did not The controller merged §1, §2 and the composed ssh config on 2026-09-27 while hq still called the design proposed. Record what is on main, what is held on a branch, and what has no code — and that the account fact shipped without a decision record, which is the next thing to write. Also drop the real account and node names the public repository must not carry, and correct ADR numbers that drifted in a renumbering.	2026-10-01 23:14:10 +02:00