yoloyolo/.planning/milestones/v1.2-phases/11-synthesis-and-config-layer/11-CONTEXT.md

Phase 11: Synthesis and Config Layer - Context

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

## Phase Boundary

Add ClassFreqConfigs entries for all 18 new classes in AllClasses() plus 3 LDAP/Kerberos/Syslog classes (adding them to AllClasses() too). Update PrintConfig to output classes grouped by family with section header comments. Add [groups] TOML config support for users to reassign protocols to different sound families. Fix all broken synth/config tests.

## Implementation Decisions

ClassFreqConfigs Entries

• D-01: Add ClassFreqConfigs entries for all 18 new classes currently in AllClasses(). Use Hz values, waveforms, pans, and groups from the Phase 9 frequency allocation table comment in synth/config.go lines 74-110. Use WaveformPresetHarmonics() for all new entries (not hand-tuned harmonics).
• D-02: Add ClassLDAP, ClassKerberos, ClassSyslog to AllClasses() in classify/types.go. Create ClassFreqConfigs entries for them using autoAssignFreq-derived Hz values (FNV hash in [2500, 4000] Hz range). Their group is "Infrastructure", waveform is Triangle (matching the Infrastructure family pattern).
• D-03: After D-01 and D-02, AllClasses() returns 35 entries (32 + 3). TestAllClassesCount updated to 35.

PrintConfig Group Headers (GRP-02)

• D-04: PrintConfig groups classes by their Group field value. Each group gets a comment header line: # <Group> followed by a blank line, then all classes in that group. Groups are ordered: Infrastructure, Web, Mail, Remote Access, File Transfer, Database, Discovery, VoIP, Unknown.
• D-05: Within each group, classes are ordered by ascending BaseHz (matching the frequency allocation table order).
• D-06: User-defined classes (not in AllClasses but in FreqCfgs) are emitted after all built-in groups under a "# User-defined" section header.

TOML Groups Config (GRP-03)

• D-07: Users define group reassignments in TOML with a [groups] table using simple key-value pairs: IMAP = "Web" reassigns IMAP from Mail to Web group. The key is the TrafficClass string value, the value is the target group name.
• D-08: Group reassignment only affects --print-config output grouping and the Group field in FreqConfig. It does NOT change frequency, waveform, or pan — those stay as designed. PrintConfig reflects the reassignment.
• D-09: Unknown group names in [groups] config are accepted (user can invent custom group names). Unknown class names produce a warning (same pattern as [sounds.X] with unknown class).

Claude's Discretion

• Exact Hz values for LDAP, Kerberos, Syslog (computed from autoAssignFreq FNV hash)
• Pan positions for LDAP, Kerberos, Syslog
• Test structure for new ClassFreqConfigs entries and PrintConfig group output
• Whether to add [groups] to rawConfig struct as map[string]string or a custom type
• How to handle group reassignment in the merge/load pipeline

Folded Todos

• "Expand Traffic Classes" (from .planning/todos/pending/001-expand-traffic-classes.md) — Phase 11 completes the synthesis side of this request. Constants/rules were added in Phase 10; now all classes get sound configurations.

<canonical_refs>

Canonical References

Downstream agents MUST read these before planning or implementing.

Synth Package (primary modification target)

• synth/config.go — ClassFreqConfigs map (add 21 new entries), frequency allocation table comment (lines 74-110), FreqConfig struct, WaveformPresetHarmonics function
• synth/config_test.go — TestAllClassesHaveConfig, TestClassFreqConfigsMatchAllClasses, TestFrequenciesInRange, TestFrequenciesUnique, TestNewBankHas14Layers

Config Package (PrintConfig + groups)

• config/config.go — PrintConfig function (lines 270-336), rawConfig struct (line 38-41), LoadResult struct, merge function, autoAssignFreq function, addAutoFreqEntries
• config/config_test.go — TestLoadAllDefaultsPresent, TestPrintConfigOutput

Classification Package (AllClasses update)

• classify/types.go — AllClasses() function, TrafficClass constants (add LDAP/Kerberos/Syslog to AllClasses())
• classify/classifier_test.go — TestAllClassesCount (update from 32 to 35)

Requirements

• .planning/REQUIREMENTS.md — GRP-02, GRP-03
• .planning/ROADMAP.md — Phase 11 success criteria

Prior Phase Context

• .planning/phases/09-frequency-design-and-group-architecture/09-CONTEXT.md — Frequency design decisions, waveform-per-family strategy
• .planning/phases/10-classification-layer/10-CONTEXT.md — PROTO-08 frequency strategy (D-01: autoAssignFreq for LDAP/Kerberos/Syslog)

</canonical_refs>

<code_context>

Existing Code Insights

Reusable Assets

• WaveformPresetHarmonics(wt, baseHz, sampleRate) — generates harmonics for any waveform at any frequency; use for all 21 new ClassFreqConfigs entries
• autoAssignFreq(className) — FNV hash into [2500, 4000] Hz; use for LDAP/Kerberos/Syslog Hz values
• classAnnotation(cls, cfg, autoClasses) — already handles "default", "override", "auto-assigned" annotations
• copyDefaults() and merge() — existing config merge pipeline to extend with group support

Established Patterns

• ClassFreqConfigs entries follow: classify.ClassX: {BaseHz, WaveformType, Harmonics: WaveformPresetHarmonics(...), Pan, Group} pattern
• PrintConfig iterates AllClasses() for built-ins, then sorts user-defined separately
• rawConfig uses TOML struct tags for decoding; adding [groups] follows same pattern
• SoundOverride uses pointer fields for partial overrides

Integration Points

• config.Load() returns LoadResult with FreqCfgs map — group reassignments must be applied before returning
• PrintConfig reads FreqCfgs and AllClasses() — group headers derived from FreqConfig.Group field
• NewBank() in synth/bank.go creates layers from ClassFreqConfigs — all new entries will get synthesis layers automatically
• TestNewBankHas14Layers in synth/bank_test.go — name is stale, needs update to reflect 35 classes

</code_context>

## Specific Ideas

• The frequency allocation table comment in synth/config.go (lines 74-110) is the authoritative source for all Hz, waveform, group, and pan values for the 18 table-designed classes
• LDAP/Kerberos/Syslog get Infrastructure group + Triangle waveform (matching existing Infrastructure family) but their Hz comes from autoAssignFreq, not the table
• PrintConfig currently has no group awareness — it just lists all classes in AllClasses() order. The refactor adds group-based iteration with comment headers
• go test ./... must pass fully after Phase 11 — this is the first time since Phase 10 that the full test suite should be green

## Deferred Ideas

None — discussion stayed within phase scope.

---

Phase: 11-synthesis-and-config-layer Context gathered: 2026-03-27