reasampler/src/core/model/CLAUDE.md

src/core/model — the pure bank/sample index and its multi-bank container

Scope

Pure (REAPER-free, unit-tested outside the DAW) sample-index models: the single-bank index, the multi-bank registry that wraps it, its JSON codec, the gap-preserving per-bank slot carrier, and the capture-recipe fingerprint. No REAPER types, no filesystem I/O — see root CLAUDE.md for the pure-core/shell split this directory sits on.

Invariants

Pool privileges (multi-bank).

• The pool is privileged, not special-cased: structurally one BankIndex among many in bank_book; semantically it always exists, is un-deletable, and un-renamable (fixed id + fixed display name "Pool"). New projects and migrated single-bank projects start with the pool and zero named banks. Enforced in the pure rules layer, not just the UI.
• No action path may delete or rename the pool, leave a project with zero banks, or evacuate the pool (the pool is evacuation's destination, not a source).

Bank identity, movement, dedup.

• Bank id is the stable key (GUID-style, minted on create); display name and ordinal are mutable. Display names are unique — trimmed + case-insensitive (ASCII) — enforced by createBank/renameBank; the pool's reserved name "Pool" is protected by the same check.
• Movement moves the index entry, not the file: move/copy between banks is index-only (remove from A's BankIndex, add to B's); the underlying file stays in the shared project bank folder. Per-bank subfolders on disk are an explicit non-goal.
• Dedup-by-hash is per-bank. Moving a sample whose hash already exists in the destination bank collapses onto the existing entry there. Cross-bank dedup is not enforced — the same hash may exist in the pool and a named bank simultaneously.
• Move is the default (removes from source, adds to destination); copy is the deliberate secondary act (adds to destination, leaves source intact).
• Delete drops members (files are not deleted); evacuate returns all of a bank's members to the pool (index-only, same destination-collapse rule). Evacuate cannot be applied to the pool. A plain delete of a non-empty bank orphans those members out of every index until prune reclaims their files — the UI confirms on non-empty delete and offers evacuate as the alternative.

Sample removal.

• Remove is index-only: drops one Sample entry from one BankIndex; mutates only index + ext-state, no file written/moved/deleted, no timeline item touched.
• Remove can orphan a file — the same designed orphaned-until-prune state a non-empty delete-bank produces — when it drops the last index reference to a file. Reclaimed later by prune, never by remove.
• The pool's contents are removable; the pool container is not. Remove-from-pool is allowed.
• Remove scope is this-bank only (settled 2026-07-24): drops the entry from this bank, leaving copies in other banks untouched. scope: this-bank | all-banks is a latent seam; only this-bank is a surfaced verb.
• Removes are silent — no confirm dialog. Recoverability comes from batched REAPER undo (Undo_BeginBlock/Undo_EndBlock): one Ctrl-Z restores the index entry. This undo-batching is Phase-B-wide (create/rename/reorder/delete-bank, move, copy, evacuate, and remove all batch this way). hashReferencedElsewhere is a tested model API retained for Phase R prune; it has no shell caller in the remove path.

Precision implications.

• Relative-paths-only survives unchanged: every BankIndex in the book keeps the relative-path invariant at its add boundary; movement is index-only so files never relocate.
• Non-destructive: bank create/rename/delete/activate/evacuate and sample move/copy/remove mutate only index + ext-state; no file is written, moved, or deleted, and no timeline item is touched.

Modules

• bank_model — Sample metadata struct + BankIndex (add/remove/query/tier/dedup-by-hash + JSON round-trip). Test it hard — it is the heart.
• bank_book — multi-bank registry: an ordered set of banks each wrapping a BankIndex. Pool privileges (un-deletable/un-renamable/un-evacuable, never zero banks) enforced in-model. Owns create/rename/reorder/delete of named banks, active-bank id, and index-only move/copy/remove of a sample between banks. The JSON round-trip lives in the sibling bank_book_json TU (Q-W5 split; serialize/deserialize via a private static nameKey seam) — one model, one codec, same public surface.
• slot_map (core/model) — the gap-preserving display-position carrier for ONE bank (sample id → slot, ≥0), extracted from bank_book (Q-W1): append/remove/reorder (insert-before-and-shift)/reconcile against live membership, resetDense migration seed, JSON round-trip. Wrapped (not merged) by bank_book.
• resample_name — the display name a resample's new bank entry takes, so repeated bakes read as one iteration chain (Kick -> Kick r2 -> Kick r3) rather than as N unrelated captures. Presentation only: the machine-readable lineage is the ledger's parentSampleId, and nothing parses this name back into one. The rule is per-NAME, not per-bank — two add-distinct bakes of the same source both land as "<name> r2", so display names are not unique and a browser reading the chain must read the ledger.
• provenance — capture-recipe fingerprint: build/encode/compare a rsprov1 fingerprint of scope, range, tail, rate/channels, track GUIDs, and FX-chain identity. A thin reproducibility fingerprint — NOT a serialized chain to restore. It is the recipe facet of the tracking system whose authority lives in core/tracking; the lineage facet (which file derives from which) is the ledger's, not the Sample's.

Gotchas

• bank_book wraps BankIndex; it does not modify it (additive — no bank-id field on Sample). Do not add per-bank subfolders on disk or a global cross-bank dedup — both are rejected-in-review non-goals.
• bank_book_json is a sibling TU, not a separate module — its round-trip is part of bank_book's public surface, not a distinct thing to describe separately.