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*
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user