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:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user