hq/02-DECISIONS/0208-the-graphical-session-is-one-module-per-piece-on-the-meshs-seats.md

topic, status, date, deciders, reconstructed, extends

topic	status	date	deciders	reconstructed	extends
what runs on it	accepted	2026-10-04	jochen	false	02-DECISIONS/0204-a-module-contributes-shell-code-to-the-login-shell-in-named-slots.md

208. The graphical session is one module per piece, on the mesh's seats

Context

The two workstations run one predecessor desktop (research 026). It was a module of 983 lines with four flavors and 92 theme variables. One of its machines carried another machine model's hardware files, and its session's environment was a hand-kept copy of the account's. The operator asked for the desktop as modules at the shell's level, consistent across machines, with sway as a sibling of i3. To-be 38 named this WP7, and to-be 37 left one question for the resolver: how a module says it needs a display server held on its node.

Considered Options

• One desktop module, as before (research 026 §1, G1). Rejected: flavors again, and the evidence is a flavor on the wrong machine.
• One module per piece of software. Chosen.
• For "i3 needs an X server" (research 026 §3):
  • a new field (R2), rejected as a second way to say what provisions already say;
  • assigning carefully (R3), rejected because that is the misassignment the evidence shows;
  • a provision with the machine's reach (R1), chosen.
• For other modules' lines in a holder's file (research 026 §5):
  • only drop-ins (C1), rejected because two files the session needs have no drop-in convention;
  • only slots (C2), rejected as needless where the tool already reads a directory;
  • both, the boundary drawn by the tool (C3), chosen.

Decision

1. One module per piece of software: lemurs, xorg, i3, xterm, picom, rofi, dmenu, dunst, the lock screen, xclip, the clipboard manager, feh, i3status-rust, a theme module, fonts, gnome-keyring, and later sway, foot, waybar and mako. No flavors. What follows a machine's hardware is that model's hardware module (research 027/03).

2. The roles are node seats in the mesh's own set, each with the verbs research 026/05 starts it with:

seat	holders	verbs to start with
node-login-manager	lemurs	sessions
node-display-server	xorg, sway	displays, layout
node-display-session	i3, sway	reload, workspaces, windows
node-terminal-emulator	xterm, foot	open
node-launcher	rofi, dmenu	menu, the dmenu-compatible command
node-notifier	dunst, mako	send, history
node-lock-screen	the lock module, swaylock	lock
node-clipboard	the clipboard manager	history, copy
node-bar, node-compositor	i3status-rust, waybar; picom	none yet
node-secret-service	gnome-keyring	none yet

A compositor that is its own server holds two seats, as sway does.

3. A display is a provision with the machine's reach.

• A display server provides x11-display or wayland-display, reachable only on its own machine.
• A module that draws on a display requires the one it speaks: i3, picom, xterm and the X lock require x11-display; sway's companions require wayland-display.
• A requirement with the machine's reach is resolved on the requiring module's own node, or not at all, and is refused naming the seat's holders.
• xwayland, as its own module, provides x11-display inside a Wayland session.

This answers to-be 37 §4 by reusing provisions and reach rather than a new field. A capability the host reports, graphical-session, still gates the display server itself.

4. Other modules contribute to a holder's file in the tool's own grain.

• Where the tool reads a directory, the contributor places its own file there:

  • i3's include directory;
  • dunst's dunstrc.d;
  • XDG autostart;
  • environment.d;
  • fontconfig's conf.d;
  • ssh's config.d;
  • the login manager's session directory.

• Where it does not, ADR 0204's slots serve beyond shells. A shell contribution's for may also name:

  • xinitrc: POSIX code the session's start runs;
  • xresources: X resources merged at session start.

  The holder of node-display-server places them with ${shell:xinitrc:<slot>} and ${shell:xresources:<slot>}.

5. The display server's module writes the session's start. It writes a block at the start of ~/.xinitrc, in this order:

1. it sources the account's environment (ADR 0203);
2. it imports the session's own variables into the user manager and D-Bus activation, by an explicit list;
3. it merges the X resources;
4. it runs the xinitrc slots;
5. it ends by starting the session holder's command, which the session module contributes in the last slot.

The desktop's identity and the theme variables are environment contributions of the session and theme modules. The hand-kept environment in today's file goes, and so does the predecessor's file of secrets (research 027 question 2).

6. Per-machine values:

• Monitor layouts are profiles keyed by the monitors' identities (research 026/04). They are the operator's data, and the display server's layout verb manages them.
• DPI and theme values are module defaults now, and settings after issue 168.

Consequences

• A workstation's desktop is a list of assignments, the same on both. The one machine model's hardware is one more assignment.
• The X stack is built first, and sway is designed in from the start.
• The controller learns:
  • the eleven seats;
  • provisions with the machine's reach;
  • two more names for a contribution's for.
• What got harder: a module that draws must say which display it speaks, and one that wants both ships twice.

How it is checked

Rule	Checked by
The seats are in the mesh's own set, refused to any module that declares them	the seat table's tests
A machine-reach requirement resolves on its own node only, refused naming the holders	the controller's resolve tests
xinitrc and xresources slots are placed only by the display server's holder	the catalogue check
The session block sources the environment, merges resources, runs the slots and ends with the session	the xorg module's manifest test, and on the proving workstation

References

• Research 026, its 02, 04 and 05
• ADR 0203, ADR 0204, ADR 0207
• To-be 42