hq/02-DECISIONS/0173-the-operators-machine-is-the-meshs-and-a-module-is-what-it-declares.md

topic, status, date, deciders, reconstructed, extends

topic	status	date	deciders	reconstructed	extends
what runs on it	accepted	2026-10-02	jochen	false	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 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). 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 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 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).

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 §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 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 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 §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).
• 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).

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, documents 01 and 02 — the behaviour wanted and the inventory measured.
• ADR 0040, ADR 0112, ADR 0051, ADR 0100
• To-be 29 — the account and the home as a placement root, built; the records for them are proposed in an open change.