hq/03-DESIGN/01-to-be/37-the-operators-machine.md

layer, status, code, updated, decisions

layer	status	code	updated	decisions
to-be	in-progress	mesh-host mesh-controller mesh-tools mesh-catalog	2026-10-02	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 to 0177). This is the design to-be 29 §2 called a family and research 018 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, 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): 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). 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); 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, 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).
• 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
• To-be 29 — the account and the home; this design is the family its §2 names, beyond ~/.ssh.
• To-be 33, to-be 34 — the tools and the console, amended by ADR 0175.
• To-be 05 — the host's vocabulary, widened by ADR 0177.