tracking: one ledger, one authority — prune protection and replace-vs-add answered from the same records, fail-safe on unreadable state

src/shell/persist/CLAUDE.md

@@ -4,10 +4,11 @@
 
 The persist seam: project ext-state read/write (`session` / `ext_state_io`), the
 prune path's filesystem half (`prune_fs`), and the extension-side instance-usage
-scan (`usage_scan`) that feeds prune's referenced-set. Internal helpers shared only
-within the persist TU family live in `persist_internal.h`. The pure orphan
-computation is owned elsewhere (`core/reclaim`); the pure usage wire is owned
-elsewhere (`core/wire`) — this directory is the REAPER/filesystem-facing half only.
+scan (`usage_scan`). Internal helpers shared only within the persist TU family live
+in `persist_internal.h`. The pure orphan computation is owned elsewhere
+(`core/reclaim`), the pure usage wire elsewhere again (`core/wire`), and every
+tracking *decision* by `core/tracking`'s authority — this directory is the
+REAPER/filesystem-facing half only, and it gathers rather than decides.
 
 ## Invariants
 
@@ -18,34 +19,37 @@ elsewhere (`core/wire`) — this directory is the REAPER/filesystem-facing half
   (orphan count, reclaimed size, and — for a small set — the files); actual
   deletion is a confirmed second step. No periodic/background sweep.
 - **Referenced-set is the union across ALL banks, pool included**, further unioned
-  (pS-usage) with every live instance's held paths via `usage_scan` →
-  `prune_reconcile::mergeReferenced`. A file is an orphan iff no bank AND no live
-  instance references it.
+  with every live instance's held paths — supplied by `tracking::pruneProtection`,
+  never assembled here — via `prune_reconcile::mergeReferenced`. A file is an orphan
+  iff no bank AND no live instance references it.
 - **Safest platform deletion available.** Trash-preferred, unlink fallback — Windows
   routes through `SHFileOperationW` (`FOF_ALLOWUNDO`, verified against SDK
   10.0.26100); macOS/Linux fall back to unlink (no portable SWELL trash surface).
   `prune_fs` is the only module that calls this.
 - **Manual, explicit trigger only** — a bindable action + a `bank_panel` button,
   never a silent background sweep.
-- **Instance-usage fail-safe (pS-usage):** a capture held by any live ReaSampler
-  9000 instance can never be deleted by prune. If any `rsusage_*` record is
-  unreadable or ambiguous, prune **aborts entirely and deletes nothing** —
-  over-protection is the accepted residual, under-protection is a data-loss bug.
-  `usage_scan` decodes every `rsusage_*` key, enumerates every ReaSampler 9000 FX
-  instance (all tracks incl. master, normal + record/input chains, containers
-  recursively, take FX), and folds via the pure `sample_usage::foldUsageRecords` /
-  `usageHeldPaths` (a record with no live instance context protects all its paths —
-  identity-failure net, never degrades toward delete). This is read-only at
-  prune-scan time: `usage_scan` writes no ext-state.
-- **`PruneReport` carries `abortedUnreadableUsage` + `offendingUsageKeys`**; dry-run,
-  orphan-set, and reclaim each independently abort (delete nothing) when usage
-  state is unreadable. `BANK_PRUNE_FOLDER` (in `shell/actions`) halts on this flag
-  and prints the offending keys.
+- **Instance-usage fail-safe:** a capture held by any live ReaSampler 9000 instance
+  can never be deleted by prune. `usage_scan` decodes every `rsusage_*` key,
+  enumerates every ReaSampler 9000 FX instance (all tracks incl. master, normal +
+  record/input chains, containers recursively, take FX), and folds via the pure
+  `sample_usage::foldUsageRecords`. Read-only at prune-scan time: `usage_scan` writes
+  no ext-state.
+- **A malformed tracking ledger is Unreadable, never "empty".** `ext_state_io` keeps
+  the `LedgerStatus` alongside the ledger, and `saveToActiveProject` SKIPS the
+  `owned_files` write while it is `Unreadable` — replacing a corrupt blob would
+  destroy the only record of every file created before the corruption, silently
+  turning them into permanently unreclaimable foreign files. Captures made during
+  such a session are recorded in memory but not persisted; they degrade to foreign
+  (untouchable), which is the safe direction.
+- **`PruneReport` carries `blockedByTracking` + `ledgerUnreadable` /
+  `unreadableUsageKeys`**; dry-run, orphan-set, and reclaim each independently abort
+  (delete nothing) on a block. `BANK_PRUNE_FOLDER` (in `shell/actions`) halts on the
+  flag and prints whichever blockers fired.
 
 ## Modules
 
