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.

---

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)

Phase D2 is functionally complete — D2-W1, D2-W2, D2-W3-A, D2-W3-B all landed; see COMPLETED.md.

Deferred: panel UI indicator for per-track lane/mode state (a per-track lane-split marker). The mode switch already shows the active mode; no natural cheap home for a per-track indicator was found in the bank panel. Explicitly deferred — not silently dropped. Can be picked up later if wanted.

---

Phase S — MIDI-playback instrument (native VST3 sampler; a second build artifact)

Landed on dev (merged 2026-07-27); DAW verification pending Daniel's smoke test. S1–S18 and the product-name/binary-rename work are all on dev. The cross-artifact ingest relay (S13 bullet) was explicitly DEGRADED and remains deferred — see below. Completed material archived in COMPLETED.md. Authoritative spec: CONTEXT.md §MIDI-playback instrument — additive phase spec (Phase S). Product framing: docs/product/midi-playback.md.

S13 — cross-artifact ingest relay (deferred)

SPIKE VERDICT (ps-w12, 2026-07-27): DEGRADED — relay deferred. The instrument's REAPER bridge (reaper_bridge) is deliberately READ-ONLY; a relay would need a new instrument WRITE seam into ext-state and an extension-side timer poller servicing a drop-ingest inbox key with a claim/clear nonce — the same cross-process handshake race the S17 spec rejected for alternative (A). Both the read-only-instrument boundary and the new poller are load-bearing design calls, so the relay is deferred to a future wave. The shipped ingest gesture stays drop-onto-docked-panel (S8). The degrade path (editor shows a "drop files onto the ReaSampler bank panel to add them" affordance) landed as part of Phase S. See COMPLETED.md §S13 for full context.

• Cross-artifact ingest relay: the editor hands the dropped path + this instance's identity to the extension as a bank-ingest request over an agreed seam. DEFERRED — relay mechanism proved load-bearing to redesign; drop-onto-panel (S8) is the shipped ingest path. Requires (a) a new instrument WRITE seam into ext-state and (b) an extension-side timer poller + claim/clear nonce. A future wave when the design is ready.

Phase S — product name (ReaSampler 9000)

The MIDI-playback instrument's product name is ReaSampler 9000 (Daniel, 2026-07-26, on DAW-testing the S1–S6 instrument). The extension remains ReaSampler; the instrument is ReaSampler 9000. Framing + propagation surfaces: docs/product/midi-playback.md §Product name.

• Compat verification (must-DAW-verify before shipping the rename): the working assumption is that REAPER rebinds a saved instance by its VST3 class UID, not by the module filename, so a filename rename with an unchanged UID keeps saved projects working (existing instances still resolve). This is not yet confirmed from source — a web check surfaced a JUCE/VST3-replace-VST2 case suggesting REAPER's binding is more nuanced than "UID only" (it can involve an FXID match), so treat UID-rebind as to-verify, not asserted fact. DAW-verify: save a project with a ReaSampler 9000 instance under the old filename, rename the module, reopen — confirm the instance rebinds and restores its state. If REAPER does key partly on filename, fall back to keeping the current filename (display-strings-only) and record that as the shipped choice.

Phase S — held and optional-forever (noted, not specified)

