reasampler/PLAN.md

# PLAN.md — ReaSampler milestone roadmap

Living milestone roadmap for ReaSampler. Derived from CONTEXT.md's 11-step build
order; CONTEXT.md remains the authoritative spec — this file is the tickable
checklist, not a re-statement of the spec. When a point lands, doc-keeper removes
it here and appends it to `COMPLETED.md`.

**Conventions**
- One checkbox `- [ ]` = one discrete, independently-landable point.
- Each milestone opens with a **Goal** (one line) and a **Verify** criterion
  (the acceptance gate; precision invariants pulled in where one applies).
- Verify-in-DAW points require a manual REAPER run; pure points are gated by CTest.
- "See CONTEXT.md §…" points at the authoritative detail — do not duplicate it here.

---

## Milestone 9 — slots (MPC-style)
**Goal:** "Capture to slot N" / "insert slot N", MIDI-bindable. CONTEXT.md
Build order 9.
**Verify (in DAW):** Slot capture and slot insert fire from MIDI bindings; slot
state persists via the index.

- [ ] Slot model + slot↔sample assignment.
- [ ] "Capture to slot N" / "insert slot N" actions, MIDI-bindable.

## Milestone 10 — provenance (re-capture from source)
**Goal:** Populate `Sample.provenance` (parent sample id + a capture-recipe
fingerprint) on resample-from-sample, and ship a **"re-capture from source"**
action that regenerates a sample from its recorded source. Reconciled with the
dual-canvas (Phase D2) model. CONTEXT.md §Data model, §capture; product framing +
the reconciliation forks in `docs/product/provenance.md`.
**Verify (in DAW):** A sample resampled from a bank sample carries its parent id +
recipe fingerprint; "re-capture from source" regenerates the file into the bank
(never auto-inserting into the timeline — load-bearing principle); re-capture with
an unchanged source + request is byte-identical to the original (bit-identical
repeats); non-destructive to source items/tracks.

> **PROPOSAL — pending Daniel's fork picks (2026-07-23).** Reshaped from the old
> "provenance + null-test verify" M10. **Cut (fixed by Daniel):** the null-test
> verification *action* and the true-pre-FX-dry *mechanism* the old note required —
> both dropped, see `docs/product/provenance.md` §What was cut. **Kept:** provenance
> + re-capture. The `Sample.provenance` struct and its JSON round-trip **already
> exist** (M1) — M10 populates and consumes the field, it does not add it. The points
> below reflect the **leaned path** (bank-only re-capture, thin fingerprint); the
> re-place variant is deferred behind forks P2–P4. Lock the points once Daniel picks.

- [ ] Populate `Sample.provenance` on resample-from-sample: `parentSampleId` (the
  bank sample the capture derived from) + `fxChainSnapshot` as a **capture-recipe
  fingerprint** (scope + source FX-chain identity at capture time — a drift/repro
  fingerprint, NOT a pre-FX-dry chain; see product note fork P1).
- [ ] "Re-capture from source" action: regenerate a provenanced sample by re-running
  its recorded capture request against the source's **current** state; update the
  bank file + Sample in place. **Bank-only — never inserts/re-places into the
  timeline** (load-bearing principle). Reports if the source drifted since capture.
- [ ] Verify: re-capture of an unchanged source is byte-identical to the original
  capture (bit-identical repeats); non-destructive (`FxBypassGuard` snapshot/restore
  as M7); relative-paths-only preserved.

**Dual-canvas reconciliation (forks for Daniel — `docs/product/provenance.md`):**
Under the leaned path (bank-only re-capture) provenance is **pure per-sample bank
metadata**, `bank_model` and `view_mode_model` **stay decoupled**, and M10 touches
no canvas code — compliance is satisfied by staying on the right side of the
capture-never-places line. Forks P3 (canvas/lane memory in provenance) and P4
(re-capture auto-tag interaction) only wake up if Daniel wants **P2 =
re-capture-and-replace-on-timeline**, which would make re-place a mode-aware
placement. Awaiting picks on P1 (fingerprint shape) and P2 (re-capture scope).

