diff --git a/.planning/phases/10-classification-layer/10-CONTEXT.md b/.planning/phases/10-classification-layer/10-CONTEXT.md new file mode 100644 index 0000000..73bf13c --- /dev/null +++ b/.planning/phases/10-classification-layer/10-CONTEXT.md @@ -0,0 +1,104 @@ +# Phase 10: Classification Layer - Context + +**Gathered:** 2026-03-27 +**Status:** Ready for planning + + +## Phase Boundary + +Add ~21 new TrafficClass constants and port-matching rules covering all new protocol families (Mail, File Transfer, Remote Access, Database, Discovery, VoIP, Web extension, Infrastructure extension). All existing 10 protocol classifications remain unchanged — no regression. `AllClasses()` covers all new classes and `DefaultRules` maps all new ports. + + + + +## Implementation Decisions + +### PROTO-08 Frequency Strategy +- **D-01:** LDAP, Kerberos, and Syslog get built-in TrafficClass constants and classification rules, but their synthesis frequencies are handled by `autoAssignFreq` (FNV hash in [2500, 4000] Hz) rather than designed table slots. No Phase 9 frequency table redesign needed. +- **D-02:** These 3 classes do NOT get entries in `ClassFreqConfigs` in this phase — they are treated like user-defined custom classes for frequency purposes. Phase 11 will add their `ClassFreqConfigs` entries using `autoAssignFreq`-compatible Hz values. + +### Plain vs TLS Port Handling +- **D-03:** Plaintext and TLS/secure variants of the same protocol share a single TrafficClass. Multiple ports map to the same class constant: IMAP (143) + IMAPS (993) → ClassIMAP, POP3 (110) + POP3S (995) → ClassPOP3, LDAP (389) + LDAPS (636) → ClassLDAP, SIP (5060) + SIPS (5061) → ClassSIP, FTP data (20) + FTP control (21) → ClassFTP. +- **D-04:** Exception: SMTP (port 25) and SMTP-submission (port 587) remain separate classes (ClassSMTP and ClassSMTPSub) because Phase 9 designed distinct frequency slots for them (214 Hz and 305 Hz respectively). + +### Naming Convention +- **D-05:** Follow existing uppercase convention for TrafficClass string values: "IMAP", "POP3", "RDP", "MySQL", etc. Matches existing "ICMP", "DNS", "HTTPS" pattern. SMTP-submission uses "SMTP-sub" to match the Phase 9 frequency table label. + +### Rule Ordering +- **D-06:** New port-specific rules insert before the catch-all `{tcp, 0, ClassOtherTCP}` and `{udp, 0, ClassOtherUDP}` entries. Catch-alls remain last. First-match-wins semantics preserved. + +### Claude's Discretion +- Exact ordering of new rules within the specific-port section (before catch-alls) +- Test structure — whether to extend existing TestClassify or add new test functions +- How to update `TestAllClassesCount` (hardcoded to 14) — update the count or make it dynamic +- Whether to group rules by family in `DefaultRules` with comments, or keep flat + + + + +## Canonical References + +**Downstream agents MUST read these before planning or implementing.** + +### Classification Package (primary modification target) +- `classify/types.go` — TrafficClass constants, `AllClasses()` function (currently 14 classes) +- `classify/rules.go` — `DefaultRules` slice (currently 12 rules, first-match-wins) +- `classify/classifier.go` — `Classifier.Classify()` method, `hashBucket()` function +- `classify/classifier_test.go` — Tests for all existing classes, `TestAllClassesCount` (hardcoded to 14) + +### Synth Package (reference — not modified in Phase 10) +- `synth/config.go` — Frequency allocation table comment (lines 74-110), `ClassFreqConfigs` map, `FreqConfig` struct with Group field + +### Requirements +- `.planning/REQUIREMENTS.md` — PROTO-01 through PROTO-09 +- `.planning/ROADMAP.md` — Phase 10 success criteria + +### Research +- `.planning/research/FEATURES.md` — Complete protocol list with ports, families, priorities +- `.planning/research/STACK.md` — gopacket layer availability (port-based classification confirmed for all new protocols) +- `.planning/research/PITFALLS.md` — Rule count scaling (linear scan ~12→~40), PROTO-08 gap +- `.planning/phases/09-frequency-design-and-group-architecture/09-RESEARCH.md` — Pitfall 6: PROTO-08 classes not in table + + + + +## Existing Code Insights + +### Reusable Assets +- `buildTCPPacket(t, dstPort)` and `buildUDPPacket(t, dstPort)` test helpers — reuse for all new protocol tests +- `Rule` struct with Protocol/DstPort/Class — same structure works for all new rules +- `hashBucket()` function — unchanged, still handles unmatched packets + +### Established Patterns +- TrafficClass is a `string` type with `const` declarations — add new constants following same pattern +- `AllClasses()` returns a hand-maintained slice — must be updated with all new classes +- `DefaultRules` is a `[]Rule` literal — new rules append before catch-alls +- Tests use table-driven subtests within `TestClassify` — follow same pattern for new protocols + +### Integration Points +- `AllClasses()` is used by `synth/config_test.go` `TestClassFreqConfigsMatchAllClasses` to verify every class has a FreqConfig entry — new classes added here will fail that test until Phase 11 adds their ClassFreqConfigs entries +- `TestAllClassesCount` hardcodes `14` — must be updated to new count +- Phase 11 depends on these constants existing to add ClassFreqConfigs entries + + + + +## Specific Ideas + +- The complete protocol list with ports is documented in `.planning/research/FEATURES.md` (lines 297-311) +- Phase 9 frequency table comment in `synth/config.go` (lines 74-110) shows exactly which classes are expected with their family groupings +- The `TestClassFreqConfigsMatchAllClasses` cross-check will break when new classes are added without ClassFreqConfigs entries — Phase 10 planner needs to account for this (skip or temporarily adjust the test) + + + + +## Deferred Ideas + +None — discussion stayed within phase scope. + + + +--- + +*Phase: 10-classification-layer* +*Context gathered: 2026-03-27* diff --git a/.planning/phases/10-classification-layer/10-DISCUSSION-LOG.md b/.planning/phases/10-classification-layer/10-DISCUSSION-LOG.md new file mode 100644 index 0000000..9707f76 --- /dev/null +++ b/.planning/phases/10-classification-layer/10-DISCUSSION-LOG.md @@ -0,0 +1,47 @@ +# Phase 10: Classification Layer - 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:** 10-classification-layer +**Areas discussed:** PROTO-08 frequency gap, Plain vs TLS port handling + +--- + +## PROTO-08 Frequency Gap + +| Option | Description | Selected | +|--------|-------------|----------| +| Auto-assign range (Recommended) | Let autoAssignFreq handle them (FNV hash in [2500, 4000] Hz). Built-in constants + rules, but frequencies behave like user-defined classes. Simplest, no table redesign. | ✓ | +| Extend the table | Add 3 more slots above SIP at 2449 Hz. Proper built-in ClassFreqConfigs entries. Pushes into auto-assign territory, requires range shift. | | +| Squeeze into Infrastructure band | Insert 3 slots between existing Infrastructure entries (65-133 Hz). Most musically coherent but touches Phase 9's locked design. | | + +**User's choice:** Auto-assign range (Recommended) +**Notes:** LDAP, Kerberos, Syslog get TrafficClass constants and rules but their Hz values come from autoAssignFreq rather than designed table slots. No Phase 9 table redesign needed. + +--- + +## Plain vs TLS Port Handling + +| Option | Description | Selected | +|--------|-------------|----------| +| Same class (Recommended) | IMAP 143 and IMAPS 993 both classify as ClassIMAP. Simpler, fewer classes. Exception: keep SMTP/SMTP-sub separate per Phase 9 design. | ✓ | +| Separate classes | IMAP and IMAPS are distinct TrafficClasses with distinct sounds. More granular but doubles class count and needs more frequency slots. | | +| Same class, no SMTP exception | Merge everything including SMTP + SMTP-sub into single ClassSMTP. Wastes Phase 9 SMTP-sub slot at 305 Hz. | | + +**User's choice:** Same class (Recommended) +**Notes:** Plain/TLS variants share one class. SMTP (25) and SMTP-submission (587) remain separate because Phase 9 designed distinct frequency slots for them. + +--- + +## Claude's Discretion + +- Rule ordering within specific-port section +- Test structure for new protocols +- How to update TestAllClassesCount +- Whether to group rules by family with comments + +## Deferred Ideas + +None — discussion stayed within phase scope.