• Tier 2 — "expressive" (HELD). Velocity layers, round-robin (anti-machine-gun), full ADSR, per-sample tuning/gain trim, sustain loops. The next depth increment once Tier 0–1 proves the instrument belongs — its points are not drawn up here.
• Tier 3 — "instrument polish" (optional-forever). Filters, filter/pitch envelopes, LFOs, per-voice pan, choke groups, a modest FX slot. A direction to leave room for, never a commitment. Note: S16 lands the pitch envelope + the Varispeed/ Preserve pitch-engine mode early (Daniel's directive) — the Tier-3 "filter/pitch envelopes" line now means the filter envelope + LFOs remainder.
• Sinc Varispeed-quality upgrade (HELD — WDL_Resampler). WDL_Resampler's sinc mode beats the core's 2-point linear interp for Varispeed base-repitch quality (see the S16 WDL finding). An optional per-voice quality toggle (linear default / sinc), RT-suitable but heavier. Held as a Tier-2/3 quality option — not needed for S15/S16, not scheduled. (A resampler couples duration, so it is a Varispeed-quality option only, not a Preserve engine.)
• WDL_SimplePitchShifter swap (HELD — fork S16-F2 route a). WDL_SimplePitchShifter as a drop-in swap for the pitch_shift pure module if the hand-rolled OLA onset latency or warble proves musically unacceptable. Same PitchEngine::Preserve contract behind the seam. WDL excluded from the shipped build by include-chain (windows.h); held as the quality/latency alternative.
• Trigger choke-on-note-off (HELD — fork S15-F1). A future option for Trigger mode to cut (choke) on note-off or on a same-group re-trigger (hi-hat open/closed). Deliberately out of S15 scope (Trigger ignores note-off entirely there); a Tier-3 choke-group direction.

Phase S — editor view-model redesign (three views: Sample / Browse / Zone)

Additive Phase S sub-phase (S-VIEW; Daniel, 2026-07-27, r9). Re-partitions the ReaSampler 9000 editor from a two-view toggle into a three-view model where the loaded sample is the home — Sample (default face), Browse (modal picker over Sample), Zone (dedicated keymap surface). Adds three performance parameters (key-tracking, preview velocity, and the r10 velocity→amp transfer curve) and three visual components (envelope overlay, real piano-key pattern, and the r10 velocity-curve editor), and frames two engineering prerequisites (drop-to-FX bug, default window size). An editor redesign — the S3 voice engine, keymap resolution, and read-only-over-bank contract are unchanged; component state extends additively for key-tracking; VST3 class UID unchanged. Authoritative spec: CONTEXT.md §Phase S — editor view-model redesign (S-VIEW). Product framing: docs/product/midi-playback.md §Addendum r9. When a point lands, doc-keeper moves it to COMPLETED.md.

Depends on Phase S being on dev (this redesigns Phase S editor shells — reasampler_editor.cpp + the pure src/vst/ geometry modules). Phase L L3 is FINISHED and merged (2026-07-27, commit c53683e — reasampler_editor.cpp + reasampler_embed.cpp restyled through the L1 kit). S-VIEW builds the new three-view layout directly on the current L3 look-and-feel as its baseline — one implementation pass, styled correctly from the start. There is no two-pass "land S-VIEW then restyle through L3" — L3 already happened; every new S-VIEW surface (Sample face, Browse modal, Zone surface, envelope overlay + node handles, piano-key strip, preview cluster) is drawn through the L1 kit at build time, inheriting the L3 palette and component-draw grammar. Restyle-after is not a concern.

Goal: A three-view editor that makes "pick a capture, tune it, play it" fast, easy, and fun — Sample is home, Browse is an easy-to-summon modal picker, Zone is the deliberate keymap surface. Verify (in DAW): open on a 1080p screen → full Sample face (hero waveform + envelope overlay + fenced root + preview-trigger + control strip) with no scroll; Browse opens as a modal over Sample, select+confirm loads a new capture; Zone opens on its own button, key-tracking + the piano-key pattern work; drop-a-capture-onto-FX instantiates a playing instance.

Phase S editor Wave B — Sample-face recomposition (r11; Daniel, 2026-07-27)

Daniel's post-landing DAW pass on the S-VIEW editor: all linear sliders → small radial knobs grouped into a fenced knob deck (envelope controls grouped as a unit); the mode toggles compact, not full-width; the inline velocity-curve box → a miniature curve preview button + full-size popup editor (right-click deletes a node in the popup); the hero waveform full-width. A pure view recomposition — zero engine/state/persistence change, VST3 class UID unchanged. Authoritative layout spec: CONTEXT.md §S-VIEW → "The Sample-face recomposition (r11)" (band order, group taxonomy, cell metrics, popup geometry, inventory contract — nothing silently dropped). Product framing: docs/product/midi-playback.md §Addendum r11. GATED on the knob-primitive track (separate, in flight) — S-VIEW-11/12 consume the primitive, they do not build it. All drawing through the L1 kit; all layout/hit-test in pure geometry modules.

• S-VIEW-11 — the knob deck. Pure knob_deck (group boxes + caption rows + compact-toggle rects + knob-cell rects + deterministic group wrap + hit-test; mirror of action_bar/param_slider; unit-tested) + shell: the Sample control strip becomes three fenced groups — AMP ENVELOPE (Gate|Trigger caption toggle; Attack·Hold·Decay·Sustain· Release or Fade In·Length %·Fade Out knobs, 5-cell width reserved so mode flips never reflow), PITCH (Varisp|Preserve caption toggle; Key Track knob), PITCH ENV (Off|On caption toggle; P.Attack·P.Decay·P.Depth knobs, Disabled-not-hidden when Off). Slider rows
  • full-width toggles retire from the Sample face; the hero becomes the elastic band (bottom-anchored fixed deck). Preview-velocity slider becomes a cluster knob cell (same persisted seam).
• S-VIEW-12 — curve popup + full-width hero. Pure curve_popup (sheet/close/box geometry + outside-sheet dismissal test; mirror of overflow_menu; unit-tested) + shell: the inline velocity-curve box leaves the hero band (hero runs full width, S11 markers + envelope overlay unchanged); a 28×28 miniature curve preview button lands immediately right of the preview-velocity knob (live miniature trace; Active while its popup is open); click opens the centered popup hosting the full-size curve editor — all landed interactions preserved (drag, click-add, Alt-click delete, drag-off delete) plus NEW right-click node delete (endpoint-guarded, commits like Alt-click). Dismiss: Close ×, outside-click (no drag in flight), Esc.
• S-VIEW-13 — Zone-panel parity (gated on fork R11-F2). The Zone param panel adopts the same knob deck + curve-preview-button/popup; retires param_slider's slider rows outright (one control grammar on both surfaces of the one storage site).

Open forks (Daniel's to call before Wave B builds) — recorded in the CONTEXT.md §S-VIEW fork ledger: R11-F1 hero height vs. default window (lean: elastic hero, keep 840×620); R11-F2 Zone-panel parity (lean: yes — one grammar).

Phase S editor redesign — forks (Daniel's to call)

(r9/r10 forks all settled: S-VIEW-F1 and S-VIEW-F2 SETTLED 2026-07-27 — folded into S-VIEW-4 / S-VIEW-3. F1: preview velocity persists via envelope-v6 ComponentState. F2: envelope nodes are draggable via the pure envelope_edit module. R10-F1 SETTLED 2026-07-27 — Option A flat y=1, folded into S-VIEW-9. S-VIEW-F3 SETTLED — full-window overlay, implemented as Browse renders as a full-window modal over Sample (landed in S-VIEW-1/S-VIEW-5). r11 opens two new forks — R11-F1 (hero height vs. default window) and R11-F2 (Zone-panel parity) — see the Wave B block above.)

---

Phase Q — Quality (structural reorganization; zero-runtime-cost)

New pillar, own lettered namespace, and — uniquely — the LAST structural pillar. Phase Q is a pure structural refactor: it reorganizes src/ into a healthier shape (more encapsulation, granular namespaces, core//shell//app/ subdirectories) against a stated quality bar — "mtytel Vital is my code reference for quality" — to bring the codebase "into the realm of something I can stand to look at." It ships no feature and changes no behavior: the test suite passing unchanged is the proof of correctness. Namespaced Q (Quality) — M/D/B/R/V/S/L are all taken; Q names the end (the quality bar), the reorg being the means. Authoritative spec: CONTEXT.md §Phase Q — structural reorganization (reorg spec). Product framing, the Vital-grounded target shape, the grep-verified SOLID audit that is the evidence base, and the settled/recommended fork record (Q-1..Q-6): docs/product/code-organization.md. When a point lands, doc-keeper moves it to COMPLETED.md.

THE GATE (load-bearing — state first; reconciled to reality 2026-07-27). Phase Q is gated on the tree being otherwise quiescent. Daniel's plain readiness target: "when Phase S and L3 are finished." As of 2026-07-27 both gate conditions are satisfied: Phase S merged to dev (2026-07-27); Phase L L3 (the VST restyle) merged to dev (2026-07-27, commit c53683e) — Phase L is complete (L1/L2/L3/L4/L5/L6/L7 all landed, see COMPLETED.md). D2 is functionally complete (D2-W1..W3-B landed; the lone open item, a per-track lane-split panel indicator, is explicitly deferred, not a blocking residual). M9 (slots) is abandoned (Daniel, 2026-07-27) — will not be built. D2 is named in the gate only so that reactivating its deferred panel indicator re-arms the quiescence condition; neither D2 nor M9 blocks the gate today. Why the gate: Phase Q touches nearly every file in src/ (relocate into subdirectories, re-namespace every header, split the four largest TUs, plus the §2b renames). Every large in-flight branch (Phase S on its worktree, and L3 once it lands) is diffed against the current flat layout; landing a rename-and-relocate-everything reorg mid-flight forces every open branch through the worst conflict class (every hunk moved, every qualified reference changed) — a combinatorial re-resolution, not a linear one. Phase Q is last precisely because it reshapes the ground every other pillar stands on. Landing it early taxes every subsequent phase; landing it last taxes nothing. The gate is now satisfied — Phase Q may begin, entering at the Q-W0 audit wave (the structural waves Q-W1+ do not begin until Q-W0's triage closes and Daniel signs off — see the Q-W0 sub-gate above).

M9 disposition — resolved (Daniel, 2026-07-27): abandoned. M9 is out; it will not be reactivated. The gate remains satisfied; no re-arm condition applies.

PRE-RESTRUCTURE AUDIT WAVE (Q-W0 — added 2026-07-27, Daniel's ask; runs FIRST). Before any structural point (Q-W1+) begins, Phase Q now opens with a functional + DSP quality audit (Q-W0) — a thorough static analysis of the code from a functional-correctness and algorithm-quality point of view, complementary to (not a repeat of) the grep-verified SOLID/naming audit that already grounds Q-W1..Q-W6. Q-W0 hunts DSP smells (close eye on the pitch engine), reinvented wheels, duplicate code, poor-quality algorithms, leaky pure/shell boundaries, and domain-modeling smells around env-coupled constants; it produces a written, triaged findings report. The gate to begin Q-W1 is that Q-W0's triage is complete and Daniel has signed off on each finding's disposition (fix-now vs. document-and-defer). Q-W0's findings may add or reshape downstream Q-W1..Q-W6 points; fixes that Q-W0 classifies fix-now are remediated in Q-W0 (or folded into the wave that already touches the file), not deferred silently into the structural waves.

Settled (Q-1, this-doc): the phase is Q (Quality); point-id family Q1..Qn, wave prefixes Q-W0 (the pre-restructure audit) then Q-W1..Q-W6 (the structural reorg). Settled (Q-10/Q-11, Daniel 2026-07-27): Q-10 audit-report home = a committed doc (docs/product/code-quality-audit.md, not a tracked issue list); Q-11 pitch-remediation depth = defer to findings (default document-and-defer; weigh a bounded OLA fix before a technique replacement; a technique replacement is a Daniel decision at triage time, not an automatic Q-W0 action). Recommended, Daniel's to call (Q-2..Q-9, see docs/product/code-organization.md §6): Q-2 JSON extraction in scope + first (rec: yes); Q-3 directory shape core//shell//app/ top-split with subsystem dirs beneath (rec: this over pure-Vital subsystem-first — it makes the pure/shell invariant structural); Q-4 sub-namespace to match sub-directory (rec: both); Q-5 split god-modules to the audit's named seams, no finer (rec: yes); Q-6 OCP registration-table as the final wave (rec: in, last); Q-7 naming rides the relocation waves, no dedicated naming wave (rec: yes — forced once Q-3/Q-4 settle); Q-8 class/module renames — fix the two that actively mislead (BankIndex→ BankModel; the JSON Parser→json::Reader/Writer), leave the merely-quirky (rec); Q-9 align the capture_realtime/realtime_record shell↔core word order during W3 (rec: yes).

HARD CONSTRAINT — performance (see CONTEXT.md §Phase Q, docs/product/code-organization.md §3). The reorg must cost zero runtime. On the three hot paths — peaks envelope compute, audition/preview, the realtime-capture tick — no added virtual dispatch, no header→TU indirection, no changed call/inline or branch shape. computeEnvelope stays a free function on const std::vector<float>&; audition split stays a direct call-through; the realtime idle tick stays a single pointer test; FxBypassGuard stays stack RAII. This is an acceptance criterion on every point: a split that would add a hot-path indirection is out of scope — rework it or drop it.

NAMING dimension (added 2026-07-27; grep-verified audit in docs/product/code-organization.md §2b). Beyond giving symbols a directory + namespace home (Q-3/Q-4), Phase Q also gives poorly/inconsistently-named symbols a consistent name, against the same Vital bar. The audit found: four class Parser copies collapsing to one json::Parser (Q-W1); shared pure-UI rect types (FooterRect/ButtonRect) that the codebase already hand-checks for collision (footer_bar.h's "NAME NOTE") — resolved by the Q-4 sub-namespaces for free; the bank_model/BankIndex file↔class word-mismatch (Q-8); and the capture_realtime/ realtime_record shell↔core word-order inversion (Q-9). Renames ride the wave that already relocates/splits the file — no dedicated naming wave (Q-7); the geometry-mirror compute*/hitTest* verb vocabulary and the _tests suffix are already consistent and are preserved verbatim. Naming changes are zero-behavior-change like the rest of Phase Q, and the FOREVER-STABLE contract strings (command ids, action names, ext-state namespace/keys, VST3 UID) are not C++ symbols and are never renamed.

Every point is independently landable and CTest-green at EVERY step. The CMake per-module static-lib + per-module test-executable seams already draw the module boundaries; a file move + namespace change is mechanically verifiable — ctest --test-dir build is green or it isn't. Green-CTest-at-every-point is an acceptance criterion. Big-bang is rejected; the reorg is risk-ordered waves (W1 safe opener → W2–W5 god-module splits → W6 OCP finish).

Q-W0 — pre-restructure functional + DSP quality audit (runs FIRST; gates Q-W1)

Goal: Before a single structural point moves, perform a thorough static/functional audit of the codebase and produce a written, triaged findings report. This is the functional-correctness and algorithm-quality complement to the grep-verified SOLID/naming audit that already grounds Q-W1..Q-W6 (§2/§2b of docs/product/code-organization.md) — it goes deeper on does the code do the right thing well, not where does the responsibility live. It hunts, across the whole src/ tree: duplicate code, reinvented wheels, poor-quality algorithms (close eye on the pitch engine), numerical-robustness and artifact hazards in the DSP paths, leaky pure/shell boundaries, and domain-modeling smells around env-coupled constants (values stored in a frame/rate/DPI/tick-coupled domain that should be stored rate-free and resolved at use). Every finding is classified for disposition: eliminate-before-restructure (fix-now) vs. document-and-defer (with rationale). Nothing structural (Q-W1+) begins until this wave closes and Daniel signs off on the disposition of every finding. CONTEXT.md §Phase Q (Q-W0 audit scope + triage). See docs/product/code-organization.md §2c. Verify: A findings report exists and is complete over the named audit surfaces (DSP/audio incl. pitch; architecture smells; env-coupled-constant domain-modeling smells). Every finding is triaged (fix-now vs. documented-and-deferred, each with a one-line rationale). Fix-now findings are either remediated in this wave or explicitly assigned to the downstream wave that already touches the file (recorded per finding); no fix-now finding is left implicit. Any behavior-changing remediation lands with its module's CTest executable green and (where a DSP path changes audibly) a stated before/after listening or null check. The gate to Q-W1 is: triage complete + Daniel signed off. Depends on: the GATE (tree quiescent). Precedes every other Q wave — Q-W1 depends on Q-W0.

• DSP / audio audit — close eye on pitch. Assess algorithm quality (correctness, artifacts, numerical robustness, interpolation quality, reinvented-wheel vs. established DSP technique) across: src/vst/pitch_shift (hand-rolled OLA pitch-preserve — window/overlap choice, phase handling, transient/formant behavior, buffer edges), sampler_core (repitch ratio math, interpolation order/quality, loop-point crossfade, voice-stealing correctness/click behavior), peaks (envelope min/max binning), wav_trim (decay-scan threshold + truncate plan), and the capture/tail paths. Pitch-remediation depth (Q-11 SETTLED, Daniel 2026-07-27): defer to findings — default document-and-defer; only if the audit surfaces artifacts that matter, weigh a bounded OLA fix (window/overlap/edge tuning) before a technique replacement. A technique replacement (phase-vocoder / WSOLA) reshapes pitch_shift, spills a downstream Q-wave point, and is a Daniel decision at triage time, not an automatic Q-W0 action — Q-W0 surfaces the recommendation, Daniel calls it.
• Architecture-smell audit. Duplicate code, reinvented wheels, poor abstractions, and any leaky pure/shell boundary (a core/ module reaching a REAPER/host type, or geometry/algorithm math living untestable in a shell). Cross-check against — but do not merely restate — the §2/§2b SOLID/naming findings; Q-W0's contribution is the functional smells those audits didn't target.
• Env-coupled-constant domain-modeling audit (explicit smell category). Flag ANY value stored in a frame/rate/DPI/tick-coupled domain that should be stored rate-free and resolved at the point of use — per the load-bearing invariant that wall-clock times are rate-free SECONDS resolved against the live project rate (sample_map), with NO hardcoded sample rates in src/. Treat this as domain-modeling (store rate-free, resolve at use), not "rescale by rate." There was a prior incident here — envelope times stored in the frame domain — so this is a first-class category, not a footnote. Sweep envelope times, loop points, fade lengths, tail lengths, and any UI geometry constant that silently assumes a DPI/rate.
• Triage + report. Write the findings report as a committed doc, docs/product/code-quality-audit.md (Q-10 SETTLED, Daniel 2026-07-27 — beside the SOLID/naming audit, not a tracked issue list); classify each finding fix-now vs. document-and-defer with a one-line rationale; for each fix-now, note whether it is remediated in Q-W0 or assigned to the downstream wave that already opens the file. Deferred findings carry a documented rationale so they are a decision, not an omission.
• Sign-off gate. Daniel reviews the triage and signs off on each disposition. Q-W1 does not begin until this is done; fold any new/reshaped downstream points the audit surfaces into Q-W1..Q-W6 before starting them.

Q-W1 — safe opener: extract core/json + impose the directory/namespace layout on clean modules

Goal: The zero-god-module-risk opener. Two moves: (1) extract a pure core/json module (parser + serializer) and delete the four hand-rolled Parsers in bank_model / bank_book / view_mode_model / owned_manifest (the single largest DRY+SRP violation, and entirely off the hot paths); (2) impose the settled core//shell//app/ directory layout + sub-namespaces (reasampler::model/view/capture/audio/ui/reclaim/version/json) on the 30 clean pure libs + the clean shells that need no splitting — pure relocation, no logic change. Proves the wave discipline (relocate + encapsulate, CTest-green) before any god-module surgery. CONTEXT.md §Phase Q (json extraction; directory + namespace map). Verify: CTest green at every commit. The four duplicate Parsers are gone, replaced by one core/json consumed by all four models; round-trip serialization is byte-identical to before (no format change — a structural dedupe, not a behavior change). Every relocated clean module compiles and its test executable passes unmoved. Sample (model) vs AudioSample (audio) vs unified Parser (json) do not collide once sub-namespaced. No REAPER type crosses into any core/ file; the CMake pure/shell enforcement still holds. Depends on: the GATE (tree quiescent) and Q-W0 closed (audit triaged + Daniel signed off; any fix-now findings the audit assigned to Q-W1 folded in). First structural wave.

• Extract core/json (pure parser + serializer: parseString/parseInt/parseKey/skipValue + escape, plus emit helpers); unify under reasampler::json; guard the Parser name against cross-lib collision. Off all hot paths — safe to abstract freely.
• Rewire bank_model, bank_book, view_mode_model, owned_manifest onto core/json; delete the four duplicate Parsers. Round-trip output byte-identical (dedupe, not reformat).
• Relocate the 30 clean pure libs into core/{model,view,capture,audio,ui,reclaim,version, json}/ and the clean shells into shell/{capture,panel,view,persist,actions}/; move main.cpp to app/. Update CMakeLists.txt src/ paths only (no target-graph change).
• Apply sub-namespaces matching the directories on every relocated clean module (the god-modules re-namespace their own new TUs as they split, W2–W5). Resolve Sample/ AudioSample/Parser homes. This alone resolves the naming collisions (§2b.2): the shared pure-UI rect types (FooterRect/ButtonRect/Selection/CellRect) get one ui:: owner — retire the hand-collision "NAME NOTE" in footer_bar.h.
• Naming riders (Q-8, if settled): rename the survivor JSON parser to json::Parser (or json::Reader/json::Writer); if Daniel takes the BankIndex→BankModel rename, land it here (mechanical class rename, verified by bank_model_tests). No rename on a file this wave isn't already relocating (Q-7).
• Confirm CTest green + no hot-path change: peaks/audition/realtime-tick untouched by this wave (pure relocation of clean modules; peaks stays a free function).

Q-W2 — split bank_panel.cpp (the biggest god-module, 2424 LOC)

Goal: Split the largest god-module (8+ responsibilities) along the audit's named seams: panel_render / panel_thumbnails / panel_audition / panel_input / panel_bank_ops / panel_window. Split the fat bank_panel.h alongside (Interface Segregation). Preserve the audition hot path as a direct call-through, never virtual. panel_bank_ops becomes the single home for the bank-CRUD verbs that W4 will dedupe actions.cpp against. CONTEXT.md §Phase Q (bank_panel split seams; hot-path audition guardrail). See docs/product/code-organization.md §2.1, §5. Verify: CTest green at every commit. Each seam is its own TU under shell/panel/; the panel draws, thumbnails, auditions, handles input, does bank ops, and manages its window exactly as before (no behavior change — verify in DAW that the panel is visually and interactively unchanged). Audition/preview call path stays a direct call-through (no virtual dispatch, no added header→TU indirection on the preview path). The ~20-function public API is now segmented across the split headers. Depends on: Q-W1 (directory/namespace layout established). Independently landable.

• Split rendering (draw*/paint*) → panel_render; thumbnail compute+cache → panel_thumbnails.
• Split the audio audition/preview engine → panel_audition — direct call-through, not virtual; preview idle path unchanged.
• Split input handling (mouse/key/wheel) + new-content detection → panel_input; window lifecycle + OS drag-out/drop-target → panel_window.
• Extract bank-CRUD verbs → panel_bank_ops (the future single owner; W4 dedupes actions.cpp against it). Split bank_panel.h into per-seam headers (I).
• Verify in DAW: panel unchanged; CTest green; no hot-path indirection added.

Q-W3 — split main.cpp (hoist orchestration; leave main = pointers + entry + dispatch)

Goal: Reduce main.cpp (1762 LOC) to its actual job — API pointers + ReaperPluginEntry + dispatch (~the owns-pointers ~120 lines) — by hoisting: capture_orchestrator (RunCapture / captureAndIndexOne / renderOffline / batch/recapture/realtime Run*), scope_resolve (resolveRange/resolveRazorRange/collectSelectedTracks + provenance assembly inputs), and realtime_lifecycle (the realtime-capture state machine + globals + selection guards). FxBypassGuard moves out but stays a stack RAII object (precision-critical); the realtime idle tick stays a single pointer test. CONTEXT.md §Phase Q (main split seams; FxBypassGuard + realtime-tick guardrails). See docs/product/code-organization.md §2.1, §3. Verify: CTest green at every commit. Capture (offline + realtime + batch + recapture) behaves identically in DAW; the null test still nulls, bit-identical repeats still match (the precision invariants FxBypassGuard protects are unchanged); capture ≠ placement holds (no hoisted Run* path gains an InsertMedia call). The realtime idle fast-path is still a single pointer test. main.cpp is now pointers + entry + dispatch only. Depends on: Q-W1. Independent of Q-W2.

• Hoist capture orchestration → capture_orchestrator (shell/capture/); keep FxBypassGuard a stack RAII object as it moves (precision-invariant-critical).
• Hoist scope/source resolution + provenance assembly inputs → scope_resolve.
• Hoist the realtime-capture lifecycle state machine + globals + the two RAII selection guards → realtime_lifecycle; idle tick stays a single pointer test.
• Leave main.cpp = API-pointer ownership + ReaperPluginEntry + dispatch; move to app/.
• Naming rider (Q-9, if settled): align the capture_realtime (shell) / realtime_record (pure) word-order inversion to the house shell↔core convention (rec: stem capture_realtime, shell suffixed) — a free rider since W3 already hoists the realtime lifecycle. No rename on a file this wave isn't already touching (Q-7).
• Verify in DAW: null test nulls, bit-identical repeats match, capture≠placement holds; CTest green; no realtime-tick branch-shape change.

Q-W4 — split actions.cpp + dedupe bank verbs against panel_bank_ops

Goal: Split the two unrelated command-id families in one TU (981 LOC) into design_view_actions / bank_actions / prune_action, and dedupe actions.cpp's own promptText/mintBankId and bank verbs against the panel_bank_ops single-owner established in Q-W2. prune_action keeps the doBankPruneFolder deletion authority contract intact (routes to persist's prune_fs after W5). CONTEXT.md §Phase Q (actions split seams; bank-verb dedupe). See docs/product/code-organization.md §2.1, §2.4. Verify: CTest green at every commit. Every action fires identically in DAW (Design View family; multi-bank create/rename/reorder/delete/evacuate/activate/move/copy/remove; prune). The bank-CRUD verbs have one implementation home (no bank_panel/actions duplication). Each bank verb still wraps its mutation in one batched undo point; the prune action still writes no ext state and opens no undo point. Command-id strings are unchanged (FOREVER-STABLE contract — a reorg must not touch a shipped command id). Depends on: Q-W2 (panel_bank_ops is the dedupe target). Independent of Q-W3.

• Split → design_view_actions (toggle/activate/tag/untag/showBoth/moveItems), bank_actions (bank CRUD family), prune_action (doBankPruneFolder — the single file-deletion action).
• Dedupe actions.cpp's promptText/mintBankId + bank verbs against panel_bank_ops (one owner); do not change any command-id string.
• Verify in DAW: all action families fire unchanged; one bank op = one Ctrl-Z; prune still no-undo/no-ext-state; CTest green.

Q-W5 — split persist.cpp (isolate the single file-deletion authority into prune_fs)

Goal: Split persist.cpp (766 LOC, 5 responsibilities) into session (lifecycle+poll, BeginLoadProjectState reload hook), ext_state_io (the ext-state ↔ JSON serialization bridge + GUID minting + folder relocation), and prune_fs (prune scanning + deleteOrphanFile via SHFileOperationW). The split concentrates the byte-deleting authority into one obvious module — it must never spread it. CONTEXT.md §Phase Q (persist split seams; deletion-authority isolation). See docs/product/code-organization.md §2.1, §7. Verify: CTest green at every commit. Session save/load/undo-reload, ext-state round-trip, folder relocation, and prune deletion all behave identically in DAW. File deletion lives in exactly one module (prune_fs) — the single-file-deletion-authority invariant is improved (concentrated), never diluted. Relative-paths-only persistence is unchanged. Depends on: Q-W1. Best after Q-W4 (so prune_action routes cleanly to prune_fs), but independently landable.

• Split → session (lifecycle/poll + projectconfig reload hook), ext_state_io (serialization bridge + GUID minting + folder relocation).
• Isolate prune scanning + deleteOrphanFile (SHFileOperationW) → prune_fs — the one file-deletion module; nothing else may delete bytes.
• Verify in DAW: save/load/undo-reload/relocation/prune unchanged; deletion authority is one module; relative-paths-only holds; CTest green.

Q-W6 — OCP registration-table + residual fat-header (I) splits

Goal: Close the last SOLID wart: replace the ~350-line hand-written non-table action registration blocks (now isolated in app/main.cpp after Q-W3) with a registration table, so adding an action edits one place, not four parallel ones (OCP). Split any remaining fat headers (capture.h/persist.h) not already resolved by their TU splits (I). CONTEXT.md §Phase Q (OCP registration-table). See docs/product/code-organization.md §2.3, §6 (Q-6). Verify: CTest green at every commit. Every action still registers, appears in the Actions list, and fires via hookcommand exactly as before; command-id + display strings unchanged (FOREVER-STABLE, per-channel); unload still mirror-unregisters everything. Adding a hypothetical new action now touches the table only (demonstrated in review, not shipped). Remaining fat headers are segmented. Depends on: Q-W3 (registration code must be isolated first). Sequenced last; the most droppable point if the phase needs narrowing (Q-6).

• Convert the hand-written Register("command_id"/"gaccel"/"hookcommand") blocks to a data-driven registration table; unload mirror-unregisters from the same table.
• Split residual fat headers (capture.h/persist.h and any other) alongside their TUs (I).
• Verify: all actions register/fire/unregister unchanged; command-id strings untouched; CTest green.

Phase Q — sequencing

GATE: Phase S + Phase L L3 merged to dev (D2 complete, M9 abandoned) — tree quiescent
      ("when Phase S and L3 are finished" — L1/L2/L3/L4–L7 all landed — GATE SATISFIED)
  │
  ▼
Q-W0 (pre-restructure functional + DSP quality audit — findings report + triage)
  │   ── SUB-GATE: triage complete + Daniel signed off on every disposition ──
  ▼   (fix-now findings remediated/assigned; downstream Q-W1..W6 reshaped as needed)
Q-W1 (safe opener: core/json extract + directory/namespace layout on clean modules)
  ├─► Q-W2 (split bank_panel) ──► Q-W4 (split actions + dedupe bank verbs vs panel_bank_ops)
  ├─► Q-W3 (split main.cpp; hoist orchestration) ──► Q-W6 (OCP registration-table + I splits)
  └─► Q-W5 (split persist; isolate prune_fs)   [best after Q-W4]

Q-W0 is the entry point — the functional/DSP audit runs FIRST and gates Q-W1 (no structural point begins until its triage closes and Daniel signs off). W1 is then the safe, high-leverage structural opener (all later waves assume the layout it establishes). The four god-module splits (W2–W5) are risk-ordered and mostly parallel-safe; W4 depends on W2's panel_bank_ops, W6 depends on W3's isolated registration code. Big-bang is rejected — every wave is independently landable and CTest-green.

Phase Q — must-verify-before-build

• Q-W0 closed before any structural point — the functional/DSP audit's findings report exists, every finding is triaged (fix-now vs. document-and-defer, each with rationale), fix-now findings are remediated or assigned to the wave that opens their file, and Daniel has signed off on every disposition. Q-W1 does not begin otherwise. (CONTEXT.md §Phase Q Q-W0; naming/DSP smell categories §2c of docs/product/code-organization.md.)
• Hot-path call/inline shape — before landing each split, confirm no virtual dispatch and no header→TU indirection was added on peaks envelope compute, audition/preview, or the realtime tick. computeEnvelope stays a free function on const std::vector<float>&; audition stays a direct call-through; the idle tick stays a single pointer test. (CONTEXT.md §Phase Q, docs/product/code-organization.md §3.)
• Command-id + display strings are FOREVER-STABLE — a reorg must not change a shipped command_id string, action display name, ext-state namespace, or VST3 class UID. Re-namespacing C++ symbols is orthogonal to these on-the-wire/on-disk contract strings; keep them byte-identical (per-channel, per the Phase V V4 contract). (CONTEXT.md §Phase Q.)
• Name-collision sweep on sub-namespacing — Sample (model) vs AudioSample (audio) vs the unified Parser (json), plus the shared pure-UI rect types FooterRect/ButtonRect (already hand-collision-checked in footer_bar.h), and any other cross-lib name that collides once flattened into granular namespaces. Resolve by each symbol's new subsystem home before landing W1. (naming audit §2b.2; docs/product/code-organization.md §6 Q-4/Q-8.)
• Naming stays zero-behavior-change and off the wire — the §2b renames touch C++ symbols only; no command_id string, action display name, ext-state namespace/key, reasampler: lane prefix, or VST3 class UID is renamed (naming audit §2b.5). A rename that would alter a shipped contract literal is out of scope, full stop.
• The GATE — do not begin any Q point until Phase S + Phase L L3 are merged to dev and the tree is quiescent (D2 complete, M9 abandoned). Re-confirm quiescence against dev before W1.