From 9dd3440b750e3cd86f74dd069eb05f05a1c92a11 Mon Sep 17 00:00:00 2001 From: daniel-c-harvey Date: Wed, 29 Jul 2026 09:50:37 -0400 Subject: [PATCH] =?UTF-8?q?docs(phase-q):=20record=20Q-W0=20close=20+=20Q-?= =?UTF-8?q?W1=20landing=20=E2=80=94=20points=20moved=20to=20COMPLETED.md;?= =?UTF-8?q?=20skipped=20riders=20and=20bank=5Fbook=20nameKey=20residual=20?= =?UTF-8?q?preserved?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- COMPLETED.md | 72 ++++++++++++++++++++++++++++++++++++++ PLAN.md | 97 ++++++++++++++++------------------------------------ 2 files changed, 101 insertions(+), 68 deletions(-) diff --git a/COMPLETED.md b/COMPLETED.md index dbfba43..613de11 100644 --- a/COMPLETED.md +++ b/COMPLETED.md @@ -2883,3 +2883,75 @@ now covered by the same mechanism. - [x] `reasampler_processor`: `reloadInstrument` decodes from `SampleRefs_` (bank-free); `SampleRefs` table added to `ComponentState` v10; heal timer + poll-to-play removed; preview summing removed; `PreviewCard` member removed. - [x] `sample_map`: `SampleRefs` type + `SampleRefEntry` struct; `refreshRefsFromBank`, `retainRefs`, `resolvePerformanceFromRefs` (decodes directly from refs, no bank blob required); `kComponentStateVersion` bumped to 10; pre-v10 lift to empty refs. - [x] `ComponentState` v10 serialization round-trip: new `sampleRefs` field; pre-v10 blobs migrate on load. + +--- + +## Q-W0 fix-now remediations — closes Q-W0 (2026-07-28) + +> **Merged to `phase-q` 2026-07-28 (commit `546927e`).** Closes the Q-W0 sub-gate — Q-W0 +> (pre-restructure functional + DSP quality audit) is now fully closed. Part of the phase-q +> integration that later reached 60/60 green with Q-W1. + +**Goal:** Land the six Daniel-approved fix-now remediations from the Q-W0 audit triage, plus +seven review riders surfaced during their review, before any structural Q-wave begins. +**Verify:** Each remediation lands with its module's CTest target green; the audible DSP fixes +carry a stated before/after listening check. + +- [x] **T1-01** — linked-lag stereo SOLA + follower self-heal fallback. +- [x] **T1-03** — playable-span prime bound. +- [x] **T1-09** — declick dead-state removal. +- [x] **T2-01a** — provenance wire-cursor hardening backport. +- [x] **T3-01** — rate-derived gain ramp. +- [x] **T3-03** — rate-derived fade ceiling. +- [x] Seven additional review riders landed in the same merge (not individually itemized in + this entry). + +**Notes/decisions:** +- Landing these six fix-nows (plus the review riders) closes Q-W0 entirely — audit, triage, + sign-off, and remediation are all complete — and opens Q-W1. + +--- + +## Q-W1 — safe opener: `core/json` extraction + directory/namespace layout (2026-07-29) + +> **Merged to `phase-q` 2026-07-29. Integrated suite 60/60 green.** First structural wave of +> Phase Q; unblocked by the Q-W0 fix-now remediations closing 2026-07-28. + +**Goal:** The zero-god-module-risk opener. Extract a pure `core/json` module (parser + +serializer) and delete the five hand-rolled JSON decoders — the four `Parser`s in `bank_model` +/ `bank_book` / `view_mode_model` / `owned_manifest` plus `tail_control`'s fifth decoder; impose +the settled `core/`/`shell/`/`app/` directory layout + sub-namespaces on the clean pure libs, +clean shells, and clean VST pure libs — pure relocation, no logic change. +**Verify:** CTest green at every commit (60/60). The five duplicate JSON decoders are gone, +replaced by one `core/json` consumed by all five former consumers; round-trip serialization is +byte-identical to before. Every relocated clean module compiles and its test executable passes +unmoved. No REAPER type crosses into any `core/` file. + +- [x] `core/json` extracted (`json::Reader`/`json::Writer`); `bank_model`, `bank_book`, + `view_mode_model`, `owned_manifest`, and `tail_control` rewired onto it; the five hand-rolled + JSON decoders deleted. +- [x] Wire-`Cursor` family collapsed into `core/wire` — one hardened survivor codec. +- [x] Shared `readFileBytes` pure helper added; linked by both artifacts. +- [x] `slot_map` extracted from `bank_book`, with its own `slot_map_tests`. +- [x] ~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}/`; `main.cpp` moved to `app/`. Sub-namespaces applied to every relocated clean + module. +- [x] Rect unification: one concrete `ui::Rect` + `contains()` + per-role aliases — the + XYWH-vs-LTRB fork retired, `footer_bar.h`'s "NAME NOTE" collision workaround gone. +- [x] `clamp01` deduplicated. +- [x] Naming riders: survivor JSON parser minted as `json::Reader`/`json::Writer`; `BankIndex` + renamed to `BankModel` (verified by `bank_model_tests`). +- [x] `reasampler_uid.h` relocated to `core/wire/`. +- [x] Interim `core/namespaces.h` shim added for the six not-yet-split god TUs; each downstream + split wave (Q-W2 onward) retires its own includes of it as that module splits. + +**Notes/decisions:** +- **Riders explicitly skipped/deferred:** 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. diff --git a/PLAN.md b/PLAN.md index b907ed6..5624d3c 100644 --- a/PLAN.md +++ b/PLAN.md @@ -315,11 +315,13 @@ panel adopts knob deck + curve popup, `param_slider` slider rows retired on that > 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-28): audit COMPLETE, triage COMPLETE, sign-off COMPLETE.** 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 Q-W1 sub-gate is satisfied once -the six approved fix-now remediations land** (final point below; in flight on `pq-w0-fixes`). +**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 @@ -376,72 +378,31 @@ before/after listening or null check. **The gate to Q-W1 is: triage complete + D 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.** -- [ ] **Fix-now remediations (approved 2026-07-28; Q-W0-scoped; in flight on branch - `pq-w0-fixes`):** T1-01 linked-lag stereo splice alignment, T1-03 Preserve prime bound + - immediate `freezeTail()`, T1-09 `declickR_` dead-state removal (rider on the `sampler_core` - edits), T2-01(a) provenance wire-cursor hardening backport, T3-01 gain-ramp seconds, T3-03 - fade-ceiling seconds. Each lands with its module's CTest target green; the audible DSP fixes - with a stated before/after listening check. **Landing these closes Q-W0 and opens Q-W1.** ## 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 five hand-rolled JSON decoders** — the four `Parser`s in -`bank_model` / `bank_book` / `view_mode_model` / `owned_manifest` **plus `tail_control`'s fifth -decoder** (T2-02, Q-W0's undercount fix — the wave's one-JSON-path goal is not met without it) — -the single largest DRY+SRP violation, 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` + the `instrument` -family) on the **30 clean pure libs + the clean shells that need no splitting + the ~20 clean -VST pure libs** (T4 §1.5, under the settled T4-18 `core/instrument/{engine,map,ui}` + -`shell/instrument/` shape) — pure relocation, no logic change. **Q-W0 additions (SETTLED -2026-07-28):** the shared `readFileBytes` pure helper (T2-03); the wire-`Cursor` collapse into -one shared codec beside `core/json` (T2-01(b)); the rect unification — one **concrete** -`ui::Rect` + `contains()` + per-role aliases, NOT a template (T2-05 ≡ T4-21). 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 five duplicate JSON decoders are gone, replaced by -one `core/json` consumed by all five consumers; 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`, **and - `tail_control` (T2-02)** onto `core/json`; **delete the five duplicate decoders.** Round-trip - output byte-identical (dedupe, not reformat). -- [ ] Add the shared `readFileBytes` pure helper to the `core/` utility home; both artifacts - link it (T2-03). -- [ ] Collapse the length-prefixed wire-`Cursor` family into one shared wire codec beside - `core/json`, consumed by `provenance` / `assignment_request` / `sample_usage` / - `parseBankGeneration` (T2-01(b) — the structural half; the hardening backport lands in Q-W0). -- [ ] Riders on files this wave already opens: `slot_map` extraction from `bank_book` (T4-05); - `view_mode_model` planner split (T4-06 — optional if the wave wants to stay minimal); - `view_lanes` split only if relocation touches `view.cpp` anyway (T4-09). -- [ ] Relocate the 30 clean pure libs into `core/{model,view,capture,audio,ui,reclaim,version, - json}/` **+ the ~20 clean VST pure libs into `core/instrument/{engine,map,ui}/` (T4-18 - SETTLED, Daniel 2026-07-28)**, and the clean shells into - `shell/{capture,panel,view,persist,actions,instrument}/`; 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/W2v–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 — one **concrete** `ui::Rect` + `contains()` + per-role aliases, retiring the - XYWH-vs-LTRB fork and folding in `editor_geometry`'s `Rect` (T2-05 ≡ T4-21 — explicitly NOT a - template); retire the hand-collision "NAME NOTE" in `footer_bar.h`. Riders: `clamp01` dedup - (T4-24); the `hitIndex` hit-test template only as an opportunistic follow-on once the rect - unification lands (T4-22). -- [ ] **Naming riders (Q-8 — SETTLED, Daniel 2026-07-28: both renames):** the survivor JSON - parser is minted as **`json::Reader`/`json::Writer`**; land **`BankIndex`→`BankModel`** 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). +> **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) **Goal:** Split the largest extension god-module (8+ responsibilities) along the audit's named