reasampler/docs/product/removal-and-prune.md

# Removal & prune — product notes

Framing, rationale, and open forks behind the two missing removal capabilities:
**sample-remove** (a sample-level index verb) and **prune** (the file-lifecycle
path CONTEXT.md keeps forward-referencing but never scoped). The tickable spec
lives in `PLAN.md` (Phase B point B5 for remove; **Phase R** for prune) and the
authoritative technical detail in `CONTEXT.md` (§Sample removal, §Prune — file
lifecycle). This doc holds the *why* — the workflow, the guardrails, the
index-vs-file boundary, and the forks that need a Daniel decision.

Status: framed by product-designer (2026-07-23). Sample-remove forks R-A/R-B and
prune forks R-C/R-D/R-E are surfaced below; **none are settled** — they need a
Daniel call before B5 / Phase R implementation.

---

## The one boundary that governs everything: index vs. file

ReaSampler already draws a hard line, stated repeatedly in CONTEXT.md: **a bank
operation touches the *index*, never the *file*.** Move, copy, evacuate, and
delete-bank are all index-only; files persist on disk "until prune." Every
removal capability below sits on exactly one side of that line, and keeping the
two verbs on opposite sides is the whole design.

- **Sample-remove drops an index entry.** It is the sample-level sibling of the
  bank verbs — move/copy/evacuate all keep the sample *somewhere*; remove is
  "drop this entry outright." It is **index-only, non-destructive to the file**,
  and — exactly like a plain delete-bank of a non-empty bank — it can *create*
  an orphan when it removes the last index reference to a file. It sits on the
  **same side of the line as every existing Phase B op.**

- **Prune deletes files off disk.** It is the *only* operation in the entire
  system that removes bytes. It reconciles the physical bank folder against the
  union of all bank indices and reclaims files referenced by no bank. It sits on
  the **file side of the line, alone.**

So the crisp statement, worth putting in the spec verbatim:

> **Remove creates orphans; prune reclaims them.** Sample-remove and delete-bank
> drop index entries and may leave a file referenced by nothing. Prune is the
> single path that turns such an orphan back into free disk space. No other
> operation deletes a file; prune deletes *only* files no index references.

This is why they are two different scope objects (Phase B vs. Phase R), even
though a naive reading ("both are 'delete' verbs") would lump them together.

---

## Sample-remove — the missing sample-level verb

### What the user is doing

The user has a sample they no longer want in a bank (or in the pool): a bad take,
a duplicate they don't want collapsed, a sample they filed into "Drums" by
mistake. Today they can *relocate* it (move/copy/evacuate) but they cannot drop
it. Remove is the "get this out of here" verb. Two intents hide inside it, and
the distinction is a fork (R-A below):

1. **Remove from *this* bank** — drop the entry from the bank the user is looking
   at, leaving any copies in other banks untouched. (If the sample was copied
   into "Drums" and also lives in the pool, remove-from-Drums leaves the pool copy
   alone.)
2. **Remove from *everywhere*** — drop every index entry for this sample across
   all banks in one act ("purge this sample from the library").

### Reconciling with existing invariants

- **Collapse-by-hash:** unaffected. Remove operates on a specific `Sample` entry
  in a specific `BankIndex` (the `remove` primitive `bank_model` already has, per
  CLAUDE.md — B5 exposes it, it does not add it). Because dedup is per-bank and
  cross-bank dedup is deliberately *not* enforced, "remove from this bank" and
  "the same hash still lives in another bank" coexist cleanly — that is the same
  coexistence copy already relies on.
- **Files-are-never-deleted-by-a-bank-op:** upheld. Remove is index-only, exactly
  like move/copy/evacuate/delete-bank. When remove drops the *last* reference to a
  file, it produces the **same orphaned-until-prune state** a non-empty
  delete-bank already produces — a designed state, not a new hazard class. The
  file is reclaimed later by prune, never by remove.