-- `shell/persist` (`session` / `ext_state_io` / `prune_fs`) — the persist seam, split by responsibility (Q-W5; the former `persist.cpp` god-TU and its `persist.h` compatibility umbrella are both retired — callers include `shell/persist/session.h` / `ext_state_io.h` directly). `session` owns the `ReaSamplerSession` lifecycle: the poll identity-transition detection (load / Save-As / forked sibling / recycled pointer) and the `projectconfig`-driven deferred undo/redo reload. `ext_state_io` owns project ext state (`SetProjExtState`/`GetProjExtState`, namespace `"reasampler"`) ↔ `BankBook` JSON, `ViewModeModel` JSON, `TailSetting` JSON, `OwnedManifest` JSON, the writing-version stamp, GUID minting, and bank-folder relocation. `prune_fs` hosts the prune dry-run / full-set orphan queries (supplying `referencedPaths()` + `owned().paths()` to the `prune_reconcile` pure core) and is **the single file-deletion authority over user files in the bank folder** (`deleteOrphanFile` via `SHFileOperationW`); nothing else in the system deletes bank-folder bytes. **pS-usage:** the prune scan unions instance usage via `usage_scan`; `PruneReport` carries `abortedUnreadableUsage` + `offendingUsageKeys`; dry-run / orphan-set / reclaim each independently abort (delete nothing) when usage state is unreadable.
-- `usage_scan` — extension-side prune-scan shell (pS-usage): at prune-scan time, enumerates every `rsusage_*` ext-state key, decodes each `sample_usage` wire record, enumerates every ReaSampler 9000 FX instance across all tracks + master / normal + record chains / containers (recursive) / take FX, and folds with `sample_usage::foldUsageRecords` / `usageHeldPaths` to produce the set of held paths — or `abortPrune` when any record is unreadable (fail-safe: an unreadable record may protect anything, so the prune halts). Feeds `prune_reconcile::mergeReferenced`. Read-only: writes no ext-state.
+- `shell/persist` (`session` / `ext_state_io` / `prune_fs`) — the persist seam, split by responsibility (Q-W5; the former `persist.cpp` god-TU and its `persist.h` compatibility umbrella are both retired — callers include `shell/persist/session.h` / `ext_state_io.h` directly). `session` owns the `ReaSamplerSession` lifecycle: the poll identity-transition detection (load / Save-As / forked sibling / recycled pointer) and the `projectconfig`-driven deferred undo/redo reload. `ext_state_io` owns project ext state (`SetProjExtState`/`GetProjExtState`, namespace `"reasampler"`) ↔ `BankBook` JSON, `ViewModeModel` JSON, `TailSetting` JSON, the tracking ledger JSON, the writing-version stamp, GUID minting, and bank-folder relocation. `session` additionally owns `recordCreated` — **the one writer of a birth record**, called at the same point the `Sample` is added, deriving lineage from that `Sample`'s own provenance. `prune_fs` hosts the prune dry-run / full-set orphan queries (gathering `referencedPaths()` plus `tracking::pruneProtection`'s two inputs for the `prune_reconcile` pure core) and is **the single file-deletion authority over user files in the bank folder** (`deleteOrphanFile` via `SHFileOperationW`); nothing else in the system deletes bank-folder bytes. Dry-run / orphan-set / reclaim each independently abort (delete nothing) when the authority reports a block.
+- `usage_scan` — extension-side prune-scan shell: enumerates every `rsusage_*` ext-state key, decodes each `sample_usage` wire record, enumerates every ReaSampler 9000 FX instance across all tracks + master / normal + record chains / containers (recursive) / take FX, and returns the pure `sample_usage::foldUsageRecords` result verbatim. One of the two inputs `tracking::pruneProtection` reads; it decides nothing itself. Read-only: writes no ext-state.
 - `persist_internal.h` — internal-only shared helpers for the persist TU family (`session` / `ext_state_io` / `prune_fs`); included only by those three TUs, never a public seam (mirror of the panel's `panel_state.h` / the editor's `editor_internal.h` precedent). Holds the former anonymous-namespace helpers more than one split TU needs (active-project + `.rpp` path lookup, project-dir derivation, growing `GetProjExtState` read, project-GUID minting, bank-folder relocation) — all definitions live in `ext_state_io.cpp`. REAPER-free header: the project handle crosses this seam as the same opaque `void*` the public `session` header already uses.
 
 ## Gotchas
@@ -55,6 +59,7 @@ elsewhere (`core/wire`) — this directory is the REAPER/filesystem-facing half
   file.
 - The pure usage wire (`sample_usage`: `UsageRecord`, `planUsagePublish`,
   `foldUsageRecords`/`usageHeldPaths`, `identityMatches`) is documented under
-  `core/wire`, not here.
+  `core/wire`, and the ledger + the two consumer answers under `core/tracking` —
+  neither belongs in this file.
 - `persist_internal.h` is an internal seam, not a public header — do not include it
   outside `session.cpp` / `ext_state_io.cpp` / `prune_fs.cpp`.