yoloyolo/.planning/milestones/v1.2-phases/09-frequency-design-and-group-architecture/09-CONTEXT.md

# Phase 9: Frequency Design and Group Architecture - Context

**Gathered:** 2026-03-27
**Status:** Ready for planning

<domain>
## 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).

</domain>

<decisions>
## 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.

</decisions>

<canonical_refs>
## 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

</canonical_refs>

<code_context>
## 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

</code_context>

<specifics>
## 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

</specifics>

<deferred>
## Deferred Ideas

### Reviewed Todos (not folded)
None — the matched todo was folded as milestone context.

None — discussion stayed within phase scope.

</deferred>

---

*Phase: 09-frequency-design-and-group-architecture*
*Context gathered: 2026-03-27*