From 985ce18a4c2109641d50abf2739cc97e540e54f2 Mon Sep 17 00:00:00 2001 From: Anoop Narang Date: Mon, 28 Sep 2026 11:33:51 +0530 Subject: [PATCH] docs: move the open bug out of CLAUDE.md and into an issue MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The file carried a "Known open issue" section describing the disk reclaim race. That is the same kind of expiring fact as the pinned commit id this file already dropped: whoever fixes the race will not think to edit a conventions document, so the section rots into a description of a bug that no longer exists, and an agent reading it wastes time on a solved problem — or worse, trusts the workaround it implies. A bug belongs in the tracker, where it can be assigned, discussed and closed. Filed as hotdata-dev/liquid-cache#56, with the sequence, the `t4` LSN ordering that makes the delete win, the generation-key fix and its consequence for `DiskResidue::superseded`, and the test that would close it. Replaced with what does not expire: open an issue, and read the open ones first, because this particular gap has been re-discovered more than once. Kept the mention of `DiskResidue`, `reclaim_orphaned_disk` and `settle` in the upstream-PR section. That is not a bug report — it is the durable fact that they are fork-only, which is what makes patches touching them unupstreamable. Re-checked against upstream: zero occurrences of each. --- CLAUDE.md | 21 +++++++++------------ 1 file changed, 9 insertions(+), 12 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 767b24bf..50183c4d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -144,15 +144,12 @@ bundled with real upstream work later it is not. default-build total at all, and CI stays green because a missing test is not a failing one. -## Known open issue - -The disk reclaim path has an unclosed race. A store key is -`(entry id, identity)` and identities are reused — the file-id pool hands a -re-opened path its previous record. `reclaim_orphaned_disk` consults the index -before deleting, but a put that has landed while its index record is not yet -installed is invisible to that check, and t4 applies puts and tombstones by -LSN, so the later `remove` wins and deletes live bytes. - -Closing it needs a per-write generation in the store key, which also makes -`DiskResidue::superseded` unreachable and removes the in-place-overwrite case. -Not yet done. Do not re-report it as new. +## Reporting a problem + +Open an issue. Nothing in this file records a specific bug: a bug is by +definition temporary, and this file goes stale the moment someone fixes one +without remembering to edit it. + +Check the open issues before reporting something — known gaps in the cache's +accounting and reclamation are tracked there, and at least one has been +re-discovered more than once.