Skip to content

docs: correct two claims this repository makes that do not hold - #64

Merged
myobie merged 1 commit into
mainfrom
docs/two-claims-that-do-not-hold
Aug 23, 2026
Merged

docs: correct two claims this repository makes that do not hold#64
myobie merged 1 commit into
mainfrom
docs/two-claims-that-do-not-hold

Conversation

@myobie

@myobie myobie commented Aug 23, 2026

Copy link
Copy Markdown
Collaborator

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::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, then
ORs in 0o111. So the mode depends on the receiving host's umask:

receiver umask plain file executable file
022 0644 0755
002 0664 0775

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.yml
returns nothing: 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 is the only reason this was found.

The step now fetches the per-asset .sha256 and takes field one rather than
running shasum -c, because the published file still carries the builder's
dist/ 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.rs is rustfmt clean.

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
@myobie
myobie merged commit 007f891 into main Aug 23, 2026
2 checks passed
@myobie
myobie deleted the docs/two-claims-that-do-not-hold branch August 23, 2026 22:05
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.

1 participant