## Milestone 11 — polish
**Goal:** Batch capture (per selected item / per razor area),
resample-and-mute-source, conform-on-insert, native OS drag-out. CONTEXT.md
Build order 11, §Non-goals (drag-out deferred to last).
**Verify (in DAW):** Each polish action works without regressing the precision
invariants; drag-out places a valid file in the OS target.

- [ ] Batch capture: per selected item / per razor area.
- [ ] Resample-and-mute-source.
- [ ] Conform-on-insert (explicit).
- [ ] Native OS drag-out (deferred final; `InsertMedia` path must already work).

---

## Open questions to resolve during build
Carried from CONTEXT.md §Open questions — keep visible until each is closed by a
landed milestone.

- **`parseInt` narrowing hardening:** `src/bank_model.cpp` `parseInt` casts
  `int64_t → int` via `static_cast` without a range check; integers that fit
  in int64 but exceed `INT_MAX` are implementation-defined. Hardening candidate
  — add bounds check before the cast when integer-field validation is in scope.
- **Capture send/routing isolation (TODO):** The FX-scope capture neutralizes out-of-scope FX, gain, and pan — but NOT aux **sends**. So a downstream coloring send (e.g. a folder → reverb-track send) still routes and blends the reverb into an item/track capture, past the intended isolation point. A true item-level capture should be taken at the isolated graph point — the target scope's output before out-of-scope track FX/gain/pan **and** before out-of-scope aux/parallel sends. The hard part: distinguish **source routing that must be preserved** (e.g. a MIDI send T1→T2 where T2's synth is where a MIDI item's audio is actually produced — the "item level" for that MIDI item is T2's synth output) from **coloring sends that must be excluded** (folder→reverb). Repro: folder F1; T1 (MIDI) sends MIDI to T2 (synth); T1+T2 → F1; F1 sends to reverb T3; capturing the MIDI item on T1 currently includes the reverb, should be isolated to T2's synth output pre-F1 with the MIDI send preserved and the reverb send excluded. Likely approach: snapshot + mute out-of-scope tracks' aux sends during the render while preserving the main/source signal path — needs a rule for which sends are load-bearing.

---

# Phase D2 — Two-canvas (item-level mode projection; additive to D1)

> **Design View sub-phase.** Extends D1's track-level mode projection to **item
> level** via REAPER 7 fixed lanes: on a track present in both stances, each mode
> owns a fixed lane — the active mode's lane shows and plays, the inactive mode's is
> hidden and silenced — so a Design take and an Arrange take can share the same
> track and time position without colliding on the view. Nothing in D1 changes.
> Runtime floor rises to **REAPER 7** for this sub-phase (no version-gate branch;
> below v7 it is simply unavailable). Authoritative spec: **CONTEXT.md §Two-canvas
> sub-phase (Phase D2 / Phase E)** and the surrounding §Design View — additive phase
> spec. Product framing: `docs/product/design-view.md` §Two-canvas direction. When a
> point lands, doc-keeper moves it to `COMPLETED.md`.
>
> **D2-W1 (pure lane extension) and D2-W2 (shell: lane application + new-content detection) have landed** — see `COMPLETED.md`.

## D2-W3 — actions, persist wiring, panel UI
**Goal:** Any new lane/mode-management actions, the persist slice serializing the
lane-ownership index alongside the membership index, and any panel UI indicator.
See CONTEXT.md §Two-canvas sub-phase (Module architecture — persistence).
**Verify (in DAW):** The lane-ownership index survives Save / Save As / reopen
(rides in the `"reasampler"` `view_state` alongside the membership index);
lane/mode-management actions are registered and bindable.
**Depends on:** D2-W2.

- [ ] Any new lane/mode-management actions (`command_id`/`gaccel`/`hookcommand`);
  bindable in the Actions list.
- [ ] Persist slice: serialize/deserialize the lane-ownership index in the
  `"reasampler"` `view_state` section, alongside the membership index.
- [ ] Any panel UI indicator for lane/mode state.

---

# Phase B — Multi-bank (parallel to the M0–M11 capture roadmap and Phase D)