- **Pool privileges:** the pool cannot be *deleted, renamed, or evacuated*, but
  individual samples **can** be removed from the pool — otherwise the pool would
  become a roach-motel (samples check in, never leave except by moving to a named
  bank). Remove-from-pool is allowed; it is the pool's own "drop this sample"
  verb. (The pool-as-container privilege is untouched; only its *contents* are
  removable.)
- **Non-destructive:** remove mutates only index + ext-state, touches no file and
  no timeline item — the Phase B non-destructive guarantee extends to it verbatim.

### Guardrails

Remove is *less* dangerous than it first looks, because it never deletes a file —
the bytes survive on disk until an explicit prune. So the recovery story is: an
accidental remove loses the *index entry*, not the audio. But there are two
sharpnesses to guard:

- **Last-reference remove is the orphan-maker.** Removing a sample that exists in
  only one bank orphans its file (until prune). This is the same footgun as
  non-empty delete-bank, and it deserves the same treatment: **confirm when the
  remove drops the last index reference** ("Remove 'kick_03'? It is in no other
  bank — its file will remain on disk until pruned."). A remove of a sample that
  still lives in another bank is cheap and reversible-in-spirit (re-copy it back)
  and need not confirm. This makes the confirmation *earned* by actual risk rather
  than fired on every remove.
- **Undo.** REAPER's own undo stack does not know about ext-state index mutations.
  Whether remove is undoable — and how — is a genuine question shared with the
  rest of Phase B (see fork R-B); it is not remove-specific, but remove is where
  it bites first because remove is the first verb whose *only* effect is
  destruction of an index entry with no relocation.

### Where it lives

Remove is a `bank_book`/`BankIndex` verb (pure), a bindable `actions` entry, and a
`bank_panel` affordance on the current selection — the exact three-layer shape
every Phase B verb already takes. That is why it belongs **in Phase B as B5**, not
in a phase of its own: same modules, same pattern, same side of the index/file
line. It is the verb Phase B forgot, not a new pillar.

---

## Prune — the file-lifecycle path CONTEXT.md kept promising

### What the user is doing

The user has been working for a while: capturing, re-capturing (M10), deleting
banks, removing samples. Each of those left files on disk that no index references
any more — the "orphaned-until-prune" state the multi-bank spec designs in on
purpose. Over a long project the bank folder accumulates dead `.wav` files that
cost disk and clutter. **Prune is the reclaim pass**: "sweep the bank folder,
delete the files nothing references, tell me what you reclaimed."

This is the path CONTEXT.md forward-references in at least four places ("files
persist on disk until prune," "the capture/prune path reclaims it") but never
scopes. It is a real, promised capability with **no phase, no module, no point**
— a dangling reference the plan has to make good on.

### The load-bearing precedent: prune-on-reconcile already exists for modes

ReaSampler already shipped this exact shape once. Design View's `view_mode_model`
has **`ViewModeModel::reconcile(liveGuids)`** — a pure function fed the live set
(the tracks that still exist), returning the residual membership entries to drop
(CONTEXT.md §Design View: "prunes orphaned snapshots on every toggle/load;
tolerates unknown/stale GUIDs (prune on reconcile)"). Prune is the **file-pool
mirror of that pure pattern**:

> `reconcile(liveGuids)` reconciles *membership entries* against *live tracks*.
> Prune reconciles *files on disk* against *referenced files* (the union of every
> bank's index). Same shape — feed the pure core the live set, get back the
> residuals — one level down (files instead of GUIDs).

This is the "mirror the existing pure pattern" move the whole codebase is built
on (`bank_model`, `view_mode_model`, `bank_book` are all the same pure-registry
shape). The **pure part of prune** — "given the set of files on disk and the set
of files referenced by the book, compute the orphan set" — is a REAPER-free,
unit-testable function that belongs with the pure cores. Only the two ends are
shell work: *enumerating* the bank folder (filesystem I/O) and *deleting* the
orphans (filesystem I/O). Keep the decision (which files are orphans) pure and
tested; keep the I/O thin. This is the same pure/shell split as everything else.

### Reconciling with existing invariants

- **This is the one place the "files are never deleted" rule is *intentionally*
  broken — and it must be the *only* one.** Every other invariant says "no bank op
  deletes a file." Prune is explicitly not a bank op; it is the file-lifecycle op,
  and its entire job is deletion. The spec must state this asymmetry loudly so a
  reviewer never reads prune as violating the bank-op rule: **prune is the sole
  file-deletion authority; a bank op that deletes a file is still a bug.**
- **Referenced-set is the union across *all* banks, pool included.** A file is an
  orphan iff **no** bank in the book references it. Because copy means one file can
  be referenced by several banks, prune must union references across the whole
  book before deciding — deleting a file still referenced by "Drums" because it
  left the pool would be catastrophic. The referenced-set computation is the
  safety-critical core and the thing to test hardest (the null test of prune:
  *prune never deletes a file that any index references*).
- **Relative-paths-only / project-relative resolution:** prune enumerates and
  deletes within the project bank folder using the same M4 project-relative path
  resolution the index uses. It must resolve the *same* way the index does, or it
  could mis-identify orphans across a Save-As relocation. Prune runs against the
  *resolved current* bank folder, never a stale absolute path.
- **Collapse-by-hash:** irrelevant to prune's decision (prune works on files and
  references, not hashes) but worth noting: two index entries that collapsed onto
  one file mean one file, multiple references — prune's union handles this for
  free (the file is referenced, so it survives).
- **Determinism / bit-identical / null-test (capture):** untouched — prune sits
  below the capture path entirely, same as multi-bank.

### Guardrails — this is the genuinely destructive act

Prune deletes real bytes irreversibly (a deleted `.wav` is gone unless it went to
an OS trash — see fork R-C). It earns the strongest guardrails in the product:

- **Dry-run first, always.** Prune should *report before it deletes*: "12 files
  (34 MB) are referenced by no bank. Delete them?" A prune that silently sweeps is
  unacceptable for an irreversible file-delete. The dry-run (compute-and-report,
  the pure core with no deletion) is arguably the *primary* surface, and the
  actual deletion is the confirmed second step. This mirrors how every safe
  garbage-collector / disk-cleaner works (npm prune --dry-run, git gc reporting,
  Lightroom's "delete rejected photos" confirmation).
- **Confirm with a manifest.** The confirmation names the count and the reclaimed
  size and — for a small set — the files. The user approves a *specific* deletion,
  not an abstract "clean up."
- **Never touch a referenced file, and never touch a non-bank file.** Prune's
  scope is *files in the bank folder that the book once owned and no longer
  references*. A file that was never a bank file (a user dropped something into the
  folder by hand) is out of scope — prune should only reclaim files it can
  attribute to the bank system's own leavings, not act as a general folder cleaner.
  (This is a fork — R-D — because "how does prune know a file was ever ours"
  depends on whether we track a manifest of owned files.)
- **Recoverability via the OS trash, if we can get it (fork R-C).** If prune can
  route deletions to the platform recycle bin / trash instead of unlinking, an
  accidental prune is recoverable outside the app. Whether SWELL/the platform
  layer gives us a portable "move to trash" is a to-verify — but the *default*
  should be the safest deletion the platform affords.

### Where it lives — and why it is its own phase, not a Phase B point

Prune is **not** a Phase B point. Three reasons it earns its own lettered phase
(proposed **Phase R — Reclaim / file lifecycle**):

1. **It is a different pillar.** Phase B is the *bank container* pillar
   (index-only, non-destructive, above the file). Prune is the *file lifecycle*
   pillar (the one path that deletes files). CONTEXT.md already names it as a
   separate concern every time it says "the capture/**prune** path" — file
   lifecycle is spoken of as its own thing, owned by neither the capture nor the
   bank layer. Giving it its own phase matches how the spec already talks about it.
2. **It serves more than Phase B.** Orphans are produced by delete-bank *and*
   sample-remove (B5) *and*, arguably, by M10 re-capture superseding an old file,
   *and* by Design View's deleted-track residual files if any exist. Prune is the
   downstream reclaim for *all* file-orphaning paths, not a Phase-B-internal
   cleanup. A capability multiple pillars forward-reference should not be nested
   inside one of them.
3. **It carries a new risk class and new invariants.** Every phase so far has been
   non-destructive-to-files by construction. Prune is the first phase that deletes
   files, so it needs its own invariant section (the prune null test, the
   referenced-set union, the dry-run guarantee, trash-routing). Burying that under
   a Phase B checkbox would hide the one genuinely destructive capability in the
   product inside a phase whose headline invariant is "non-destructive." The
   dissonance alone argues for separation.

Lettered, per the established convention (`M` = capture pillar, `D` = Design View,
`B` = Banks): **`R` = Reclaim.** It reads correctly — Phase R is "the file
lifecycle pillar," not "a bank sub-step."

**Sequencing:** Phase R depends on B1/B2 (it needs the multi-bank book to compute
the referenced-set union across all banks) and on B5 conceptually (sample-remove
is a primary orphan-producer, so prune is most useful once remove exists), but it
does not depend on the B3/B4 *UI*. It can land any time after the book exists;
practically it should follow B5 so the two removal verbs ship as a coherent pair
(remove-then-prune is the workflow, mirroring evacuate-then-delete).

---

## Open forks — need a Daniel decision

### Sample-remove

**Fork R-A — remove scope: from-this-bank vs. from-everywhere vs. both.**
Does "remove sample" drop the entry from the bank in view (leaving copies in other
banks), purge every index entry across the whole book, or offer both as distinct
verbs?
- *from-this-bank* is the conservative, composable primitive (it is literally the
  `BankIndex::remove` the model already has); "from everywhere" is then "remove
  from each bank that holds it," which the user can also achieve by removing per
  bank. It matches the partition mental model (fork 3): a sample is in one bank, so
  remove-from-this-bank usually *is* remove-from-everywhere.
- *from-everywhere* as a distinct verb only earns its keep once copy has scattered
  a sample across several banks; then "purge this everywhere" is a real
  convenience.
- **Product-designer lean:** ship **from-this-bank** as B5's core verb (it is the
  model primitive, it composes, it matches the partition model), and treat
  *from-everywhere* as an optional convenience layered on top *only if* the copy
  workflow proves to scatter samples in practice. Design the seam (the action can
  take a "scope: this-bank | all-banks" parameter) so from-everywhere is a
  later flag, not a rewrite — but default the shipped affordance to this-bank.
  **Needs Daniel:** confirm this-bank-primary, or elevate from-everywhere to a
  first-class co-equal verb now.

**Fork R-B — undo model for index mutations (shared across Phase B, surfaced by
remove).** REAPER's undo stack does not cover `"reasampler"` ext-state index
mutations. So move/copy/evacuate/delete-bank/**remove** are, as specced, not on
REAPER's Ctrl-Z. Options:
- *(i)* Accept it: index mutations are not undoable via REAPER undo; the safety net
  is the confirmations + the fact that files survive (nothing is lost but the
  entry, which the user can re-create by re-capture/re-move). Cheapest.
- *(ii)* A ReaSampler-internal one-step undo for the last bank/index mutation (a
  single snapshot of the book restored on a "ReaSampler: undo last bank change"
  action). Bounded, cheap-ish, covers the "oops" case for all Phase B verbs at
  once.
- *(iii)* Hook into REAPER's undo system properly (`Undo_BeginBlock` /
  `Undo_EndBlock` with ext-state as undo state) — most integrated, most work, needs
  SDK verification that ext-state participates in undo blocks.
- **Product-designer lean:** this is bigger than remove and should be decided for
  **all of Phase B at once**, not per-verb. Lean *(ii)* — a single-snapshot
  internal undo of the last bank/index change — as the pragmatic middle: it turns
  every index verb's "oops" into a one-key recovery without wading into REAPER's
  undo internals. **Needs Daniel** (and it may retro-touch B1–B4, so surfacing it
  now rather than at B5 is deliberate — the seam is cheapest before B1 lands).

### Prune

**Fork R-C — deletion mechanism: unlink vs. OS trash.** Does prune `remove()` the
file (irreversible) or route to the platform recycle bin/trash (recoverable
outside the app)? Trash is the safer default; the question is whether SWELL / the
platform layer offers a portable move-to-trash, or whether we'd hand-roll it per
platform (Win `SHFileOperation`/`IFileOperation`, macOS `NSFileManager
trashItemAtURL`, Linux XDG trash spec). **Needs Daniel + a to-verify** on platform
support. Lean: **trash if portably available, unlink with a strong dry-run+confirm
guardrail if not.**

**Fork R-D — orphan attribution: manifest-tracked vs. index-diff vs.
folder-sweep.** How does prune know a file in the bank folder is a *reclaimable
orphan* (a bank file no index references) rather than *a file that was never
ours* (a user dropped it in by hand)?
- *(i) folder-sweep* — treat every file in the bank folder not referenced by the
  book as an orphan and reclaim it. Simplest; **dangerous** — it will delete a
  user's hand-placed file, violating "only reclaim our own leavings."
- *(ii) index-diff only* — never sweep the folder; instead, capture the file's
  identity at the moment its *last* index reference is dropped (remove/delete-bank)
  and prune only that recorded set. Safe (only ever touches files we know we
  orphaned) but requires recording orphans-at-drop-time.
- *(iii) owned-file manifest* — the book tracks the set of files it has ever
  created (capture writes to it); prune reclaims `(owned ∩ on-disk) − referenced`.
  Safest and most general (distinguishes "our orphan" from "user's file" and from
  "already-gone"); costs a manifest that rides the ext-state.
- **Product-designer lean:** *(iii) owned-file manifest* — it is the honest
  encoding of "prune reclaims only the bank system's own leavings," and it is a
  **design-the-seam-now** call: the manifest is cheap to maintain from capture
  onward but expensive to reconstruct retroactively (you cannot tell, later, which
  folder files were ever ours). If we defer prune but *don't* start tracking owned
  files now, we build a backfill cliff. **Strong recommendation: start the owned-
  file manifest as part of Phase B / capture even though prune ships in Phase R** —
  defer the feature, design the seam. **Needs Daniel** because it touches the
  persisted shape (a new tracked set) and ideally lands earlier than Phase R.

**Fork R-E — prune trigger: manual-only vs. offer-on-orphaning vs. periodic.**
When does prune run? Manual action only (user invokes "Prune bank folder"),
prompted opportunistically (after a non-empty delete-bank: "…evacuate, or delete
and prune now?"), or a background/periodic sweep? Lean: **manual-only as the core
(an explicit, dry-run-first action the user invokes deliberately)**; an *optional*
"…and prune now" affordance offered at the delete-bank confirmation as a
convenience, never a background sweep (silent irreversible file-deletion is exactly
what the guardrails forbid). **Needs Daniel** to confirm manual-primary and
whether the delete-time "prune now" convenience is wanted.

---

## Summary of the boundary (for the spec)

| | Sample-remove (B5) | Delete-bank (B1/B3, shipped-spec) | Prune (Phase R) |
|---|---|---|---|
| Object | one `Sample` entry | one bank + its member entries | files on disk |
| Side of the line | index | index | **file** |
| Deletes bytes? | no | no | **yes (only op that does)** |
| Produces orphans? | yes (last-ref) | yes (non-empty) | — (it *reclaims* them) |
| Reversible? | re-add/re-capture entry | re-create bank + re-add | **no** (unless trash, R-C) |
| Guardrail | confirm on last-ref | confirm on non-empty | dry-run + manifest confirm |