Four corrections from the review of #8, all in the files this PR already
touches:
- A local signal on the line that creates .publish-new-. The other four shapes
each got a note at their producing line, which is the whole premise of #7 —
someone renaming TMP_DST reads its own comment block and would never see the
contract note 45 lines up at OLD.
- '.publish-old- is milder' understated it. Milder is true; bounded is not. A
key whose branch is merged, deleted or renamed is never published again, so
its rotated generation stays until something outside this repo takes it —
which is the case gitdan#30 itself makes, two lines away.
- The drift check now says the prefix constants ci-cache-reclaim.sh DECLARES,
not the ones it enumerates. Those are different numbers: collect_entries()
globs .stage- and .evicting- only, because .reading- is read and never
swept. Only the declared reading makes the five-against-five count work, and
a countability check that needs a coin flip to count is not one.
- publish-snapshot.sh's own header had two stale names ten lines above the
stale pointer this PR fixes: step 1 staged at .stage-<tag> (that is
hardlink_clone_into's inner path; the staged snapshot is .publish-new-<tag>)
and step 2 named .publish-old-<tag> without the key. Pre-existing and
outside both ACs, but #6's thesis is that a plausible-looking wrong name is
the worst kind, and these are in the file the PR is about.
Comments and docs only. With comments and blank lines stripped, all three
scripts hash identically to origin/main.
The contract block asserted that neither side reclaims .publish-new- 'today'.
True when written and about to stop being true: gitdan#30 tracks adding both
.publish-* prefixes to the arbiter's enumeration, and a sibling track is
landing it this round. A comment that dates itself against a merge in flight
is worse than no comment.
Rewords all four sites (cache-lib.sh, publish-snapshot.sh, and README's table
row and prose) to reference gitdan#30 and keep the mechanism that made the
shape worth catching — .publish-new- is tagged per job per run exactly as
.stage- is — rather than the arbiter's momentary contents. The rule itself is
unchanged; it is the durable part, and it is what found this.
Adds the counting check while there: the five names here and the prefixes
ci-cache-reclaim.sh enumerates are meant to be the same length, so a mismatch
is the cheapest signal that one side gained a shape without telling the other.
daniel/gitdan's host-level arbiter (scripts/ci-cache-reclaim.sh) reclaims the
dot-prefixed trees this repo's scripts strand inside the cache volumes it
scans, and reads this repo's reader markers to decide whether one is still
live. That arrangement was documented only on the consuming side: a
contributor here could add or rename a dot-prefixed shape with no local signal
that anything outside the repo depended on the spelling, and the arbiter
enumerates by explicit prefix — deliberately, so it never sees a .reading-*
marker as a candidate — which makes an unannounced shape invisible to it
rather than conservatively handled.
Adds the producing side's half at the sites someone changing a name will
actually be looking at, pointing at gitdan's LEFTOVER NAMING CONTRACT block as
canonical rather than restating it:
- cache-lib.sh gains a header block naming every shape this repo creates under
a cache root, its producing function, and how each strands; plus the rule
that adding a shape obliges the same matching prefix over there as renaming
one does.
- Site notes at .stage-'s and .reading-'s producing lines, and at
.evicting-'s in prune-cache.sh.
- publish-snapshot.sh's .publish-old- / .publish-new- pair is documented as
the shapes that are NOT in the arbiter's list today, with .publish-new-
called out as the one that strands exactly as .stage- does and that neither
side reclaims.
- The staleness direction: CACHE_READ_STALE_SECONDS and STALE_LOCK_SECONDS are
mirrored there and the mirrors must be >= ours, because raising ours alone
makes the arbiter delete a tree under an in-flight clone (its minimum-age
guard does not back-stop that case). Lowering ours is safe in any order.
- README gains a short section a newcomer meets before adding a scratch
directory under a cache root, cross-linked from the cache-layout block.
Comments and docs only; no behaviour change.
Closes#7
publish-snapshot.sh's header described the silent-truncation failure mode as
the one "this script's own selftest (scenario 8)" reproduces. Wrong twice:
the scenario that reproduces a truncated clone is in
seed-target-dir-selftest.sh, and since #4 split the old scenario 8 into 8a and
8b it is 8b. publish-snapshot-selftest.sh does have a scenario 8 — the
abandoned-marker case — so the pointer landed on a real scenario with a
plausible number that tests something else.
Names the suite as well as the number, and says what the local scenario 8
actually is so the collision cannot re-form.
Closes#6
claude