> **Separate phase namespace.** The M-numbers belong to the capture pillar
> (M0–M11); the D-letters belong to Design View. Multi-bank is a third orthogonal
> pillar — generalizing the single bank into a pool + named banks — so it takes its
> own **lettered** namespace (B1, B2, …). "B" reads for **Banks** and, like Phase D,
> keeps the roadmaps from colliding on numbering: Phase B is not "the twelfth
> capture step," it is a different pillar. Authoritative spec: **CONTEXT.md
> §Multi-bank**. Product framing: `docs/product/multi-bank.md`. When a point lands,
> doc-keeper moves it to `COMPLETED.md`.

## B1 — bank_book (pure)
**Goal:** REAPER-free bank registry wrapping N `BankIndex` instances: pool seeded +
privileged, create/rename/reorder/delete named banks, active-bank id, move/copy a
sample between banks, JSON round-trip + legacy-migration. The heart of the phase;
mirror of `bank_model` / `view_mode_model`; **`BankIndex` untouched (additive)**.
CONTEXT.md §Multi-bank (Module architecture — pure).
**Verify:** CTest green. Pool always present, un-deletable, un-renamable,
un-evacuable (rules rejected in-model). Active-bank defaults to pool. Move is
index-only (source loses entry, destination gains it) and observes destination
collapse-by-hash; copy leaves source intact. Delete drops member index entries.
Evacuate moves all members to the pool, leaving the bank empty. JSON round-trip
lossless across pool-as-bank-zero + named banks + per-bank indices + ordinals +
active id. Legacy `bank_index` JSON parses into `{ pool }` with zero named banks.

