Files

T

daniel 5232227323 docs(phase-q): record Q-W2 + Q-W2v + Q-W3 landings — points to COMPLETED.md; ceiling overages recorded, in-DAW verification marked pending, Q-W4 dedupe-shape notes preserved

2026-07-29 11:43:22 -04:00

46 KiB

Raw Blame History

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. 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. All drawing through the L1 kit; all layout/hit-test in pure geometry modules.

S-VIEW-11, S-VIEW-12, and S-VIEW-13 have all landed — FB1 (merged 2026-07-27, suite 55/55) brought the knob deck + master gain + curve popup + full-width hero; FB2 (merged 2026-07-28, suite 55/55) brought Zone-panel parity. Phase S editor Wave B (r11) is complete. See COMPLETED.md for both FB entries.

Open forks — R11-F1 (hero height vs. default window) SETTLED at FB1 build: elastic hero, 840×620 default kept. R11-F2 (Zone-panel parity) SETTLED at FB2 build: knob deck

curve popup adopted on the Zone panel; param_slider slider rows retired on that surface.

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 forks all settled: R11-F1 SETTLED at FB1 build (elastic hero, 840×620 default kept); R11-F2 SETTLED at FB2 build (Zone panel adopts knob deck + curve popup, param_slider slider rows retired on that surface).)

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.

Q-W0 SIGN-OFF: COMPLETE (Daniel, 2026-07-28). The audit ran as four parallel tracks (T1 DSP, T2 architecture, T3 env-coupled constants, T4 sizing/placement — 59 findings; report docs/product/code-quality-audit.md, appendices docs/product/audit-notes/), and all 59 findings' dispositions are approved as proposed. The Q-W1 sub-gate is satisfied once the six approved fix-now remediations land (in flight on branch pq-w0-fixes, Q-W0-scoped): T1-01, T1-03, T1-09, T2-01(a), T3-01, T3-03. The audit's §3 plan reshape is folded into the waves below (Q-W2 6→8 seams; NEW wave Q-W2v parallel with Q-W2; Q-W3 3→4 hoists + riders; Q-W5

the ext-state-loop dedupe), and its §4 decision list is settled — see the settlement block below. The Q-11 question is answered by the audit: the SOLA pitch engine is sound — no technique replacement warranted; every pitch finding is a bounded in-technique fix or a documented operating limit.

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; + Q-W2v, the VST god-module wave added at the Q-W0 sign-off, 2026-07-28). 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).

SETTLED (Daniel, 2026-07-28 — with the Q-W0 sign-off; the REC record above kept as history): Q-5 SETTLED — split to seams-by-responsibility with the T4 seam lists adopted (bank_panel 6→8 seams adding panel_layout + panel_drag, T4-01; capture_orchestrator further split with capture_batch, T4-02), and the ~600-line file ceiling is an acceptance criterion on every split wave — seams are the method, the ceiling is the bar; arbitrary bisection to hit the number is rejected. Q-6 SETTLED: in scope, last wave, as planned. Q-8 SETTLED: both renames — BankIndex→BankModel (W1) and the JSON parser minted as json::Reader/json::Writer (W1); additionally from the audit, ICaptureBackend is deleted in Q-W3 (T4-26 — one deriver, zero polymorphic call sites; the CLAUDE.md/CONTEXT "two backends behind one interface" correction rides Q-W3 itself, recorded as a rider — the docs are not edited before that wave). Q-9 SETTLED: yes — align to stem capture_realtime, shell suffixed, during W3. VST placement (audit §4a) SETTLED: T4-18 — src/vst/ integrates into the single core//shell/ top split as core/instrument/{engine,map,ui} + shell/instrument/ (Q-3 directory map updated in CONTEXT.md §Phase Q). WAV/RIFF consolidation (audit §4e) SETTLED: a named rider on Q-W3 — one pure wav_codec owner (walker + layout + build + patch), absorbing the T4-10 ingest extraction. Q-W2v scheduling (audit §4f) SETTLED: parallel with Q-W2 (different artifact, zero file overlap; the serial "Q-W7" alternative set aside).

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.

STRUCTURAL HEURISTICS (Daniel, 2026-07-28 — acceptance criteria on every wave; these generalize the three-hot-path guardrail above, they do not replace it): (1) More directories is a must, more files is good, ~600-line file ceiling — SRP applies to namespaces, encapsulation, and file organization alike. The ceiling is the bar, the audit's named seams are the method: a file landing over ~600 needs a responsibility seam, not an arbitrary bisection; a documented hot-path exception (sampler_core.cpp, T4-14/T4-27) is legitimate, silent overshoot is not. (2) Templates are the right tool for compile-time dedup — use them where earned (the LE byte codec putLE/readLE, T4-20), not for name-only unification (the rect family is one concrete ui::Rect, NOT a template — T4-21's ruling). (3) SOLID is great but saved CPU is better — no dispatch-stack blowouts anywhere, not just the three named hot paths; prefer static polymorphism where types are compile-time-known (T4-27's warning is the canonical case: a by-class sampler_core split would put virtual envelope tick()s on the per-voice-per-sample path).

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/W2v–W5 god-module splits → W6 OCP finish).

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

