admin/felhom.eu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: remove a gate criterion that could never pass, and close three register rows

Browse Source 
PART 1 — the release gate.

G7 required the packaged .deb to sha256-match the one built from committed source. That is
unsatisfiable BY CONSTRUCTION: dpkg-deb stamps the build time into every archive, so two builds of
byte-identical source differ. It was already failing when the 1.26.1 release ran it. A criterion
nobody can satisfy gets waived once and read as advisory ever after — which is how R-29's shelf of
never-run gates was built. Sub-clause dropped, reason recorded in G7's own note the way G6's
amendment was, so a future reader can restore it if SOURCE_DATE_EPOCH ever makes it meaningful.

RULING ASKED FOR — is payload integrity covered by G9 alone? NO, and G9 is widened rather than a new
criterion invented. The package ships TWO payload files (build-deb.sh:54-55); G9 checked only the
script. The systemd UNIT was covered by nothing: G7 covered the container, G8 covers the postinst
behaviourally, G13 covers directory presence. The unit is not incidental — its After=, its
ConditionPathExists= and its Restart= decide WHEN AND WHETHER day-0 runs at all, so a drifted unit
would have shipped silently. Same shape as the /etc/felhom miss that G13 exists to prevent: a check
that proved the thing present and said nothing about what it depended on. The check passes today.

G13 moved to sit after G12 — it was minted late and left between G10 and G11.

PART 2 — register dispositions. BASELINE DISCREPANCY, reported rather than worked around: only R-128
had a row. R-154 and R-155 had NO row in either file — minted in a spike document and never carried
across, which is R-123's class, not the drift the task described. Rows created, closed, with the
reasoning, because in all three cases the reasoning is the durable part:

  R-128 closed by CORRECTING a false claim, not by making the assertion real — the coupling does not
        exist and asserting it would invent a constraint. Flagged so nobody 'restores' it.
  R-154 closed with the measurement and where it now lives in pushed source.
  R-155 NARROWED, not deleted — unchanged for FELHOM_MENU=single, inapplicable to release. Flagged so
        the guard is not later removed wholesale on the strength of 'R-155 closed it'.

