novox/hq

Files

T

jschoubben f1b1cd9aa0 Review: three ADRs no longer said what we had concluded

A sweep for claims overtaken by the last few days. Annotated rather than
rewritten, following the pattern already in 0049 -- what changed and why is the
useful part, and an accepted record should not quietly become something else.

0057's init section was wrong on all three of its claims. It said the host
needs FOUR things from an init; 0061 reduced that to one. It said every machine
the mesh targets already has systemd; Alpine does not, and it is the intended
first node. It said there is no second init to abstract over; there is now, and
the answer is still not an abstraction -- it is a four-line file per system.
What survives is the part that was always right: an init is not a dependency in
0041's sense, because it is not installed, it is what the machine already is.

0048 named Docker as the container runtime. It is now docker or podman,
detected rather than chosen -- because adoption keeps what a machine already
has, so naming one contradicted a rule already decided. That row is the only
one of the five that names two, and the record now says why.

0060 claimed the bundle is portable across operating systems. Its mechanism is;
its contents are not -- package names, unit names, service names all differ, so
an Arch host embeds an Arch bundle. That was my error, and it is the exact
confusion behind the question that found it.

The design layer had the same drift: 07 and 09 said "Docker" where they meant a
container runtime, 09 said systemd restarts the host after an upgrade when the
launcher does, and both install snippets assumed Arch. They now show Alpine and
Arch side by side, which makes the point better than prose did -- step 1
differs per system, step 2 never does.

Checked and NOT changed: 0047's "the vocabulary grows by one shape" is a claim
about the rate, not the count, and is still true. 0037 lists docker among tools
the host manages, which it does. 0041 says nothing about either.

2026-08-28 00:43:47 +02:00

7.5 KiB

Raw Blame History

status, date, deciders, reconstructed, extends

status	date	deciders	reconstructed	extends
accepted	2026-08-28	jochen	false	0057-the-host-is-a-root-service-installed-as-a-package.md

60. The host is built per operating system

Context

Three of the host's six shapes need something from the machine: service needs a service manager, package needs a package manager, container needs a container runtime. The other three — file, directory, action — need only a filesystem and the ability to run something.

The host names those capabilities generically and implements them specifically. The detector reports container-runtime, package-manager, service-manager; the appliers call docker, pacman and systemctl. So the design says capability and the code says Arch, and nothing records which of those is the intent.

The question that surfaced it: what happens on a machine that has podman, or one that does not run systemd? And underneath it, a live contradiction — research 012 decides that on conflict during adoption the machine's configuration is kept, so a machine with podman keeps podman, and then the container applier calls docker and fails.

Considered options

Abstract each capability behind an interface. One host, adapters per service manager and package manager. Rejected, and the reason is correctness rather than effort: the service applier reads LoadState to tell not installed apart from stopped, which is what stops it reporting absence as success. An interface spanning systemd and OpenRC degrades to what both can express, and the lowest common denominator is exactly where that fault lives.
Support one operating system and say so. Honest, and it makes every other machine permanently out of scope rather than not-yet.
A host per operating system. Chosen.

Decision

The host is built for an operating system family, and systemd and pacman are the Arch host's implementation rather than abstractions the mesh has to grow.

mesh-host-arch-x86_64        pacman · systemctl · docker
mesh-host-debian-x86_64      apt    · systemctl · docker      (when there is a machine)
mesh-host-alpine-x86_64      apk    · rc-service · podman     (when there is a machine)

These are not independent choices and treating them as such was the error. A machine has pacman because it is Arch. The package manager, the service manager and the packaging format arrive together, as one decision somebody made when they installed the operating system.

Almost all of it is shared

Not a rewrite per operating system. The declaration vocabulary, the store, the apply loop, the read-back discipline, the refusal model and the link are all portable. What differs is two appliers, and the rest is compiled around them.

The bundle is the exception, and an earlier version of this record wrongly listed it as portable. Its mechanism is — one embedded declaration, applied with no mesh present. Its contents are not: package names, unit names and service names all differ, so an Arch host embeds an Arch bundle and an Alpine host an Alpine one. That is the same thing this record says about package names one section down, and missing it here is what made the distinction hard to see.

The control plane names the package, because the host does not decide

A container runtime is docker on Arch and docker.io on Debian. Mapping this node needs a container runtime to a package name is deciding, which ADR 0037 puts outside the host.

It needs no new mechanism: the profile already reports what the machine is, so the declaration a node receives is already tailored to that node. The host receives a package name and installs it.

A host that cannot implement a shape refuses it

The interesting case is not Debian, it is Android — no service manager it will lend us, no package installation, usually no root. Such a host implements file, directory and action, and nothing else.

That needs no new mechanism either. A host already refuses a type it does not know; this host does not implement package is the same refusal with a different reason, and the profile reports which shapes it implements so the control plane never sends one it cannot do.

file, directory and action are the portable floor. They work anywhere there is a filesystem and a way to run something, which makes a partial host a real thing rather than a broken one.

Consequences

Each implementation stays as sharp as its operating system allows. The LoadState distinction survives because the Arch host knows it is systemd. Nothing is degraded to fit an interface spanning systems we do not run.
Delivery already worked this way, which is the strongest sign this is the right seam: the host ships as a package from the mesh's own repository (ADR 0058), and a .pkg.tar.zst is an Arch artifact. A per-OS binary is consistent with what was already decided rather than an addition to it.
The container runtime is a choice within a host, not an OS split — Arch runs docker or podman — and it is detected, not declared, because adoption keeps what the machine already has. Two are supported.

This is the opposite answer to the one above, for a reason rather than by preference. Abstracting service managers is lossy: systemd and OpenRC are different models, and LoadState has no equivalent. Container runtimes deliberately converged on one CLI, so almost nothing is lost — checked against podman 6.1.0, run, rm -f and docker's own template syntax for reading state and labels all work unchanged. Only the probe differs ({{.ServerVersion}} against {{.Version.Version}}), which makes it a two-entry lookup rather than an interface.

One difference is not in the CLI and would have shipped silently. Podman accepts --restart unless-stopped and records it, and has no daemon to act on it: containers do not come back after a reboot unless podman-restart.service is enabled, which it is not by default. Every command reports success and the effect does not happen. That belongs in the declaration — a node using podman is told to enable that unit — rather than in the host, which keeps the host dumb and puts the difference where a person can read it.
A second operating system is now additive rather than a redesign — write two appliers, ship a package. And it will be designed against a real machine rather than a guess, which is the point of not building the abstraction now.
The profile has to report the operating system, and today it reports capabilities without saying which system they belong to. Small, and needed before the control plane can tailor a package name.
Nothing states the machine requirements yet. A machine missing a capability fails at apply time rather than being refused up front, even though the host already detects it. That is a gap this record makes visible and does not close.

References

ADR 0037 — why the host is handed a package name.
ADR 0041 — one static binary, now per system as well as per architecture.
ADR 0058 — delivery, which was already per-OS.
Research 012 — adoption keeping the machine's configuration, which hardcoding a runtime contradicts.

7.5 KiB Raw Blame History