docs(hardlink): withdraw the nlink claim, which asserted more than was measured
CI / shellcheck + selftests (pull_request) Skipped

The comments said hardlink count at link time was ruled out as the
discriminator between a rewritten executable and an intact one, citing a
lib+bin crate whose two test binaries were both `nlink == 1` and appeared to
behave differently. Re-checked on review: the intact one had not been rebuilt
at all — same content, same inode — so it demonstrated nothing, and forcing
both to rebuild rewrote both.

What was actually observed is narrower and now says so: every executable
measured intact had an uplift hardlink twin Cargo must re-create anyway, every
one measured rewritten had none, and whether the twin is the mechanism or a
correlate was not determined. The rule does not rest on the answer — exempting
twinned executables would recover none of the bytes this change newly copies.

This PR exists because a claim outlived its evidence; it should not ship one.
This commit is contained in:
2026-08-27 14:50:53 -05:00
parent 0553a6b956
commit fb3c72aa28
2 changed files with 13 additions and 7 deletions
+9 -4
View File
@@ -523,10 +523,15 @@ unshare_mutable_paths() {
# Measured 2026-08-27 on cargo 1.93.1 stable, 1.96.0-nightly, 1.98.0-nightly
# (layout v1) and 1.100.0-nightly (e8cb624d5, layout v2), mold and the
# default linker alike: a `cargo test --no-run` binary in a `cp -al` clone
# rewrote the SOURCE's copy of itself in place, under both layouts. Hardlink
# count at link time is NOT what decides it — measured 2 in both a rewritten
# and an intact case, and two test binaries of one crate at `nlink == 1`
# behaved differently from each other. See gitdan-actions#17.
# rewrote the SOURCE's copy of itself in place, under both layouts.
#
# What separates that from the executables measured INTACT is not
# established. Every intact case observed was one Cargo has to re-create
# anyway to maintain an uplift hardlink — a bin target's
# `deps/<bin>-<hash>`, twinned at `<profile>/<bin>`. Whether the twin is the
# mechanism or a correlate of it was not determined, and the rule below does
# not depend on the answer: exempting twinned executables would recover no
# bytes this function newly copies. See gitdan-actions#17.
#
# The executable bit is the discriminator because it is the linker's own
# output that is at risk, not the directory it happens to land in — `.rlib`,
+4 -3
View File
@@ -587,9 +587,10 @@ echo "=== a linked TEST binary, which nothing uplifts and nothing replaces ==="
# dep-info mutations the previous scenario already covers, and the scenario
# pinned nothing. A bin-only crate with a unit test does exhibit the rewrite,
# on cargo 1.93.1 stable and on 1.98.0-nightly and 1.100.0-nightly, so that is
# what this builds. `nlink` does not predict which is which — two test binaries
# of one crate, both at 1, behaved differently — so the shape is chosen by
# measurement rather than derived.
# what this builds. The shape is chosen by measurement rather than derived:
# what separates a rewritten executable from an intact one is not established,
# so the only crate shape this scenario may rest on is one observed to exhibit
# the rewrite.
mkbincrate() {
local dir="$1" marker="$2"
mkdir -p "$dir/src"