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

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

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