---
phase: 03-pipeline-integration-and-mvp
plan: 01
subsystem: classify, synth
tags: [classification, type-system, hash-bucketing, audio-synthesis, tdd]
dependency_graph:
  requires: []
  provides: [14-class-type-system, hash-bucketed-unknowns, synth-config-14-layers]
  affects: [classify, synth, encode, aggregate]
tech_stack:
  added: []
  patterns: [hash-bucketing, deterministic-routing, additive-synthesis]
key_files:
  created:
    - synth/config_test.go (new test functions TestClassFreqConfigsComplete, TestNumLayersMatchesAllClasses)
  modified:
    - classify/types.go
    - classify/classifier.go
    - classify/classifier_test.go
    - synth/bank_test.go
    - synth/config.go
    - synth/config_test.go
decisions:
  - hashBucket uses (dstPort*31 + protoNum*7) % 4 for deterministic bucket assignment
  - TestHashBucketDistribution uses minimal custom rules (not DefaultRules) because DefaultRules catch-all OtherTCP/OtherUDP prevent hashBucket from ever being reached
  - Tasks 1 and 2 committed together: hashBucket stub and config.go required simultaneous update for compilation
metrics:
  duration: ~15min
  completed: 2026-03-26T12:11:30Z
  tasks_completed: 2
  files_modified: 6
---

# Phase 03 Plan 01: Extend TrafficClass to 14 Classes with Hash-Bucketed Unknowns Summary

**One-liner:** Replace single ClassUnknown with 4 hash-bucketed ClassUnknown1-4 classes (850-1100 Hz dissonant range), updating AllClasses() to 14 elements and synth config to match.

## What Was Built

Extended the traffic classification type system from 11 classes to 14 by replacing `ClassUnknown TrafficClass = "unknown"` with four deterministically-assigned unknown buckets. Unrecognized packets are now routed via `hashBucket(dstPort, protocol)` using a simple hash formula, ensuring each bucket gets a statistically even distribution of unrecognized traffic and produces a distinct dissonant drone tone.

### Key Changes

**classify/types.go:**
- Removed `ClassUnknown TrafficClass = "unknown"`
- Added `ClassUnknown1-4 TrafficClass = "unknown-[1-4]"`
- `AllClasses()` now returns 14 elements

**classify/classifier.go:**
- Replaced all `ClassUnknown` return sites with `hashBucket(dstPort, protocol)` calls
- Added `hashBucket()` function: `h := uint32(dstPort)*31 + uint32(protoNum)*7; switch h % 4`
- ARP/non-transport packets route to ClassUnknown1 (dstPort=0, protocol="" -> h=0)

**synth/config.go:**
- `NumLayers = 14` (was 11)
- `GainPerLayer = 1.0/14 ≈ 0.0714` (was ≈0.0909)
- Replaced `classify.ClassUnknown` entry (437 Hz) with 4 entries in 850-1100 Hz range:
  - ClassUnknown1: 862 Hz, pan=+0.6
  - ClassUnknown2: 920 Hz, pan=-0.6
  - ClassUnknown3: 981 Hz, pan=+0.9
  - ClassUnknown4: 1047 Hz, pan=-0.9

**Tests added/updated:**
- `classify/classifier_test.go`: TestAllClassesCount, TestHashBucketDistribution, updated TestClassifyUnknown
- `synth/bank_test.go`: Renamed TestNewBankHas14Layers (was 11), updated TestMixerNoClip for 14 classes
- `synth/config_test.go`: Added TestClassFreqConfigsComplete, TestNumLayersMatchesAllClasses; updated range check to 1100 Hz

## Commits

| Task | Commit | Description |
|------|--------|-------------|
| Tasks 1+2 | ff3ec7e | feat(03-01): extend TrafficClass to 14 classes with hash-bucketed unknowns |

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 1 - Bug] TestHashBucketDistribution required custom rules, not DefaultRules**
- **Found during:** Task 1 (RED phase verification)
- **Issue:** The plan specified `classify.NewClassifier(classify.DefaultRules)` in TestHashBucketDistribution. DefaultRules includes catch-all `{Protocol: "tcp", DstPort: 0, Class: ClassOtherTCP}` and `{Protocol: "udp", DstPort: 0, Class: ClassOtherUDP}` rules. These catch all unrecognized TCP/UDP ports before they reach `hashBucket`, so the test could never produce unknown-* classes.
- **Fix:** Changed TestHashBucketDistribution to use a `minimalRules` slice with only ICMP and HTTPS rules — no catch-all — so unmatched ports do reach hashBucket.
- **Files modified:** classify/classifier_test.go
- **Commit:** ff3ec7e

**2. [Rule 3 - Blocking] Tasks 1 and 2 implemented together**
- **Found during:** Task 1 (go vet verification)
- **Issue:** The plan's TDD structure had Task 1 write tests and Task 2 implement. However, Task 1's changes to types.go (removing ClassUnknown) immediately broke classifier.go and config.go compilation. `go vet` (Task 1's acceptance criterion) requires compilation.
- **Fix:** Implemented hashBucket and synth/config.go changes (Task 2 scope) during Task 1 to make compilation succeed. All Task 2 acceptance criteria were met simultaneously.
- **Commit:** Single commit ff3ec7e covers both tasks.

**3. [Rule 2 - Missing] TestFrequenciesInRange range expanded to 1100 Hz**
- **Found during:** Task 2
- **Issue:** Existing TestFrequenciesInRange enforced BaseHz <= 800 Hz. New unknown classes use 850-1047 Hz range, which would fail this check.
- **Fix:** Updated range to `cfg.BaseHz < 60 || cfg.BaseHz > 1100` with a comment explaining the D-05 unknown bucket range.
- **Files modified:** synth/config_test.go
- **Commit:** ff3ec7e

## Test Results

```
ok  github.com/netsynth/netsynth/classify  0.013s
ok  github.com/netsynth/netsynth/synth     0.855s
ok  github.com/netsynth/netsynth/aggregate 0.144s
ok  github.com/netsynth/netsynth/capture   0.007s
ok  github.com/netsynth/netsynth/encode    0.307s
ok  github.com/netsynth/netsynth/cmd/netsynth 0.007s
```

All 6 packages pass. No regressions.

## Known Stubs

None. All 14 classes have FreqConfig entries and the classifier routes all packet types deterministically.

## Self-Check: PASSED