- [ ] Bank registry: ordered `{ bank id, display name, ordinal, BankIndex }`; pool
  seeded with fixed id + fixed name; create / rename / reorder / delete named banks
  (delete drops the bank's member index entries).
- [ ] Pool-privilege rules enforced in-model: reject delete-pool, reject
  rename-pool, reject evacuate-pool, never allow zero banks.
- [ ] Active-bank id (get/set; defaults to pool); resolve active bank's `BankIndex`.
- [ ] Move sample between banks (index-only; destination collapse-by-hash observed;
  source entry removed).
- [ ] Copy sample between banks (index-only; source entry retained; destination
  collapse-by-hash observed).
- [ ] Evacuate bank: move every member to the pool (index-only; destination
  collapse-by-hash observed), leaving the bank empty; pool cannot be evacuated.
- [ ] JSON round-trip: pool-as-bank-zero inside the blob + named banks + per-bank
  indices + ordinals + active id.
- [ ] Legacy migration: a bare `bank_index` JSON promotes to the pool's index with
  zero named banks (one-way, lossless; blob authoritative thereafter).
- [ ] Tests: pool privileges (delete/rename/evacuate rejected); move
  source-loses/dest-gains; copy source-retained; evacuate empties source into pool
  with dest collapse; cross-bank same-hash coexistence; dest collapse on move into a
  bank already holding the hash; JSON lossless; legacy migration.

## B2 — persist slice (banks ↔ project ext state)
**Goal:** Serialize the book under the `banks` key in `"reasampler"` alongside the
existing sections, with the pool folded in as bank-zero; migrate a legacy
`bank_index` key into the pool on first load and retire the legacy key; reload-on-open
and Save-As survival via the existing M4 machinery. CONTEXT.md §Multi-bank (persist).
**Verify (in DAW):** Banks + named banks + active bank + all per-bank samples survive
Save / Save As / close+reopen; **relative paths only**; bank travels with the `.rpp`;
a project saved before this phase (legacy `bank_index` only) loads as pool + zero
named banks with no sample loss, and after save carries `banks` with no `bank_index`
written.
**Depends on:** B1. (Persistence-key fork settled — fork 1 (a): pool inside the
`banks` blob, legacy key retired after one-way migration.)

- [ ] Serialize/deserialize the book under the `banks` key (pool-as-bank-zero inside
  the blob; distinct section from `view_state`; no `bank_index` key written going
  forward).
- [ ] Legacy-migration path on load: absent `banks` + present `bank_index` → promote
  into pool, mint the blob, treat blob as authoritative (legacy key retired).
- [ ] Session exposes the book; the active bank's `BankIndex` is the capture add
  target (route the M7 capture family through it — additive to M7, no M7 rewrite).
- [ ] Confirm survival across Save / Save As; confirm legacy-project load path.

## B3 — actions
**Goal:** Bindable action set for the multi-bank workflow. CONTEXT.md §Multi-bank
(actions). **Verify (in DAW):** Each action registered (bindable in Actions list);
bank-activate + move/copy + evacuate MIDI-bindable; create/rename/delete/evacuate
drive the B1 model via the B2-persisted session.
**Depends on:** B1, B2.

- [ ] Create bank / rename bank / delete bank (delete drops member index entries;
  confirm-on-non-empty offered at the UI layer in B4).
- [ ] Evacuate bank → pool (move all members back to the pool; refuses on the pool).
- [ ] Activate bank (direct-by-id + cycle).
- [ ] Move selected samples → bank / copy selected samples → bank (move is default).
- [ ] Pool full-height / banks full-height toggles.
- [ ] Register each (`command_id`/`gaccel`/`hookcommand`); bank-activate + move/copy
  + evacuate MIDI-bindable.

## B4 — bank_panel vertical split (UI)
**Goal:** The vertical-split bank window — pool on top, named-banks tab-page region
below, full-height toggles — extending the M5 docked grid. CONTEXT.md §Multi-bank
(bank_panel). **Verify (in DAW):** Pool grid renders on top; named-banks tab strip
below (empty when no named banks, one tab per named bank); active-bank **unmistakably**
indicated; both full-height toggles collapse the split correctly; sample move/copy
affordance works; non-empty delete confirms and offers evacuate; the Design View mode
switch in the header is unaffected.
**Depends on:** B1, B2, B3. (Tab rendering + move-affordance mechanics — fork 5 —
settled 2026-07-23: LICE-drawn tabs + both move affordances; see Phase B open questions
and product notes → *Fork 5 — settled*.)

- [ ] Vertical split: pool grid region (top) + named-banks tab-page region (bottom).
- [ ] Named-banks tab strip: **LICE-drawn** (matching the M5 grid + Design View
  segmented switch, not SWELL-native — fork 5a); one tab per named bank; empty state
  when none. **Verify LICE tab draw against the M5 reference before use.**
- [ ] Tab-strip overflow/scroll affordance — **in scope from the start** (fork 5a): a
  naive fixed-width LICE strip breaks down at ~8–12 tabs, so ship scroll/chevron
  overflow with the strip, do not defer it.
- [ ] Pool full-height / banks full-height toggle affordances wired to B3.
- [ ] Active-bank indicator — **visually unmistakable** (settled constraint);
  placement (per-region header / single readout / lit-tab) is the residual polish
  detail.
- [ ] Create / rename / delete / activate / evacuate affordances driving B3 actions.
- [ ] Delete confirms on a non-empty bank, naming the evacuate alternative.
- [ ] Sample move affordance — **both** (fork 5b): a "move to bank" menu on the current
  selection (bindable front-end for the B3 move action) **and** drag-between-regions.
  Copy is the deliberate secondary act, offered on the menu.
- [ ] Drag mis-drop mitigation (fork 5b): clear drop-target highlighting on the
  destination region/tab during a drag; a mis-drop is recoverable by design (move is
  index-only and reversible). **Verify the drag hit-test doesn't collide with the M5
  grid's multi-select drag.**

## Phase B open questions
All five forks settled by Daniel (2026-07-23): persistence key = fold pool into `banks`,
retire legacy key (1a); delete drops members + add evacuate verb (2); move is the
default gesture (3); active-bank/shown-tab distinct with an unmistakable indicator (4);
LICE-drawn tabs + overflow, and both move affordances with drop-highlighting (5).
Folded into CONTEXT.md §Multi-bank + the B1–B4 points above. Phase B is fully settled and
ready to scope into implementation waves. One polish detail remains:

- **Active-bank indicator placement** — per-region headers vs. single header readout
  vs. lit-tab. "Unmistakable" is settled; only placement is open. Polish detail.
  (touches B4)