docs(phase-q): record Q-W0 close + Q-W1 landing — points moved to COMPLETED.md; skipped riders and bank_book nameKey residual preserved

This commit is contained in:
2026-07-29 09:50:37 -04:00
parent 0ce3f4894a
commit 9dd3440b75
2 changed files with 101 additions and 68 deletions
+29 -68
View File
@@ -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/W2vW5 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/W2vW5). 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