STATUS (2026-07-29): audit COMPLETE, triage COMPLETE, sign-off COMPLETE, fix-now remediations LANDED — Q-W0 is fully closed. The findings report is committed (docs/product/code-quality-audit.md; track appendices in docs/product/audit-notes/ — T1 DSP, T2 architecture, T3 env-constants, T4 sizing/placement; 59 findings). Daniel approved every disposition 2026-07-28. The six approved fix-now remediations plus seven review riders landed 2026-07-28 (merge 546927e) — see COMPLETED.md. Q-W1 has since landed on top of this closure (see COMPLETED.md). 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. DONE (Daniel, 2026-07-28): all 59 dispositions approved as proposed; the §3 plan reshape and §4 decisions are folded into Q-W1..Q-W6 + Q-W2v below.

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

Landed on phase-q (2026-07-29). Integrated suite 60/60 green. core/json (json::Reader/json::Writer) extracted; the five hand-rolled JSON decoders (incl. tail_control's) deleted; the wire-Cursor family collapsed into core/wire; the shared readFileBytes helper added; ~50 clean modules relocated into core/{model,view,capture, audio,ui,reclaim,version,json,util,wire}/, core/instrument/{engine,map,ui}/, shell/{capture,panel,view,persist,actions,instrument}/, app/main.cpp; sub-namespaces applied; one concrete ui::Rect + aliases (LTRB fork + footer_bar NAME NOTE retired); slot_map extracted from bank_book; clamp01 deduped; BankIndex→BankModel; reasampler_uid.h relocated to core/wire/. See COMPLETED.md for the full narrative.

Skipped/deferred riders: T4-22 (hitIndex hit-test template) — not trivial, deferred as an opportunistic follow-on once the rect unification is in use downstream; T4-06 (view_mode_model planner split) — optional, deferred; T4-09 (view_lanes split) — deferred (in scope only if a later wave touches view.cpp anyway).

Open residual — bank_book.cpp still 737 LOC. The serialize/deserialize seam is identified but blocked on a nameKey linkage design decision, escalated to Daniel and pending as of 2026-07-29. Downstream waves touching bank_book should check this residual before assuming the split is finished.

An interim core/namespaces.h shim covers the six not-yet-split god TUs; each downstream split wave (Q-W2 onward) retires its own includes of it as that module splits.

Q-W2 — split `bank_panel.cpp` (the biggest extension god-module — 3459 LOC at the Q-W0 census)

Landed on phase-q (2026-07-29, merge of pq-w2-panel). Integrated suite 61/61 green, reviewed-approved. bank_panel.cpp (3459 LOC) split into eight TUs under shell/panel/: panel_render / panel_thumbnails / panel_audition / panel_input / panel_bank_ops / panel_window / panel_layout / panel_drag, plus per-seam public headers and internal panel_state.h; audition stays a direct call-through; the one-bank-op-one-undo invariant is preserved; ~50 TU-private helpers wrapped in anonymous namespaces (a review follow-up). See COMPLETED.md for the full narrative.

Recorded ceiling overages (reviewer-endorsed, preserved as a durable record per CONTEXT's "silent overshoot is not legitimate" rule): panel_input.cpp 636, panel_render.cpp 613, panel_state.h 608 — the overage is comment volume; non-comment lines are ~322–369 per file; no honest seam remains; bisection was rejected.

Review note for the Q-W4 planning record: panel_bank_ops's verbs still embed prompts/panel-state nudges — Q-W4's dedupe needs promptless inner verbs (renameBank(id,name) etc.), not a call-site swap; promptText/mintBankId are byte-identical twins with actions.cpp and are the cheapest first dedupe.

In-DAW verification (panel parity) is PENDING on phase-q — deferred by design, not yet performed.

Q-W2v — split the VST god-modules (NEW wave — Q-W0 T4 §1.5; runs parallel with Q-W2)

Landed on phase-q (2026-07-29, merge of pq-w2v-vst). Integrated suite 61/61 green, reviewed-approved. reasampler_editor.cpp (3084 LOC, the largest file in the repo) split into eight face-axis TUs under shell/instrument/, with pure layout hoisted into core/instrument/ui/editor_geometry (discharges T2-06, newly tested); reasampler_processor.cpp split into processor_state / processor_reload / lifecycle+process() kept whole (no virtual seam, T4-29); sample_map split into a resolution core + component_state_io codec (the extension preset path no longer links the voice engine — link-proven; T4-13 ≡ T2-07); sampler_core.cpp stays whole with the documented hot-path exception comment (T4-14/T4-27); zone_params.h split out; core/wire/bytes.h (putLE/ByteReader) lands (T4-20); ThumbnailKey adopted (T2-10); a golden full-blob v11 fixture pins the codec bytes. The src/vst/ directory is gone. See COMPLETED.md for the full narrative.

Deferred/known: component_state_io.h still includes sample_map.h→sampler_core.h transitively (T2-07's header half — future work); the engine namespace is deferred (sampler_core stays flat reasampler); capture-side LE rewires are left for the capture family.

In-DAW verification (editor/processor parity) is PENDING on phase-q — deferred by design, not yet performed.

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

Landed on phase-q (2026-07-29, merge of pq-w3-main). Integrated suite 61/61 green, reviewed-approved. app/main.cpp reduced 1897 → 653 LOC (pointers + entry + dispatch; the remaining bulk is the registration residue Q-W6 dissolves) via four hoists into shell/capture/: capture_orchestrator, capture_batch, scope_resolve, realtime_lifecycle; FxBypassGuard moved intact as a stack RAII object; the realtime idle tick stays a single pointer test; ICaptureBackend deleted (T4-26) with the CLAUDE.md/CONTEXT-ARCHIVE corrections landed in the same commit; the Q-9 rename done (pure core/capture/capture_realtime, shell capture_realtime_shell + capture_realtime_finalize split, T4-08); stampCaptureSample dedupe (T2-09, divergent time-sig behavior preserved via caller arg); makeUniqueTag gains a per-session monotonic counter (T1-11 behavior fix — stems now <epoch>-<n> / rt-<epoch>-<n>; the per-process residual is documented in-code); one pure wav_codec RIFF owner absorbs wav_trim + ingest's WAV build + content hashes, with golden hash literals pinned (wav_codec_tests replaces wav_trim_tests; capture_realtime_tests replaces realtime_record_tests). See COMPLETED.md for the full narrative.

Known open: wav_trim.h's transitional forwarding shim still has three live includers (sample_map.h, editor_session.cpp, processor_reload.cpp) — repoint-and-retire is a named follow-up; ingest.cpp is trimmed to 567 LOC but keeps the namespaces.h shim (ingest + view remain the shim's unowned consumers).

In-DAW verification (null test, bit-identical repeats) is PENDING on phase-q — deferred by design, not yet performed.

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

Goal: Split the two unrelated command-id families in one TU (1016 LOC at the Q-W0 census — T4-03: the planned seams still land sub-600, no reshape) 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 (852 LOC at the Q-W0 census — T4-04: seams unchanged; the pS-usage growth landed exactly where this wave isolates it; 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. Q-W0 rider (T2-04, SETTLED 2026-07-28): generalize the GetProjExtState grow-loop retry policy into bridge_marshal's pure decode home (or its core/ successor) and rewire all three hand-rolled copies — usage_scan's prune-safety-adjacent copy included. 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.
Dedupe the GetProjExtState grow-loop ×3 (T2-04): one retry policy generalized from bridge_marshal; rewire usage_scan's prune-safety-adjacent copy with sample_usage_tests green.
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). (Q-W0: no reshape — T4-02 notes the ~385-line registration residue left in app/main.cpp after Q-W3 shrinks further under the table.) 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 (audit + triage + report — COMPLETE; all 59 dispositions signed off 2026-07-28)
  │   ── SUB-GATE: satisfied once the six approved fix-now remediations land ──
  ▼   (T1-01 T1-03 T1-09 T2-01a T3-01 T3-03 — in flight on pq-w0-fixes)
Q-W1 (safe opener: core/json ×5 + wire codec + rect unification + relocation incl. ~20 VST
  │   pure libs under core/instrument/{engine,map,ui} + riders)
  ├─► Q-W2  (split bank_panel — 8 seams) ──► Q-W4 (split actions + dedupe vs panel_bank_ops)
  ├─► Q-W2v (NEW: VST god-modules — editor 8 TUs / processor 3 TUs / component_state_io;
  │          sampler_core TU whole — documented exception)  [parallel with Q-W2: zero overlap]
  ├─► Q-W3  (split main — 4 hoists incl. capture_batch; + wav_codec, ICaptureBackend deletion,
  │          stamp dedupe, T1-11, capture_realtime_finalize) ──► Q-W6 (OCP registration-table)
  └─► Q-W5  (split persist; + ext-state-loop dedupe)   [best after Q-W4]

Q-W0 has run and is signed off (2026-07-28); its sub-gate closes when the six fix-now remediations land. W1 is the safe, high-leverage structural opener (all later waves assume the layout — including the T4-18 instrument/ placement — it establishes). The god-module splits (W2, W2v, W3, W5) are risk-ordered and mostly parallel-safe; Q-W2v runs parallel with Q-W2 (different artifact, zero file overlap — audit §4f SETTLED); 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.) Status 2026-07-28: triage + sign-off COMPLETE (all 59 dispositions); the sub-gate closes when the six fix-now remediations land (pq-w0-fixes).
~600-line ceiling on every split wave — every TU a split wave ships lands under ~600 LOC, with sampler_core.cpp the single documented exception (T4-14/T4-27). Seams are the method, the ceiling is the bar; arbitrary bisection to hit the number is rejected (Q-5 settlement, 2026-07-28).
No dispatch-stack blowouts anywhere — heuristic (3) generalizes the hot-path guardrail beyond the three named paths: prefer static polymorphism where types are compile-time-known; templates only where earned for compile-time dedup (T4-20 yes; T4-21's rect NO-template ruling).
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.

46 KiB Raw Blame History Unescape Escape