docs(cache): state the .publish-* gap as a ticket, not a present state

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.
This commit is contained in:
2026-08-24 12:56:18 -05:00
parent 0cf6cc5973
commit 0118c28f01
3 changed files with 28 additions and 15 deletions
+7 -6
View File
@@ -55,12 +55,13 @@ DST=$(snapshot_dir_for "$ROOT" "$OWN_KEY")
# `.publish-old-` and `.publish-new-` are dot-prefixed names under a cache
# root, so the cross-repo contract at the top of cache-lib.sh covers them:
# renaming either, or adding a third, requires a matching prefix in
# daniel/gitdan's ci-cache-reclaim.sh. Neither is in its list today, and
# `.publish-new-` is the shape that most needs to be — it is tagged per job per
# run, so a publisher killed between staging its snapshot and the swap below
# strands a full hardlink clone that no later run of this script will ever
# match. `.publish-old-` is milder: the sweep further down reclaims it on the
# next publish of the same key.
# daniel/gitdan's ci-cache-reclaim.sh. Both were outside its list when that
# contract was written, and `.publish-new-` is why it mattered: it is tagged
# per job per run, so a publisher killed between staging its snapshot and the
# swap below strands a full hardlink clone that no later run of this script
# will ever match. `.publish-old-` is milder the sweep further down reclaims
# it on the next publish of the same key. Bringing both under the arbiter's
# enumeration is tracked as daniel/gitdan#30.
OLD="${ROOT}/.publish-old-${OWN_KEY}-${TAG}"
SNAP_NAME=$(basename "$DST")
GRACE="${CACHE_READ_GRACE_SECONDS}"