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
claude
0cf6cc5973
