docs: correct two claims this repository makes that do not hold - #64
Merged
Conversation
Both were found by someone following the documentation exactly. Neither is a code change; the code was doing what it does and the documents described something else. 1. THE MODE IS NOT 644 OR 755. `FileMeta::executable` claimed "a file is either mode 644 or 755, and no other permission bit is replicated". The second half is true. The first half is not. Materialization creates the file with `fs::write`, giving `0666 & ~umask`, and then ORs in `0o111`. The mode therefore depends on the RECEIVING host's umask. Observed on hetz and droppy on 2026-08-23: 0664 for a plain file and 0775 for an executable one, both under umask 002. Only the executable BIT replicates. Nothing may depend on the exact figure. The comment now gives the umask table and says so, and notes that st2's render deliberately writes an exact mode instead, so the two systems differ on purpose. 2. THE CHECKSUM STEP HAS NEVER BEEN RUNNABLE. "Upgrading Fabric Safely" told the operator to fetch a combined `SHA256SUMS` from the release. No release has ever had one: `git log -S'SHA256SUMS' -- .github/workflows/release.yml` returns nothing, because the workflow publishes one `.sha256` PER ASSET and never a combined manifest. So the documented verification could not complete against any release this project has published, since b7ce527 added it. It stopped nobody until tonight, when `hetz.root` followed it exactly, could not fetch the file, and refused to substitute a different checksum rather than improvise a verification step. That refusal was correct and it is the only reason this was found. The step now fetches the per-asset `.sha256`. It takes field one rather than running `shasum -c`, because the published file still carries the builder's `dist/` path and a check against it fails on the path, not on the hash. The workflow is left alone. It was never wrong; the document described a release layout that never existed. Agent: Silber.fabric
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Boundary
I authored this. Under the rule Nathan set on 2026-08-23 I may merge it only
once cos has approved this pull request and it is green. cos has not
approved it, so it waits.
What this changes
Two claims this repository makes that do not hold. Both were found by someone
following the documentation exactly. Neither is a code change — the code was
doing what it does, and the documents described something else.
1. The mode is not 644 or 755
FileMeta::executableclaimed "a file is either mode 644 or 755, and no otherpermission bit is replicated". The second half is true. The first half is not.
Materialization creates the file with
fs::write, giving0666 & ~umask, thenORs in
0o111. So the mode depends on the receiving host's umask:Observed on hetz and droppy on 2026-08-23: 0664 and 0775, both umask 002. cos
reported it against the sentence I had quoted at them earlier the same evening.
Only the executable bit replicates. The comment now carries the table, says
nothing may depend on the exact figure, and notes that st2's render deliberately
writes an exact mode immune to umask — so the two systems differ on purpose and
the doc should stop implying they match.
2. The checksum step has never been runnable
"Upgrading Fabric Safely" told the operator to fetch a combined
SHA256SUMS.No release has ever had one.
git log -S'SHA256SUMS' -- .github/workflows/release.ymlreturns nothing: the workflow publishes one
.sha256per asset and never acombined manifest.
So the documented verification could not complete against any release this
project has published, since
b7ce527added it.It stopped nobody until tonight, when
hetz.rootfollowed it exactly, could notfetch the file, and refused to substitute a different checksum rather than
improvise a verification step. That refusal is the only reason this was found.
The step now fetches the per-asset
.sha256and takes field one rather thanrunning
shasum -c, because the published file still carries the builder'sdist/path — a check against it fails on the path, not on the hash.The workflow is left alone. It was never wrong; the document described a
release layout that never existed. I considered adding a combined manifest to
match the doc and rejected it: changing release output to fit a sentence is the
wrong direction when the sentence is the thing that is untrue.
How these were found
Not by review. Both surfaced because an operator did exactly what was written
and the system did something else — which is the only way this class of defect
ever surfaces.
Verification
Documentation only, in a doc comment and a README. No behaviour change. 233 lib
tests pass and
manifest.rsis rustfmt clean.