docs: state verify-build's dist/ guarantee at the width it enforces (closes #331)
All checks were successful
check / check (push) Successful in 50s
e2e / e2e-chrome (push) Successful in 1m26s
e2e / e2e-firefox (push) Successful in 39s

check_dist_tree walks -type f -o -type l, so the emitted-tree cross-check covers
regular files and symlinks under dist/. README.md said "nothing under dist/ that
the build did not write", which is broader: fifos, sockets, device nodes and
empty directories are not checked.

The exclusion stays. A build emits none of those types, none can carry a
shippable payload, and grep on a fifo would hang rather than fail. README.md,
the script's header comment and the check_dist_tree comment now say so in the
same words, so the code and the docs cannot drift apart again.

Documentation only: no non-comment line of script/verify-build changed.
This commit is contained in:
2026-08-23 13:15:36 +00:00
committed by sneak
parent cef6aaab11
commit c394a64a65
3 changed files with 51 additions and 27 deletions

View File

@@ -1,8 +1,10 @@
#!/bin/sh
# script/verify-build: assert that dist/ holds exactly what the build that just
# ran emitted, and that the compiled DEBUG state of that output is the one the
# caller asked for. Our own extension to scripts-to-rule-them-all, run at the
# end of make build / make build-debug.
# script/verify-build: assert that the regular files and symlinks under dist/
# are exactly what the build that just ran emitted (other file types are out of
# scope; see "What that does and does not establish" below), and that the
# compiled DEBUG state of that output is the one the caller asked for. Our own
# extension to scripts-to-rule-them-all, run at the end of make build /
# make build-debug.
#
# Why the DEBUG half exists: DEBUG makes the publicly committed test recovery
# phrase the output of wallet creation, so a release artifact built with it live
@@ -29,12 +31,16 @@
# path fresh per invocation, outside the repo, and deletes it afterwards.
#
# What that does and does not establish. It establishes that dist/ is byte for
# byte the output of the build.js run that just finished, with nothing added,
# nothing missing and nothing altered in between, and that the audited bundles
# in it compiled to the requested mode. It does NOT establish that the source
# tree or build.js were honest, and it says nothing at all to someone handed a
# dist/ from elsewhere: without the receipt from its own build they have no
# input to this check. That is signing, and it is not this control.
# byte the output of the build.js run that just finished, with no regular file
# or symlink added, missing or altered in between, and that the audited bundles
# in it compiled to the requested mode. Regular files and symlinks are the whole
# of what the tree walk covers; fifos, sockets, device nodes and empty
# directories under dist/ are not checked, because a build emits none of them,
# none can carry a shippable payload, and grep on a fifo would hang rather than
# fail. It does NOT establish that the source tree or build.js were honest, and
# it says nothing at all to someone handed a dist/ from elsewhere: without the
# receipt from its own build they have no input to this check. That is signing,
# and it is not this control.
#
# It fails rather than passes whenever it cannot determine something. Minified
# output is not a stable contract, so "matched neither marker" is not evidence
@@ -392,8 +398,10 @@ check_receipt_entries() {
# its own command line, so a linked dist/ collapses this walk to one entry
# and cross-checks nothing.
#
# Types other than regular files and symlinks are left out on purpose: a build
# emits none of them, and grep on a fifo would hang rather than fail.
# Types other than regular files and symlinks — fifos, sockets, device nodes and
# empty directories — are left out on purpose, and the guarantee is bounded to
# what is walked: a build emits none of them, none can carry a shippable
# payload, and grep on a fifo would hang rather than fail.
check_dist_tree() {
LISTING="$(mktemp "${TMPDIR:-/tmp}/verify-build-dist.XXXXXX")" ||
fail "could not create a temporary file for the dist/ listing, so the