# Phase 6: Config Package and Sound Overrides - Research **Researched:** 2026-03-26 **Domain:** Go TOML config loading, partial merge semantics, CLI flag wiring **Confidence:** HIGH --- ## User Constraints (from CONTEXT.md) ### Locked Decisions - **D-01:** Use keyed TOML tables `[sounds.]` for per-class overrides. Each table supports `frequency` (float64, Hz) and `waveform` (string: "sine", "square", "sawtooth", "triangle"). Class names match `classify.TrafficClass` string values (e.g., `[sounds.ICMP]`, `[sounds.HTTPS]`). - **D-02:** Top-level structure is flat — no deeply nested hierarchies. Future phases (custom rules) will add `[[rules]]` array-of-tables at the top level. - **D-03:** Per-field overlay merge — only fields explicitly set in TOML override defaults. Unspecified fields retain their built-in values. For example, setting only `frequency` for ICMP leaves its waveform and harmonics unchanged. This satisfies CFG-04 (partial override without replicating entire config). - **D-04:** Merge produces a `map[classify.TrafficClass]FreqConfig` that is passed to `synth.NewBank()` via the injection seam from Phase 5. The default map is `synth.ClassFreqConfigs`. - **D-05:** Discovery order (most-specific wins): `--config ` > `./netsynth.toml` > `~/.config/netsynth/config.toml`. If `--config` is specified and the file does not exist, exit with a clear error before capture begins (CFG-03). If no config is found via auto-discovery, proceed silently with defaults (CFG-02). - **D-06:** Only one config file is loaded — no multi-file merge. The first found in precedence order wins entirely. - **D-07:** Unknown keys cause an immediate startup error naming the unrecognized key (CFG-05). Use TOML strict decoding to detect unknown keys. Suggest the closest valid key name if edit distance is small (nice-to-have, Claude's discretion on implementation). - **D-08:** Type mismatches (e.g., `frequency = "not a number"`) produce a clear error with field name and expected type, before capture begins. - **D-09:** Unknown class names in `[sounds.]` produce a warning (not error) — this prepares for Phase 7 where user-defined class names are valid. - **D-10:** `encode.RunSynthesis` signature changes to accept the merged config map (or loads config internally). The `--config` flag is added to the Cobra root command in `cmd/netsynth/main.go`. - **D-11:** Config loading happens once at startup, before any capture begins — fail fast on all config errors. ### Claude's Discretion - TOML library choice (BurntSushi/toml vs pelletier/go-toml) — researcher should evaluate both - Whether to create a dedicated `config` package or keep loading in `cmd/netsynth` - Waveform string-to-WaveformType mapping implementation details - Edit distance algorithm for typo suggestions (or skip if complexity isn't justified) ### Deferred Ideas (OUT OF SCOPE) - `--print-config` command (CFG-06) — scoped to Phase 7 - Custom classification rules (`[[rules]]` TOML blocks) — scoped to Phase 7 - Config hot-reload — explicitly out of scope per REQUIREMENTS.md ## Phase Requirements | ID | Description | Research Support | |----|-------------|------------------| | CFG-01 | User can create a TOML config file that overrides default sound mappings | `[sounds.]` table pattern decodes into `map[string]SoundOverride`; per-field merge into `synth.ClassFreqConfigs` clone | | CFG-02 | Tool auto-discovers config from `./netsynth.toml` or `~/.config/netsynth/config.toml` (silent if absent) | `os.Stat` probe + `os.UserConfigDir()` for XDG path; `errors.Is(err, fs.ErrNotExist)` for silent miss | | CFG-03 | User can specify an explicit config path via `--config` flag (error if file missing) | Cobra `StringVar` flag; fail-fast `os.Stat` check returns error before capture begins | | CFG-04 | User can override individual values without replicating the entire default config (partial override) | Pointer fields (`*float64`, `*string`) in the TOML decode struct allow distinguishing "explicitly zero" from "not set"; overlay merge copies only non-nil fields | | CFG-05 | Unknown keys in config file produce a clear error with the typo'd key name | BurntSushi/toml `MetaData.Undecoded()` returns unmatched keys after decode; format as error message | --- ## Summary Phase 6 adds a `config` package responsible for loading a TOML config file, validating it, and merging it over the `synth.ClassFreqConfigs` default map. The merge output is a `map[classify.TrafficClass]synth.FreqConfig` that is handed to `synth.NewBank()` — the injection seam already exists from Phase 5. The core technical challenge is **partial override semantics**: a user who sets only `frequency` for ICMP must not accidentally clear its waveform. This requires the decode struct to use pointer fields (`*float64`, `*string`) so that absent keys remain `nil` at decode time. The merge loop then only copies non-nil values over the defaults. Unknown-key detection uses BurntSushi/toml v1.6.0's `MetaData.Undecoded()` method, which is reliable because it operates on the actual set of keys the parser traversed. The alternative (pelletier/go-toml v2.3.0's `DisallowUnknownFields`) is also viable but adds a dependency with a different API surface and returns human-formatted error strings rather than structured key lists — less useful for the "suggest closest valid key" nice-to-have. **Primary recommendation:** Use `github.com/BurntSushi/toml` v1.6.0. Use a dedicated `config` package. Implement partial merge with pointer fields in the TOML decode struct. ## Standard Stack ### Core | Library | Version | Purpose | Why Standard | |---------|---------|---------|--------------| | `github.com/BurntSushi/toml` | v1.6.0 | TOML parsing and MetaData for unknown-key detection | Simpler API than pelletier v2; `Undecoded()` returns structured `[]Key` (not formatted error strings); `DecodeFile()` is a one-liner; v1.6.0 published December 2025 | ### Supporting | Library | Version | Purpose | When to Use | |---------|---------|---------|-------------| | `os` (stdlib) | Go 1.24 | File existence checks, `UserConfigDir()` for XDG path | Always — no external dependency needed for discovery logic | | `errors`/`fs` (stdlib) | Go 1.24 | `errors.Is(err, fs.ErrNotExist)` for silent-miss on auto-discovery | Always | ### Alternatives Considered | Instead of | Could Use | Tradeoff | |------------|-----------|----------| | `BurntSushi/toml v1.6.0` | `pelletier/go-toml v2.3.0` | go-toml has `DisallowUnknownFields()` built-in (cleaner API) but returns `StrictMissingError` with a formatted string — harder to extract just the key name for a "did you mean?" suggestion. BurntSushi returns `[]toml.Key` which is structured. For this use case, BurntSushi is easier to work with. | | Pointer fields for partial override | Separate "is-set" booleans | Pointer fields are idiomatic in Go for "optional" semantics. Booleans add field count and are error-prone. | | Dedicated `config` package | Inline in `cmd/netsynth` | A `config` package makes the loader independently testable without a Cobra dependency. Given the complexity (validation, merge, discovery), a separate package is justified. | **Installation:** ```bash go get github.com/BurntSushi/toml@v1.6.0 ``` **Version verification (confirmed 2026-03-26):** ``` github.com/BurntSushi/toml v1.6.0 (December 18, 2025) github.com/pelletier/go-toml/v2 v2.3.0 (March 24, 2026 — alternative) ``` ## Architecture Patterns ### Recommended Project Structure ``` config/ ├── config.go # Load(), Merge(), Validate() — public API └── config_test.go # table-driven tests for all CFG requirements ``` The `config` package has one exported function signature the planner cares about: ```go // Load finds, parses, validates, and merges a config file. // configPath is the --config flag value; empty string triggers auto-discovery. // Returns the merged FreqConfig map (defaults + overrides) ready for synth.NewBank. // Returns an error on: file-not-found when --config is explicit, parse errors, // unknown keys, type mismatches. Returns no error (uses defaults) when no config // is found during auto-discovery. func Load(configPath string) (map[classify.TrafficClass]synth.FreqConfig, error) ``` ### Pattern 1: TOML Decode Struct with Pointer Fields **What:** The TOML config file maps to a Go struct where every overridable field is a pointer. `nil` means "not set by user"; non-nil means "user explicitly specified this value." **When to use:** Whenever you need to distinguish "field absent from config" from "field set to zero value" — mandatory for partial override semantics (CFG-04). ```go // Source: BurntSushi/toml documentation + partial-override pattern // config/config.go // SoundOverride holds optional per-class sound parameters from TOML. // Pointer fields: nil = not set (keep default), non-nil = user override. type SoundOverride struct { Frequency *float64 `toml:"frequency"` Waveform *string `toml:"waveform"` } // rawConfig is the top-level TOML decode target. type rawConfig struct { Sounds map[string]SoundOverride `toml:"sounds"` } ``` ### Pattern 2: Unknown-Key Detection with MetaData.Undecoded() **What:** After decoding, check `md.Undecoded()` for any keys in the TOML file that did not map to a field in the decode struct. Return an error naming the first unrecognized key. **When to use:** Required for CFG-05. Also the mechanism to detect field-level typos within a `[sounds.ICMP]` block (e.g., `frequncy` vs `frequency`). ```go // Source: pkg.go.dev/github.com/BurntSushi/toml // config/config.go func parse(path string) (rawConfig, error) { var raw rawConfig md, err := toml.DecodeFile(path, &raw) if err != nil { return raw, fmt.Errorf("config parse error: %w", err) } if undecoded := md.Undecoded(); len(undecoded) > 0 { // undecoded[0] is a toml.Key ([]string); join for human-readable path keyPath := strings.Join(undecoded[0], ".") return raw, fmt.Errorf("config: unknown key %q — check spelling", keyPath) } return raw, nil } ``` **IMPORTANT NOTE on nested map + Undecoded():** When the decode struct uses `map[string]SoundOverride` for `[sounds]`, the TOML library cannot know what map keys are "valid" — all string keys are valid map keys. This means `Undecoded()` will NOT catch a misspelled class name like `[sounds.ICMP_typo]` (it IS decoded, just into a wrong map key). However, `Undecoded()` WILL catch field-level typos within a class block like `[sounds.ICMP]` with `frequncy = 440` because `frequncy` doesn't match any `SoundOverride` field. Class-name validation is handled separately in the merge step (D-09: log a warning for unknown class names). ### Pattern 3: Per-Field Overlay Merge **What:** Iterate over the default `ClassFreqConfigs` map, copy it, then for each entry found in the TOML overrides, copy only the non-nil pointer fields into the working copy. **When to use:** This is the CFG-04 implementation. Must run after parse and validation. ```go // config/config.go func merge( defaults map[classify.TrafficClass]synth.FreqConfig, overrides map[string]SoundOverride, ) map[classify.TrafficClass]synth.FreqConfig { // Deep-copy defaults result := make(map[classify.TrafficClass]synth.FreqConfig, len(defaults)) for k, v := range defaults { result[k] = v } for className, override := range overrides { class := classify.TrafficClass(className) cfg, known := result[class] if !known { // D-09: unknown class name = warning, not error (Phase 7 may define it) fmt.Fprintf(os.Stderr, "Warning: config: unknown class %q (ignored)\n", className) continue } if override.Frequency != nil { cfg.BaseHz = *override.Frequency // When frequency changes, regenerate harmonics if a waveform preset is active if cfg.WaveformType != synth.WaveformCustom { cfg.Harmonics = synth.WaveformPresetHarmonics(cfg.WaveformType, cfg.BaseHz, synth.SampleRate) } } if override.Waveform != nil { wt, err := parseWaveform(*override.Waveform) if err != nil { // Validation catches this before merge; this is a safety guard continue } cfg.WaveformType = wt cfg.Harmonics = synth.WaveformPresetHarmonics(wt, cfg.BaseHz, synth.SampleRate) } result[class] = cfg } return result } ``` ### Pattern 4: Waveform String-to-Type Mapping **What:** A simple switch converts the TOML `waveform` string to `synth.WaveformType`. Validation happens before merge. ```go // config/config.go var validWaveforms = map[string]synth.WaveformType{ "sine": synth.WaveformSine, "square": synth.WaveformSquare, "sawtooth": synth.WaveformSawtooth, "triangle": synth.WaveformTriangle, } func parseWaveform(s string) (synth.WaveformType, error) { if wt, ok := validWaveforms[s]; ok { return wt, nil } valid := []string{"sine", "square", "sawtooth", "triangle"} return 0, fmt.Errorf("config: invalid waveform %q — valid values: %s", s, strings.Join(valid, ", ")) } ``` ### Pattern 5: Auto-Discovery with os.UserConfigDir **What:** Check paths in precedence order. Return the path of the first file found, or `""` (empty) if none found. Never log anything for a missing auto-discovered file. ```go // config/config.go func discoverPath() string { // 1. Working directory if _, err := os.Stat("netsynth.toml"); err == nil { return "netsynth.toml" } // 2. XDG config dir dir, err := os.UserConfigDir() if err != nil { return "" } p := filepath.Join(dir, "netsynth", "config.toml") if _, err := os.Stat(p); err == nil { return p } return "" } ``` `os.UserConfigDir()` returns `$XDG_CONFIG_HOME` or `$HOME/.config` on Linux (Go stdlib, no extra dependency). Confirmed by Go source: returns `$XDG_CONFIG_HOME` if set, else `$HOME/.config` on Unix. ### Pattern 6: encode.RunSynthesis Signature Change **What:** `RunSynthesis` currently calls `synth.NewBank(1.0, synth.ClassFreqConfigs)` hardcoded. Phase 6 changes the signature to accept the merged config map. The simplest approach: pass the merged config map as a parameter (rather than loading config inside `encode`). This keeps `encode` unaware of config loading and makes testing easier. ```go // encode/mp3.go — updated signature func RunSynthesis( snapshots []classify.WindowSnapshot, outputPath string, freqCfgs map[classify.TrafficClass]synth.FreqConfig, ) error { // ... bank := synth.NewBank(1.0, freqCfgs) // was: synth.ClassFreqConfigs // ... } ``` Caller in `cmd/netsynth/main.go` passes the result of `config.Load(configPath)`. ### Anti-Patterns to Avoid - **Decode into `map[string]interface{}`:** Loses type safety, makes unknown-field detection harder, requires runtime type assertions. Use typed structs. - **Load config inside `encode` package:** Couples audio encoding to config I/O; breaks test isolation. Config loading belongs in `cmd/netsynth/main.go` (calls `config.Load`) or a dedicated `config` package. - **Validate waveform strings after merge:** Validate before merging so the error is caught at startup (D-11), not silently ignored. - **Deep-copy using `=` assignment on map values:** `synth.FreqConfig` contains a `[]HarmonicDef` slice; a simple struct copy shares the underlying array. Use an explicit copy of the slice if you mutate `Harmonics` during merge. (The merge code above reconstructs harmonics from the preset, so this is safe — but important to be aware of.) ## Don't Hand-Roll | Problem | Don't Build | Use Instead | Why | |---------|-------------|-------------|-----| | TOML parsing | Custom parser | `BurntSushi/toml` v1.6.0 | TOML 1.1 compliance, error messages, datetime support, tested at scale | | Unknown-key detection | Post-parse key comparison | `md.Undecoded()` from BurntSushi | Already built into the library; handles nested paths correctly | | XDG config path | Manual `$HOME/.config` string concat | `os.UserConfigDir()` stdlib | Handles `$XDG_CONFIG_HOME` override correctly, platform-portable | **Key insight:** The partial-override merge logic is the one piece that must be written from scratch — no library does "overlay a sparse map of optional overrides over a typed defaults map." But it is ~20 lines of straightforward Go. ## Runtime State Inventory Step 2.5 SKIPPED — this is a new feature addition, not a rename/refactor/migration phase. No runtime state is being renamed or migrated. ## Common Pitfalls ### Pitfall 1: Undecoded() Does Not Catch Unknown Class Names **What goes wrong:** Developer assumes `md.Undecoded()` will catch `[sounds.ICMP_TYPO]` as an unknown key and provide CFG-05 coverage for class-name typos. **Why it happens:** `map[string]SoundOverride` decodes any string as a valid map key — the TOML parser has no way to know which class names are valid. `Undecoded()` only catches keys that don't match ANY field (struct field name, map key, or slice element). Since all map keys are valid, no class name is "undecodeable." **How to avoid:** Separate the two concerns. Field-level unknown keys (e.g., `frequncy`) ARE caught by `Undecoded()`. Class-name typos are caught in the merge step by checking whether `classify.TrafficClass(className)` exists in `synth.ClassFreqConfigs`. The CONTEXT.md decision D-09 says unknown class names produce a warning (not error) to allow for Phase 7 user-defined classes — so this is by design. **Warning signs:** Test for both: write a test with `[sounds.ICMP]` containing `frequncy = 440` (should error) AND a test with `[sounds.ICMP_TYPO]` containing `frequency = 440` (should warn, not error). ### Pitfall 2: Partial Override Accidentally Clears WaveformType **What goes wrong:** User sets only `frequency = 300` for ICMP. After merge, ICMP's `WaveformType` is reset to `WaveformCustom` because the merge loop creates a new `FreqConfig{}` instead of starting from the default. **Why it happens:** Copy-by-value from defaults is skipped, or merge starts from a zero-value struct. **How to avoid:** Always start the merge from the DEFAULT `FreqConfig` for that class. The merge loop copies `defaults[class]` first, then overlays only non-nil pointer fields. **Warning signs:** Test case: set only `frequency` for a class with `WaveformCustom` — verify waveform field is unchanged. Test case: set only `waveform` for a class — verify frequency is unchanged. ### Pitfall 3: Frequency Change Does Not Regenerate Harmonics for Preset Waveforms **What goes wrong:** User sets `frequency = 300` for HTTPS (which has `WaveformCustom` by default, so this is fine). But if a user sets `frequency = 300` for a class that was previously configured with `WaveformSine` (via an earlier config entry), the harmonics may be stale from the old frequency. **Why it happens:** `synth.WaveformPresetHarmonics` generates harmonics based on `baseHz`. If you update `BaseHz` without regenerating harmonics, the preset harmonics are anchored to the old frequency. **How to avoid:** In the merge function: when updating `Frequency`, check if `WaveformType != WaveformCustom`. If true, regenerate `Harmonics` from the new frequency. The merge example above handles this correctly. **Warning signs:** For the 14 built-in classes, all have `WaveformCustom` (hand-tuned harmonics), so this pitfall only bites if the user sets both `waveform` and `frequency` in two separate steps — or if a future phase pre-configures preset waveforms on built-ins. ### Pitfall 4: --config File-Not-Found vs Auto-Discovery Silence **What goes wrong:** When `--config /path/to/missing.toml` is specified, the code returns the same "no config found, using defaults" behavior as auto-discovery silence. **Why it happens:** `os.Stat` errors are treated uniformly regardless of how the path was obtained. **How to avoid:** In the `Load` function, branch on whether `configPath` was explicitly provided: if it was, a `fs.ErrNotExist` is a user error (return error); if it came from auto-discovery, `fs.ErrNotExist` is normal (return `nil` error, use defaults). **Warning signs:** CFG-03 acceptance criterion explicitly tests this: explicit path must error, absent auto-discovery must be silent. ### Pitfall 5: go.mod Tidy Drops TOML Dependency **What goes wrong:** `go mod tidy` is run after adding BurntSushi/toml to go.mod but before any `.go` file in the module actually imports it. Tidy removes it. **Why it happens:** `go mod tidy` removes unused dependencies. **How to avoid:** Add the import in `config/config.go` before running `go mod tidy`. ## Code Examples ### Complete config.go Skeleton ```go // Source: BurntSushi/toml docs + project pattern // config/config.go package config import ( "errors" "fmt" "io/fs" "os" "path/filepath" "strings" "github.com/BurntSushi/toml" "github.com/netsynth/netsynth/classify" "github.com/netsynth/netsynth/synth" ) type SoundOverride struct { Frequency *float64 `toml:"frequency"` Waveform *string `toml:"waveform"` } type rawConfig struct { Sounds map[string]SoundOverride `toml:"sounds"` } // Load is the single public entry point. // configPath: value of --config flag; empty = auto-discover. func Load(configPath string) (map[classify.TrafficClass]synth.FreqConfig, error) { path, explicit, err := resolvePath(configPath) if err != nil { return nil, err } if path == "" { // No config found during auto-discovery — use defaults silently (CFG-02) return copyDefaults(), nil } raw, err := parseFile(path) if err != nil { if explicit && errors.Is(err, fs.ErrNotExist) { return nil, fmt.Errorf("config file not found: %s", path) } return nil, err } if err := validate(raw); err != nil { return nil, err } return merge(copyDefaults(), raw.Sounds), nil } ``` ### Example TOML Config File ```toml # netsynth.toml — override ICMP and SSH sounds [sounds.ICMP] frequency = 80.0 waveform = "square" [sounds.SSH] frequency = 400.0 # waveform not set — SSH keeps its default waveform ``` ### Test Pattern (table-driven) ```go // config/config_test.go func TestLoadPartialOverride(t *testing.T) { // Write a temp TOML file with only frequency for ICMP tomlContent := ` [sounds.ICMP] frequency = 100.0 ` f, _ := os.CreateTemp(t.TempDir(), "*.toml") f.WriteString(tomlContent) f.Close() cfgs, err := Load(f.Name()) if err != nil { t.Fatalf("Load: %v", err) } // ICMP frequency overridden if cfgs[classify.ClassICMP].BaseHz != 100.0 { t.Errorf("ICMP BaseHz: got %v, want 100.0", cfgs[classify.ClassICMP].BaseHz) } // ICMP waveform unchanged (WaveformCustom = 0) if cfgs[classify.ClassICMP].WaveformType != synth.WaveformCustom { t.Errorf("ICMP WaveformType: got %v, want WaveformCustom", cfgs[classify.ClassICMP].WaveformType) } // DNS frequency unchanged if cfgs[classify.ClassDNS].BaseHz != synth.ClassFreqConfigs[classify.ClassDNS].BaseHz { t.Errorf("DNS BaseHz unexpectedly changed") } } func TestLoadUnknownKey(t *testing.T) { tomlContent := ` [sounds.ICMP] frequncy = 440 ` f, _ := os.CreateTemp(t.TempDir(), "*.toml") f.WriteString(tomlContent) f.Close() _, err := Load(f.Name()) if err == nil { t.Fatal("expected error for unknown key 'frequncy', got nil") } if !strings.Contains(err.Error(), "frequncy") { t.Errorf("error should name the bad key, got: %v", err) } } ``` ## State of the Art | Old Approach | Current Approach | When Changed | Impact | |--------------|------------------|--------------|--------| | `google/gopacket` | `gopacket/gopacket` v1.5.0 | 2022-2024 | N/A for this phase | | BurntSushi/toml v0.x | v1.6.0 (TOML 1.1 enabled by default) | December 2025 | TOML 1.1 compliance; API unchanged, same `Decode`/`DecodeFile` functions | | `go-audio/generator` | ARCHIVED (Feb 2026, read-only) | February 2026 | Do not use; project already avoids it | **Current versions confirmed 2026-03-26:** - `BurntSushi/toml` v1.6.0 (December 18, 2025) — TOML 1.1 default, stable API - `pelletier/go-toml/v2` v2.3.0 (March 24, 2026) — alternative if structured error needed ## Open Questions 1. **Typo suggestion for unknown keys (D-07 nice-to-have)** - What we know: BurntSushi returns `[]toml.Key` (structured), Levenshtein distance is ~15 lines of Go or `github.com/agnivade/levenshtein` (tiny, zero-dependency) - What's unclear: Is the complexity worth it for 2 valid field names per class block (`frequency`, `waveform`)? - Recommendation: Skip the external library. Implement inline: for each undecoded key, if it has edit distance ≤ 2 from any valid key name, append " (did you mean: X?)" to the error. The valid key set for field names is small and static: `["frequency", "waveform"]`. This is ~10 lines of Go. 2. **copyDefaults() — shallow vs deep copy of Harmonics slices** - What we know: `synth.FreqConfig.Harmonics` is a `[]HarmonicDef`. Go's `map[K]V` assignment copies struct values (including slice headers) but the underlying array is shared. - What's unclear: Does this matter if merge only replaces the whole slice (via `WaveformPresetHarmonics`) rather than appending to it? - Recommendation: Since the merge code assigns a freshly-generated `[]HarmonicDef` from `WaveformPresetHarmonics` (never mutates the original), shallow copy is safe. No deep copy needed. Document this in a comment for future maintainers. ## Environment Availability Step 2.6: This phase introduces one new external dependency: | Dependency | Required By | Available | Version | Fallback | |------------|------------|-----------|---------|----------| | `github.com/BurntSushi/toml` | config.Load() TOML parsing | ✓ (fetched via go get) | v1.6.0 | pelletier/go-toml v2.3.0 | | `os.UserConfigDir()` | Auto-discovery of `~/.config/netsynth/config.toml` | ✓ (Go stdlib) | Go 1.13+ | N/A — stdlib | | Go 1.24.1 toolchain | Module minimum | ✓ | 1.24.1 | N/A | | C compiler (CGo) | go-lame MP3 encoding (pre-existing) | Assumed ✓ (Phase 2+ already requires this) | — | N/A | No missing dependencies with no fallback. BurntSushi/toml confirmed fetchable from pkg.go.dev. ## Validation Architecture ### Test Framework | Property | Value | |----------|-------| | Framework | Go standard `testing` package | | Config file | None — `go test ./...` | | Quick run command | `go test ./config/...` | | Full suite command | `go test ./...` | ### Phase Requirements → Test Map | Req ID | Behavior | Test Type | Automated Command | File Exists? | |--------|----------|-----------|-------------------|-------------| | CFG-01 | TOML overrides applied to correct class | unit | `go test ./config/... -run TestLoadOverride` | Wave 0 | | CFG-02 | No config file → silent, uses defaults | unit | `go test ./config/... -run TestLoadNoConfig` | Wave 0 | | CFG-03 | `--config` explicit path → error if missing | unit | `go test ./config/... -run TestLoadExplicitMissing` | Wave 0 | | CFG-04 | Partial override: unset fields unchanged | unit | `go test ./config/... -run TestLoadPartialOverride` | Wave 0 | | CFG-05 | Unknown key → error naming the key | unit | `go test ./config/... -run TestLoadUnknownKey` | Wave 0 | | CFG-03 | `--config` flag wired in Cobra | integration | `go test ./cmd/netsynth/... -run TestConfigFlag` | Wave 0 | ### Sampling Rate - **Per task commit:** `go test ./config/... -count=1` - **Per wave merge:** `go test ./... -count=1` - **Phase gate:** Full suite green before `/gsd:verify-work` ### Wave 0 Gaps - [ ] `config/config.go` — package does not exist yet; create in Wave 1 - [ ] `config/config_test.go` — covers CFG-01 through CFG-05 - [ ] `cmd/netsynth/main_test.go` — add `TestConfigFlag` covering CFG-03 CLI integration *(Existing test infrastructure covers all other packages; only `config/` is new.)* ## Sources ### Primary (HIGH confidence) - `pkg.go.dev/github.com/BurntSushi/toml` — v1.6.0 API: `DecodeFile`, `MetaData.Undecoded()`, `[]Key` type; verified 2026-03-26 - Go stdlib `os.UserConfigDir()` — returns `$XDG_CONFIG_HOME` or `$HOME/.config` on Linux; Go 1.13+ feature - `pkg.go.dev/github.com/pelletier/go-toml/v2` — v2.3.0 `DisallowUnknownFields()` / `StrictMissingError` API; verified 2026-03-26 ### Secondary (MEDIUM confidence) - WebSearch: BurntSushi/toml Undecoded() approach verified against official GitHub source (`toml/decode.go`) - WebSearch: pelletier/go-toml v2 DisallowUnknownFields verified against official docs - WebSearch: `os.UserConfigDir` XDG compliance — confirmed returns `$XDG_CONFIG_HOME` or `$HOME/.config` on Linux per golang/go issue #29960 ### Tertiary (LOW confidence) - WebSearch: edit distance typo suggestion libraries (agnivade/levenshtein, go-edlib) — not deeply evaluated; recommendation is inline 10-line implementation to avoid dependency ## Metadata **Confidence breakdown:** - Standard stack: HIGH — versions confirmed via `go get` live fetch (v1.6.0 BurntSushi, v2.3.0 pelletier) - Architecture: HIGH — patterns derived from library documentation + existing codebase patterns - Pitfalls: HIGH — Undecoded() + map key limitation is a documented behavior; partial-override via pointer fields is an established Go idiom - TOML typo suggestion: LOW — nice-to-have from D-07; no deep investigation needed given small valid-key set **Research date:** 2026-03-26 **Valid until:** 2026-06-26 (BurntSushi/toml is stable; go-toml v2 moves faster but is not the chosen library)