docs: state verify-build's dist/ guarantee at the width it enforces (closes #331)

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.

README.md

@@ -91,7 +91,7 @@ output of the `build.js` run that just finished, with no regular file or symlink
 added, removed or altered in between. 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
+carry a shippable payload, and grep on a fifo would hang rather than fail. It
 establishes nothing about whether the source tree or `build.js` were honest, and
 it offers nothing to someone handed a `dist/` from elsewhere — without the
 receipt from its own build there is no input to the check. Verifiable provenance
@@ -149,15 +149,15 @@ provide:
   vendoring run that was released
 - `script/verify-build --expect release|debug --receipt PATH` — 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), and that the compiled `DEBUG`
+  ran emitted (other file types are out of scope; see
-  state of the bundles in it is the one that was asked for. Both arguments are
+  [Build Receipts](#build-receipts)), and that the compiled `DEBUG` state of the
-  required and neither has a default: the expected mode is stated by the caller
+  bundles in it is the one that was asked for. Both arguments are required and
-  rather than read from `AUTISTMASK_DEBUG`, and the file list comes from the
+  neither has a default: the expected mode is stated by the caller rather than
-  build's receipt rather than from `dist/` (see
+  read from `AUTISTMASK_DEBUG`, and the file list comes from the build's receipt
-  [Build Receipts](#build-receipts)). Run automatically at the end of
+  rather than from `dist/` (see [Build Receipts](#build-receipts)). Run
-  `make build` and `make build-debug`; fails loudly rather than passing whenever
+  automatically at the end of `make build` and `make build-debug`; fails loudly
-  it cannot determine something. Not part of `make check`, which does not depend
+  rather than passing whenever it cannot determine something. Not part of
-  on build artifacts existing.
+  `make check`, which does not depend on build artifacts existing.
 - `script/test-verify-build` — exercise every failure mode of
   `script/verify-build` against a fixture tree in a temp dir, asserting the exit
   status and the message of each, and read the `make build` and

TODO.md

@@ -51,7 +51,7 @@ but the review is broader than any of them.
   `-type f -o -type l`, so the guarantee covers regular files and symlinks under
   `dist/`; fifos, sockets, device nodes and empty directories 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. The exclusion is deliberate and
+  grep on a fifo would hang rather than fail. The exclusion is deliberate and
   unchanged — the README said "nothing under `dist/` that the build did not
   write", which was broader than that. Documentation only; no executable line
   changed.

script/verify-build

@@ -1,10 +1,8 @@
 #!/bin/sh
-# script/verify-build: assert that the regular files and symlinks under dist/
+# script/verify-build: assert that dist/ holds exactly what the build that just
-# are exactly what the build that just ran emitted (other file types are out of
+# ran emitted, and that the compiled DEBUG state of that output is the one the
-# scope; see "What that does and does not establish" below), and that the
+# caller asked for. Our own extension to scripts-to-rule-them-all, run at the
-# compiled DEBUG state of that output is the one the caller asked for. Our own
+# end of make build / make build-debug.
-# 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