Research 025: how a module plugs into the operator's shell

Opened after the zsh module's rollout (to-be 38 WP5) was stopped: every machine carries the same predecessor-written startup file, the module's block would duplicate it and drop lines, nothing installs the prompt, and execute never reads .zshrc. Weighs how modules contribute environment and shell code, where the operator's own lines go, ordering, and what a contribution is addressed to.
2026-10-04 10:30:18 +02:00
parent 96df3ccc88
commit ac6c306df3
3 changed files with 339 additions and 0 deletions
@@ -0,0 +1,72 @@
 ---
 status: active
 initiated: 2026-10-04
 touches:
  - 02-DECISIONS/0174-a-node-varies-a-module-through-settings-and-kept-regions-never-an-edit.md
  - 02-DECISIONS/0176-the-login-shell-is-a-node-seat-and-execute-is-its-contract.md
  - 02-DECISIONS/0102-the-mesh-writes-into-a-shared-file-never-over-it.md
  - 02-DECISIONS/0182-inside-a-home-the-mesh-owns-what-it-places-and-holds-the-rest-as-found.md
  - 02-DECISIONS/0112-a-module-definition-names-no-node-mesh-or-path.md
  - 03-DESIGN/01-to-be/27-a-module-requires-the-mesh-resolves.md
  - 03-DESIGN/01-to-be/31-a-module-declares-its-fail2ban-jail.md
  - 03-DESIGN/01-to-be/37-the-operators-machine.md
  - 03-DESIGN/01-to-be/38-building-the-operators-machine.md
  - 04-ISSUES/168-a-setting-reaches-every-file-and-contribution/00-report.md
 became: []
 ---
 # 025 — How a module plugs into the operator's shell
 ## What is investigated
 The shell module writes the mesh's part of the account's shell startup file. But the shell is not the
 only module that needs a line there. A prompt theme loads itself from it. A language version manager
 sets a variable and sources its loader. A toolchain puts its directory on `PATH`. A desktop module
 names the browser. Today all of these sit in one hand-written file, and the shell module as written
 carries some of them in its own block and loads others only "if a module placed them". Nothing says
 how they get placed.
 This effort asks four things:
 1. **How a module contributes to the shell**: what it declares, who composes it, and in what order it
   lands.
 2. **Where the environment lives.** Variables and `PATH` entries are facts about the account, not
   lines of one shell's syntax. They should reach every shell (interactive or not), the login shell's
   `execute` verb, and programs a graphical session starts.
 3. **Where the operator's own lines go,** so that assigning the shell module loses nothing the
   machine does today.
 4. **Which part of a file the mesh owns.** ADR 0174 calls the kept region the operator's; the host and
   to-be 38 implement the inverse (the mesh owns a marked block, and everything outside it is the
   operator's). The record this becomes says which.
 ## Why
 Rolling out the shell module (to-be 38 WP5) was stopped on 2026-10-04 after a review of what assigning
 it would do. Measured in [01](01-what-the-shell-file-holds-today.md):
 - Every machine carries the same predecessor-written startup file, so the module's block would be
  appended after its own older copy and everything would run twice.
 - The block drops lines the machines rely on today.
 - Nothing installs the prompt theme or the plugins the block loads.
 - The `execute` verb runs a non-interactive login shell, which never reads the file the block is
  written into.
 The operator's direction: other modules must be able to plug themselves into the shell; the prompt
 becomes its own module; assigning the shell module must lose no functionality; and the environment,
 `PATH` above all, needs an answer of its own.
 ## What it touches
 - The manifest. A contribution to the shell is either a new use of the existing `contributes` /
  `receives` pair or a new gathered field like `jails` (to-be 31).
 - The controller's composition, if the controller assembles the text.
 - The `login-shell` seat (ADR 0176): what a holder must do with what is contributed to it, and
  whether a module or the mesh declares the seat. Research 023 asks the related question of a seat
  naming the files its holder owns.
 - ADR 0174's wording of the kept region, and ADR 0182's classification of the paths under a home.
 - The zsh module, and the modules this makes possible: the prompt, a version manager, a toolchain.
 ## Documents
 - [01 — What the shell file holds today](01-what-the-shell-file-holds-today.md): evidence.
 - [02 — How a module plugs in](02-how-a-module-plugs-in.md): the options and the starting position.
@@ -0,0 +1,103 @@
 # 01 — What the shell file holds today
 Measured 2026-10-04 on the four machines of one installation: two servers and two workstations. All
 four have the account's login shell set to zsh, zsh installed from the distribution, and a
 predecessor-written startup file. The predecessor is retired, so nothing manages these files any more.
 ## The startup file is the same everywhere
 The account's `~/.zshrc` is **byte-identical on all four machines**: 102 lines, one checksum.
 `~/.zshrc.local`, which the last line of `~/.zshrc` sources, comes in **two variants**: one shared by
 both servers, and one shared by both workstations. So the "per-machine" part is really a
 per-*kind*-of-machine part.
 The predecessor produced these from one module with two *flavors*: a prompt flavor and an
 autocomplete flavor, each of which swapped in a different local file. Its install hook also:
 - cloned the prompt theme and three plugins from their upstream repositories into `~/.zsh/`;
 - installed fonts;
 - changed the login shell.
 On the workstations the theme and plugins are still on disk, left over and now owned by nothing. The
 servers have none of them.
 ## What the 102 lines are
 Sorted by who should own each line once the machine is modules:
 | Lines today | What they are | Natural owner |
 |---|---|---|
 | `EDITOR`, `VISUAL`, `XDG_CONFIG_HOME`, `PATH` gaining `~/.local/bin` and two script directories | the account's environment | the shell's default, or the environment itself |
 | `PATH` gaining a toolchain's directory | environment, for one tool | the toolchain's module |
 | a version manager's directory variable plus sourcing its loader | environment *and* shell code | the version manager's module |
 | two variables naming the operator's own script library | environment, the operator's own | the operator |
 | a variable that turns off an agent's terminal-title handling | environment, for one tool | the agent's module |
 | the terminal title hook, keybindings, `dircolors`, the `ls`/`grep` aliases, `ll`/`la`/`l`, a container-run alias, two disk-usage functions, two port aliases | interactive shell behaviour | the shell's default |
 | the prompt's instant-prompt cache, the theme, the prompt's own configuration file | shell code, order-sensitive (instant prompt first) | the prompt module |
 | autosuggestions, syntax highlighting (and, unloaded, an autocomplete plugin on disk) | shell code, order-sensitive (syntax highlighting last) | a plugin module, or the prompt module |
 | sourcing `~/.zshrc.local` | the operator's hook | the operator |
 The workstation variant of the local file adds:
 - more environment: a desktop toolkit theme, a file manager's plugin list, `BROWSER`, `VISUAL`
  overridden to a graphical editor, a language toolchain's binary directory on `PATH`;
 - two pieces of shell code: one that pads the prompt to the bottom of the terminal under a display, and
  one that sources a function file another module places;
 - a hook sourcing a further per-node file.
 The server variant holds only that last module-placed source line.
 **Count:** a workstation runs 65 non-comment lines from the two files (53 shared, 12 local); a server
 runs 54. Of a workstation's 65:
 - about a quarter (15) are environment;
 - about half are interactive defaults no other module cares about;
 - the remaining quarter is other modules' code and hooks (a prompt, plugins, a version manager, an
  agent's functions), loaded from the shell file only because there was nowhere else to put it.
 ## The shell module as written
 The `zsh` module of to-be 38 WP5 (catalogue change, unmerged):
 - writes one block, appended at the end of `~/.zshrc`, holding a subset of the shared file:
  - its environment lines, minus the toolchain directory, the version manager and the agent variable;
  - the title hook, keybindings and the most common aliases, minus the port aliases;
  - guarded `source` lines for the theme and two plugins *if present*;
  - the source of `~/.zshrc.local`.
 - assigned to any of the four machines, appends that block after the identical lines already there, so
  every line in it runs twice, `~/.zshrc.local` included.
 - on the servers, the guarded prompt lines find nothing; nothing installs the theme anywhere.
 ## Which startup file reaches what
 zsh's startup order, and what each path through it reads:
 | started as | reads |
 |---|---|
 | interactive login (a console, ssh with a terminal) | `.zshenv`, `.zprofile`, `.zshrc`, `.zlogin` |
 | interactive non-login (a new terminal window) | `.zshenv`, `.zshrc` |
 | non-interactive login: `zsh -lc …`, what the `execute` verb runs | `.zshenv`, `.zprofile`, `.zlogin`, **not** `.zshrc` |
 | non-interactive: a script, `ssh host command` | `.zshenv` only |
 So an environment written into `.zshrc` reaches neither `execute` nor a script. The distribution's
 system-wide login profile, which zsh's system `zprofile` sources, only ever *appends* to `PATH` when an
 entry is missing. An entry the account's `.zshenv` puts first therefore survives a login.
 A graphical session's programs (a launcher, a bar, a window manager's key bindings) are started from the
 display manager and the service manager, not from a shell, and read none of these files. The service
 manager's own place for the account's environment is `~/.config/environment.d/`. Today it holds nothing
 on any of the four machines, so a program launched from the window manager does not see `PATH` entries
 that a terminal does.
 ## What the mesh already has for "many modules, one file"
 Measured over the catalogue's 69 module definitions:
 | mechanism | used by | shape |
 |---|---|---|
 | `contributes` / `receives` | 28 contribute, 15 receive | A consumer contributes **facts** keyed by a requirement. The provider receives all of them as one file in the mesh's own format, and **renders them itself**. "The controller does not know what a reverse proxy is." |
 | `listens` / `filtering` | 40 declare listens, 1 composes | The controller derives the whole firewall rule set from every module's ports and writes it where the holder asks. |
 | `jails` / `jailing` | 3 declare, 1 composes | Each module supplies its jail **in the tool's own format**. The controller assembles them, sorted, into the one file the holder names. |
 | `into: block` on a file | 2 | One module's marked region inside a file something else owns. Text outside the region is kept byte for byte. Placement is at the end, or at the start. |
 None of these is a contribution of shell code or of environment today.
