novox/hq
6
0
Fork 0
Code Issues 5 Pull Requests 1 Releases Wiki Activity

ADR 0210: a tool's configuration is its seat holder's, and every other module extends it through the seat

Browse Source
This commit is contained in:
jochen
2026-10-04 15:19:44 +02:00
parent 6ac936f170
commit 8394a7bfb1
4 changed files with 127 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
02-DECISIONS/0203-the-accounts-environment-is-one-modules-and-every-module-contributes-to-it.md
+5
View File
@@ -93,6 +93,11 @@ A node with contributions and no holder writes them nowhere. The holder's absenc
node's assignments, and no contributor is refused for it, because a missing `PATH` entry is a gap, not
a broken machine.
> **The mechanism changed — 2026-10-04, by [ADR 0210](0210-a-tools-configuration-is-its-seat-holders-and-every-other-module-extends-it-through-the-seat.md).** A contribution is now a dependency on
> node-environment, met and refused as ADR 0207 says, so a node without the holder refuses the
> contributor instead of writing the contribution nowhere. The rest of this section, and the
> decision, stand.
## Consequences
- A shell's part in the environment is one line in its always-read startup file, sourcing the
02-DECISIONS/0208-the-graphical-session-is-one-module-per-piece-on-the-meshs-seats.md
+6
View File
@@ -87,6 +87,12 @@ reports, `graphical-session`, still gates the display server itself.
The holder of `node-display-server` places them with `${shell:xinitrc:<slot>}` and
`${shell:xresources:<slot>}`.
> **The mechanism changed — 2026-10-04, by [ADR 0210](0210-a-tools-configuration-is-its-seat-holders-and-every-other-module-extends-it-through-the-seat.md).** A contributor no longer places its own
> file in another tool's directory. It contributes to the tool's seat, and the seat's holder places it,
> in that directory or through a placeholder. Every contribution, the `xinitrc` and `xresources` slots
> included, is a dependency on the seat that receives it. What a contribution contains still follows
> the tool's grain.
**5. The display server's module writes the session's start.** It writes a block at the start of
`~/.xinitrc`, in this order:
02-DECISIONS/0210-a-tools-configuration-is-its-seat-holders-and-every-other-module-extends-it-through-the-seat.md
+115
View File
@@ -0,0 +1,115 @@
---
topic: the mesh
status: accepted
date: 2026-10-04
deciders: jochen
reconstructed: false
extends: 02-DECISIONS/0207-a-module-depends-on-the-node-seats-that-apply-its-resources.md
---
# 210. A tool's configuration is its seat holder's, and every other module extends it through the seat
## Context
One fault kept coming back while the machines' modules were rolled out
([to-be 42](../03-DESIGN/01-to-be/42-the-machines-modules-in-order.md)): two modules want the same
thing on a node.
- The bar module and the package manager's module both declared the package that brings the
package manager's helper scripts. The node stopped resolving
([issue 235](../04-ISSUES/235-an-assignment-that-cannot-be-composed-is-recorded-anyway/00-report.md)).
- The launcher, the clipboard manager, the wallpaper and the bar each wrote a file of their own into
the window manager's include directory, as [ADR 0208](0208-the-graphical-session-is-one-module-per-piece-on-the-meshs-seats.md)
§4 allowed. Nothing says those modules need the window manager. Assigned without it, they write
configuration nothing reads. Assigned with a different session holder, they write into a directory
that holder does not own.
- [ADR 0203](0203-the-accounts-environment-is-one-modules-and-every-module-contributes-to-it.md) §5
lets a module contribute to the environment on a node that has no holder: the contribution is
written nowhere, and nothing says so.
The mesh already has the piece that answers this.
[ADR 0207](0207-a-module-depends-on-the-node-seats-that-apply-its-resources.md) made a module depend on
the seat that applies its resources, derived from what it declares. A contribution is the same kind
of need. It is configuration that only the seat's holder can apply.
## Considered Options
1. **Let the first module to declare a file or package own it,** and refuse the second. Rejected:
ownership then depends on the order modules were written, and the second module has no lawful way
to say what it needs.
2. **Allow shared declarations** of one package or file by several modules, merged by the host.
Rejected: a shared file has no owner to answer for it, and removing one module cannot tell what it
alone put there.
3. **Each tool's configuration belongs to the module holding the tool's seat. Every other module
extends it with a contribution to that seat, and a contribution is a dependency on the seat.**
Chosen. It is the operator's statement of the rule.
## Decision
**1. One owner.** A tool's configuration files, and the tool's package, belong to the module that
holds the tool's seat on the node. Only that module writes them.
- The package manager's configuration and helper packages are the package manager's module's.
- The account's environment is node-environment's holder's.
- The window manager's configuration is node-display-session's holder's.
**2. Other modules extend, never write.** A module that needs something in another tool's
configuration declares a **contribution to that tool's seat**:
- its content, in the grain the seat defines (variables and paths, shell code for a named shell and
slot, a window-manager configuration fragment, a notifier rule);
- never a path inside the holder's files or directories.
The holder places what it receives:
- the controller renders the contributions into the holder's files through the holder's placeholders,
as [ADR 0203](0203-the-accounts-environment-is-one-modules-and-every-module-contributes-to-it.md) and
[ADR 0204](0204-a-module-contributes-shell-code-to-the-login-shell-in-named-slots.md) already do;
- or the holder writes each contribution to its tool's own drop-in directory. That directory is then
the holder's resource, not the contributor's.
**3. A contribution is a dependency on the seat that receives it.** The controller derives it from the
contribution, as ADR 0207 derives one from a resource. It is met, checked and refused exactly as ADR
0207 §3 and §4 say:
- refused at `assign` when no module on the node holds the seat and the catalogue has a holder;
- refused at composition after the switch.
**4. Needing what another module's package delivers is the same.** A module that needs a program
another seat's holder installs does not declare that package. It depends on the seat, and through
the seat's verbs where they exist. One package is declared by one module on a node.
**5. A seat says what it receives.** A seat lists the contribution kinds its holder accepts. A
contribution of a kind the seat does not list is refused at registration.
## Consequences
- **ADR 0203 §5** no longer holds: a module contributing to the environment depends on
node-environment, and a node without the holder refuses it. The rest of that record stands.
- **ADR 0208 §4**: its first list, contributors placing their own files in another tool's directory,
is replaced by §2 above. The tool's grain stays the guide for what a contribution contains. The
`xinitrc` and `xresources` slots already work this way, and now carry a dependency on
node-display-server.
- **The desktop modules change:** the launcher, the clipboard manager, the wallpaper and the bar
contribute their window-manager lines to node-display-session instead of writing into the include
directory. The bar keeps relying on the package manager's helper scripts through node-package-manager.
- **The two kinds of collision cannot recur:**
- two modules declaring one package or one file;
- a contribution to a seat nobody on the node holds.
A composition that finds either is a fault in a module, not a state a node can be left in.
- **What got harder:** a seat that receives contributions must define their grain, and its holder must
place them. Each new kind is a small change to the controller's renderer or to the holder.
## How it is checked
| Rule | Checked by |
|---|---|
| A contribution derives a dependency on the seat that receives it | the controller's resolve tests |
| A contribution to a seat with no holder on the node is refused at `assign` when the catalogue has a holder | the same tests, and `assign` live |
| One package or file is declared by one module on a node | the controller's composition test, and `module check` across the catalogue |
| A contribution of a kind its seat does not list is refused | the catalogue check, which registration runs |
| No module declares a path inside another module's files or directories | the catalogue check |
## References
- [ADR 0203](0203-the-accounts-environment-is-one-modules-and-every-module-contributes-to-it.md),
[ADR 0204](0204-a-module-contributes-shell-code-to-the-login-shell-in-named-slots.md),
[ADR 0207](0207-a-module-depends-on-the-node-seats-that-apply-its-resources.md),
[ADR 0208](0208-the-graphical-session-is-one-module-per-piece-on-the-meshs-seats.md)
- [Issue 235](../04-ISSUES/235-an-assignment-that-cannot-be-composed-is-recorded-anyway/00-report.md)
02-DECISIONS/README.md
+1
View File
@@ -192,6 +192,7 @@ python3 00-META/checks/index.py fail if stale
- **0190** — [A seat's work is shared by its holders, and building is the first such role](0190-a-seats-work-is-shared-by-its-holders-and-building-is-the-first-such-role.md)
- **0202** — [A provider declares what it derives for each consumer, and the mesh tells both ends](0202-a-provider-declares-what-it-derives-for-each-consumer.md)
- **0207** — [A module depends on the node seats that apply its resources](0207-a-module-depends-on-the-node-seats-that-apply-its-resources.md)
- **0210** — [A tool's configuration is its seat holder's, and every other module extends it through the seat](0210-a-tools-configuration-is-its-seat-holders-and-every-other-module-extends-it-through-the-seat.md)
### Its tiers, from the bottom up