76 lines
2.7 KiB
Markdown
76 lines
2.7 KiB
Markdown
|
# Phase 6: Config Package and Sound Overrides - 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-26
|
||
|
|
**Phase:** 06-config-package-and-sound-overrides
|
||
|
|
**Areas discussed:** TOML structure, Config merge, Auto-discovery precedence, Error reporting
|
||
|
|
**Mode:** --auto (all areas auto-selected, recommended defaults chosen)
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## TOML Structure
|
||
|
|
|
||
|
|
| Option | Description | Selected |
|
||
|
|
|--------|-------------|----------|
|
||
|
|
| Keyed table `[sounds.<classname>]` | Natural TOML pattern, matches traffic class names | ✓ |
|
||
|
|
| Flat key-value pairs | Simpler but doesn't scale to per-class overrides | |
|
||
|
|
| Nested `[sounds.<classname>.audio]` | Unnecessary nesting depth | |
|
||
|
|
|
||
|
|
**User's choice:** [auto] Keyed table `[sounds.<classname>]` (recommended default)
|
||
|
|
**Notes:** Matches classify.TrafficClass string values directly. Supports `frequency` and `waveform` fields per class.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Config Merge Semantics
|
||
|
|
|
||
|
|
| Option | Description | Selected |
|
||
|
|
|--------|-------------|----------|
|
||
|
|
| Per-field overlay | Only specified fields override defaults (CFG-04) | ✓ |
|
||
|
|
| Full section replace | Setting any field in a class replaces all fields | |
|
||
|
|
| Deep merge with arrays | Overkill for flat config structure | |
|
||
|
|
|
||
|
|
**User's choice:** [auto] Per-field overlay (recommended default)
|
||
|
|
**Notes:** Satisfies CFG-04 requirement. User sets one field, everything else keeps defaults.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Auto-Discovery Precedence
|
||
|
|
|
||
|
|
| Option | Description | Selected |
|
||
|
|
|--------|-------------|----------|
|
||
|
|
| Local > user > flag | Most-specific wins: --config > ./netsynth.toml > ~/.config/ | ✓ |
|
||
|
|
| Flag only | Simpler but no auto-discovery (violates CFG-02) | |
|
||
|
|
| Multi-file merge | Load and merge all found configs | |
|
||
|
|
|
||
|
|
**User's choice:** [auto] Local > user-level > flag (recommended default)
|
||
|
|
**Notes:** Standard CLI convention. Only one file loaded — no multi-file merge complexity.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Error Reporting
|
||
|
|
|
||
|
|
| Option | Description | Selected |
|
||
|
|
|--------|-------------|----------|
|
||
|
|
| Fail-fast with key name + suggestion | Exit at startup, name the bad key (CFG-05) | ✓ |
|
||
|
|
| Warning and continue | Tolerant but hides mistakes | |
|
||
|
|
| Strict with no suggestions | Simpler but less helpful | |
|
||
|
|
|
||
|
|
**User's choice:** [auto] Fail-fast with key name and optional typo suggestion (recommended default)
|
||
|
|
**Notes:** Matches CFG-05 requirement. Unknown class names are warnings (not errors) to prepare for Phase 7.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Claude's Discretion
|
||
|
|
|
||
|
|
- TOML library choice
|
||
|
|
- Package organization (dedicated `config` package vs inline)
|
||
|
|
- Waveform string mapping implementation
|
||
|
|
- Edit distance for typo suggestions
|
||
|
|
|
||
|
|
## Deferred Ideas
|
||
|
|
|
||
|
|
- `--print-config` (CFG-06) — Phase 7
|
||
|
|
- Custom rules `[[rules]]` — Phase 7
|