@@ -0,0 +1,164 @@
 # 02 — How a module plugs in
 Four questions, taken one at a time: the environment, shell code, the operator's own lines, and
 ordering. Each has the options weighed and a starting position. The positions were set with the
 operator on 2026-10-04 and are what this effort tests, not what it has decided.
 ## 1. The environment: variables and `PATH`
 A variable or a `PATH` entry is a fact about the account. It holds whichever shell is the login shell,
 and it is wanted by:
 - every shell, interactive or not;
 - the login shell's `execute`;
 - a graphical session's programs.
 [01](01-what-the-shell-file-holds-today.md) measures that `.zshrc` reaches only the first kind, and
 only interactively.
 | | option | for | against |
 |---|---|---|---|
 | E1 | Each module writes lines into the shell's rc file (today) | nothing new | misses `execute`, scripts and the graphical session; written in one shell's syntax, so a second shell module starts over |
 | E2 | A module **contributes environment facts** (a variable and its value; a `PATH` entry and its position). The controller gathers them per node. The login-shell holder renders them into its shell's always-read file (`~/.zshenv` for zsh) | reaches every zsh, `execute` included; a contributor names no path and no shell; a second shell renders the same facts | a graphical session still sees none of it |
 | E3 | E2, and the gathered facts are **also** written as the service manager's user environment (`~/.config/environment.d/`) | the graphical session sees the same `PATH` as the terminal | two renderings of one fact set; the user manager reads it only when it starts |
 | E4 | One composed file in the service manager's `environment.d` syntax, sourced by the shell with export-all | one file, two readers | ties the shell to the service manager's syntax, which is close to POSIX assignments but not equal (its `${VAR:-default}` and quoting rules differ); a value with a space breaks one reader or the other |
 **Starting position: E2, with E3 as the second step.**
 - The facts are the contribution; each reader renders them in its own syntax. This is the
  `contributes` / `receives` boundary applied once more: the controller does not know what a shell is.
 - E3 then needs no new contribution, only a second renderer. Its natural owner is the service-manager
  seat's holder (ADR 0177), not the shell.
 - Whether the controller does the rendering or the holder's own code does is question 5 below.
 What the shell module itself sets (`EDITOR`, `XDG_CONFIG_HOME`, `~/.local/bin` on `PATH`) is the
 shell module's own contribution, made the same way rather than written as lines. Once issue 168 closes,
 the values a person varies become settings of whichever module contributes them (ADR 0174).
 ## 2. Shell code: a prompt, plugins, a version manager's loader
 This *is* one shell's syntax, and order matters: a prompt's instant-prompt cache must run first, and
 syntax highlighting last.
 | | option | for | against |
 |---|---|---|---|
 | S1 | **A contribution of code for one shell** (the shell it is for, the code, a slot), gathered by the controller and placed inside the holder's block in slot order. The same shape as `jails`, which a module supplies in fail2ban's own format and the controller assembles | a contributor names no path; the order is declared and checkable; unassigning the contributor removes its code at the next composition; a node holding fish simply has no zsh code rendered, and the resolver can say so | the controller gains one more gathered field; code for a shell travels in the declaration (in the clear, so no secrets in it, as for any file) |
 | S2 | **A drop-in directory**: each module places its own `~/.zsh/rc.d/NN-name.zsh`, and the shell's block sources the directory | no controller change; each file is its module's own, removed when undeclared | every contributor hard-codes a path inside the shell module's territory, against ADR 0112's spirit; order is a naming convention nothing checks; nothing ties the file to the shell actually being zsh |
 | S3 | Contributions as facts the holder renders (`contributes`/`receives` proper) | one mechanism with question 1 | code is not a fact; the holder would only paste it, which is S1 with an extra file |
 **Starting position: S1.** It makes one contribution, *to the shell*, with three parts: variables,
 `PATH` entries, and code for named shells.
 - A prompt module contributes zsh code in the first slot, and its own configuration file is its own
  owned file (ADR 0182).
 - A version manager contributes its directory variable, and its loader as code for each shell it
  supports.
 - A toolchain contributes a `PATH` entry and nothing else.
 What has to be settled: what a contribution is *addressed to*. It could be the `login-shell` seat, so
 that whichever module holds it renders the contributions, or a requirement the shell module provides.
 Section 6 covers that.
 ## 3. The operator's own lines: the "local override"
 Assigning the shell module must lose nothing the machine does today. That has two halves.
 **What is common is the module's default, not an override.** The startup file is identical on all four
 machines ([01](01-what-the-shell-file-holds-today.md)). A line every machine has is the shell module's
 default, or another module's contribution. It is not a local override that a person would keep in step
 on every machine by hand. Most of today's file therefore moves into the shell module's block and into
 the contributions above. Little of it stays the operator's.
 **What is the operator's is everything outside the mesh's block.** The host already works this way:
 - the mesh's region is the marked block;
 - text outside it is kept byte for byte, and checked unchanged;
 - the region is given back when the module goes.
 | | option | for | against |
 |---|---|---|---|
 | O1 | The mesh's block at the **start** of the file; the operator's lines after it | the operator's lines run last and win, which is what an override means; already supported (`at: start`) | a file the operator later rewrites must keep the markers; the host refuses a broken pair rather than guess |
 | O2 | A named operator region *inside* a file the mesh writes whole (ADR 0174's wording) | the file is entirely the mesh's except one hole | the opposite of what the host implements; a file a person already owns becomes the mesh's |
 | O3 | Only `~/.zshrc.local`, sourced from the block; `~/.zshrc` the mesh's whole | one obvious place | takes over a file the person owns today; ADR 0182 classifies the shell's own file as *written into*, not owned |
 **Starting position: O1.** `~/.zshrc.local` keeps working because the operator's own lines source it,
 not because the mesh's block does.
 The record this effort becomes corrects ADR 0174's description of the kept region as a **progressive
 insight**: the decision stands (a node varies a module by settings or by the operator's own lines,
 never by an edit), and only its description of which side is marked changes.
 **The one-off migration** is a person's act, listed in the module's documentation (ADR 0182):
 - remove from today's file every line the block or a contribution now carries;
 - keep the rest below the block.
 Until a prompt module and the other contributors exist, the lines they will carry stay among the
 operator's own. Nothing is lost at any step.
 ## 4. Order
 Order matters only for code. Variables are set before any code runs, and `PATH` entries carry their own
 position: before or after the system's.
 | | option | for | against |
 |---|---|---|---|
 | R1 | Numbers (`10`, `50`, `90`) | familiar | every contributor guesses a number; collisions are silent |
 | R2 | **A few named slots**, `first` / `normal` / `last`, with the module name breaking ties | the prompt says `first` and highlighting says `last` because that is what they mean; the composed result is the same bytes every time | three slots may not be enough |
 **Starting position: R2.** Inside the shell module's block, the order is:
 1. the environment;
 2. the `first` slot;
 3. the shell module's own defaults;
 4. the `normal` slot;
 5. the `last` slot.
 The operator's lines come after the block, as option O1 says.
 ## 5. Who renders: the controller or the holder's code
 The holder could render the contributions itself:
 - by its bundle writing the files when what it receives changes (ADR 0182's third class, "written by
  the module's own process");
 - or by the controller rendering them into the holder's block at composition, as it assembles `jails`.
 **Starting position: the controller assembles, the holder states the format.**
 - *Assembling* is what the controller already does for jails: sort the pieces and concatenate them into
  the holder's region.
 - *Formatting* an environment fact as a line of shell is the holder's knowledge. The holder declares it
  as a pattern beside its claim, for example "a variable renders as `export NAME=value`", so the
  controller learns no shell.
 - This keeps the module bundle-free for its files, and keeps the composed result visible in the
  declaration before a machine applies it.
 To be tested: whether a pattern can express `PATH` composition (prepend versus append, de-duplication)
 cleanly, or whether that one case forces holder code.
 ## 6. What a contribution is addressed to
 | | option | for | against |
 |---|---|---|---|
 | A1 | The `login-shell` seat: the seat's protocol says a holder renders the shell contributions on its node | a contributor depends on "the login shell", not on zsh; works the same for any holder | the seat today is declared by the zsh module itself (ADR 0126). A second shell module may only claim it, never declare it, and the seat exists only while zsh's definition is registered |
 | A2 | A requirement the shell module provides (`contributes` keyed by it, as the reverse proxy is) | an existing mechanism | a contributor on a node with no shell module fails to resolve, though a prompt with no shell is merely useless |
 **Starting position: A1,** with the seat moved into the mesh's own seat set beside the service manager.
 A shell is as universal a role as a service manager, and a protocol that now carries a rendering duty
 should not depend on one module's registration. Research 023 (a seat's protocol naming what its holder
 owns) is the general form of this, and the two should not decide it twice.
 ## Open questions
 - Whether a contribution may be conditional on a capability: the workstation-only environment (a
  browser, a toolkit theme) is a desktop module's contribution, which arrives only where that module is
  assigned. Measured, this may need nothing new.
 - How the prompt module and a plugin module divide the plugins. Packaging decides it as much as
  ownership: the plugins come from upstream repositories, not distribution packages, on these machines.
 - Whether the `execute` verb should read the interactive file at all once the environment is in
  `.zshenv`. The position here is no: a non-interactive login shell plus the environment is what a
  command needs, and the prompt's code should not run for it.
 - How a contribution reaches a second shell assigned beside the holder, which to-be 38 WP5 names as the
  first follow-up record. Under A1 a non-holder renders nothing, so the question becomes whether a
  non-holding shell module may render contributions for interactive use.