diff --git a/.planning/phases/09-frequency-design-and-group-architecture/09-CONTEXT.md b/.planning/phases/09-frequency-design-and-group-architecture/09-CONTEXT.md new file mode 100644 index 0000000..c699660 --- /dev/null +++ b/.planning/phases/09-frequency-design-and-group-architecture/09-CONTEXT.md @@ -0,0 +1,111 @@ +# Phase 9: Frequency Design and Group Architecture - Context + +**Gathered:** 2026-03-27 +**Status:** Ready for planning + + +## Phase Boundary + +Design a complete, documented frequency allocation table for all ~35 traffic classes organized into family bands with musical interval spacing. Add a `Group` string field to `FreqConfig`. This is design-only — no new TrafficClass constants or classification rules are written (that's Phase 10). + + + + +## Implementation Decisions + +### Frequency Band Layout +- **D-01:** Full rebalance — all classes (including existing 14) are redistributed into their logical family bands. Existing v1.0/v1.1 frequencies are NOT frozen. ICMP, DNS, HTTPS, etc. move to their family's band. +- **D-02:** Total built-in frequency range: 60-2000 Hz. Each family gets a contiguous sub-band within this range. Families are separated by enough space to be perceptually distinct. +- **D-03:** Within-family spacing uses musical interval ratios with at least a major second (ratio 1.122) between any two protocols in the same family (per FREQ-02). + +### Auto-Assign Range +- **D-04:** Custom class auto-assign range moves from [1200, 2350] to [2500, 4000] Hz. Update `autoAssignFreq` constants in `config/config.go`: `baseHz = 2500.0`, compute `numSteps` to cover the range with 50 Hz steps. +- **D-05:** The test in `config/config_test.go` that validates auto-assign range bounds (`[1200, 2350]`) must be updated to match the new range. + +### Group Field Design +- **D-06:** Add `Group string` field to `FreqConfig` struct. Simple string, not an enum. Values are family names: "Infrastructure", "Web", "Mail", "File Transfer", "Remote Access", "Database", "Discovery", "VoIP", "Unknown". +- **D-07:** All existing `ClassFreqConfigs` entries get a Group value assigned. Unknown buckets get Group "Unknown". + +### Waveform-per-Family Strategy +- **D-08:** Each protocol family shares a single waveform type for timbral coherence. Within-family distinction comes from Hz spacing and pan position, not waveform. +- **D-09:** Waveform-to-family assignment is at Claude's discretion. Constraint: all 4 waveform types (sine, square, sawtooth, triangle) should be used across the 8 families. Families with more than 4 groups double up on the most fitting waveform. + +### Claude's Discretion +- Specific Hz values for each class within their family band (must satisfy D-03 interval constraint) +- Which waveform type maps to which family (D-09) +- Pan position assignments for new classes +- Exact family band boundaries within the 60-2000 Hz range +- Harmonic definitions for new waveform-type entries (use `WaveformPresetHarmonics` rather than hand-tuned) +- Whether to consolidate `TestAllClassesHaveConfig` and the renamed `TestClassFreqConfigsMatchAllClasses` or leave separate + +### Folded Todos +- **"Expand Traffic Classes"** (from `.planning/todos/pending/001-expand-traffic-classes.md`) — Requests adding IMAP, POP3, SNMP, FTP and more. Phase 9 designs the frequency slots for these; Phase 10 implements the actual TrafficClass constants and rules. + + + + +## Canonical References + +**Downstream agents MUST read these before planning or implementing.** + +### Synth Package (primary modification target) +- `synth/config.go` — `FreqConfig` struct (add Group field), `ClassFreqConfigs` map (rebalance all entries), `WaveformPresetHarmonics` function +- `synth/config_test.go` — `TestFrequenciesInRange` (Nyquist-based, already future-proofed in Phase 8), `TestFrequenciesUnique`, `TestClassFreqConfigsMatchAllClasses` + +### Config Package (auto-assign update) +- `config/config.go` — `autoAssignFreq` function (lines 208-218), `addAutoFreqEntries` function (lines 225-238) +- `config/config_test.go` — Auto-assign range validation test (line 363: currently checks `[1200, 2350]`) + +### Classification (reference only — not modified in Phase 9) +- `classify/types.go` — `TrafficClass` constants, `AllClasses()` — defines what classes exist today +- `classify/rules.go` — `DefaultRules` — current port→class mapping + +### Research Context +- `.planning/research/ARCHITECTURE.md` — Frequency band design notes, group-coherent allocation strategy +- `.planning/research/PITFALLS.md` — Pitfall C4 (resolved), frequency collision risks +- `.planning/REQUIREMENTS.md` — FREQ-01..04, GRP-01, GRP-04 + + + + +## Existing Code Insights + +### Reusable Assets +- `WaveformPresetHarmonics(wt, baseHz, sampleRate)` — generates bandlimited harmonics for any waveform type at any frequency. Use this for new entries instead of hand-tuning harmonics. +- `WaveformType` enum with 4 types already defined — no new waveform types needed. + +### Established Patterns +- `ClassFreqConfigs` is a `map[classify.TrafficClass]FreqConfig` — new entries follow the same pattern +- Existing entries use hand-tuned `Harmonics` slices, but D-09 says to use `WaveformPresetHarmonics` for new entries (waveform-per-family approach) +- `autoAssignFreq` uses FNV-32a hash for deterministic mapping — same algorithm, just updated constants + +### Integration Points +- `FreqConfig` struct gains `Group string` field — all existing map literal entries must add the field value to compile +- `autoAssignFreq` constant changes in `config/config.go` affect `addAutoFreqEntries` behavior +- Phase 10 will add new `TrafficClass` constants that reference the frequency slots designed here +- Phase 11 will use the `Group` field for `--print-config` grouping + + + + +## Specific Ideas + +- The frequency allocation table should be documented in a code comment above `ClassFreqConfigs` or in a planning doc, listing every class with its Hz, waveform, group, and pan position — no class left as TBD (per success criteria 1) +- Rebalancing existing protocols means SMTP (currently 440 Hz) would move to the Mail family band alongside new IMAP/POP3 entries + + + + +## Deferred Ideas + +### Reviewed Todos (not folded) +None — the matched todo was folded as milestone context. + +None — discussion stayed within phase scope. + + + +--- + +*Phase: 09-frequency-design-and-group-architecture* +*Context gathered: 2026-03-27* diff --git a/.planning/phases/09-frequency-design-and-group-architecture/09-DISCUSSION-LOG.md b/.planning/phases/09-frequency-design-and-group-architecture/09-DISCUSSION-LOG.md new file mode 100644 index 0000000..b420fca --- /dev/null +++ b/.planning/phases/09-frequency-design-and-group-architecture/09-DISCUSSION-LOG.md @@ -0,0 +1,84 @@ +# Phase 9: Frequency Design and Group Architecture - Discussion Log + +> **Audit trail only.** Do not use as input to planning, research, or execution agents. +> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered. + +**Date:** 2026-03-27 +**Phase:** 09-frequency-design-and-group-architecture +**Areas discussed:** Frequency band layout, Auto-assign range update, Group field design, Waveform-per-family strategy + +--- + +## Frequency Band Layout + +| Option | Description | Selected | +|--------|-------------|----------| +| Freeze existing | Keep all 14 current frequencies untouched. New protocols placed above 1047 Hz. | | +| Rebalance all into families | Move existing protocols into their logical family bands. Cleaner design but changes existing Hz values. | ✓ | +| Hybrid — freeze knowns, rebalance unknowns | Keep 10 known protocols frozen, move 4 unknown buckets higher. | | + +**User's choice:** Rebalance all into families +**Notes:** User chose full rebalance despite the risk of breaking v1.1 user TOML configs with explicit Hz overrides. Clean family organization takes priority. + +### Follow-up: Frequency Range + +| Option | Description | Selected | +|--------|-------------|----------| +| 60-2000 Hz | Comfortable low-mid range. Families get ~1 octave each. | ✓ | +| 60-4000 Hz (wide spread) | More room but higher frequencies can sound thin. | | +| 100-3000 Hz (mid-focused) | Avoids bass extremes, good speaker compatibility. | | + +**User's choice:** 60-2000 Hz + +--- + +## Auto-Assign Range Update + +| Option | Description | Selected | +|--------|-------------|----------| +| 2500-4000 Hz | Clean gap above built-ins. Custom classes sound distinctly higher. | ✓ | +| 2100-3500 Hz (tight gap) | Starts just above ceiling, risk of perceptual blending. | | +| 3000-5000 Hz (far above) | Maximum separation but can sound shrill. | | + +**User's choice:** 2500-4000 Hz +**Notes:** 50 Hz steps across the range, matching the existing step algorithm. + +--- + +## Group Field Design + +| Option | Description | Selected | +|--------|-------------|----------| +| Simple string | Group string field. Easy to extend, no code changes for new groups. | ✓ | +| Typed enum (GroupType int) | Go const iota enum. Compile-time safety but rigid. | | +| String with validation | String with known-groups list. Catches typos but more complex. | | + +**User's choice:** Simple string +**Notes:** Values: Infrastructure, Web, Mail, File Transfer, Remote Access, Database, Discovery, VoIP, Unknown. + +--- + +## Waveform-per-Family Strategy + +| Option | Description | Selected | +|--------|-------------|----------| +| One waveform per family | Each family shares a waveform type for timbral coherence. | ✓ | +| Mix waveforms within families | Each protocol picks its own waveform. More variety, less family identity. | | +| You decide | Claude picks best assignment. | | + +**User's choice:** One waveform per family +**Notes:** All 4 waveform types used across 8 families. Families exceeding 4 groups share waveforms. + +--- + +## Claude's Discretion + +- Specific Hz values for each class within family bands +- Waveform-to-family mapping +- Pan position assignments +- Family band boundaries within 60-2000 Hz +- Harmonic definitions (use WaveformPresetHarmonics) + +## Deferred Ideas + +None — discussion stayed within phase scope.