Documentation only: no code, no build, no ISO, no upload, no box touched.
This commit is contained in:
authentik Default Admin
2026-07-31 21:31:54 +02:00
parent f2fc76ec4b
commit e9a74a0019
3 changed files with 59 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/runbooks/iso-release-gate.md
+53 -18
View File
@@ -134,12 +134,29 @@ osirrox -indev "$ISO" -find /proxmox/packages 2>/dev/null | grep -c 'felhom-'
osirrox -indev "$ISO" -extract /proxmox/packages/<pkg>.deb /tmp/p.deb
dpkg-deb -I /tmp/p.deb | grep -E '^ (Package|Version):'
```
**PASS =** exactly one `felhom-*.deb`, its version recorded in the manifest, and its sha256 matching
the package built from committed source.
**PASS =** exactly one `felhom-*.deb`, its version recorded in the manifest, and **no `Depends`**
(the payload is a script and a unit file; the binaries it calls run at first boot, not at postinst
time, so there is nothing for `dpkg --configure -a` to order against).
*Why:* Spike 4 measured that this is the only delivery mechanism that survives an interactive install
(`[first-boot]` is never placed on the system — `Config.pm:118`, `Install.pm:746`, `:1360`).
> **Amendment, 2026-07-31 — a sub-clause that could never pass is removed, and the reason recorded.**
> This criterion originally also required *"its sha256 matching the package built from committed
> source"*. **That is unsatisfiable by construction, not by accident:** `dpkg-deb` stamps the build
> time into every archive, so two builds of byte-identical source produce different `.deb` hashes.
> The check was written expecting reproducibility the tool does not offer, and it was already failing
> when the 1.26.1 release ran it.
>
> A criterion nobody can satisfy is worse than no criterion: it gets waived the first time and read
> as advisory ever after. This project already carries a shelf of gates that exist and are never run
> (**R-29**), and that is exactly how they got there.
>
> **The payload-integrity claim it was reaching for is carried by G9**, which compares the *contents*
> rather than the container — see G9's own amendment, which widens it to cover both payload files.
> If `dpkg-deb` is ever made reproducible here (`SOURCE_DATE_EPOCH`), this sub-clause can be restored
> and would then mean something.
### G8 — The postinst cannot fail, and cannot need what it hasn't got
```bash
@@ -157,17 +174,35 @@ installer's DHCP happened to hold, so a box installed with the cable out has non
exits non-zero surfaces as an error in the middle of a customer's install — far worse than the stub
not running. `set -e` is banned because it converts any unexpected non-zero into exactly that failure.
### G9 — `felhom-bootstrap.sh` matches repo HEAD byte-for-byte
### G9 — **both** payload files match repo HEAD byte-for-byte
Extract the script from the package and compare:
Extract each payload file from the package and compare:
```bash
dpkg-deb --fsys-tarfile /tmp/p.deb | tar -xO ./usr/local/sbin/felhom-bootstrap.sh | sha256sum
dpkg-deb --fsys-tarfile /tmp/p.deb | tar -xO ./usr/local/sbin/felhom-bootstrap.sh | sha256sum
sha256sum scripts/iso/felhom-bootstrap.sh
dpkg-deb --fsys-tarfile /tmp/p.deb | tar -xO ./lib/systemd/system/felhom-bootstrap.service | sha256sum
sha256sum scripts/iso/felhom-bootstrap.service
```
**PASS =** identical.
**PASS =** both identical.
*Why:* it is the one genuinely frozen, drift-capable payload — everything else the box uses is fetched
at run time from `main`. An ISO in a drawer for six months still runs this exact script.
*Why:* these are the genuinely frozen, drift-capable payloads — everything else the box uses is
fetched at run time from `main`. An ISO in a drawer for six months still runs exactly these.
> **Amendment, 2026-07-31 — widened from one file to two, because the unit was uncovered.**
> G9 originally checked only `felhom-bootstrap.sh`. The package ships **two** payload files
> (`scripts/iso/pkg/build-deb.sh:54-55`), and the second one — the systemd unit — was checked by no
> criterion at all: G7 covered the container (and its sha sub-clause was unsatisfiable anyway), G8
> covers the postinst *behaviourally*, G13 covers directory *presence*.
>
> The unit is not incidental. Its `After=network-online.target pve-cluster.service pveproxy.service`,
> its `ConditionPathExists=!/etc/felhom/.bootstrap-done` and its `Restart=on-failure` are what decide
> **when and whether day-0 runs at all**. A drifted or hand-edited unit would have shipped silently —
> the same shape as the `/etc/felhom/` miss that G13 exists to prevent, where a check proved the thing
> present and said nothing about what it depended on.
>
> The check passes today: `build-deb.sh` installs both files verbatim from the same source directory.
> **Note it self-asserts only the script** (`build-deb.sh:86-89`) — extending that assertion to the
> unit is a code change, filed as an observation rather than made here.
### G10 — The profile and every build input are committed
@@ -181,6 +216,16 @@ 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).
### 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
`https://iso.felhom.eu/<name>` checksums to the same value. The round trip is the claim — a local
checksum proves only that the local file is what it is.
### G12 — The bucket stays private
**PASS =** the bucket's `Public Access` remains **Disabled**; the custom domain is the only public path.
### G13 — every directory the payload writes into is IN the package
```bash
@@ -199,16 +244,6 @@ it. The installed box registered at the hub, failed to persist the token, and th
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
`https://iso.felhom.eu/<name>` checksums to the same value. The round trip is the claim — a local
checksum proves only that the local file is what it is.
### G12 — The bucket stays private
**PASS =** the bucket's `Public Access` remains **Disabled**; the custom domain is the only public path.
---
## Result recording