docs: add refinement span config and validation

README.md

@@ -70,6 +70,7 @@ Edit `config.yaml` (autosave goes to `config.autosave.yaml`).
 - `refinement.enabled` — enables explicit candidate refinement stage
 - `refinement.max_concurrent` — refinement budget hint
 - `refinement.min_candidate_snr_db` — floor for future scheduling decisions
+- `refinement.min_span_hz` / `refinement.max_span_hz` — clamp refinement window span (0 = no clamp)
 - `resources.prefer_gpu` — GPU preference hint
 - `resources.max_refinement_jobs` — processing budget hint
 - `resources.max_recording_streams` — recording/streaming budget hint

config.yaml

@@ -31,6 +31,8 @@ refinement:
   enabled: true
   max_concurrent: 8
   min_candidate_snr_db: 0
+  min_span_hz: 0
+  max_span_hz: 0
 resources:
   prefer_gpu: true
   max_refinement_jobs: 8

internal/config/config.go

@@ -359,6 +359,9 @@ func applyDefaults(cfg Config) Config {
 	if cfg.Refinement.MaxSpanHz < 0 {
 		cfg.Refinement.MaxSpanHz = 0
 	}
+	if cfg.Refinement.MaxSpanHz > 0 && cfg.Refinement.MinSpanHz > cfg.Refinement.MaxSpanHz {
+		cfg.Refinement.MaxSpanHz = cfg.Refinement.MinSpanHz
+	}
 	if cfg.Resources.MaxRefinementJobs <= 0 {
 		cfg.Resources.MaxRefinementJobs = cfg.Refinement.MaxConcurrent
 	}

internal/config/config_test.go

@@ -62,3 +62,13 @@ func TestProfileDefaultsPresent(t *testing.T) {
 		t.Fatalf("missing wideband-balanced profile")
 	}
 }
+
+func TestRefinementSpanDefaults(t *testing.T) {
+	cfg := Default()
+	cfg.Refinement.MinSpanHz = 20000
+	cfg.Refinement.MaxSpanHz = 10000
+	cfg = applyDefaults(cfg)
+	if cfg.Refinement.MaxSpanHz != cfg.Refinement.MinSpanHz {
+		t.Fatalf("expected max span to clamp to min when inverted: %+v", cfg.Refinement)
+	}
+}