B5: sample-remove verb — index-only drop, this-bank scope, confirm-on-last-reference

src/bank_book.h

@@ -85,6 +85,30 @@ enum class TransferResult {
     RejectedSameBank,
 };
 
+// Scope of a sample-remove (fork R-A, settled 2026-07-24). ThisBank is the default
+// and the ONLY behavior surfaced in the UI/action layer; AllBanks is a latent seam —
+// live and tested at the model level, promotable later behind this parameter without
+// a rewrite, but never wired to an affordance in B5.
+//  - ThisBank: drop the entry from the one named source bank only. A same-hash entry
+//              in another bank survives (no cross-bank cascade — dedup is per-bank).
+//  - AllBanks: drop the sample's entry from EVERY bank that holds the source id
+//              ("purge from the library"). Latent; unsurfaced.
+enum class RemoveScope {
+    ThisBank,
+    AllBanks,
+};
+
+// Outcome of BankBook::removeSample. Mirrors TransferResult's honesty: the op reports
+// what happened rather than silently mutating on a bad request.
+//  - Removed:              at least one index entry was dropped.
+//  - RejectedUnknownBank:  the source bank id named no bank (ThisBank scope only).
+//  - RejectedSampleAbsent: the sample id was in no bank in scope (nothing removed).
+enum class RemoveResult {
+    Removed,
+    RejectedUnknownBank,
+    RejectedSampleAbsent,
+};
+
 // An ordered registry of banks with the pool seeded as bank-zero, per-bank sample
 // indices, an active-bank pointer, and lossless JSON round-trip. The heart of the
 // multi-bank phase — mirror of bank_model / view_mode_model.
@@ -155,6 +179,37 @@ public:
                               const std::string& fromBankId,
                               const std::string& toBankId);
 
+    // -- Sample removal (index-only; the file is NEVER touched — orphaned until prune) --
+
+    // Drops a sample's index entry (the sample-level sibling of move/copy/evacuate).
+    // Index-only and non-destructive to the file: a last-reference remove leaves the
+    // file on disk, orphaned until Phase R prune — remove NEVER deletes bytes.
+    //
+    // Scope (fork R-A): ThisBank (default, the only surfaced verb) drops the entry from
+    // `fromBankId` alone; AllBanks (latent seam) drops the sample id from every bank
+    // that holds it. See RemoveResult for the outcome set.
+    //   * ThisBank:  RejectedUnknownBank if `fromBankId` names no bank; RejectedSampleAbsent
+    //                if that bank does not hold the id; Removed on a drop.
+    //   * AllBanks:  `fromBankId` is ignored (the id is purged book-wide);
+    //                RejectedSampleAbsent if NO bank held the id; Removed otherwise.
+    // No mutation occurs on any Rejected outcome (no-op guardrail for the undo layer).
+    RemoveResult removeSample(const std::string& sampleId,
+                              const std::string& fromBankId,
+                              RemoveScope scope = RemoveScope::ThisBank);
+
+    // Reference-count query backing the confirm-on-last-reference guardrail: does any
+    // bank OTHER than `exceptBankId` still hold an entry whose contentHash == `hash`?
+    //
+    // Identity is the CONTENT HASH, not the file path: hash is the canonical dedup key
+    // the whole model already reasons in (findByHash / collapse-by-hash), and two
+    // entries that share content share one file — so "some other bank still references
+    // this hash" is exactly "removing here does not orphan the file." An EMPTY hash is
+    // never matched (it does not participate in dedup, mirroring findByHash), so an
+    // empty-hash sample reads as referenced-nowhere-else — the safe, confirm-eliciting
+    // direction (we cannot prove another bank shares an unhashed file).
+    bool hashReferencedElsewhere(const std::string& hash,
+                                 const std::string& exceptBankId) const;
+
     // -- Query ---------------------------------------------------------------
 
     // The bank with `id`, or nullptr. Pointer invalidated by any mutating call.