From f76789358d7edd0fd4158543c46efa95c12ce4f4 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 26 Aug 2026 12:31:50 -0500 Subject: [PATCH 1/9] ci(gitea): gate scripts/ with shellcheck and the selftests MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This repo had eight scripts, six selftest suites and nothing that ran any of them. It is a composite action consumed at `@v1` — a moving tag — by three repos' CI, so a bad edit here reaches zemyna, emowheel and lublub at once and is discovered by whichever of them builds next. One job: `shellcheck -x --source-path=scripts scripts/*.sh`, then `bash scripts/selftest.sh`. `-x` follows the `. cache-lib.sh` every script sources, which is where most of the logic being checked lives; without it shellcheck reports SC1091 and analyses each file with a hole in it. The full suite, not `--fast`: `hardlink-clone-selftest.sh` and `restore-mtimes-selftest.sh` are the two that drive a real Cargo rather than a fixture, and selftest.sh's own header says `--fast` is for iterating, not for signing off a change. So the job installs a stable toolchain. The scratch workspaces they build use path dependencies only, so nothing reaches crates.io, and the job references no credentials at all. Modelled on daniel/gitdan's workflow, including the two clauses of the draft-skip guard (`github.event_name != 'pull_request' || !github.event.pull_request.draft` — the first is what stops the second from also skipping pushes to `main`, where there is no `pull_request` context) and the per-commit concurrency group for `push`. No `container.volumes:` entry, deliberately: the suites want a cold target dir every run, since "did this rebuild?" is exactly what restore-mtimes-selftest asks. This job takes no share of the shared CI cache disk budget. Turning the gate on surfaced three pre-existing findings, all fixed here rather than suppressed or waived: - `restore-mtimes-selftest.sh` SC2038: `find | xargs touch` -> `-print0 | xargs -0`. - `hardlink-clone-selftest.sh` SC2295: `${f#$base_fix/}` -> `${f#"$base_fix"/}`. - `cache-lib.sh` SC2016: a per-line disable with the rationale. The single quotes are load-bearing — the program is for the inner shell, where `$f` is its loop variable, `$rc` its accumulator and `$$` its pid — so this is the documented-false-positive case, not a stopgap. --- .gitea/workflows/ci.yaml | 83 ++++++++++++++++++++++++++++++ README.md | 17 +++++- scripts/cache-lib.sh | 3 ++ scripts/hardlink-clone-selftest.sh | 2 +- scripts/restore-mtimes-selftest.sh | 2 +- 5 files changed, 104 insertions(+), 3 deletions(-) create mode 100644 .gitea/workflows/ci.yaml diff --git a/.gitea/workflows/ci.yaml b/.gitea/workflows/ci.yaml new file mode 100644 index 0000000..89331bd --- /dev/null +++ b/.gitea/workflows/ci.yaml @@ -0,0 +1,83 @@ +name: CI + +on: + push: + branches: [main] + pull_request: + branches: [main] + # Spelled out only to keep `ready_for_review` in the list — naming any type + # replaces the whole default set, so the other three have to be restated. + # It is inert on this instance (draft state here is the `WIP:` title + # prefix, so un-drafting is a title edit and raises no + # `ready_for_review` action) and costs nothing. + # + # The consequence, which is the part that bites: the `if:` guard below is + # evaluated when a run is CREATED, and un-drafting creates no run. A PR + # opened as a draft keeps its skip decision until something else produces + # one. Push an empty commit after un-WIP'ing. + types: [opened, synchronize, reopened, ready_for_review] + +# gitdan-ci runs four repos' CI on two capacity slots, and the compiler-backed +# suites below are multi-minute. A superseded run costs a slot in front of +# somebody's build, so drop it. +# +# `push` groups on `github.sha` rather than `github.ref`: a constant per-branch +# group is what let this Gitea (1.26.0) cancel two of daniel/gitdan's merge +# runs outright while `cancel-in-progress` was gated away from `push` entirely +# — see the long note in that repo's ci.yaml for the evidence. Giving every +# commit its own group leaves that behaviour nothing to act on. +concurrency: + group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.ref || github.sha }} + cancel-in-progress: true + +jobs: + selftest: + name: shellcheck + selftests + # Two clauses, both load-bearing. The second skips draft PRs: Gitea sets + # draft:true when the title starts with `WIP:`, so work-in-progress pushes + # cost the shared runner nothing until the PR is un-WIP'd. The first is + # what keeps that from also skipping pushes to `main` — a `push` event has + # no `pull_request` context, so `github.event.pull_request.draft` is empty + # there and the negation alone would be unreliable. Never drop it. + if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.draft }} + runs-on: ubuntu-latest + timeout-minutes: 20 + # Deliberately no `container.volumes:` entry, unlike every repo that + # CONSUMES this action. The suites below build throwaway workspaces under + # `mktemp -d` and want a cold target dir every time — a persistent cache + # would make "did this run rebuild?" unanswerable, which is the question + # restore-mtimes-selftest.sh exists to ask. So this job takes no share of + # the shared CI cache disk budget. + steps: + - name: Checkout sources + uses: actions/checkout@v4 + + - name: Install shellcheck + uses: taiki-e/install-action@v2 + with: + tool: shellcheck + + # `hardlink-clone-selftest.sh` and `restore-mtimes-selftest.sh` drive a + # real Cargo against a real scratch workspace — they are the only things + # here that verify the hardlink-aliasing and mtime-freshness behaviour + # against the compiler rather than against a fixture, and selftest.sh's + # own header says `--fast` is for iterating, not for signing off a + # change. So CI installs a toolchain and runs the full set. + # + # The scratch workspaces use path dependencies only, so nothing here + # reaches crates.io. + - name: Install Rust toolchain + uses: dtolnay/rust-toolchain@stable + + # Every script, including the suites themselves. `-x` follows the + # `. cache-lib.sh` each one sources, which is where most of the logic + # being checked actually lives; without it shellcheck reports SC1091 and + # analyses each file with a hole in it. + - name: shellcheck + run: shellcheck -x --source-path=scripts scripts/*.sh + + # One command, not six: selftest.sh is the entry point a developer runs, + # so a suite added there is gated here without a matching edit in this + # file. + - name: Selftests + run: bash scripts/selftest.sh diff --git a/README.md b/README.md index 235bca9..7a11859 100644 --- a/README.md +++ b/README.md @@ -445,10 +445,25 @@ not automatic. ## Development ```bash -bash scripts/selftest.sh # everything (~1 min; needs cargo) +shellcheck -x --source-path=scripts scripts/*.sh +bash scripts/selftest.sh # everything (needs cargo) bash scripts/selftest.sh --fast # fixture-only suites, no compiler ``` +Both run in CI — `.gitea/workflows/ci.yaml`, one job, on pushes to `main` and +on PRs that were non-draft when the run was created. It installs shellcheck +and a stable Rust toolchain and references no credentials; the scratch +workspaces the compiler-backed suites build use path dependencies only, so +nothing reaches crates.io. It runs the full suite rather than `--fast`, +because the two compiler-backed suites are the ones that check this scheme +against real Cargo instead of against a fixture. Draft (`WIP:`-titled) PRs +skip it, and un-drafting does **not** un-skip them — the guard is evaluated +when a run is created and un-drafting creates none, so push an empty commit +after un-WIP'ing. + +This repo is consumed by three other repos' CI at `@v1`, a moving tag, so a +change here reaches all of them at once. That is what the gate is for. + | suite | covers | |---|---| | `hardlink-clone-selftest.sh` | that a build in a clone cannot mutate its source — with a control proving a raw `cp -al` does. Needs a real compiler. | diff --git a/scripts/cache-lib.sh b/scripts/cache-lib.sh index 2f94aea..6eabffa 100755 --- a/scripts/cache-lib.sh +++ b/scripts/cache-lib.sh @@ -210,6 +210,9 @@ _unshare_files() { # The inner shell propagates a failure of any individual copy-and-rename out # through xargs (which exits 123 if any invocation exits 1-125), so a # partially-unshared tree is reported rather than silently accepted. + # shellcheck disable=SC2016 # the quoted program is for the INNER shell: $f + # is its loop variable, $rc its accumulator and $$ its pid. Expanding any of + # them here is what the single quotes exist to prevent. find "$@" -links +1 -print0 2>/dev/null | xargs -0 -r -n 64 bash -c 'rc=0; for f; do cp -p -- "$f" "$f.unshare.$$" && mv -f -- "$f.unshare.$$" "$f" || rc=1; done; exit $rc' _ } diff --git a/scripts/hardlink-clone-selftest.sh b/scripts/hardlink-clone-selftest.sh index a066c2b..7364a49 100755 --- a/scripts/hardlink-clone-selftest.sh +++ b/scripts/hardlink-clone-selftest.sh @@ -133,7 +133,7 @@ hardlink_clone_into "$base_fix" "$clone_fix" "selftest" || fail "hardlink_clone_ # rebuild would prove nothing — the rebuild replaces those files anyway. shared=0; unshared=0 while IFS= read -r f; do - rel="${f#$base_fix/}" + rel="${f#"$base_fix"/}" [ -e "$clone_fix/$rel" ] || continue if [ "$(stat -c '%i' "$f")" = "$(stat -c '%i' "$clone_fix/$rel")" ]; then case "$rel" in diff --git a/scripts/restore-mtimes-selftest.sh b/scripts/restore-mtimes-selftest.sh index cc57414..66db0ea 100755 --- a/scripts/restore-mtimes-selftest.sh +++ b/scripts/restore-mtimes-selftest.sh @@ -122,7 +122,7 @@ assert_log_lacks() { # every run — simulate that before each restore-mtimes.sh pass, exactly as # CI would see it, so this test exercises the script the same way CI does. stamp_checkout_now() { - find . -path ./.git -prune -o -type f -print | xargs touch + find . -path ./.git -prune -o -type f -print0 | xargs -0 touch } echo "=== building scratch workspace ===" -- 2.43.0 From fb7a788c90e7d5204edb037c32a4d5ee9cad8ca4 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 26 Aug 2026 12:32:21 -0500 Subject: [PATCH 2/9] feat(cache): give same-ref jobs separate build directories via cache-lineage MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A cache key names a REF. What a target directory holds is the product of a ref and a build configuration, and emowheel builds the same ref twice on every push — once for the host, once for wasm32, in two jobs that start together. Keyed on the ref alone, `cargo-cache@v1` handed both the same CARGO_TARGET_DIR, and Cargo's target-directory lock is exclusive: the second job sat on "Blocking waiting for file lock on build directory" for the length of the first while holding a runner capacity slot, so a third repo's queued job waited behind a job doing nothing. `cache-lineage` is that second dimension. It names ONE directory level under the cache root: /target- no lineage (unchanged) //target- a lineage Nesting, not a suffix on the key, and that is the whole design decision. `prune-cache.sh`'s liveness pass classifies a directory by recomputing `target-` for every branch on origin and evicting whatever does not match — a `target--wasm32` matches nothing, so it would be classified dead and evicted unconditionally on every run. daniel/gitdan's host-level arbiter reads the same shape (BRANCH_DIR_RE); a suffixed name falls out of that too, so those caches would never be reclaim candidates and a whole lineage would go missing from the shared disk budget. Nesting leaves both matchers reading exactly the names they already read, one level down — which is a layout that arbiter already walks (CI_CACHE_MAX_DEPTH is 2, and its own suite pins the depth-2 case). Every interacting part, checked rather than assumed: - SEED: `seed-target-dir.sh` takes the root as an argument, so a PR branch in a lineage layers over THAT lineage's base snapshot. Asserted. - PUBLISH: `publish-snapshot.sh` derives both ends of the swap from the root. The publish action now takes the root from the `CARGO_CACHE_ROOT` the consume step exported, and CHECKS its own inputs against it — a publish step left at the default while its consume step nested would otherwise republish a different lineage's live target dir over that lineage's snapshot, on every push, silently. `mode: release-lock` is exempt: it releases a lock on `$CARGO_TARGET_DIR` and never touches a root. - WATERMARK: per target dir, so it follows the lineage. Unchanged. - PRUNE and LIVENESS: scoped to the root they are given, so a pass in one lineage neither evicts nor sees a sibling's caches, or the flat layout's. Liveness keeps resolving real branch names, which is what a key suffix would have broken. - ci_cache_reclaim: verified by dry-run against a fixture in this layout — all six nested and flat dirs collected as candidates, protection resolved correctly on the nested ones, and a `.stage-` stranded inside the lineage found by the leftover sweep. Refused lineage names are refused at resolve time, each rejection naming the reader that imposes it: a path separator (the arbiter's depth budget), a Cargo profile name (its no-descend list), a `target-`/`snapshot-` prefix (this repo's own prune globs), a hex suffix (its per-branch-dir shape), a dot prefix (the leftover-naming contract). None of these fails visibly on its own — each produces a working directory that some pass silently stops seeing. Setting no lineage resolves to the cache root byte for byte, so lublub, zemyna and emowheel's `ci` job keep the exact directories they have on the volume. New suite `cache-root-selftest.sh` (19 assertions), red-proven against three deliberate breakages: a `cache_root_for` that ignores the lineage, a disabled validator, and a `verify` that never rejects a mismatch. --- README.md | 109 ++++++++++++++++-- cargo-cache-publish/action.yml | 28 ++++- cargo-cache/action.yml | 44 +++++++- scripts/cache-lib.sh | 100 +++++++++++++++++ scripts/cache-root-selftest.sh | 194 +++++++++++++++++++++++++++++++++ scripts/cache-root.sh | 61 +++++++++++ scripts/selftest.sh | 2 +- 7 files changed, 522 insertions(+), 16 deletions(-) create mode 100755 scripts/cache-root-selftest.sh create mode 100755 scripts/cache-root.sh diff --git a/README.md b/README.md index 7a11859..671f9f5 100644 --- a/README.md +++ b/README.md @@ -317,6 +317,39 @@ spelling of some new dot-prefixed name — a name it reads for a decision but never reclaims — that is exactly this category, and it needs the matching `DEPEND_*` entry on gitdan's side before it ships, not after. +### The directory LAYOUT is part of that contract as well + +Names are one half; where they sit is the other. gitdan's arbiter walks a +volume's `_data` tree to `CI_CACHE_MAX_DEPTH`, which is **2** — deliberately +tight, because a deeper walk starts meeting Cargo's own +`incremental/-` directories, which match the same name shape it +uses to recognise a cache dir and must never be evicted individually. So: + +``` +_data/target- depth 1 — no lineage +_data//target- depth 2 — a lineage +_data///target- depth 3 — INVISIBLE to the arbiter +``` + +That budget is the whole reason `cache-lineage` is one path component and not +a path. Nesting deeper is not an error anywhere: the caches work, the +in-workflow prune pass keeps managing them, and the one script whose job is +the shared disk budget across every repo simply never sees them again. + +It is also why the fix for daniel/gitdan#60 nests rather than suffixing the +cache key. A `target--` name would be read as dead by +`prune-cache.sh`'s liveness pass — which classifies by recomputing +`target-` for every branch on origin — and evicted +unconditionally on every run; and it falls out of the arbiter's own +`BRANCH_DIR_RE` too, so the same directories would never be candidates there +either. Nesting leaves both matchers reading exactly the names they already +read, one level down. + +One known rough edge, on gitdan's side and cosmetic: that script logs an +eviction as `/`, so a nested `target-` and a flat one +of the same key are indistinguishable in its output. It evicts the right +directory; the line just doesn't say which. + --- ## Inputs @@ -326,6 +359,7 @@ never reclaims — that is exactly this category, and it needs the matching | input | default | meaning | |---|---|---| | `cache-root` | `/cache` | mount point of the persistent volume inside the job container | +| `cache-lineage` | *(empty)* | one directory level under `cache-root`, for a second job building the same ref for a different target or profile — see [Multiple jobs in one workflow](#multiple-jobs-in-one-workflow) | | `protected-branches` | `dev main` | refs that publish snapshots and are never evicted | | `min-free-percent` | `10` | prune when free space drops below this | | `restore-mtimes` | `true` | restore tracked-file mtimes from git history | @@ -334,7 +368,7 @@ never reclaims — that is exactly this category, and it needs the matching | `own-ref` | *(auto)* | override; defaults to `github.head_ref`, else `github.ref_name` | | `base-ref` | *(auto)* | override; defaults to `github.base_ref` (empty on push) | | `seed-fallback-dir` | *(empty)* | absolute path to seed from when no snapshot exists — for migrating off an existing flat cache | -| `watermark-file` | `.ci-watermark--sha` | must differ per job when two jobs share one cache key | +| `watermark-file` | `.ci-watermark--sha` | must differ per job when two jobs share one target directory; the default already does | | `lock-id` | `-` | identifies this job's cache lock | | `stale-lock-seconds` | `7200` | age past which another job's lock is treated as abandoned | @@ -350,6 +384,7 @@ Exports to the job environment: `CARGO_TARGET_DIR`, `CARGO_CACHE_ROOT`, | input | default | meaning | |---|---|---| | `cache-root` | `/cache` | must match the consume action | +| `cache-lineage` | *(empty)* | must match the consume action; a mismatch fails the step rather than publishing the wrong tree | | `protected-branches` | `dev main` | refs that publish snapshots | | `mode` | `publish` | `publish`, or `release-lock` for the `if: always()` step | | `own-ref` | *(auto)* | override; defaults to `github.head_ref`, else `github.ref_name` | @@ -366,13 +401,70 @@ of a merge-preview build, which is not what `dev` is. ## Multiple jobs in one workflow -Jobs sharing a cache key (a `ci` job and a `wasm` job on the same branch, say) -each need their **own** watermark file. A shared one breaks the moment two -jobs run in sequence within one trigger: job A advances the watermark to HEAD, -and job B then reads that just-advanced value, computes an empty diff, and -loses the merge protection entirely. The default (`.ci-watermark--sha`) -already gives each job its own; only override `watermark-file` if you also -override `lock-id`, and then keep both distinct per job. +Two jobs building the same ref — a `ci` job and a `wasm` job, say — are two +consumers of one cache key, and the cache key alone is not enough to keep them +apart. + +**Give each its own lineage.** A cache key names a *ref*; what a target +directory holds is the product of a ref and a build configuration. Left to the +key alone, both jobs export the same `CARGO_TARGET_DIR`, and Cargo's +build-directory lock is exclusive — so on a runner with more than one slot the +second job sits on `Blocking waiting for file lock on build directory` for the +length of the first, occupying a capacity slot while doing nothing +(daniel/gitdan#60). `cache-lineage` is that second dimension: + +```yaml + - name: Restore the Cargo cache + uses: https://gitdan.com/daniel/gitdan-actions/cargo-cache@v1 + with: + cache-lineage: wasm32 # the `ci` job sets none + + # ... build steps ... + + - name: Record watermark, publish cache snapshot + uses: https://gitdan.com/daniel/gitdan-actions/cargo-cache-publish@v1 + with: + cache-lineage: wasm32 # the SAME value, or the step fails +``` + +A lineage nests one directory level under the cache root +(`//target-`), so each lineage gets its own target +dirs, its own snapshots, and its own prune pass. Everything else works as it +already did, one level down: a PR branch in a lineage layers over **that +lineage's** base snapshot, the publisher branch publishes into it, and a prune +pass run inside it never sees a sibling lineage's caches. + +Setting no lineage resolves to the cache root unchanged, byte for byte, so a +workflow that does not use one keeps the exact directories it already has on +the volume. + +**Both actions need the same value.** `cargo-cache-publish` derives both ends +of the snapshot swap from its own `cache-root`, so a publish step left at the +default while its consume step nested would republish a *different* lineage's +live target dir over that lineage's snapshot, on every push, with nothing in +the log to say so. The publish action therefore compares its own inputs +against the `CARGO_CACHE_ROOT` the consume step exported and fails the step on +a mismatch. (The `mode: release-lock` call is exempt: it releases a lock on +`$CARGO_TARGET_DIR` and never touches a cache root, so it takes no lineage.) + +**Some lineage names are refused.** A lineage is one path component, drawn +from `[A-Za-z0-9._-]`, and several otherwise-reasonable names are rejected at +resolve time because a *reader elsewhere* would stop seeing the caches +underneath them: a Cargo profile name (`debug`, `release`, `doc`, …) is one +gitdan's arbiter never descends into, a `target-`/`snapshot-` prefix makes the +lineage directory itself an eviction candidate for this repo's own prune pass, +and a hex-suffixed name is read by that arbiter as a per-branch cache dir in +its own right. `validate_cache_lineage()` in `scripts/cache-lib.sh` states each +rejection with the reader that imposes it. + +**Watermarks are still per job.** Two jobs in one lineage — or one job before +lineages were introduced — each need their **own** watermark file. A shared one +breaks the moment two jobs run in sequence within one trigger: job A advances +the watermark to HEAD, and job B then reads that just-advanced value, computes +an empty diff, and loses the merge protection entirely. The default +(`.ci-watermark--sha`) already gives each job its own; only override +`watermark-file` if you also override `lock-id`, and then keep both distinct +per job. --- @@ -466,6 +558,7 @@ change here reaches all of them at once. That is what the gate is for. | suite | covers | |---|---| +| `cache-root-selftest.sh` | that a lineage nests one level and nothing else moves: no lineage resolves byte-for-byte to the cache root, two lineages on one cache key get disjoint target dirs, seed/publish/prune all stay inside their own lineage, a PR layers over its own lineage's base snapshot — **and one rejection per lineage name a reader elsewhere would stop seeing**, plus the publish-side mismatch guard | | `hardlink-clone-selftest.sh` | that a build in a clone cannot mutate its source — with a control proving a raw `cp -al` does. Needs a real compiler. | | `seed-target-dir-selftest.sh` | seed-source preference, lock-file stripping, two jobs racing on one cache key, **and one scenario per check a hardlink clone is validated against**: a source rotated wholesale, a subtree silently lost from the walk, a copy that reports failure over a tree both other checks read as whole, and a source identity that resolved at neither end — plus a staging tree that could not be privately owned being discarded rather than published, and the publisher's log showing it waited on the consumer's own reader-lock marker before reclaiming a rotated snapshot | | `publish-snapshot-selftest.sh` | the atomic swap, that a live consumer survives a republish, and the publisher's side of the rotation race: deferred reclamation under a live reader, and its sweep once the reader is gone | diff --git a/cargo-cache-publish/action.yml b/cargo-cache-publish/action.yml index 86729ed..a4b94d0 100644 --- a/cargo-cache-publish/action.yml +++ b/cargo-cache-publish/action.yml @@ -10,6 +10,15 @@ inputs: description: 'Mount point of the persistent cache volume. Must match the consume action.' required: false default: '/cache' + cache-lineage: + description: >- + Must match the cargo-cache step in this job. Checked rather than + assumed: this action derives both ends of the snapshot swap from its own + cache-root, so a publish step left at the default while its consume step + nested would republish a DIFFERENT lineage's live target dir over that + lineage's snapshot, on every push, silently. A mismatch fails the step. + required: false + default: '' protected-branches: description: >- Space-separated refs that publish snapshots. A run whose own ref is not @@ -67,6 +76,11 @@ runs: # Everything here reads the environment the consume action exported, so a # workflow that forgets to run cargo-cache first fails loudly here rather # than silently publishing a snapshot of the wrong directory. + # + # The cache root is taken from that same environment for the same reason, + # and this action's own cache-root/cache-lineage inputs are checked against + # it rather than used. The two have always had to agree; until a lineage + # existed they always did, because nobody overrode the default. - id: resolve shell: bash env: @@ -92,6 +106,18 @@ runs: : "${CARGO_CACHE_KEY:?cargo-cache-publish: CARGO_CACHE_KEY not set by the cargo-cache action}" echo "active=yes" >> "$GITHUB_OUTPUT" + # Only in publish mode. The `release-lock` call is an `if: always()` + # step that consuming workflows invoke with `mode:` and nothing else — + # it releases $CARGO_CACHE_LOCK_ID on $CARGO_TARGET_DIR and never + # touches a cache root at all, so holding its default inputs to the + # consume step's would fail the cleanup step of every job that sets a + # lineage, for a value it does not use. + if [ "${{ inputs.mode }}" = "publish" ]; then + : "${CARGO_CACHE_ROOT:?cargo-cache-publish: CARGO_CACHE_ROOT not set by the cargo-cache action}" + bash "${CARGO_CACHE_SCRIPTS}/cache-root.sh" verify \ + "${{ inputs.cache-root }}" "${{ inputs.cache-lineage }}" "$CARGO_CACHE_ROOT" + fi + OWN_REF="${{ inputs.own-ref }}" [ -n "$OWN_REF" ] || OWN_REF="${{ github.head_ref || github.ref_name }}" @@ -131,7 +157,7 @@ runs: run: | set -euo pipefail bash "${CARGO_CACHE_SCRIPTS}/publish-snapshot.sh" \ - "$CARGO_CACHE_KEY" "${{ inputs.cache-root }}" \ + "$CARGO_CACHE_KEY" "$CARGO_CACHE_ROOT" \ "${{ github.job }}-${{ github.run_id }}-$$" # Released in both modes. In `publish` mode this is the normal end-of-job diff --git a/cargo-cache/action.yml b/cargo-cache/action.yml index f3eba09..84d3777 100644 --- a/cargo-cache/action.yml +++ b/cargo-cache/action.yml @@ -10,6 +10,18 @@ inputs: description: 'Mount point of the persistent cache volume inside the job container.' required: false default: '/cache' + cache-lineage: + description: >- + Distinguishes two jobs that build the SAME ref for different targets or + profiles (a host build and a wasm32 build, say) and would otherwise + resolve to one CARGO_TARGET_DIR and serialise on Cargo's exclusive + build-directory lock. Names one directory level under cache-root: + //target-. Must be a single path component; + several names are refused outright because a reader elsewhere would stop + seeing the caches under them (see validate_cache_lineage in + scripts/cache-lib.sh). Pass the same value to cargo-cache-publish. + required: false + default: '' protected-branches: description: >- Space-separated refs that publish snapshots and are never evicted. @@ -54,8 +66,9 @@ inputs: watermark-file: description: >- Name of this job's build-watermark file inside the target dir. MUST be - distinct per job when two jobs share one cache key. Defaults to - .ci-watermark--sha. + distinct per job when two jobs share one target directory — which two + jobs no longer need to do; cache-lineage gives them separate ones. + Defaults to .ci-watermark--sha, already distinct per job. required: false default: '' lock-id: @@ -74,6 +87,12 @@ outputs: cache-key: description: 'Sanitized cache key for this run''s own ref.' value: ${{ steps.resolve.outputs.cache-key }} + cache-root: + description: >- + Resolved cache root — cache-root, plus the lineage directory when one is + set. Every directory this action reads or writes is under it. Also + exported as CARGO_CACHE_ROOT. + value: ${{ steps.resolve.outputs.cache-root }} seeded-from: description: 'Where the target dir came from: own | base-snapshot | own-snapshot | fallback-dir | concurrent-peer | cold.' value: ${{ steps.seed.outputs.seeded-from }} @@ -95,6 +114,16 @@ runs: # `base_ref` is populated only for pull_request events. A push run has # nothing to layer over: its own ref IS the reference branch. It # publishes, it does not consume. + # + # The cache root is resolved first because every path below hangs off it. + # A lineage nests one directory level (`//target-`), + # which is what lets two jobs on ONE ref hold two build directories and so + # not serialise on Cargo's exclusive lock. It is resolved through + # cache-root.sh rather than interpolated here so the name is validated — + # several otherwise-reasonable lineage names put their whole subtree out of + # reach of a pass that has to see it. Everything downstream reads the + # resolved value, and it is exported as CARGO_CACHE_ROOT so the publish + # action can check it agrees with its own inputs. - id: resolve shell: bash run: | @@ -102,6 +131,8 @@ runs: SCRIPTS=$(cd "${{ github.action_path }}/.." && pwd)/scripts [ -d "$SCRIPTS" ] || { echo "::error::cargo-cache: scripts/ not found at $SCRIPTS"; exit 1; } echo "CARGO_CACHE_SCRIPTS=${SCRIPTS}" >> "$GITHUB_ENV" + CACHE_ROOT=$(bash "${SCRIPTS}/cache-root.sh" resolve \ + "${{ inputs.cache-root }}" "${{ inputs.cache-lineage }}") OWN_REF="${{ inputs.own-ref }}" [ -n "$OWN_REF" ] || OWN_REF="${{ github.head_ref || github.ref_name }}" BASE_REF="${{ inputs.base-ref }}" @@ -116,7 +147,7 @@ runs: echo "cache: own ref '${OWN_REF}' -> ${OWN_KEY} (no base ref — this ref publishes, it does not consume)" fi - TARGET_DIR="${{ inputs.cache-root }}/target-${OWN_KEY}" + TARGET_DIR="${CACHE_ROOT}/target-${OWN_KEY}" WATERMARK="${{ inputs.watermark-file }}" [ -n "$WATERMARK" ] || WATERMARK=".ci-watermark-${{ github.job }}-sha" LOCK_ID="${{ inputs.lock-id }}" @@ -128,10 +159,11 @@ runs: echo "base-key=${BASE_KEY}" echo "lock-id=${LOCK_ID}" echo "watermark-file=${WATERMARK}" + echo "cache-root=${CACHE_ROOT}" } >> "$GITHUB_OUTPUT" { echo "CARGO_TARGET_DIR=${TARGET_DIR}" - echo "CARGO_CACHE_ROOT=${{ inputs.cache-root }}" + echo "CARGO_CACHE_ROOT=${CACHE_ROOT}" echo "CARGO_CACHE_KEY=${OWN_KEY}" echo "CARGO_CACHE_LOCK_ID=${LOCK_ID}" echo "CI_WATERMARK_FILE=${WATERMARK}" @@ -155,7 +187,7 @@ runs: bash "${SCRIPTS}/seed-target-dir.sh" \ "${{ steps.resolve.outputs.cache-key }}" \ "${{ steps.resolve.outputs.base-key }}" \ - "${{ inputs.cache-root }}" \ + "${{ steps.resolve.outputs.cache-root }}" \ "${{ github.job }}-${{ github.run_id }}-$$" \ "${{ inputs.seed-fallback-dir }}" \ "${{ steps.resolve.outputs.lock-id }}" @@ -206,7 +238,7 @@ runs: set -euo pipefail SCRIPTS=$(cd "${{ github.action_path }}/.." && pwd)/scripts bash "${SCRIPTS}/prune-cache.sh" \ - "${{ inputs.cache-root }}" \ + "${{ steps.resolve.outputs.cache-root }}" \ "${{ steps.resolve.outputs.target-dir }}" \ "${{ inputs.protected-branches }}" \ "${{ inputs.min-free-percent }}" diff --git a/scripts/cache-lib.sh b/scripts/cache-lib.sh index 6eabffa..7662251 100755 --- a/scripts/cache-lib.sh +++ b/scripts/cache-lib.sh @@ -114,6 +114,106 @@ cache_key() { target_dir_for() { printf '%s/target-%s' "$1" "$2"; } snapshot_dir_for() { printf '%s/snapshot-%s' "$1" "$2"; } +# --------------------------------------------------------------------------- +# Cache lineages +# --------------------------------------------------------------------------- +# +# A cache key names a REF. What a target directory holds is the product of a +# ref and a BUILD CONFIGURATION, and the two are not the same thing: emowheel +# builds the same ref twice on every push, once for the host and once for +# wasm32, in two jobs that run concurrently. Keyed on the ref alone both +# resolve to one CARGO_TARGET_DIR, and Cargo's build-directory lock is +# exclusive — so the second job sits on `Blocking waiting for file lock on +# build directory` for the length of the first, holding a runner capacity slot +# while doing nothing (daniel/gitdan#60). +# +# A lineage is that second dimension, and it is expressed as ONE DIRECTORY +# LEVEL above the per-ref directories rather than as a suffix on the key: +# +# /target- no lineage (the flat layout) +# //target- a lineage +# +# Nesting rather than suffixing is what keeps every existing reader correct +# without teaching any of them a new name shape. `prune-cache.sh` resolves +# liveness by recomputing `target-` for every branch on +# origin and evicting whatever does not match — a suffixed `target--wasm32` +# matches nothing, so it would be classified dead and unconditionally evicted +# on every single run. The host-level arbiter in daniel/gitdan reads the same +# shape (its BRANCH_DIR_RE), and a suffixed name falls out of it too: not +# evicted there, but never a candidate either, so a whole lineage becomes +# invisible to the global disk budget. Nesting leaves both matchers reading +# exactly the names they already read, one directory deeper. +# +# ONE LEVEL, AND NOT TWO. The arbiter walks a volume to CI_CACHE_MAX_DEPTH, +# which is 2 — `_data/target-` and `_data//target-`. It is +# kept tight there on purpose (a deeper walk starts meeting Cargo's own +# `incremental/-` directories, which match the same name shape and +# must never be evicted individually), so a lineage is a single path component +# and validate_cache_lineage refuses one containing a slash. + +# Directory names daniel/gitdan's ci-cache-reclaim.sh refuses to descend into +# (its CI_CACHE_NODESCEND_NAMES). A lineage named one of these puts its whole +# subtree outside the global arbiter's reach: the caches accumulate and the one +# script whose job is the shared disk budget cannot see them. +CACHE_LINEAGE_RESERVED_NAMES="debug release deps incremental build .fingerprint tmp examples doc" + +# The shape that same script reads as a per-branch cache directory (its +# BRANCH_DIR_RE). A lineage matching it is taken for a cache dir in its own +# right — never descended into, and an eviction candidate whole, which is the +# entire lineage rather than one ref's share of it. +CACHE_LINEAGE_BRANCH_DIR_RE='^.+-[0-9a-f]{7,40}$' + +# Every rejection below names the reader that imposes it, because that is the +# only way the constraint survives: none of these is a filesystem limit, and a +# name that trips one produces no error anywhere — it produces a lineage that +# silently stops being pruned, or silently stops being reclaimed. +validate_cache_lineage() { + local lineage="$1" reserved + [ -n "$lineage" ] || return 0 + + case "$lineage" in + */*) + echo "::error::cache lineage '${lineage}' must be a single path component: the host-level arbiter walks a cache volume to depth 2, so //target- is as deep as a cache directory may sit and still be reclaimable" >&2 + return 1 + ;; + .*) + echo "::error::cache lineage '${lineage}' must not start with a dot: every dot-prefixed entry under a cache root belongs to the leftover-naming contract (see the top of this file), and a lineage is not garbage to be reclaimed" >&2 + return 1 + ;; + target-* | snapshot-*) + echo "::error::cache lineage '${lineage}' must not start with 'target-' or 'snapshot-': prune-cache.sh globs both prefixes at the cache root, so the lineage directory itself would become an eviction candidate" >&2 + return 1 + ;; + *[!A-Za-z0-9._-]*) + echo "::error::cache lineage '${lineage}' may contain only [A-Za-z0-9._-] — the same charset cache_key() sanitises a ref down to" >&2 + return 1 + ;; + esac + + for reserved in $CACHE_LINEAGE_RESERVED_NAMES; do + if [ "$lineage" = "$reserved" ]; then + echo "::error::cache lineage '${lineage}' is one of the Cargo directory names daniel/gitdan's ci-cache-reclaim.sh never descends into (CI_CACHE_NODESCEND_NAMES) — every cache under it would be invisible to the host-level disk budget" >&2 + return 1 + fi + done + + if [[ $lineage =~ $CACHE_LINEAGE_BRANCH_DIR_RE ]]; then + echo "::error::cache lineage '${lineage}' ends in a hex suffix, which is the shape daniel/gitdan's ci-cache-reclaim.sh reads as a per-branch cache directory — it would treat the lineage directory as one cache and evict the whole thing" >&2 + return 1 + fi + + return 0 +} + +# The cache root a lineage's directories actually live under. An empty lineage +# resolves to the cache root unchanged, byte for byte: that is what makes this +# a no-op for every consumer that does not set one, rather than a migration. +cache_root_for() { + local root="$1" lineage="${2:-}" + validate_cache_lineage "$lineage" || return 1 + printf '%s%s' "$root" "${lineage:+/$lineage}" +} + # --------------------------------------------------------------------------- # Disk accounting # --------------------------------------------------------------------------- diff --git a/scripts/cache-root-selftest.sh b/scripts/cache-root-selftest.sh new file mode 100755 index 0000000..f33fee7 --- /dev/null +++ b/scripts/cache-root-selftest.sh @@ -0,0 +1,194 @@ +#!/usr/bin/env bash +# Regression test for cache-root.sh and the lineage rules in cache-lib.sh — +# the fix for daniel/gitdan#60, where two jobs building the same ref for +# different targets resolved to one CARGO_TARGET_DIR and serialised on Cargo's +# exclusive build-directory lock. +# +# 1. NO LINEAGE CHANGES NOTHING — the effective root is the cache root byte +# for byte, so every consumer that does not set a lineage keeps the exact +# directories it already has on the volume. This is the whole of the +# migration story for lublub, zemyna and emowheel's `ci` job, so it is +# asserted rather than assumed. +# 2. TWO LINEAGES, ONE REF, TWO TARGET DIRS — the bug itself. The two jobs +# keep one cache key (they are the same ref) and still get directories +# that are neither equal nor nested one inside the other, which is what +# Cargo's per-directory lock needs in order not to serialise them. +# 3. THE WHOLE PIPELINE MOVES TOGETHER — seed, publish and prune all operate +# inside the lineage root. A pass run in one lineage must not evict, or +# even see, a sibling lineage's caches or the flat layout's. +# 4. BASE SEEDING IS PER LINEAGE — a PR branch layers over ITS OWN lineage's +# base snapshot, not over whatever the flat root happens to hold. This is +# the property that keeps a warm start for both jobs rather than one. +# 5. A NAME NO READER CAN HANDLE IS REFUSED AT RESOLVE TIME — one assertion +# per constraint, each named for the reader that imposes it. None of these +# is a filesystem limit: every one of them produces a working directory +# that some pass silently stops seeing, which is the failure mode this +# whole scheme exists to avoid rather than to relocate. +# 6. A PUBLISH THAT DISAGREES WITH ITS CONSUME STEP FAILS LOUDLY — the +# footgun the lineage input introduces. cargo-cache-publish derives both +# ends of the snapshot swap from its own `cache-root`, so a publish step +# left at the default while its consume step nested would republish the +# OTHER lineage's live target dir over that lineage's snapshot, silently. +set -euo pipefail +script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd) +. "$script_dir/cache-lib.sh" + +scratch=$(mktemp -d) +trap 'rm -rf "$scratch"' EXIT +root="$scratch/cache"; mkdir -p "$root" +pass_count=0 +fail() { echo "ASSERTION FAILED: $*" >&2; exit 1; } +ok() { pass_count=$((pass_count + 1)); echo "PASS: $*"; } + +resolve() { bash "$script_dir/cache-root.sh" resolve "$@"; } + +# A tree that looks enough like a Cargo target dir for the pipeline scripts, +# with a marker naming which lineage produced it — scenario 4 turns on reading +# that marker back out of a seeded directory. +make_tree() { + local d="$1" marker="$2" + mkdir -p "$d/debug/deps" "$d/debug/.fingerprint/x" + echo "$marker" > "$d/debug/deps/libx.rlib" + echo "$marker" > "$d/lineage-marker" + echo "$marker" > "$d/debug/.fingerprint/x/dep-lib-x" +} + +echo "=== 1. no lineage changes nothing ===" + +[ "$(resolve /cache)" = /cache ] || fail "an omitted lineage changed the root" +[ "$(resolve /cache '')" = /cache ] || fail "an empty lineage changed the root" +ok "no lineage resolves to the cache root unchanged" + +KEY=$(cache_key dev) +[ "$(target_dir_for "$(resolve /cache '')" "$KEY")" = "/cache/target-$KEY" ] \ + || fail "the flat target-dir name moved" +[ "$(snapshot_dir_for "$(resolve /cache '')" "$KEY")" = "/cache/snapshot-$KEY" ] \ + || fail "the flat snapshot name moved" +ok "the flat layout's directory names are untouched" + +echo +echo "=== 2. two lineages, one ref, two target dirs ===" + +HOST_ROOT=$(resolve /cache) +WASM_ROOT=$(resolve /cache wasm32) +[ "$WASM_ROOT" = /cache/wasm32 ] || fail "lineage root resolved to '$WASM_ROOT'" +HOST_DIR=$(target_dir_for "$HOST_ROOT" "$KEY") +WASM_DIR=$(target_dir_for "$WASM_ROOT" "$KEY") +[ "$HOST_DIR" != "$WASM_DIR" ] || fail "both lineages resolved to $HOST_DIR" +case "$WASM_DIR" in "$HOST_DIR"/*) fail "the wasm target dir sits inside the host one" ;; esac +case "$HOST_DIR" in "$WASM_DIR"/*) fail "the host target dir sits inside the wasm one" ;; esac +ok "one cache key ($KEY), two disjoint target dirs: $HOST_DIR and $WASM_DIR" + +echo +echo "=== 3. the whole pipeline moves together ===" + +DEAD=$(cache_key feat/dead) +lin="$root/wasm32" +mkdir -p "$lin" +make_tree "$root/target-$DEAD" flat +make_tree "$root/native/target-$DEAD" native +make_tree "$lin/target-$DEAD" wasm32 +bash "$script_dir/seed-target-dir.sh" "$KEY" "" "$lin" tag-3 > "$scratch/seed3.log" 2>&1 \ + || { cat "$scratch/seed3.log"; fail "seed inside a lineage root failed"; } +[ -d "$lin/target-$KEY" ] || fail "seed did not create $lin/target-$KEY" +[ -d "$root/target-$KEY" ] && fail "seed created a directory at the flat root as well" +ok "seed creates its directory under the lineage root and nowhere else" + +make_tree "$lin/target-$KEY" wasm32 +bash "$script_dir/publish-snapshot.sh" "$KEY" "$lin" tag-3 > "$scratch/pub3.log" 2>&1 \ + || { cat "$scratch/pub3.log"; fail "publish inside a lineage root failed"; } +[ -d "$lin/snapshot-$KEY" ] || fail "publish did not create $lin/snapshot-$KEY" +[ -d "$root/snapshot-$KEY" ] && fail "publish created a snapshot at the flat root as well" +ok "publish writes its snapshot under the lineage root and nowhere else" + +# Free space far below the threshold, so pass 2 evicts every eligible +# directory it can see. What it can see is the point of the scenario. +CACHE_LIVENESS=false CACHE_DF_OVERRIDE="1000000 1000" \ + bash "$script_dir/prune-cache.sh" "$lin" "$lin/target-$KEY" 'dev main' 10 \ + > "$scratch/prune3.log" 2>&1 || { cat "$scratch/prune3.log"; fail "prune inside a lineage root failed"; } +[ -d "$lin/target-$DEAD" ] && { cat "$scratch/prune3.log"; fail "prune left its own lineage's evictable cache in place"; } +[ -d "$root/target-$DEAD" ] || fail "prune reached out of its lineage and evicted the flat root's cache" +[ -d "$root/native/target-$DEAD" ] || fail "prune reached into a sibling lineage and evicted its cache" +ok "prune under disk pressure evicts inside its own lineage only" + +echo +echo "=== 4. base seeding is per lineage ===" + +BASE=$(cache_key dev) +PR=$(cache_key feat/pr) +rm -rf "$lin" "$root/snapshot-$BASE" +mkdir -p "$lin" +make_tree "$root/snapshot-$BASE" flat-base +make_tree "$lin/snapshot-$BASE" wasm32-base +bash "$script_dir/seed-target-dir.sh" "$PR" "$BASE" "$lin" tag-4 > "$scratch/seed4.log" 2>&1 \ + || { cat "$scratch/seed4.log"; fail "seeding a PR branch inside a lineage failed"; } +[ -d "$lin/target-$PR" ] || fail "the PR branch's lineage target dir was not created" +got=$(cat "$lin/target-$PR/lineage-marker") +[ "$got" = wasm32-base ] || fail "the PR branch layered over '$got', not its own lineage's base snapshot" +grep -q 'base snapshot' "$scratch/seed4.log" || { cat "$scratch/seed4.log"; fail "seed did not report a base-snapshot clone"; } +ok "a PR branch layers over its own lineage's base snapshot ($got)" + +echo +echo "=== 5. a name no reader can handle is refused ===" + +reject() { + local lineage="$1" want="$2" desc="$3" out + if out=$(resolve /cache "$lineage" 2>&1); then + fail "lineage '$lineage' was accepted (resolved to '$out') — $desc" + fi + case "$out" in + *"$want"*) ;; + *) fail "lineage '$lineage' was rejected without naming '$want': $out" ;; + esac + ok "rejected '$lineage' — $desc" +} + +reject 'a/b' 'single path component' "the arbiter walks a volume to depth 2" +reject '.hidden' 'dot' "every dot-prefixed name under a cache root is leftover-contract territory" +reject 'target-x' 'prune-cache.sh' "prune-cache.sh globs target-* at the cache root" +reject 'snapshot-x' 'prune-cache.sh' "prune-cache.sh globs snapshot-* at the cache root" +reject 'wasm 32' 'A-Za-z0-9._-' "a cache key is sanitised to that charset and a lineage sits beside one" +reject 'release' 'CI_CACHE_NODESCEND_NAMES' "the arbiter never descends into a Cargo profile name" +reject 'doc' 'CI_CACHE_NODESCEND_NAMES' "same, for the docs profile directory" +reject 'lineage-deadbeef' 'per-branch cache directory' "the arbiter reads a hex-suffixed name as one cache dir" + +for good in wasm32 web android host wasm32.release lineage_2; do + out=$(resolve /cache "$good") || fail "lineage '$good' was rejected: $out" + [ "$out" = "/cache/$good" ] || fail "lineage '$good' resolved to '$out'" +done +ok "ordinary lineage names still resolve" + +echo +echo "=== 6. a publish that disagrees with its consume step fails loudly ===" + +verify() { bash "$script_dir/cache-root.sh" verify "$@"; } + +verify /cache wasm32 /cache/wasm32 > /dev/null 2>&1 \ + || fail "verify rejected a publish step that agrees with its consume step" +verify /cache '' /cache > /dev/null 2>&1 \ + || fail "verify rejected an unmigrated consumer's matching default pair" +ok "verify accepts a publish step whose inputs match what the consume step exported" + +# The exact shape of the mistake: the consume step nested, the publish step +# kept the default. Left unchecked this republishes the host lineage's live +# target dir over the host lineage's snapshot, from the wasm job. +if out=$(verify /cache '' /cache/wasm32 2>&1); then + fail "verify accepted a publish step that resolved to /cache while the job exported /cache/wasm32" +fi +case "$out" in + *'/cache/wasm32'*) ;; + *) fail "the mismatch error does not quote what the consume step exported: $out" ;; +esac +case "$out" in + *'SAME cache-root and cache-lineage'*) ;; + *) fail "the mismatch error does not say what to do about it: $out" ;; +esac +ok "verify rejects a publish step that forgot the lineage, and says so" + +if verify /cache 'a/b' /cache/a/b > /dev/null 2>&1; then + fail "verify accepted an invalid lineage as long as both sides agreed on it" +fi +ok "verify validates the lineage as well as comparing it" + +echo +echo "cache-root-selftest: ${pass_count} assertions passed" diff --git a/scripts/cache-root.sh b/scripts/cache-root.sh new file mode 100755 index 0000000..eb218ec --- /dev/null +++ b/scripts/cache-root.sh @@ -0,0 +1,61 @@ +#!/usr/bin/env bash +# Resolves — and cross-checks — the cache root a job's directories live under. +# +# cache-root.sh resolve [lineage] +# cache-root.sh verify +# +# `resolve` prints the effective root: the cache root unchanged when no lineage +# is given, or `/` when one is. Invalid lineage names are +# rejected here rather than downstream — see validate_cache_lineage() in +# cache-lib.sh, where every rejection names the reader that imposes it. +# +# `verify` is the publish side's guard. cargo-cache-publish resolves the same +# two inputs the consume action was given and compares the result against the +# CARGO_CACHE_ROOT the consume step exported into the job environment. The two +# actions have always had to agree — `cache-root`'s description in the publish +# action says "must match the consume action" — and until a lineage existed +# they always did, because nobody overrode the default. A disagreement is not +# a harmless no-op: publish-snapshot.sh takes the root as an argument and +# derives BOTH ends of the swap from it, so a publish step that kept the +# default while its consume step nested would read `/target-` — the +# OTHER lineage's live target dir — and republish it over `/snapshot-`, +# which is that lineage's snapshot. Two jobs would then be publishing one +# snapshot from one tree on every push, and nothing in either action would say +# so. Hence: fail the job, loudly, rather than resolve the ambiguity in +# either direction. +# +# A thin CLI over cache-lib.sh, kept as its own entry point for the same +# reason branch-cache-key.sh is: an out-of-band job that needs to find a +# lineage's directories should resolve the path the way the action does +# instead of reimplementing the rule. +set -euo pipefail +. "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/cache-lib.sh" + +MODE="${1:-}" +case "$MODE" in + resolve) + [ $# -ge 2 ] && [ $# -le 3 ] || { + echo "::error::cache-root.sh resolve: expected [lineage]" >&2 + exit 1 + } + [ -n "$2" ] || { echo "::error::cache-root.sh: cache-root must not be empty" >&2; exit 1; } + cache_root_for "$2" "${3:-}" + ;; + verify) + [ $# -eq 4 ] || { + echo "::error::cache-root.sh verify: expected " >&2 + exit 1 + } + [ -n "$2" ] || { echo "::error::cache-root.sh: cache-root must not be empty" >&2; exit 1; } + expected=$(cache_root_for "$2" "$3") + if [ "$expected" != "$4" ]; then + echo "::error::cache-root.sh: this step resolves its cache root to '${expected}' (cache-root '$2', cache-lineage '$3') but the cargo-cache step in this job exported '$4'. Pass the SAME cache-root and cache-lineage to both actions." >&2 + exit 1 + fi + echo "cache root: ${expected} (agrees with the cargo-cache step in this job)" + ;; + *) + echo "::error::cache-root.sh: unknown mode '${MODE}' (expected resolve or verify)" >&2 + exit 1 + ;; +esac diff --git a/scripts/selftest.sh b/scripts/selftest.sh index 9bf3f88..0c7168a 100755 --- a/scripts/selftest.sh +++ b/scripts/selftest.sh @@ -13,7 +13,7 @@ script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd) FAST=0 [ "${1:-}" = "--fast" ] && FAST=1 -FIXTURE_TESTS=(seed-target-dir-selftest.sh publish-snapshot-selftest.sh prune-cache-selftest.sh) +FIXTURE_TESTS=(cache-root-selftest.sh seed-target-dir-selftest.sh publish-snapshot-selftest.sh prune-cache-selftest.sh) CARGO_TESTS=(hardlink-clone-selftest.sh restore-mtimes-selftest.sh) TESTS=("${FIXTURE_TESTS[@]}") -- 2.43.0 From 3f97d3d1e73a4cf7b5f94f368545551894e8db3c Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 26 Aug 2026 12:46:03 -0500 Subject: [PATCH 3/9] fix(selftest): make the two compiler-backed suites survive a CI runner MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The new gate's first run went red on both suites that drive a real Cargo. Neither failure was a defect in what they test; both were assumptions about the machine, which had only ever been a dev box with a nightly installed and no colour forcing. Fixed here rather than waived — turning a gate on is what obliges fixing what it finds. COLOUR. Every assertion in restore-mtimes-selftest.sh, and one in hardlink-clone-selftest.sh, reads cargo's own words out of a build log (`Compiling libdep`, `Fresh probe`). gitdan-ci's runner image forces colour, so cargo wrote `Compiling\e[0m libdep` into the log and `grep -q "Compiling libdep"` stopped matching. The suite then reported the opposite of what happened — the failure printed the log, and the log plainly said `Compiling libdep`. Both suites now pin CARGO_TERM_COLOR=never, which is the format their assertions are written against. Red-proven: with the export removed and CARGO_TERM_COLOR=always, restore-mtimes-selftest reproduces the CI failure verbatim ("expected to find: Compiling libdep"); with it, 14/14 pass under the same forced colour. THE NIGHTLY PROBE ASKED THE WRONG QUESTION. `cargo +nightly -V` answers "did a cargo proxy called with +nightly exit 0", which is not "will this build have checksum freshness": `-V` short-circuits before `-Z` is validated at all. So the probe said "on" on a runner where the flag was not in effect, and the suite asserted the checksum-freshness mutation family against a build that never had it — failing in the CONTROL, where a failure reads as "the hazard is gone" rather than "the toolchain is wrong". It now probes the capability: `cargo +nightly -Z checksum-freshness locate-project`, the narrowest command that actually parses the flag. It rejects the stable channel and an unknown flag name alike, needs no network and builds nothing. Red-proven: the old channel probe, pointed at a cargo without the flag, reproduces the CI failure exactly. AND THE OFF PATH DID NOT WORK EITHER. The suite's header claimed that without checksum freshness "the test still covers the build/ and *.d families". It did not: the final scenario backdates the source to 2001 and asserts the rebuild is not Fresh, which is checksum-freshness-only reasoning. Under Cargo's ordinary mtime freshness a 2001 source IS older than the artifact and Fresh is the correct answer, so the scenario asserted a bug. It is now gated on the mode and skipped loudly, like the control's dep-* assertion already was: 5 assertions with a nightly, 3 without. CI installs a nightly as well as stable (nightly first, so stable stays the default) — that hazard is the one this whole scheme exists to close, and a CI that skips it is checking the cheap half. --- .gitea/workflows/ci.yaml | 12 ++++++ README.md | 7 +++- scripts/hardlink-clone-selftest.sh | 60 ++++++++++++++++++++++++------ scripts/restore-mtimes-selftest.sh | 9 +++++ 4 files changed, 74 insertions(+), 14 deletions(-) diff --git a/.gitea/workflows/ci.yaml b/.gitea/workflows/ci.yaml index 89331bd..4bb9ea8 100644 --- a/.gitea/workflows/ci.yaml +++ b/.gitea/workflows/ci.yaml @@ -66,6 +66,18 @@ jobs: # # The scratch workspaces use path dependencies only, so nothing here # reaches crates.io. + # Nightly first, stable second, so stable ends up the default and + # nightly is only reachable through an explicit `+nightly`. + # + # Nightly is not optional here. `hardlink-clone-selftest.sh` gates its + # two strongest assertions on `-Z checksum-freshness` — the mode where + # Cargo's dep-info file carries per-source checksums and is rewritten in + # place, which is the mutation that turns a hardlink clone into SILENT + # stale-artifact reuse rather than a slow build. Without a nightly the + # suite still runs, and skips exactly the hazard this whole scheme exists + # to close. + - name: Install Rust nightly + uses: dtolnay/rust-toolchain@nightly - name: Install Rust toolchain uses: dtolnay/rust-toolchain@stable diff --git a/README.md b/README.md index 671f9f5..3f4d847 100644 --- a/README.md +++ b/README.md @@ -544,7 +544,10 @@ bash scripts/selftest.sh --fast # fixture-only suites, no compiler Both run in CI — `.gitea/workflows/ci.yaml`, one job, on pushes to `main` and on PRs that were non-draft when the run was created. It installs shellcheck -and a stable Rust toolchain and references no credentials; the scratch +and both a stable and a nightly Rust toolchain (nightly for +`-Z checksum-freshness`, without which `hardlink-clone-selftest.sh` skips the +two assertions that cover the silent-stale-reuse hazard) and references no +credentials; the scratch workspaces the compiler-backed suites build use path dependencies only, so nothing reaches crates.io. It runs the full suite rather than `--fast`, because the two compiler-backed suites are the ones that check this scheme @@ -559,7 +562,7 @@ change here reaches all of them at once. That is what the gate is for. | suite | covers | |---|---| | `cache-root-selftest.sh` | that a lineage nests one level and nothing else moves: no lineage resolves byte-for-byte to the cache root, two lineages on one cache key get disjoint target dirs, seed/publish/prune all stay inside their own lineage, a PR layers over its own lineage's base snapshot — **and one rejection per lineage name a reader elsewhere would stop seeing**, plus the publish-side mismatch guard | -| `hardlink-clone-selftest.sh` | that a build in a clone cannot mutate its source — with a control proving a raw `cp -al` does. Needs a real compiler. | +| `hardlink-clone-selftest.sh` | that a build in a clone cannot mutate its source — with a control proving a raw `cp -al` does. Needs a real compiler, **and a nightly for two of its five assertions**: the checksum-freshness dep-info file is the mutation that turns a hardlink clone into silent stale-artifact reuse, and it only exists under `-Z checksum-freshness`. Without one those two are skipped, loudly. | | `seed-target-dir-selftest.sh` | seed-source preference, lock-file stripping, two jobs racing on one cache key, **and one scenario per check a hardlink clone is validated against**: a source rotated wholesale, a subtree silently lost from the walk, a copy that reports failure over a tree both other checks read as whole, and a source identity that resolved at neither end — plus a staging tree that could not be privately owned being discarded rather than published, and the publisher's log showing it waited on the consumer's own reader-lock marker before reclaiming a rotated snapshot | | `publish-snapshot-selftest.sh` | the atomic swap, that a live consumer survives a republish, and the publisher's side of the rotation race: deferred reclamation under a live reader, and its sweep once the reader is gone | | `prune-cache-selftest.sh` | liveness, protection, locking, eviction order, self-clear, **and that a cache a job claims *inside* the check-to-unlink window survives it** — against a real scratch `origin` | diff --git a/scripts/hardlink-clone-selftest.sh b/scripts/hardlink-clone-selftest.sh index 7364a49..818032f 100755 --- a/scripts/hardlink-clone-selftest.sh +++ b/scripts/hardlink-clone-selftest.sh @@ -73,11 +73,33 @@ mkcrate "$crate_dir" cd "$crate_dir" export CARGO_INCREMENTAL=0 + +# Every assertion below reads cargo's own words out of a build log +# (`Compiling libdep`, `Fresh probe`). A CI image that forces colour splices an +# ANSI reset between the status word and the crate name, at which point every +# one of those greps silently stops matching and the suite reports the +# opposite of what happened — observed on gitdan-ci's runner image, where +# scenario 2 failed while the log it printed plainly showed `Compiling libdep`. +# Pin the format the assertions are written against. +export CARGO_TERM_COLOR=never # Checksum freshness is where the worst failure lives (the dep-* file carries # per-source checksums and is rewritten in place). Only available on nightly; # without it the test still covers the build/ and *.d families. CHECKSUM_MODE="off" -if cargo +nightly -V >/dev/null 2>&1; then +# Probe the CAPABILITY, not the channel. `cargo +nightly -V` answers "did a +# cargo proxy called with +nightly exit 0", which is a different question from +# "will this build have checksum freshness" — `-V` short-circuits before `-Z` +# is validated at all, so that probe says yes on any cargo that resolves the +# name, including one whose nightly has since moved the flag. The scenario +# below then asserts the checksum-freshness mutation family against a build +# that never had it, and fails in the CONTROL, where a failure reads as "the +# hazard is gone" rather than "the toolchain is wrong". Observed the first +# time this suite ran on gitdan-ci. +# +# `-Z locate-project` is the narrowest command that actually parses the +# flag: it rejects the stable channel and an unknown flag name alike, needs no +# network, and builds nothing. +if cargo +nightly -Z checksum-freshness locate-project >/dev/null 2>&1; then export CARGO_UNSTABLE_CHECKSUM_FRESHNESS=true CARGO_BIN=(cargo +nightly) CHECKSUM_MODE="on" @@ -161,18 +183,32 @@ fi ok "no file in the source changed after a full rebuild in the clone" echo -echo "=== the whole point: the source's next build is still correct ===" -# The source's cache holds artifacts built from CONTENT_A. Advance the source -# to CONTENT_B (as a merge would) and rebuild in it. If the clone had -# corrupted its dep-info, Cargo would report Fresh and keep the stale rlib. -printf '%s\n' "$CONTENT_B" > src/lib.rs -touch -d '@1000000000' src/lib.rs -log="$scratch/rebuild.log" -CARGO_TARGET_DIR="$base_fix" "${CARGO_BIN[@]}" build -v > "$log" 2>&1 || { cat "$log"; fail "rebuild in the source failed"; } -if grep -qE '^\s+Fresh probe' "$log"; then - fail "source declared its own crate Fresh against sources it has never built — stale-artifact reuse" +if [ "$CHECKSUM_MODE" = "on" ]; then + echo "=== the whole point: the source's next build is still correct ===" + # The source's cache holds artifacts built from CONTENT_A. Advance the + # source to CONTENT_B (as a merge would) and rebuild in it. If the clone had + # corrupted its dep-info, Cargo would report Fresh and keep the stale rlib. + # + # CHECKSUM-FRESHNESS ONLY, and the backdated mtime is why. Under checksum + # freshness the dep-info file's per-source checksums decide, so a 2001 + # timestamp on changed content must still rebuild — the assertion below. + # Under Cargo's ordinary MTIME freshness the same timestamp means the source + # is older than the artifact, and reporting Fresh is the correct answer; + # asserting otherwise asserts a bug. This scenario was written against a + # machine with a nightly installed and, run without one, failed on that + # correct answer. + printf '%s\n' "$CONTENT_B" > src/lib.rs + touch -d '@1000000000' src/lib.rs + log="$scratch/rebuild.log" + CARGO_TARGET_DIR="$base_fix" "${CARGO_BIN[@]}" build -v > "$log" 2>&1 || { cat "$log"; fail "rebuild in the source failed"; } + if grep -qE '^\s+Fresh probe' "$log"; then + fail "source declared its own crate Fresh against sources it has never built — stale-artifact reuse" + fi + ok "source correctly rebuilt its crate after advancing to the clone's content" +else + echo "=== skipped: the source's-next-build scenario needs checksum freshness ===" + echo " (a nightly cargo accepting -Z checksum-freshness; see the probe above)" fi -ok "source correctly rebuilt its crate after advancing to the clone's content" echo echo "hardlink-clone-selftest: ${pass_count} assertions passed" diff --git a/scripts/restore-mtimes-selftest.sh b/scripts/restore-mtimes-selftest.sh index 66db0ea..020c9c1 100755 --- a/scripts/restore-mtimes-selftest.sh +++ b/scripts/restore-mtimes-selftest.sh @@ -75,6 +75,15 @@ # Asserts BOTH jobs correctly recompile the dependency and succeed. set -euo pipefail +# Every assertion below reads cargo's own words out of a build log +# (`Compiling libdep`, `Fresh probe`). A CI image that forces colour splices an +# ANSI reset between the status word and the crate name, at which point every +# one of those greps silently stops matching and the suite reports the +# opposite of what happened — observed on gitdan-ci's runner image, where +# scenario 2 failed while the log it printed plainly showed `Compiling libdep`. +# Pin the format the assertions are written against. +export CARGO_TERM_COLOR=never + script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd) restore_mtimes="$script_dir/restore-mtimes.sh" -- 2.43.0 From 5e8e773f78b823cf28fd333a653e46c5ccc02eba Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 26 Aug 2026 12:50:42 -0500 Subject: [PATCH 4/9] test(hardlink): report the mutation families, don't assert one of them MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CI's nightly is 1.100.0-nightly (2026-08-25); the machine this suite was written on had 1.96.0-nightly (2026-02-24). On the newer one the control's `cp -al` clone mutates only the build/ and *.d families — upstream appears to have stopped rewriting `.fingerprint/*/dep-*` in place under checksum freshness — so the suite went red on the *absence* of a hazard. That is the wrong shape for a gate. The control's job is to prove the hazard exists at all, which a non-empty mutated set already does; naming one family as mandatory makes the suite red whenever upstream stops doing something we never wanted it to do, and red in the CONTROL, where a failure reads as "the hazard is gone" rather than "upstream changed". It is now a note either way. Nothing is given up. The fix scenario asserts the source is byte-identical after a full rebuild in the clone, which covers every family the running Cargo has, named or not — and the checksum-freshness scenario after it tests the stale-reuse hazard directly. The dep-* line only ever documented which family was in play. `unshare_mutable_paths` keeps unsharing dep-* regardless, and its measurement block now records both observations with their versions: 22 MB of a 6.9 GB tree against a failure mode that is a wrong answer rather than a slow one. --- README.md | 4 ++-- scripts/cache-lib.sh | 12 +++++++++++- scripts/hardlink-clone-selftest.sh | 19 +++++++++++++++++-- 3 files changed, 30 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 3f4d847..8e2e0fb 100644 --- a/README.md +++ b/README.md @@ -546,7 +546,7 @@ Both run in CI — `.gitea/workflows/ci.yaml`, one job, on pushes to `main` and on PRs that were non-draft when the run was created. It installs shellcheck and both a stable and a nightly Rust toolchain (nightly for `-Z checksum-freshness`, without which `hardlink-clone-selftest.sh` skips the -two assertions that cover the silent-stale-reuse hazard) and references no +scenario that covers the silent-stale-reuse hazard) and references no credentials; the scratch workspaces the compiler-backed suites build use path dependencies only, so nothing reaches crates.io. It runs the full suite rather than `--fast`, @@ -562,7 +562,7 @@ change here reaches all of them at once. That is what the gate is for. | suite | covers | |---|---| | `cache-root-selftest.sh` | that a lineage nests one level and nothing else moves: no lineage resolves byte-for-byte to the cache root, two lineages on one cache key get disjoint target dirs, seed/publish/prune all stay inside their own lineage, a PR layers over its own lineage's base snapshot — **and one rejection per lineage name a reader elsewhere would stop seeing**, plus the publish-side mismatch guard | -| `hardlink-clone-selftest.sh` | that a build in a clone cannot mutate its source — with a control proving a raw `cp -al` does. Needs a real compiler, **and a nightly for two of its five assertions**: the checksum-freshness dep-info file is the mutation that turns a hardlink clone into silent stale-artifact reuse, and it only exists under `-Z checksum-freshness`. Without one those two are skipped, loudly. | +| `hardlink-clone-selftest.sh` | that a build in a clone cannot mutate its source — with a control proving a raw `cp -al` does. Needs a real compiler, **and a nightly for its last scenario**: the source's-next-build check reasons about content rather than mtime, so it only means anything under `-Z checksum-freshness`. Without one it is skipped, loudly. The control also reports which mutation families the running Cargo exhibits — a note, not an assertion, since that set moves upstream. | | `seed-target-dir-selftest.sh` | seed-source preference, lock-file stripping, two jobs racing on one cache key, **and one scenario per check a hardlink clone is validated against**: a source rotated wholesale, a subtree silently lost from the walk, a copy that reports failure over a tree both other checks read as whole, and a source identity that resolved at neither end — plus a staging tree that could not be privately owned being discarded rather than published, and the publisher's log showing it waited on the consumer's own reader-lock marker before reclaiming a rotated snapshot | | `publish-snapshot-selftest.sh` | the atomic swap, that a live consumer survives a republish, and the publisher's side of the rotation race: deferred reclamation under a live reader, and its sweep once the reader is gone | | `prune-cache-selftest.sh` | liveness, protection, locking, eviction order, self-clear, **and that a cache a job claims *inside* the check-to-unlink window survives it** — against a real scratch `origin` | diff --git a/scripts/cache-lib.sh b/scripts/cache-lib.sh index 7662251..0d01bef 100755 --- a/scripts/cache-lib.sh +++ b/scripts/cache-lib.sh @@ -332,7 +332,17 @@ _unshare_files() { # /.fingerprint//dep- (only under # CARGO_UNSTABLE_CHECKSUM_FRESHNESS, # where this file carries the -# per-source blake3 checksums) +# per-source blake3 checksums. +# NOT reproduced on +# 1.100.0-nightly (2026-08-25), +# measured by this repo's own CI +# — upstream appears to have +# stopped writing it in place. +# Kept in the unshared set +# anyway: it costs 22 MB of a +# 6.9 GB tree, and the failure +# it guards is a wrong answer, +# not a slow one.) # /build//output, root-output (Cargo build-script metadata) # /build//out/** (whatever the build script # writes into OUT_DIR — build diff --git a/scripts/hardlink-clone-selftest.sh b/scripts/hardlink-clone-selftest.sh index 818032f..22fc62b 100755 --- a/scripts/hardlink-clone-selftest.sh +++ b/scripts/hardlink-clone-selftest.sh @@ -134,11 +134,26 @@ fi ok "raw cp -al clone mutates the source ($(printf '%s\n' "$ctl_mutated" | wc -l) paths)" printf '%s\n' "$ctl_mutated" | sed 's/^/ /' +# Reported, not asserted, and the distinction is the point. The control's job +# is to prove the hazard exists at all, which the non-empty set above already +# does; this line records WHICH families a given Cargo exhibits. +# +# `.fingerprint/*/dep-*` is the worst of them — it carries the per-source +# checksums, so mutating it through a shared inode turns a hardlink clone into +# silent stale-artifact reuse rather than a slow build. It was measured on +# cargo 1.9x nightly (see unshare_mutable_paths in cache-lib.sh) and is NOT +# reproduced on 1.100.0-nightly (2026-08-25), where the control mutates only +# the build/ and *.d families. Failing on its absence would mean this suite +# goes red whenever upstream stops doing something we never wanted it to do — +# and it would go red in the CONTROL, where a failure reads as "the hazard is +# gone" rather than "upstream changed". Nothing is lost by reporting it: the +# fix scenario below asserts the source is byte-identical after a full rebuild +# in the clone, which covers every family this Cargo has, named or not. if [ "$CHECKSUM_MODE" = "on" ]; then if printf '%s' "$ctl_mutated" | grep -q '\.fingerprint/.*/dep-'; then - ok "control confirms the checksum-freshness dep-info file is among the mutated set" + echo " note: this cargo DOES rewrite .fingerprint/*/dep-* in place under checksum freshness" else - fail "expected .fingerprint/*/dep-* in the control's mutated set under checksum freshness" + echo " note: this cargo does NOT rewrite .fingerprint/*/dep-* in place; only the build/ and *.d families appear above" fi fi -- 2.43.0 From 6a80423bd0f3eba6692754579314248bfbeb8755 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 26 Aug 2026 12:54:24 -0500 Subject: [PATCH 5/9] test(hardlink): settle checksum freshness by experiment, not by asking MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Third toolchain probe in this branch, and the first one that asks the question the suite actually depends on. The two before it each let the suite assert a property the toolchain did not have: cargo +nightly -V answers "did a proxy called with +nightly exit 0". `-V` short-circuits before `-Z` is parsed at all. cargo +nightly -Z checksum-freshness answers "is the flag still accepted". locate-project 1.100.0-nightly (2026-08-25) accepts it and resolves freshness by mtime anyway, which is how CI reached the final scenario and failed there. The final scenario depends on exactly one property: that changed content with an OLDER mtime rebuilds. Under mtime freshness the correct answer is Fresh, so under mtime freshness that scenario asserts a bug — which is what CI reported. So the probe performs that experiment, on its own crate and its own target dir, with no clone anywhere near it. That separation is also what keeps it a control rather than a restatement: the probe establishes that the toolchain rebuilds on content, the scenario establishes that a hardlink clone did not take that away. Verified both ways locally: with a real content-freshness nightly, mode on and 4 assertions; with the env var stripped inside the probe — the runner's condition, faithfully — the probe says so by name, mode goes off, the scenario is skipped loudly and the remaining 3 assertions pass. --- README.md | 2 +- scripts/hardlink-clone-selftest.sh | 73 ++++++++++++++++++++---------- 2 files changed, 51 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 8e2e0fb..96fd1b1 100644 --- a/README.md +++ b/README.md @@ -562,7 +562,7 @@ change here reaches all of them at once. That is what the gate is for. | suite | covers | |---|---| | `cache-root-selftest.sh` | that a lineage nests one level and nothing else moves: no lineage resolves byte-for-byte to the cache root, two lineages on one cache key get disjoint target dirs, seed/publish/prune all stay inside their own lineage, a PR layers over its own lineage's base snapshot — **and one rejection per lineage name a reader elsewhere would stop seeing**, plus the publish-side mismatch guard | -| `hardlink-clone-selftest.sh` | that a build in a clone cannot mutate its source — with a control proving a raw `cp -al` does. Needs a real compiler, **and a nightly for its last scenario**: the source's-next-build check reasons about content rather than mtime, so it only means anything under `-Z checksum-freshness`. Without one it is skipped, loudly. The control also reports which mutation families the running Cargo exhibits — a note, not an assertion, since that set moves upstream. | +| `hardlink-clone-selftest.sh` | that a build in a clone cannot mutate its source — with a control proving a raw `cp -al` does. Needs a real compiler, **and a nightly that actually resolves freshness by content for its last scenario**: the source's-next-build check reasons about content rather than mtime, so under mtime freshness it would assert a bug. Whether the toolchain does is settled by experiment on a throwaway crate, not by asking it — 1.100.0-nightly accepts `-Z checksum-freshness` and rebuilds on mtime anyway. Otherwise the scenario is skipped, loudly. The control also reports which mutation families the running Cargo exhibits — a note, not an assertion, since that set moves upstream. | | `seed-target-dir-selftest.sh` | seed-source preference, lock-file stripping, two jobs racing on one cache key, **and one scenario per check a hardlink clone is validated against**: a source rotated wholesale, a subtree silently lost from the walk, a copy that reports failure over a tree both other checks read as whole, and a source identity that resolved at neither end — plus a staging tree that could not be privately owned being discarded rather than published, and the publisher's log showing it waited on the consumer's own reader-lock marker before reclaiming a rotated snapshot | | `publish-snapshot-selftest.sh` | the atomic swap, that a live consumer survives a republish, and the publisher's side of the rotation race: deferred reclamation under a live reader, and its sweep once the reader is gone | | `prune-cache-selftest.sh` | liveness, protection, locking, eviction order, self-clear, **and that a cache a job claims *inside* the check-to-unlink window survives it** — against a real scratch `origin` | diff --git a/scripts/hardlink-clone-selftest.sh b/scripts/hardlink-clone-selftest.sh index 22fc62b..525e4fd 100755 --- a/scripts/hardlink-clone-selftest.sh +++ b/scripts/hardlink-clone-selftest.sh @@ -85,32 +85,59 @@ export CARGO_TERM_COLOR=never # Checksum freshness is where the worst failure lives (the dep-* file carries # per-source checksums and is rewritten in place). Only available on nightly; # without it the test still covers the build/ and *.d families. -CHECKSUM_MODE="off" -# Probe the CAPABILITY, not the channel. `cargo +nightly -V` answers "did a -# cargo proxy called with +nightly exit 0", which is a different question from -# "will this build have checksum freshness" — `-V` short-circuits before `-Z` -# is validated at all, so that probe says yes on any cargo that resolves the -# name, including one whose nightly has since moved the flag. The scenario -# below then asserts the checksum-freshness mutation family against a build -# that never had it, and fails in the CONTROL, where a failure reads as "the -# hazard is gone" rather than "the toolchain is wrong". Observed the first -# time this suite ran on gitdan-ci. -# -# `-Z locate-project` is the narrowest command that actually parses the -# flag: it rejects the stable channel and an unknown flag name alike, needs no -# network, and builds nothing. -if cargo +nightly -Z checksum-freshness locate-project >/dev/null 2>&1; then - export CARGO_UNSTABLE_CHECKSUM_FRESHNESS=true - CARGO_BIN=(cargo +nightly) - CHECKSUM_MODE="on" -else - CARGO_BIN=(cargo) -fi -echo "=== checksum-freshness mode: ${CHECKSUM_MODE} ===" - CONTENT_A='pub fn f() -> u32 { 1 }' CONTENT_B='pub fn f() -> u32 { 22222 } pub fn g() -> u32 { 7 }' +# Probe the BEHAVIOUR, not the channel and not the flag. Two weaker probes +# were tried against gitdan-ci's runner and each let the suite assert a +# property the toolchain did not have: +# +# `cargo +nightly -V` — answers "did a proxy called with +# +nightly exit 0". `-V` +# short-circuits before `-Z` is +# even parsed. +# `cargo +nightly -Z checksum-freshness — answers "is this flag still +# locate-project` accepted". 1.100.0-nightly +# (2026-08-25) accepts it and does +# not resolve freshness by content +# anyway. +# +# The scenario at the end of this file depends on one thing and it is neither +# of those: that changed content with an OLDER mtime rebuilds. Under mtime +# freshness the correct answer is Fresh, so under mtime freshness that +# scenario asserts a bug. So the probe simply performs that experiment, on its +# own crate and its own target dir, with no clone anywhere near it — which is +# also what makes it a control rather than a restatement of the scenario: the +# probe establishes that the toolchain rebuilds on content, the scenario +# establishes that a hardlink clone did not take that away. +CHECKSUM_MODE="off" +CARGO_BIN=(cargo) +checksum_freshness_active() { + local d="$scratch/freshness-probe" t="$scratch/freshness-probe-target" + mkcrate "$d" + ( + cd "$d" || exit 1 + printf '%s\n' "$CONTENT_A" > src/lib.rs + CARGO_TARGET_DIR="$t" cargo +nightly build -q > /dev/null 2>&1 || exit 1 + printf '%s\n' "$CONTENT_B" > src/lib.rs + touch -d '@1000000000' src/lib.rs + CARGO_TARGET_DIR="$t" cargo +nightly build -v > "$scratch/freshness-probe.log" 2>&1 || exit 1 + ! grep -qE '^\s+Fresh probe' "$scratch/freshness-probe.log" + ) +} +if cargo +nightly -Z checksum-freshness locate-project > /dev/null 2>&1; then + export CARGO_UNSTABLE_CHECKSUM_FRESHNESS=true + if checksum_freshness_active; then + CARGO_BIN=(cargo +nightly) + CHECKSUM_MODE="on" + else + unset CARGO_UNSTABLE_CHECKSUM_FRESHNESS + echo "note: this nightly accepts -Z checksum-freshness but still resolves freshness by mtime" + fi +fi +cd "$crate_dir" +echo "=== checksum-freshness mode: ${CHECKSUM_MODE} ===" + build_base() { local dir="$1" printf '%s\n' "$CONTENT_A" > src/lib.rs -- 2.43.0 From eb3f0bd09b56c8489a4d5690938482f6600b15fb Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 26 Aug 2026 12:57:15 -0500 Subject: [PATCH 6/9] docs(ci): say what the nightly step actually buys today MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The step's comment claimed nightly was not optional. CI's own first green run falsified that: 1.100.0-nightly accepts -Z checksum-freshness and resolves freshness by mtime regardless, so the suite's probe reports it and skips the scenario either way. The step stays — twenty seconds, and the coverage returns by itself the day upstream restores the behaviour — but the comment now says that rather than the opposite. The open question about what upstream actually did is daniel/gitdan#62. --- .gitea/workflows/ci.yaml | 17 ++++++++++------- README.md | 8 ++++---- 2 files changed, 14 insertions(+), 11 deletions(-) diff --git a/.gitea/workflows/ci.yaml b/.gitea/workflows/ci.yaml index 4bb9ea8..a0a70c4 100644 --- a/.gitea/workflows/ci.yaml +++ b/.gitea/workflows/ci.yaml @@ -69,13 +69,16 @@ jobs: # Nightly first, stable second, so stable ends up the default and # nightly is only reachable through an explicit `+nightly`. # - # Nightly is not optional here. `hardlink-clone-selftest.sh` gates its - # two strongest assertions on `-Z checksum-freshness` — the mode where - # Cargo's dep-info file carries per-source checksums and is rewritten in - # place, which is the mutation that turns a hardlink clone into SILENT - # stale-artifact reuse rather than a slow build. Without a nightly the - # suite still runs, and skips exactly the hazard this whole scheme exists - # to close. + # `hardlink-clone-selftest.sh`'s last scenario needs a Cargo that + # resolves freshness by CONTENT — the mode where the dep-info file + # carries per-source checksums, which is the mutation that turns a + # hardlink clone into silent stale-artifact reuse rather than a slow + # build. As of 1.100.0-nightly (2026-08-25) no nightly provides it: + # `-Z checksum-freshness` is still accepted and freshness is still + # resolved by mtime, so the suite's probe reports that by name and skips + # the scenario. This step therefore buys nothing today and is kept + # anyway — it costs about twenty seconds, and the day upstream restores + # the behaviour the coverage comes back with no edit here. See daniel/gitdan#62. - name: Install Rust nightly uses: dtolnay/rust-toolchain@nightly - name: Install Rust toolchain diff --git a/README.md b/README.md index 96fd1b1..039802f 100644 --- a/README.md +++ b/README.md @@ -544,10 +544,10 @@ bash scripts/selftest.sh --fast # fixture-only suites, no compiler Both run in CI — `.gitea/workflows/ci.yaml`, one job, on pushes to `main` and on PRs that were non-draft when the run was created. It installs shellcheck -and both a stable and a nightly Rust toolchain (nightly for -`-Z checksum-freshness`, without which `hardlink-clone-selftest.sh` skips the -scenario that covers the silent-stale-reuse hazard) and references no -credentials; the scratch +and both a stable and a nightly Rust toolchain (nightly so +`hardlink-clone-selftest.sh` can run its content-freshness scenario — which no +nightly currently enables, so it is skipped and the step is kept only against +the day upstream restores it) and references no credentials; the scratch workspaces the compiler-backed suites build use path dependencies only, so nothing reaches crates.io. It runs the full suite rather than `--fast`, because the two compiler-backed suites are the ones that check this scheme -- 2.43.0 From 5a90d5c829516e9747a614a28cbee3e3c1a8a1b8 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 26 Aug 2026 13:34:42 -0500 Subject: [PATCH 7/9] test(hardlink): let the freshness probe report that it could not measure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review finding on #13. `checksum_freshness_active()` returned non-zero for any reason — including its own `cargo build` failing — and the caller's `else` branch then announced "this nightly accepts -Z checksum-freshness but still resolves freshness by mtime" regardless. On a machine where content freshness IS live, breaking only the probe's build produced that sentence, which is false, and silently dropped the scenario, which is lost coverage. Reachable, not theoretical: it needs a half-installed toolchain, which is exactly the state a probe exists to notice. The whole point of the preceding commit was to settle this by experiment rather than by asking, and an experiment that cannot tell a negative result from a failed measurement is not settling it. "This toolchain resolves freshness by mtime" is a statement about Cargo; "a probe build failed" is a statement about this machine. They are not interchangeable. Three outcomes now, carried in an exit code: 0 measured ACTIVE both builds ran, the backdated rebuild recompiled 1 measured INACTIVE both builds ran, the backdated rebuild was Fresh 2 NOT MEASURED a probe step failed; nothing was learned Every step that could fail for a reason other than the experiment's own outcome exits 2 explicitly, so a `set -e` abort cannot be mistaken for the 1 that means "measured, and the answer is mtime". Outcome 2 emits a ::warning:: saying in those words that this is a failure to measure and not a finding about Cargo, and prints the tail of both probe logs. The scenario still skips for 1 and 2 alike — everything else the suite asserts is independent of freshness mode — but the reason is now carried to the skip line, so the two are distinguishable at a glance. Verified all three states on a machine where freshness is live: unmodified, mode `on` and 4 assertions; probe build broken with a bogus flag, mode `unmeasured` with the warning and 3 assertions, and no claim about mtime; CARGO_UNSTABLE_CHECKSUM_FRESHNESS stripped inside the probe — CI's condition — mode `off` naming mtime, and 3 assertions. --- README.md | 2 +- scripts/hardlink-clone-selftest.sh | 75 ++++++++++++++++++++++-------- 2 files changed, 57 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 039802f..d2abbfe 100644 --- a/README.md +++ b/README.md @@ -562,7 +562,7 @@ change here reaches all of them at once. That is what the gate is for. | suite | covers | |---|---| | `cache-root-selftest.sh` | that a lineage nests one level and nothing else moves: no lineage resolves byte-for-byte to the cache root, two lineages on one cache key get disjoint target dirs, seed/publish/prune all stay inside their own lineage, a PR layers over its own lineage's base snapshot — **and one rejection per lineage name a reader elsewhere would stop seeing**, plus the publish-side mismatch guard | -| `hardlink-clone-selftest.sh` | that a build in a clone cannot mutate its source — with a control proving a raw `cp -al` does. Needs a real compiler, **and a nightly that actually resolves freshness by content for its last scenario**: the source's-next-build check reasons about content rather than mtime, so under mtime freshness it would assert a bug. Whether the toolchain does is settled by experiment on a throwaway crate, not by asking it — 1.100.0-nightly accepts `-Z checksum-freshness` and rebuilds on mtime anyway. Otherwise the scenario is skipped, loudly. The control also reports which mutation families the running Cargo exhibits — a note, not an assertion, since that set moves upstream. | +| `hardlink-clone-selftest.sh` | that a build in a clone cannot mutate its source — with a control proving a raw `cp -al` does. Needs a real compiler, **and a nightly that actually resolves freshness by content for its last scenario**: the source's-next-build check reasons about content rather than mtime, so under mtime freshness it would assert a bug. Whether the toolchain does is settled by experiment on a throwaway crate, not by asking it — 1.100.0-nightly accepts `-Z checksum-freshness` and rebuilds on mtime anyway. The experiment reports **three** outcomes, not two: active, measured-inactive, and *not measured* when a probe build failed. The scenario is skipped for the last two alike, but a failure to measure is never reported as a measurement. The control also reports which mutation families the running Cargo exhibits — a note, not an assertion, since that set moves upstream. | | `seed-target-dir-selftest.sh` | seed-source preference, lock-file stripping, two jobs racing on one cache key, **and one scenario per check a hardlink clone is validated against**: a source rotated wholesale, a subtree silently lost from the walk, a copy that reports failure over a tree both other checks read as whole, and a source identity that resolved at neither end — plus a staging tree that could not be privately owned being discarded rather than published, and the publisher's log showing it waited on the consumer's own reader-lock marker before reclaiming a rotated snapshot | | `publish-snapshot-selftest.sh` | the atomic swap, that a live consumer survives a republish, and the publisher's side of the rotation race: deferred reclamation under a live reader, and its sweep once the reader is gone | | `prune-cache-selftest.sh` | liveness, protection, locking, eviction order, self-clear, **and that a cache a job claims *inside* the check-to-unlink window survives it** — against a real scratch `origin` | diff --git a/scripts/hardlink-clone-selftest.sh b/scripts/hardlink-clone-selftest.sh index 525e4fd..974564e 100755 --- a/scripts/hardlink-clone-selftest.sh +++ b/scripts/hardlink-clone-selftest.sh @@ -110,33 +110,70 @@ CONTENT_B='pub fn f() -> u32 { 22222 } pub fn g() -> u32 { 7 }' # also what makes it a control rather than a restatement of the scenario: the # probe establishes that the toolchain rebuilds on content, the scenario # establishes that a hardlink clone did not take that away. +# THREE OUTCOMES, NOT TWO. An experiment that cannot tell a negative result +# from a failed measurement is not settling the question, and the two are not +# interchangeable here: "this toolchain resolves freshness by mtime" is a +# statement about Cargo, while "a probe build failed" is a statement about this +# machine. Collapsing them — which an earlier cut of this did, by returning +# non-zero for both — makes a half-installed toolchain print a confident and +# wrong explanation and quietly drop a scenario. The scenario still has to be +# skipped in either case; what must not happen is the log claiming to know why. +# +# 0 content freshness measured ACTIVE — both builds ran, the backdated +# rebuild recompiled +# 1 measured INACTIVE — both builds ran, the backdated +# rebuild reported Fresh +# 2 NOT MEASURED — a probe step failed; nothing was +# learned about the toolchain +# +# Every step that could fail for a reason other than the experiment's own +# outcome exits 2 explicitly, so a `set -e` abort can never be mistaken for the +# `1` that means "measured, and the answer is mtime". CHECKSUM_MODE="off" +CHECKSUM_REASON="no nightly on PATH accepting -Z checksum-freshness" CARGO_BIN=(cargo) -checksum_freshness_active() { +checksum_freshness_probe() { local d="$scratch/freshness-probe" t="$scratch/freshness-probe-target" - mkcrate "$d" + mkcrate "$d" || return 2 ( - cd "$d" || exit 1 - printf '%s\n' "$CONTENT_A" > src/lib.rs - CARGO_TARGET_DIR="$t" cargo +nightly build -q > /dev/null 2>&1 || exit 1 - printf '%s\n' "$CONTENT_B" > src/lib.rs - touch -d '@1000000000' src/lib.rs - CARGO_TARGET_DIR="$t" cargo +nightly build -v > "$scratch/freshness-probe.log" 2>&1 || exit 1 - ! grep -qE '^\s+Fresh probe' "$scratch/freshness-probe.log" + cd "$d" || exit 2 + printf '%s\n' "$CONTENT_A" > src/lib.rs || exit 2 + CARGO_TARGET_DIR="$t" cargo +nightly build -q > "$scratch/freshness-probe-warm.log" 2>&1 || exit 2 + printf '%s\n' "$CONTENT_B" > src/lib.rs || exit 2 + touch -d '@1000000000' src/lib.rs || exit 2 + CARGO_TARGET_DIR="$t" cargo +nightly build -v > "$scratch/freshness-probe.log" 2>&1 || exit 2 + if grep -qE '^\s+Fresh probe' "$scratch/freshness-probe.log"; then exit 1; fi + exit 0 ) } if cargo +nightly -Z checksum-freshness locate-project > /dev/null 2>&1; then export CARGO_UNSTABLE_CHECKSUM_FRESHNESS=true - if checksum_freshness_active; then - CARGO_BIN=(cargo +nightly) - CHECKSUM_MODE="on" - else - unset CARGO_UNSTABLE_CHECKSUM_FRESHNESS - echo "note: this nightly accepts -Z checksum-freshness but still resolves freshness by mtime" - fi + probe_rc=0 + checksum_freshness_probe || probe_rc=$? + case "$probe_rc" in + 0) + CARGO_BIN=(cargo +nightly) + CHECKSUM_MODE="on" + CHECKSUM_REASON="" + ;; + 1) + unset CARGO_UNSTABLE_CHECKSUM_FRESHNESS + CHECKSUM_REASON="this nightly accepts -Z checksum-freshness but resolves freshness by mtime" + ;; + *) + unset CARGO_UNSTABLE_CHECKSUM_FRESHNESS + CHECKSUM_MODE="unmeasured" + CHECKSUM_REASON="a probe build failed, so this was NOT MEASURED — this toolchain may or may not resolve freshness by content" + # Loud, because the cost is silently lost coverage on a machine that + # might have had it. The suite continues: everything else it asserts is + # independent of freshness mode. + echo "::warning::hardlink-clone-selftest: could not measure whether this toolchain resolves freshness by content — a probe build failed. This is a failure to measure, not a finding about Cargo." + tail -n 15 "$scratch/freshness-probe-warm.log" "$scratch/freshness-probe.log" 2>/dev/null | sed 's/^/ /' >&2 || true + ;; + esac fi cd "$crate_dir" -echo "=== checksum-freshness mode: ${CHECKSUM_MODE} ===" +echo "=== checksum-freshness mode: ${CHECKSUM_MODE}${CHECKSUM_REASON:+ — ${CHECKSUM_REASON}} ===" build_base() { local dir="$1" @@ -248,8 +285,8 @@ if [ "$CHECKSUM_MODE" = "on" ]; then fi ok "source correctly rebuilt its crate after advancing to the clone's content" else - echo "=== skipped: the source's-next-build scenario needs checksum freshness ===" - echo " (a nightly cargo accepting -Z checksum-freshness; see the probe above)" + echo "=== skipped: the source's-next-build scenario needs content-based freshness ===" + echo " reason: ${CHECKSUM_REASON}" fi echo -- 2.43.0 From 5b46986cd7d2ecceff19b72ac67e197cfac34a66 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 26 Aug 2026 14:28:22 -0500 Subject: [PATCH 8/9] test(hardlink): make the errexit invariant real, and stop gpg deciding a gate MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two review findings on #13. THE STATED INVARIANT WAS NOT IN FORCE. The header claimed a `set -e` abort could never be mistaken for the `1` that means "measured, and the answer is mtime". It could not fire at all: `checksum_freshness_probe || probe_rc=$?` runs the left side with errexit suppressed, and that suppression propagates into the subshell. An unguarded step there fell through to `exit 0` and reported ACTIVE — a fourth outcome the header said was impossible. The guard audit was complete, so nothing was broken; the wrong mechanism had the credit, in a comment inviting the next editor to add an unguarded step and rely on it. The suggested fix — `set -e` as the first line of the subshell — does not work, and measured on bash 5.3 it makes things worse rather than not-better: set -e inside a subshell called via `||` or `if` still falls through: rc=0 set -e inside, called with errexit off at the site aborts, but with the FAILING COMMAND's status — `false` gives 1, which is exactly the value that means "mtime" So both halves are needed and neither is decoration: `set +e` around the call site, so the subshell can arm its own errexit at all, and `trap 'exit 2' ERR` inside it, so an abort lands on "not measured" instead of on an answer. The explicit `|| exit 2` guards stay as the first line of defence. All of that is now written down where the false claim was. Red-proven with one unguarded `false` between the `touch` and the second build, on a box where freshness is live: without the fix, mode `on` and 4 assertions — the reviewer's fourth outcome, reproduced; with it, mode `unmeasured`, the warning, 3 assertions; unmodified, mode `on` and 4. Recorded in the same block, since the next person to hit a `2` will ask: why it skips rather than fails. The gated scenario is the only thing here that depends on freshness mode, and failing would turn a statement about one machine into a red gate reading "the hardlink scheme is broken" across three consuming repos. What would change the answer is `2` becoming the everyday CI outcome, and run 2583 measures that it is not — gitdan-ci reports `1`. GPG. The two suites that commit in scratch repos inherited the developer's GLOBAL `commit.gpgsign`, so whether this gate passes could depend on their gpg agent — seen as a red `restore-mtimes-selftest.sh` caused by a full disk breaking gpg, in a suite with nothing to say about either. Pinned off locally, in the throwaway repos only: `git config commit.gpgsign false` beside the identity the scratch repo already sets, and `-c commit.gpgsign=false` on prune-cache-selftest's three commits, matching its existing `-c` style. Red-proven under a GIT_CONFIG_GLOBAL with gpgsign on and a nonexistent gpg program: without it `fatal: failed to write commit object`, with it both suites pass. --- scripts/hardlink-clone-selftest.sh | 38 ++++++++++++++++++++++++++---- scripts/prune-cache-selftest.sh | 6 ++--- scripts/restore-mtimes-selftest.sh | 5 ++++ 3 files changed, 42 insertions(+), 7 deletions(-) diff --git a/scripts/hardlink-clone-selftest.sh b/scripts/hardlink-clone-selftest.sh index 974564e..f5f8510 100755 --- a/scripts/hardlink-clone-selftest.sh +++ b/scripts/hardlink-clone-selftest.sh @@ -126,9 +126,32 @@ CONTENT_B='pub fn f() -> u32 { 22222 } pub fn g() -> u32 { 7 }' # 2 NOT MEASURED — a probe step failed; nothing was # learned about the toolchain # -# Every step that could fail for a reason other than the experiment's own -# outcome exits 2 explicitly, so a `set -e` abort can never be mistaken for the -# `1` that means "measured, and the answer is mtime". +# Two mechanisms, and BOTH are needed. Every step that could fail for a reason +# other than the experiment's own outcome exits 2 explicitly; the subshell also +# arms `set -e` with an ERR trap that maps any unguarded failure onto 2, so a +# step added later without a guard lands on "not measured" rather than on an +# answer. +# +# The `set +e` around the call site is what makes the second mechanism work, +# and it is not decoration. A command on the left of `||` — or in an `if` +# condition — runs with errexit suppressed, and that suppression propagates +# into a subshell and is NOT undone by a `set -e` inside it (verified on bash +# 5.3: an unguarded `false` there falls through to `exit 0` and reports +# ACTIVE). Calling with errexit disarmed at the site is the only form that +# lets the subshell re-arm it. The ERR trap is then required on top, because a +# bare `set -e` abort exits with the FAILING COMMAND's status — `false` gives +# 1, which is precisely the value that means "measured, and the answer is +# mtime". Belt and braces here buys a wrong answer; belt, braces and a trap +# buys "not measured". +# +# WHY 2 SKIPS RATHER THAN FAILS. The scenario it gates is the only thing in +# this suite that depends on freshness mode; everything else still runs and +# still catches real regressions. Failing instead would turn a statement about +# one machine's toolchain into a red gate reading "the hardlink scheme is +# broken" across the three repos consuming this action — the same category +# error the three-state split exists to prevent, one level up. What would +# change the answer is 2 becoming the everyday CI outcome; it is not (gitdan-ci +# reports 1, by measurement). CHECKSUM_MODE="off" CHECKSUM_REASON="no nightly on PATH accepting -Z checksum-freshness" CARGO_BIN=(cargo) @@ -136,6 +159,8 @@ checksum_freshness_probe() { local d="$scratch/freshness-probe" t="$scratch/freshness-probe-target" mkcrate "$d" || return 2 ( + set -e + trap 'exit 2' ERR cd "$d" || exit 2 printf '%s\n' "$CONTENT_A" > src/lib.rs || exit 2 CARGO_TARGET_DIR="$t" cargo +nightly build -q > "$scratch/freshness-probe-warm.log" 2>&1 || exit 2 @@ -148,8 +173,13 @@ checksum_freshness_probe() { } if cargo +nightly -Z checksum-freshness locate-project > /dev/null 2>&1; then export CARGO_UNSTABLE_CHECKSUM_FRESHNESS=true + # Errexit off across the call, so the subshell can arm its own — see the + # header. `probe_rc` is read before it is restored. probe_rc=0 - checksum_freshness_probe || probe_rc=$? + set +e + checksum_freshness_probe + probe_rc=$? + set -e case "$probe_rc" in 0) CARGO_BIN=(cargo +nightly) diff --git a/scripts/prune-cache-selftest.sh b/scripts/prune-cache-selftest.sh index 1ffa885..ab7c8cf 100755 --- a/scripts/prune-cache-selftest.sh +++ b/scripts/prune-cache-selftest.sh @@ -65,10 +65,10 @@ origin="$scratch/origin.git"; git init -q --bare "$origin" work="$scratch/work"; git init -q "$work" ( cd "$work" - git -c user.email=t@t -c user.name=t commit -q --allow-empty -m init + git -c user.email=t@t -c user.name=t -c commit.gpgsign=false commit -q --allow-empty -m init git branch -M main - git checkout -q -b dev; git -c user.email=t@t -c user.name=t commit -q --allow-empty -m dev - git checkout -q -b feat/live; git -c user.email=t@t -c user.name=t commit -q --allow-empty -m live + git checkout -q -b dev; git -c user.email=t@t -c user.name=t -c commit.gpgsign=false commit -q --allow-empty -m dev + git checkout -q -b feat/live; git -c user.email=t@t -c user.name=t -c commit.gpgsign=false commit -q --allow-empty -m live git remote add origin "$origin" git push -q origin main dev feat/live ) diff --git a/scripts/restore-mtimes-selftest.sh b/scripts/restore-mtimes-selftest.sh index 020c9c1..c9412a1 100755 --- a/scripts/restore-mtimes-selftest.sh +++ b/scripts/restore-mtimes-selftest.sh @@ -140,6 +140,11 @@ cd "$repo" git init -q git config user.email test@example.com git config user.name "restore-mtimes-selftest" +# Local to this mktemp'd throwaway repo. Without it the eight commits below +# inherit the developer's GLOBAL commit.gpgsign, which makes whether this gate +# passes depend on their gpg agent — observed as a red run caused by a full +# disk breaking gpg, in a suite that has nothing to say about either. +git config commit.gpgsign false cat > Cargo.toml <<'EOF' [workspace] -- 2.43.0 From e94c46f2ec20b53f58fddef3aa7f64bd24915a6b Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 26 Aug 2026 14:40:27 -0500 Subject: [PATCH 9/9] test(hardlink): move the probe's INACTIVE answer off bash's error codes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review finding on #13, and the last change to this function. A typo'd variable name on a line that HAS its `|| exit 2` guard — `$CONTNET_B` for `$CONTENT_B` — fails in EXPANSION, before the command runs, so neither the guard nor the ERR trap ever sees it. Under `set -u` that exits 1, which was the code meaning "measured, and the answer is mtime". Not a live defect: the probe references only set variables today, and the 1 gitdan-ci reports is a genuine measurement. The defect is that the answer codes and the error codes overlapped at all. Three rounds on this function each found a narrower way for a shell-generated 1 to be read as a measurement — an unguarded command, then a guarded line whose guard could not fire — and each was closed by narrowing the failure surface, which is a game with no last move. INACTIVE is now 3, and anything that is not 0 or 3 is NOT MEASURED. Bash generates 1, 2, 126, 127 and 128+n for its own errors and never 3, so "not an answer" is decided by a property of the shell rather than by an enumeration of the ways a step can go wrong. A step added later without a guard, or with a guard that cannot fire, lands on NOT MEASURED by construction. The guards and the trap stay, with their job restated: reporting rather than correctness. They put a failed step on 2 with both probe logs printed instead of on some incidental status — nicer to debug, and the same destination either way. The `set +e` bracket at the call site keeps its own note, since a `set -e` that cannot fire is the kind of thing a reader assumes works. The not-measured message now quotes the actual exit code, so the two ways to reach it are distinguishable in a log without reading this file. Red-proven with the reviewer's own mutation, A/B: with INACTIVE at 1 the typo reports `mode: off — resolves freshness by mtime`, a false measurement; at 3 it reports `mode: unmeasured — the probe exited 1`. All four paths re-verified — unmodified 4 assertions; env stripped inside the probe, measured INACTIVE with the mtime reason; a broken probe build, unmeasured via a guard; an unguarded `false`, unmeasured via the trap. --- README.md | 2 +- scripts/hardlink-clone-selftest.sh | 70 ++++++++++++++++++------------ 2 files changed, 44 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index d2abbfe..31d833c 100644 --- a/README.md +++ b/README.md @@ -562,7 +562,7 @@ change here reaches all of them at once. That is what the gate is for. | suite | covers | |---|---| | `cache-root-selftest.sh` | that a lineage nests one level and nothing else moves: no lineage resolves byte-for-byte to the cache root, two lineages on one cache key get disjoint target dirs, seed/publish/prune all stay inside their own lineage, a PR layers over its own lineage's base snapshot — **and one rejection per lineage name a reader elsewhere would stop seeing**, plus the publish-side mismatch guard | -| `hardlink-clone-selftest.sh` | that a build in a clone cannot mutate its source — with a control proving a raw `cp -al` does. Needs a real compiler, **and a nightly that actually resolves freshness by content for its last scenario**: the source's-next-build check reasons about content rather than mtime, so under mtime freshness it would assert a bug. Whether the toolchain does is settled by experiment on a throwaway crate, not by asking it — 1.100.0-nightly accepts `-Z checksum-freshness` and rebuilds on mtime anyway. The experiment reports **three** outcomes, not two: active, measured-inactive, and *not measured* when a probe build failed. The scenario is skipped for the last two alike, but a failure to measure is never reported as a measurement. The control also reports which mutation families the running Cargo exhibits — a note, not an assertion, since that set moves upstream. | +| `hardlink-clone-selftest.sh` | that a build in a clone cannot mutate its source — with a control proving a raw `cp -al` does. Needs a real compiler, **and a nightly that actually resolves freshness by content for its last scenario**: the source's-next-build check reasons about content rather than mtime, so under mtime freshness it would assert a bug. Whether the toolchain does is settled by experiment on a throwaway crate, not by asking it — 1.100.0-nightly accepts `-Z checksum-freshness` and rebuilds on mtime anyway. The experiment reports **three** outcomes, not two: active, measured-inactive, and *not measured*. Its answer codes are `0` and `3`, deliberately clear of every status bash generates for its own errors — so nothing that goes wrong inside the probe, including an expansion failure no guard can catch, can be read as an answer. The scenario is skipped for the last two alike, but a failure to measure is never reported as a measurement. The control also reports which mutation families the running Cargo exhibits — a note, not an assertion, since that set moves upstream. | | `seed-target-dir-selftest.sh` | seed-source preference, lock-file stripping, two jobs racing on one cache key, **and one scenario per check a hardlink clone is validated against**: a source rotated wholesale, a subtree silently lost from the walk, a copy that reports failure over a tree both other checks read as whole, and a source identity that resolved at neither end — plus a staging tree that could not be privately owned being discarded rather than published, and the publisher's log showing it waited on the consumer's own reader-lock marker before reclaiming a rotated snapshot | | `publish-snapshot-selftest.sh` | the atomic swap, that a live consumer survives a republish, and the publisher's side of the rotation race: deferred reclamation under a live reader, and its sweep once the reader is gone | | `prune-cache-selftest.sh` | liveness, protection, locking, eviction order, self-clear, **and that a cache a job claims *inside* the check-to-unlink window survives it** — against a real scratch `origin` | diff --git a/scripts/hardlink-clone-selftest.sh b/scripts/hardlink-clone-selftest.sh index f5f8510..163f176 100755 --- a/scripts/hardlink-clone-selftest.sh +++ b/scripts/hardlink-clone-selftest.sh @@ -121,43 +121,57 @@ CONTENT_B='pub fn f() -> u32 { 22222 } pub fn g() -> u32 { 7 }' # # 0 content freshness measured ACTIVE — both builds ran, the backdated # rebuild recompiled -# 1 measured INACTIVE — both builds ran, the backdated +# 3 measured INACTIVE — both builds ran, the backdated # rebuild reported Fresh -# 2 NOT MEASURED — a probe step failed; nothing was -# learned about the toolchain +# anything else NOT MEASURED — nothing was learned about the +# toolchain # -# Two mechanisms, and BOTH are needed. Every step that could fail for a reason -# other than the experiment's own outcome exits 2 explicitly; the subshell also -# arms `set -e` with an ERR trap that maps any unguarded failure onto 2, so a -# step added later without a guard lands on "not measured" rather than on an -# answer. +# THE ANSWER CODES ARE 0 AND 3, AND THE GAP IS THE MECHANISM. Bash produces 1 +# for an ordinary command failure, 2 for a usage error, 126/127 for a command +# it could not run, 128+n for a signal, and — this is the one that matters — +# 1 for an unbound-variable or other EXPANSION failure, which happens before +# the command runs and is therefore invisible to a `||` guard and to an ERR +# trap alike. It never produces 3. So "not an answer code" is decided by a +# property of the shell rather than by an enumeration of the ways a step can +# go wrong, and a step added later without a guard, or with a guard that +# cannot fire, lands on NOT MEASURED by construction. # -# The `set +e` around the call site is what makes the second mechanism work, -# and it is not decoration. A command on the left of `||` — or in an `if` -# condition — runs with errexit suppressed, and that suppression propagates -# into a subshell and is NOT undone by a `set -e` inside it (verified on bash -# 5.3: an unguarded `false` there falls through to `exit 0` and reports -# ACTIVE). Calling with errexit disarmed at the site is the only form that -# lets the subshell re-arm it. The ERR trap is then required on top, because a -# bare `set -e` abort exits with the FAILING COMMAND's status — `false` gives -# 1, which is precisely the value that means "measured, and the answer is -# mtime". Belt and braces here buys a wrong answer; belt, braces and a trap -# buys "not measured". +# That is the whole reason INACTIVE is not 1. It was, and three review rounds +# on this function each found a narrower way for a shell-generated 1 to be read +# as a measurement — an unguarded command, then a typo'd variable name on a +# line that HAS its guard. Each was closed by narrowing the failure surface, +# which is a game with no last move. Moving the answer off the codes bash can +# generate ends it instead: there is no longer a mutation that turns an error +# into an answer, only mutations that turn an error into a different error. # -# WHY 2 SKIPS RATHER THAN FAILS. The scenario it gates is the only thing in +# The guards below stay, and so does the trap, but their job is now reporting +# rather than correctness: they make a failed step land on 2 with its logs +# printed instead of on some incidental status, which is nicer to debug and +# lands in the same place either way. +# +# One piece of that reporting layer is load-bearing and not obvious. A command +# on the left of `||` — or in an `if` condition — runs with errexit suppressed, +# and that suppression propagates into a subshell and is NOT undone by a +# `set -e` inside it (measured on bash 5.3: an unguarded `false` there falls +# through to `exit 0`). Calling with errexit disarmed at the site is the only +# form that lets the subshell re-arm it; hence the `set +e` bracket. The ERR +# trap is then required on top, because a bare `set -e` abort exits with the +# FAILING COMMAND's status, and `false` gives 1. +# +# WHY NOT-MEASURED SKIPS RATHER THAN FAILS. The scenario it gates is the only thing in # this suite that depends on freshness mode; everything else still runs and # still catches real regressions. Failing instead would turn a statement about # one machine's toolchain into a red gate reading "the hardlink scheme is # broken" across the three repos consuming this action — the same category # error the three-state split exists to prevent, one level up. What would -# change the answer is 2 becoming the everyday CI outcome; it is not (gitdan-ci -# reports 1, by measurement). +# change the answer is not-measured becoming the everyday CI outcome; it is not +# (gitdan-ci reports a measured INACTIVE, by measurement). CHECKSUM_MODE="off" CHECKSUM_REASON="no nightly on PATH accepting -Z checksum-freshness" CARGO_BIN=(cargo) checksum_freshness_probe() { local d="$scratch/freshness-probe" t="$scratch/freshness-probe-target" - mkcrate "$d" || return 2 + mkcrate "$d" || return 2 # 2 is simply "not 0 and not 3"; see the header ( set -e trap 'exit 2' ERR @@ -167,7 +181,9 @@ checksum_freshness_probe() { printf '%s\n' "$CONTENT_B" > src/lib.rs || exit 2 touch -d '@1000000000' src/lib.rs || exit 2 CARGO_TARGET_DIR="$t" cargo +nightly build -v > "$scratch/freshness-probe.log" 2>&1 || exit 2 - if grep -qE '^\s+Fresh probe' "$scratch/freshness-probe.log"; then exit 1; fi + # 3, not 1: see the header. This is the only statement in the subshell that + # may report a measurement, and it is the only one that may exit 3. + if grep -qE '^\s+Fresh probe' "$scratch/freshness-probe.log"; then exit 3; fi exit 0 ) } @@ -186,18 +202,18 @@ if cargo +nightly -Z checksum-freshness locate-project > /dev/null 2>&1; then CHECKSUM_MODE="on" CHECKSUM_REASON="" ;; - 1) + 3) unset CARGO_UNSTABLE_CHECKSUM_FRESHNESS CHECKSUM_REASON="this nightly accepts -Z checksum-freshness but resolves freshness by mtime" ;; *) unset CARGO_UNSTABLE_CHECKSUM_FRESHNESS CHECKSUM_MODE="unmeasured" - CHECKSUM_REASON="a probe build failed, so this was NOT MEASURED — this toolchain may or may not resolve freshness by content" + CHECKSUM_REASON="the probe exited ${probe_rc}, which is not one of its answer codes, so this was NOT MEASURED — this toolchain may or may not resolve freshness by content" # Loud, because the cost is silently lost coverage on a machine that # might have had it. The suite continues: everything else it asserts is # independent of freshness mode. - echo "::warning::hardlink-clone-selftest: could not measure whether this toolchain resolves freshness by content — a probe build failed. This is a failure to measure, not a finding about Cargo." + echo "::warning::hardlink-clone-selftest: could not measure whether this toolchain resolves freshness by content — the probe exited ${probe_rc}. This is a failure to measure, not a finding about Cargo." tail -n 15 "$scratch/freshness-probe-warm.log" "$scratch/freshness-probe.log" 2>/dev/null | sed 's/^/ /' >&2 || true ;; esac -- 2.43.0