reasampler/src/shell/persist/CLAUDE.md

src/shell/persist — project ext-state persistence, prune filesystem I/O, usage scan

Scope

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). 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

• Prune is the single, exclusive file-deletion authority. No bank op, no capture op, no Design View op deletes a file; if any path other than prune deletes a bank file, reject it in review. The ONE carve-out — a shell removing a file it wrote itself moments earlier that no index ever referenced, wherever it sits — is stated in full at prune_fs.cpp's header and nowhere else.
• Dry-run first, always; no silent deletion. Prune reports before it deletes (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 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: 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 ledger this build cannot read is degraded, never "empty". ext_state_io keeps the LedgerStatus alongside the ledger, and saveToActiveProject SKIPS the owned_files write while tracking::ledgerDegraded holds — replacing a blob we could not read would destroy the only record of every file created before it, silently turning them into permanently unreclaimable foreign files. The status is written only by loadFromProject, so it is sticky until the project is reloaded: captures made during such a session are recorded in memory but not persisted, and degrade to foreign (untouchable), which is the safe direction.
• PruneReport carries blockedByTracking + ledgerUnreadable / ledgerFutureVersion / 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, with channel-correct recovery lines — a corrupt blob may be cleared, a newer build's must not be.

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, 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, beside them, tiedUsageFor, the resample's replace-vs-add input, deliberately co-located so "both answers come out of one TrackingState" is structural rather than a rule two files must remember. It is also 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

• The pure orphan computation (prune_reconcile, (owned ∩ present) − referenced) is documented under core/reclaim, not here — do not duplicate its spec in this file.
• The pure usage wire (sample_usage: UsageRecord, planUsagePublish, foldUsageRecords/usageHeldPaths, identityMatches) is documented under 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.