Q-W1 pt2: core/shell/app relocation + sub-namespaces; one concrete ui::Rect (LTRB fork retired); slot_map split from bank_book; BankIndex→BankModel; 59/59 green

src/shell/persist/usage_scan.h

@@ -0,0 +1,60 @@
+#include "core/namespaces.h"
+#pragma once
+// usage_scan — the EXTENSION-side shell of the pS-usage seam (see sample_usage.h for
+// the pure core, the fail-safe folds, and the full design note). At prune-scan time it
+// answers ONE question: which project-relative bank paths are held by a LIVE ReaSampler
+// 9000 instance — or must the prune ABORT because a usage record could not be read?
+//
+// Three reads, no writes (the prune scan's READ-ONLY contract holds):
+//   1. Enumerate every "rsusage_<guid>" key in the "reasampler" ext-state namespace
+//      (EnumProjExtState) and decode each record (sample_usage wire). A key that is
+//      present but cannot be read or decoded folds to abortPrune (fail-safe: an
+//      unreadable record may protect anything, so the prune halts and deletes nothing).
+//   2. Enumerate every ReaSampler 9000 FX instance in the project — all tracks
+//      (master included), normal + record/input chains, FX containers recursively, and
+//      take FX (same container recursion) — matching each FX's fx_ident AND
+//      original_name via the pure sample_usage::identityMatches (class-UID hex, module
+//      filename base, display name; see the matcher note there).
+//   3. Fold with the pure liveness rule (sample_usage::foldUsageRecords /
+//      usageHeldPaths): a record counts iff its publishing track still hosts >= 1
+//      instance; a record with no track context counts while any instance exists; and
+//      when records exist but ZERO instances were identified anywhere, EVERY record's
+//      paths are protected (the identity-failure net — a matcher failure must never
+//      degrade toward delete).
+//
+// The result feeds prune_reconcile::mergeReferenced in persist's scanPruneOrphans, so
+// `referenced` = bank references ∪ live-instance holds — a held capture can never be
+// an orphan, and BANK_PRUNE_FOLDER (the only deletion authority) can never delete it.
+// abortPrune propagates through PruneScan/PruneReport to the action, which halts.
+//
+// REAPER-facing: the .cpp includes reaper_plugin_functions.h WITHOUT
+// REAPERAPI_IMPLEMENT (main.cpp owns the API pointers — CLAUDE.md §contract). The
+// header stays REAPER-free (`proj` is the opaque ReaProject* the persist seam already
+// passes around as void*).
+
+#include <string>
+#include <vector>
+
+namespace reasampler {
+
+// The scan outcome. When abortPrune is true a present rsusage_* record could not be
+// read or decoded — the caller MUST halt the prune (delete nothing). offendingKeys
+// names the exact "rsusage_<guid>" keys that triggered the abort so the action can
+// print them for operator recovery (clear via ReaScript:
+//   reaper.SetProjExtState(0, "reasampler", "<key>", "")
+// for each offending key). heldPaths on abort is the protect-all set (every readable
+// record's paths) — meaningful only as a belt-and-braces fallback; the abort flag is
+// the authoritative signal. Otherwise heldPaths is every project-relative path held by
+// a live ReaSampler 9000 instance, de-duped, in record order — empty in the common
+// no-records case (the FX enumeration is skipped entirely).
+struct UsageScanResult {
+    bool abortPrune = false;
+    std::vector<std::string> offendingKeys;  // non-empty iff abortPrune
+    std::vector<std::string> heldPaths;
+};
+
+// Scan `proj` (nullptr = active project). READ-ONLY: no ext-state write, no project
+// mutation.
+UsageScanResult liveInstanceHeldPaths(void* proj);
+
+}  // namespace reasampler