Merge pull request 'To-be 42: the kernel module holds the kernel's run-time settings, huge pages first (ADR 0369, issue 746)' (#357) from design/42-kernel-module-holds-runtime-settings into main

03-DESIGN/01-to-be/42-the-machines-modules-in-order.md

@@ -2,8 +2,9 @@
 layer: to-be
 status: in-progress
 code: [mesh-catalog, mesh-controller, mesh-host]
-updated: 2026-10-12
+updated: 2026-10-14
 decisions:
+  - "ADR 0369"
   - "ADR 0303"
   - "ADR 0215"
   - "ADR 0173"
@@ -75,7 +76,7 @@ In order:
 | 8 | `docker` | the runtime's packages, base configuration, group | four configurations, one owner on one machine |
 | 9 | `ssh-client` | everything under `~/.ssh` (research 027/03) | a predecessor's entries winning over the mesh's; stale keys |
 | 10 | scripts | the operator's own scripts, shared and per role (research 027/03) | under no version control, copied by hand |
-| 11 | `kernel` | kernel, microcode, boot entries | two machines without microcode |
+| 11 | `kernel` | kernel, microcode, boot entries, and the kernel's run-time settings per machine (transparent huge pages first) | two machines without microcode; huge pages left at the distribution's `always` on a machine whose slow disks they flood (issue 746) |
 
 `systemd`, `pacman` and `docker` hold the three seats that apply resources
 (ADR 0207):
@@ -83,7 +84,19 @@ every module that declares a service, a package or a container depends on them b
 They go on every machine before the rest, and once they have, an unmet dependency is refused rather
 than reported.
 
-`kernel` is last because a mistake in it costs a boot. `docker` holds the runtime seat
+`kernel` is last because a mistake in it costs a boot. Its run-time settings are the exception and come
+first (ADR 0369, issue 746): they change nothing at boot that the kernel does not already accept at run time, and
+each is a per-machine setting whose default is what the kernel boots with, so assigning the module changes
+no machine until that machine is given another value. The first is transparent huge pages. On the
+control-node, with `always`, the journal's memory-mapped files were held in 2 MiB pages, so each small journal
+write cost a 2 MiB write-back; the journal daemon and a log-reading intrusion-prevention service wrote
+gigabytes in minutes onto a mirrored pair of spinning disks that also holds the bus's store, and the
+controller lost its lease. That machine is set to `madvise`. The module writes the mode at boot and, on a
+change, the new value directly; it reads it back and fails its unit if it did not take, gives back the mode
+it found when unassigned, and on a running machine rotates the journal once so the open journal files are
+mapped anew in small pages. How it is checked: the module's tests run its script against
+a stand-in directory, its unit's health is the unit's state, and its tool `kernel_huge_pages` shows the
+mode in force and the file pages each unit holds in huge pages. `docker` holds the runtime seat
 (ADR 0166), with its settings declared as
 ADR 0164 decides and the capability detected as
 ADR 0165 decides; what of the three is not built yet is tracked by issue 398.