docs(09): capture phase context
This commit is contained in:
@@ -0,0 +1,111 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user