diff --git a/documentation/runbooks/iso-release-gate.md b/documentation/runbooks/iso-release-gate.md index a081320..70f41d5 100644 --- a/documentation/runbooks/iso-release-gate.md +++ b/documentation/runbooks/iso-release-gate.md @@ -181,6 +181,24 @@ git rev-parse HEAD; git rev-parse origin/main # equal reference boxes cannot be rebuilt from `main`. A published image must never reach that state, and R-144 records a lab ISO that already has (`nested-probe`'s profile no longer exists). +### G13 — every directory the payload writes into is IN the package + +```bash +dpkg-deb -c /tmp/p.deb | awk '{print $6}' | grep -x './etc/felhom/' +``` +**PASS =** present, along with `./usr/local/sbin/` and `./lib/systemd/system/`. + +*Why, and it is the most expensive lesson in this file:* the first release build passed G7, G8 **and +G9** and still produced a box that could never pair. `felhom-bootstrap.sh` writes its appliance token +(`:431`), its pairing code (`:435`) and `.bootstrap-done` into `/etc/felhom/`, and the package did not +ship that directory — the old `stub-first-boot.sh` had created it explicitly and the packaging dropped +it. The installed box registered at the hub, failed to persist the token, and then returned +`HTTP 401 — still retrying` forever, with no claim code ever shown. + +**G9 proves the payload is the right payload. It says nothing about what the payload depends on.** +Any future criterion of the form "the correct file is present" should be paired with one of the form +"and everything it needs at run time is too". `build-deb.sh` asserts this itself and is red-proofed. + ### G11 — A published checksum, and a verified round trip **PASS =** the `.sha256` and the manifest are uploaded beside the ISO, **and** the file downloaded from diff --git a/scripts/iso/build-felhom-iso.sh b/scripts/iso/build-felhom-iso.sh index 555b9dd..f6534f9 100755 --- a/scripts/iso/build-felhom-iso.sh +++ b/scripts/iso/build-felhom-iso.sh @@ -48,7 +48,7 @@ set -euo pipefail # does not exist: the ISO is a frozen artifact, while felhom-host-install.sh is fetched at RUN TIME # from the website's git-sync of `main` (R-94/R-110), so whatever version an ISO carries, the script a # box runs is always current. Coupling them would invent a constraint. The claim is corrected instead. -ISO_VERSION="1.26.0" # the ISO's own version. INDEPENDENT of felhom-host-install.sh's SCRIPT_VERSION, +ISO_VERSION="1.26.1" # the ISO's own version. INDEPENDENT of felhom-host-install.sh's SCRIPT_VERSION, # which is fetched at run time from main and is not frozen into the image. IMAGE="${FELHOM_ISO_ASSISTANT_IMAGE:-felhom-iso-assistant:trixie}" HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" diff --git a/scripts/iso/pkg/build-deb.sh b/scripts/iso/pkg/build-deb.sh index be16087..8502d65 100755 --- a/scripts/iso/pkg/build-deb.sh +++ b/scripts/iso/pkg/build-deb.sh @@ -14,6 +14,7 @@ # CONTENTS — exactly two files, and deliberately not three: # /usr/local/sbin/felhom-bootstrap.sh 0755 (byte-identical to scripts/iso/felhom-bootstrap.sh) # /lib/systemd/system/felhom-bootstrap.service 0644 +# /etc/felhom/ 0755 (empty — the bootstrap's runtime state dir) # The old stub also wrote /etc/felhom/bootstrap.env (0600). This package does NOT, because # felhom-bootstrap.sh:91 reads it only `if [[ -r ... ]]` and its defaults at :95-96 are EXACTLY what # the generic pairing env set (build-felhom-iso.sh:257-258). Shipping it would add a 0600 file to a @@ -34,6 +35,14 @@ WORK="$(mktemp -d "${TMPDIR:-/tmp}/felhom-deb.XXXXXX")" trap 'rm -rf "$WORK"' EXIT ROOT="$WORK/pkg" install -d -m 0755 "$ROOT/DEBIAN" "$ROOT/usr/local/sbin" "$ROOT/lib/systemd/system" +# /etc/felhom is the bootstrap's RUNTIME STATE directory, and shipping it is not optional: +# felhom-bootstrap.sh writes the appliance token there (:431), the pairing code (:435) and +# .bootstrap-done (the unit's ConditionPathExists). The old stub created it explicitly +# (stub-first-boot.sh: `install -d -m 0755 /etc/felhom /usr/local/sbin`). Dropping the env FILE from +# this package was correct; dropping the DIRECTORY with it was not — a box installed without it +# registers at the hub, fails to persist its token, and then 401s forever without ever showing a +# claim code. Measured on a real interactive install, 2026-07-31. +install -d -m 0755 "$ROOT/etc/felhom" sed "s/^Package: /Version: $VERSION\nPackage: /" /dev/null >/dev/null 2>&1 || true { head -1 "$HERE/debian/control"; echo "Version: $VERSION"; tail -n +2 "$HERE/debian/control"; } \ @@ -67,6 +76,13 @@ fi if [[ "$(tail -1 <<<"$POST_RAW")" != "exit 0" ]]; then echo "build-deb: postinst does not end 'exit 0' (G8)" >&2; exit 3 fi +# G13 — every directory the payload writes into must be IN the package. G9 proves the script is the +# right script; it says nothing about the directories that script needs. +for d in ./etc/felhom/ ./usr/local/sbin/ ./lib/systemd/system/; do + if ! dpkg-deb -c "$DEB" | awk '{print $6}' | grep -qx "$d"; then + echo "build-deb: $d is not in the package (G13) — the payload would fail at run time" >&2; exit 3 + fi +done A="$(dpkg-deb --fsys-tarfile "$DEB" | tar -xO ./usr/local/sbin/felhom-bootstrap.sh | sha256sum | cut -d' ' -f1)" B="$(sha256sum "$ISO_DIR/felhom-bootstrap.sh" | cut -d' ' -f1)" if [[ "$A" != "$B" ]]; then