Skip to content

Walk the download and the checksum in the operator guide - #211

Merged
iderex merged 1 commit into
mainfrom
release/walk-the-download-and-the-checksum
Aug 27, 2026
Merged

iderex merged 1 commit into
mainfrom
release/walk-the-download-and-the-checksum

Conversation

@iderex

@iderex iderex commented Aug 27, 2026

Copy link
Copy Markdown
Contributor

Closes #42.

What was wrong

docs/operator-guide.md opened its "Getting it" section with three sentences,
and two of them had stopped being true.

git show origin/main:docs/operator-guide.md | sed -n '34,36p'
There is nothing to download. This board publishes no binary, no checksum file
and no release, so nothing on this page tells you how to verify a download, and
whether anything is ever published is not decided. The route that exists is a

Whether anything is ever published is decided:

git show origin/main:docs/decisions/0021-what-this-board-publishes.md | sed -n '5,6p'
This board publishes downloadable release artefacts. They are signed. The
release notes say, in the notes themselves rather than only here, that the

And the reason the download walk could not be written has ended. The last thing
recorded on #42 said a walk written before the artefact names existed would name
files by guessing them. Those names are fixed in the tree now:

git show origin/main:.github/workflows/release.yml | grep -nE 'name="lab_|cp NOTICE|sha256sum \./\* >|THIRD-PARTY|sbom'
146:            name="lab_${TAG}_${goos}_${goarch}"
227:          cp "${first_notices}" "${assets}/THIRD-PARTY-NOTICES.md"
228:          cp "${first_bom}" "${assets}/lab_${TAG}_sbom.cdx.json"
229:          cp NOTICE.md LICENSE docs/privacy.md "${assets}/"
232:          sha256sum ./* > SHA256SUMS

So the walk is written against what that file produces rather than against a
guess, and every asset name in the new section comes from those lines.

What this changes

One file. docs/operator-guide.md gains a download route, a per-platform
checksum check and a pointer to where the signature is verified, and keeps the
checkout route it already had as the one that always works.

The per-platform half is what the issue asks for in as many words - "with the
command written out for each platform, because a checksum nobody knows how to
check is decoration". Linux and macOS get the two spellings of the same tool
with --ignore-missing, which is what lets a reader check the two or three
files they actually downloaded against a checksum file covering eight. Windows
gets Get-FileHash with the Select-String line to compare it against, and
certutil beside it, because neither shell there has a --check equivalent and
the comparison is the reader's to make by eye.

What it deliberately does not do

It does not restate the signature verification. docs/release-notes-preamble.md
carries those commands and where the keys come from, and every release is
published with that text in its notes. A second copy here would be
restated-not-referenced against the one a downloader actually holds, so the
guide points at it and adds the one sentence a reader needs before following it:
do not take the key from the release.

It makes no claim that a release exists, and none has been cut:

gh api repos/Flowfin/lab/releases --jq 'length'
0

gh api repos/Flowfin/lab/tags --jq 'length'
0

The page tells a reader to open the releases page and says that an empty one
means the checkout route is the only one available to them. That sentence is
true today and stays true on the day the first release is cut, which a sentence
asserting either state would not.

The means

Markdown prose in docs/, which is the means every other operator-facing
document on this board already uses and the one the prose rules and the paths
leg of the invariants scan can read. Nothing here needs a mechanism that prose
cannot carry: what the section asserts about the release is checkable against
.github/workflows/release.yml, which is quoted above rather than paraphrased,
and the commands it hands the reader are run on their machine rather than by
anything here.

The gate

Run at the head of this branch, 2edacce:

go build ./cmd/... ./internal/...
go vet ./cmd/... ./internal/...
gofmt -l cmd internal
(no output)
go test -count=1 ./cmd/... ./internal/...
ok  	github.com/Flowfin/lab/cmd/bom	16.688s
ok  	github.com/Flowfin/lab/cmd/contexts	2.160s
ok  	github.com/Flowfin/lab/cmd/lab	5.862s
ok  	github.com/Flowfin/lab/cmd/notices	51.160s
ok  	github.com/Flowfin/lab/cmd/pullrequest	1.394s
ok  	github.com/Flowfin/lab/internal/bom	1.651s
ok  	github.com/Flowfin/lab/internal/check	3.282s
ok  	github.com/Flowfin/lab/internal/contexts	1.788s
ok  	github.com/Flowfin/lab/internal/hardware	1.377s
ok  	github.com/Flowfin/lab/internal/invariants	2.252s
ok  	github.com/Flowfin/lab/internal/notices	1.531s
ok  	github.com/Flowfin/lab/internal/prose	1.830s
ok  	github.com/Flowfin/lab/internal/pullrequest	1.423s

go run ./cmd/lab check .
examined .
1 experiment directory walked, 1 record read
26 decision records read
the time this run read is 2026-08-27T08:52:41Z
0 refused

The paths leg of that last run is the one that matters for a change of this
shape: it resolves every repository-relative path a document under docs/ names
and refuses one that is not in the tree. docs/release-notes-preamble.md is
named in prose and resolves. The release asset names are bare words with no
leading directory segment, which that reading deliberately does not treat as
paths, so nothing here asks it to resolve a file that only exists inside a
published release.

No second reader

This change has had no reader other than whoever wrote it. The evidence above
stands in place of one: the sentences it replaces are quoted from the default
branch, every asset name it introduces is quoted from the workflow that produces
it, and the two negative claims - no release, no tag - are the output of the
commands beside them rather than an assertion.

The guide said there was nothing to download, that this board publishes no
binary and no checksum file, and that whether anything is ever published was
not decided. Two of those three sentences stopped being true when record 0021
answered the question and the release workflow landed: the workflow fixes the
asset names, the checksum file and its format, so the walk this issue asks for
no longer has to guess at the thing it describes.

What is added is a download route and a checksum check, with the command
written out for each platform, because a checksum nobody knows how to check is
decoration. Linux and macOS get the two spellings of the same tool with
--ignore-missing, which is what lets a reader check the two files they
downloaded against a checksum file covering eight. Windows gets Get-FileHash
with the line to compare it against, and certutil beside it, because neither
shell there has a --check equivalent and the comparison is the reader's to
make.

The failure it prevents is an operator holding a downloaded binary with no way
to tell whether the bytes arrived as they left, which is the state this page
left them in while telling them there was nothing to download.

Two things it does not do. It does not restate the signature verification: the
release notes carry those commands and where the keys come from, and a second
copy in this tree would drift against the one every release publishes. And it
makes no claim that a release exists - the page tells a reader to open the
releases page and says that an empty one means the checkout route is the only
one available, so the sentence does not go stale on the day the first release
is cut.

Refs #42

Signed-off-by: Nils Lehnen <30603423+iderex@users.noreply.github.com>
@iderex
iderex merged commit 87d1b2e into main Aug 27, 2026
25 checks passed
@iderex
iderex deleted the release/walk-the-download-and-the-checksum branch August 27, 2026 09:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Write the operator guide

1 participant