docs(cache): producer half of the depended-upon names contract (#11)

Co-authored-by: Claude <claude@gitdan.com> Co-committed-by: Claude <claude@gitdan.com>
2026-08-24 23:03:29 +00:00
parent a9e9190e5a
commit df6f1b91fb
3 changed files with 51 additions and 0 deletions
@@ -14,6 +14,19 @@
 # until STALE_LOCK_SECONDS, after which it is treated as abandoned by a job
 # the runner killed before it reached its own release step. Honouring a lock
 # forever would let one crashed job pin a directory permanently.
+#
+# `.ci-lock-<id>` IS A CROSS-REPO CONTRACT NAME with daniel/gitdan's
+# `scripts/ci-cache-reclaim.sh`: that host-level arbiter reads this same
+# marker (its `leftover_is_locked()`) to decide whether a leftover it is about
+# to reclaim is still held open by a live job. `cache-lib.sh`'s
+# `write_cache_lock()` writes the identical shape independently of this
+# script. Rename or reshape this marker here without a matching change on
+# gitdan's side and the arbiter's lock check silently stops matching — a live
+# job's staging tree loses its liveness guard and becomes an ordinary reclaim
+# candidate while still in use. See the "Scratch names in a cache root" section
+# in README.md, and daniel/gitdan's `DEPENDED-UPON NAMES CONTRACT` block in
+# `scripts/ci-cache-reclaim.sh`, for the full arrangement — this repo's half
+# is: don't rename `.ci-lock-` without telling that script.
 set -euo pipefail

 MODE="${1:?usage: cache-lock.sh acquire|release <dir> <lock-id>}"