docs(05-02): complete bank-decoupling plan — SUMMARY, STATE, ROADMAP updated
This commit is contained in:
@@ -23,7 +23,7 @@ Full details: `.planning/milestones/v1.0-ROADMAP.md`
|
||||
|
||||
**Milestone Goal:** Users can customize how traffic sounds via a TOML config file — setting custom frequencies, waveform types, and their own classification rules with named sounds.
|
||||
|
||||
- [ ] **Phase 5: Waveform Types and Bank Decoupling** - Internal refactors establishing waveform enum and injectable bank signature
|
||||
- [x] **Phase 5: Waveform Types and Bank Decoupling** - Internal refactors establishing waveform enum and injectable bank signature (completed 2026-03-26)
|
||||
- [ ] **Phase 6: Config Package and Sound Overrides** - TOML loading, auto-discovery, partial merge, and frequency/waveform overrides wired end-to-end
|
||||
- [ ] **Phase 7: Custom Rules and Print-Config** - User-defined classification rules and --print-config UX
|
||||
|
||||
@@ -37,11 +37,11 @@ Full details: `.planning/milestones/v1.0-ROADMAP.md`
|
||||
1. User can set a traffic class to square, sawtooth, or triangle waveform and hear a tonally distinct sound with no audible aliasing or buzzing artifacts
|
||||
2. Sine waveform continues to produce the same output as v1.0 — no regression
|
||||
3. The synthesis bank builds layers from a passed-in config map rather than a hardcoded class list
|
||||
**Plans:** 1/2 plans executed
|
||||
**Plans:** 2/2 plans complete
|
||||
|
||||
Plans:
|
||||
- [x] 05-01-PLAN.md — Waveform types: WaveformType enum, WaveformPresetHarmonics, NewLayer resolution
|
||||
- [ ] 05-02-PLAN.md — Bank decoupling: NewBank injected config map, dynamic GainPerLayer, test updates
|
||||
- [x] 05-02-PLAN.md — Bank decoupling: NewBank injected config map, dynamic GainPerLayer, test updates
|
||||
|
||||
### Phase 6: Config Package and Sound Overrides
|
||||
**Goal**: Users can create a TOML config file to override frequency and waveform per traffic class, with auto-discovery, partial override semantics, and clear validation errors
|
||||
@@ -74,6 +74,6 @@ Plans:
|
||||
| 2. Audio Synthesis Engine | v1.0 | 3/3 | Complete | 2026-03-26 |
|
||||
| 3. Pipeline Integration and MVP | v1.0 | 2/2 | Complete | 2026-03-26 |
|
||||
| 4. Power User Features | v1.0 | 2/2 | Complete | 2026-03-26 |
|
||||
| 5. Waveform Types and Bank Decoupling | v1.1 | 1/2 | In Progress| |
|
||||
| 5. Waveform Types and Bank Decoupling | v1.1 | 2/2 | Complete | 2026-03-26 |
|
||||
| 6. Config Package and Sound Overrides | v1.1 | 0/? | Not started | - |
|
||||
| 7. Custom Rules and Print-Config | v1.1 | 0/? | Not started | - |
|
||||
|
||||
+11
-8
@@ -2,15 +2,15 @@
|
||||
gsd_state_version: 1.0
|
||||
milestone: v1.1
|
||||
milestone_name: Custom Sound Mappings
|
||||
status: executing
|
||||
stopped_at: Completed 05-01-PLAN.md
|
||||
last_updated: "2026-03-26T16:35:44.333Z"
|
||||
status: verifying
|
||||
stopped_at: Completed 05-02-PLAN.md
|
||||
last_updated: "2026-03-26T16:39:38.288Z"
|
||||
last_activity: 2026-03-26
|
||||
progress:
|
||||
total_phases: 3
|
||||
completed_phases: 0
|
||||
completed_phases: 1
|
||||
total_plans: 2
|
||||
completed_plans: 1
|
||||
completed_plans: 2
|
||||
percent: 0
|
||||
---
|
||||
|
||||
@@ -27,7 +27,7 @@ See: .planning/PROJECT.md (updated 2026-03-26)
|
||||
|
||||
Phase: 05 (waveform-types-and-bank-decoupling) — EXECUTING
|
||||
Plan: 2 of 2
|
||||
Status: Ready to execute
|
||||
Status: Phase complete — ready for verification
|
||||
Last activity: 2026-03-26
|
||||
|
||||
Progress: [░░░░░░░░░░] 0%
|
||||
@@ -51,6 +51,7 @@ Progress: [░░░░░░░░░░] 0%
|
||||
|
||||
**Recent Trend:** Stable
|
||||
| Phase 05 P01 | 3min | 2 tasks | 3 files |
|
||||
| Phase 05 P02 | 4 | 2 tasks | 4 files |
|
||||
|
||||
## Accumulated Context
|
||||
|
||||
@@ -61,6 +62,8 @@ Progress: [░░░░░░░░░░] 0%
|
||||
- [v1.1 Roadmap]: User class name collision with built-in TrafficClass strings is an unresolved design question — decide before coding Phase 7 (treat as override vs. reject as ambiguous)
|
||||
- [Phase 05]: FreqConfig struct uses named field syntax for ClassFreqConfigs entries (required by WaveformType addition)
|
||||
- [Phase 05]: WaveformType zero value is WaveformCustom — all 14 existing ClassFreqConfigs entries retain hand-tuned harmonics without modification
|
||||
- [Phase 05]: NewBank accepts injected config map instead of reading ClassFreqConfigs global — injection seam for Phase 6 config loading
|
||||
- [Phase 05]: gainPerLayer computed as 1.0/float64(len(cfgs)) — correct for any class count, no-clip guarantee preserved
|
||||
|
||||
### Pending Todos
|
||||
|
||||
@@ -72,6 +75,6 @@ None.
|
||||
|
||||
## Session Continuity
|
||||
|
||||
Last session: 2026-03-26T16:35:44.326Z
|
||||
Stopped at: Completed 05-01-PLAN.md
|
||||
Last session: 2026-03-26T16:39:38.281Z
|
||||
Stopped at: Completed 05-02-PLAN.md
|
||||
Resume file: None
|
||||
|
||||
@@ -0,0 +1,80 @@
|
||||
---
|
||||
phase: 05-waveform-types-and-bank-decoupling
|
||||
plan: "02"
|
||||
subsystem: synth
|
||||
tags: [bank, decoupling, dynamic-gain, injection-seam, refactor]
|
||||
dependency_graph:
|
||||
requires: [05-01]
|
||||
provides: [NewBank injected config map, gainPerLayer dynamic computation]
|
||||
affects: [synth/bank.go, encode/mp3.go, synth/bank_test.go, synth/config_test.go]
|
||||
tech_stack:
|
||||
added: []
|
||||
patterns: [dependency injection, dynamic gain scaling, config map injection]
|
||||
key_files:
|
||||
created: []
|
||||
modified:
|
||||
- synth/bank.go
|
||||
- encode/mp3.go
|
||||
- synth/bank_test.go
|
||||
- synth/config_test.go
|
||||
decisions:
|
||||
- "NewBank now accepts (tau float64, cfgs map[classify.TrafficClass]FreqConfig) — no global state dependency"
|
||||
- "gainPerLayer computed as 1.0/float64(len(cfgs)) so any N-class config auto-scales to avoid clipping"
|
||||
- "RenderWindow iterates b.layers directly in both loops — no classify.AllClasses() dependency"
|
||||
- "encode/mp3.go passes synth.ClassFreqConfigs as default — v1.0 behavior preserved exactly"
|
||||
metrics:
|
||||
duration: "~4 min"
|
||||
completed_date: "2026-03-26"
|
||||
tasks: 2
|
||||
files: 4
|
||||
requirements:
|
||||
- WAVE-01
|
||||
- WAVE-02
|
||||
---
|
||||
|
||||
# Phase 5 Plan 02: Bank Decoupling and Dynamic GainPerLayer Summary
|
||||
|
||||
OscillatorBank decoupled from global ClassFreqConfigs via injected config map, with gainPerLayer computed dynamically as 1/N so any class count produces correct no-clip mixing.
|
||||
|
||||
## What Was Built
|
||||
|
||||
- **`OscillatorBank.gainPerLayer float64`** field added to struct — computed at construction time as `1.0 / float64(len(cfgs))`
|
||||
- **`NewBank(tau float64, cfgs map[classify.TrafficClass]FreqConfig)`** — new two-argument signature replaces global ClassFreqConfigs dependency; iterates cfgs map directly to create layers
|
||||
- **`RenderWindow` UpdateTarget loop** — refactored from `classify.AllClasses()` iteration to `for class, layer := range b.layers`, making it work for any config map
|
||||
- **`RenderWindow` render loop** — refactored to use `b.gainPerLayer` (instance field) instead of `GainPerLayer` constant, enabling correct scaling for non-14 class counts
|
||||
- **`encode/mp3.go` call site** — updated to `synth.NewBank(1.0, synth.ClassFreqConfigs)`, preserving v1.0 behavior exactly
|
||||
- **Updated test suite** — all 7 existing `NewBank` calls updated to two-argument form; two new tests added: `TestNewBankDynamicGain` (verifies 1/3 gain for 3-class config) and `TestNewBankCustomConfigNoClip` (verifies no-clip with 2-class config)
|
||||
- **`TestNumLayersMatchesAllClasses`** updated to assert `len(synth.ClassFreqConfigs) == len(classify.AllClasses())` without depending on `synth.NumLayers`
|
||||
|
||||
## Tasks Completed
|
||||
|
||||
| Task | Description | Commit | Files |
|
||||
|------|-------------|--------|-------|
|
||||
| 1 | Decouple NewBank and fix GainPerLayer | 43307c3 | synth/bank.go, encode/mp3.go |
|
||||
| 2 | Update tests for new NewBank signature and dynamic gain | b2b5ab6 | synth/bank_test.go, synth/config_test.go |
|
||||
|
||||
## Verification
|
||||
|
||||
- `go test ./synth/... ./encode/... -v`: 44 tests, all pass (41 existing + 2 new bank tests)
|
||||
- `go test ./...`: all 6 packages pass (aggregate, capture, classify, cmd, encode, synth)
|
||||
- `go vet ./...`: clean
|
||||
- `go build ./...`: clean
|
||||
- `classify.AllClasses()` not referenced in bank.go (confirmed via grep)
|
||||
- No single-argument `NewBank(` calls remain in production or test code
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
None — plan executed exactly as written.
|
||||
|
||||
## Known Stubs
|
||||
|
||||
None — all decoupling logic is fully implemented and wired.
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- synth/bank.go: FOUND (verified by go build)
|
||||
- encode/mp3.go NewBank call updated: FOUND (synth.NewBank(1.0, synth.ClassFreqConfigs))
|
||||
- synth/bank_test.go TestNewBankDynamicGain: FOUND (verified by go test)
|
||||
- synth/bank_test.go TestNewBankCustomConfigNoClip: FOUND (verified by go test)
|
||||
- synth/config_test.go TestNumLayersMatchesAllClasses updated: FOUND
|
||||
- Commits 43307c3, b2b5ab6: both present in git log
|
||||
Reference in New Issue
Block a user