From 4c8e2d9bcbedfec04fc4dbff3d349df811af2d8b Mon Sep 17 00:00:00 2001
From: Jan Svabenik <jan@svabi.ch>
Date: Sat, 21 Mar 2026 18:44:40 +0100
Subject: [PATCH] docs: add refinement span config and validation

---
 README.md                      |  1 +
 config.yaml                    |  2 ++
 internal/config/config.go      |  3 +++
 internal/config/config_test.go | 10 ++++++++++
 4 files changed, 16 insertions(+)

diff --git a/README.md b/README.md
index fdce0cb..969d64e 100644
--- a/README.md
+++ b/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
diff --git a/config.yaml b/config.yaml
index b7d94aa..e560eb8 100644
--- a/config.yaml
+++ b/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
diff --git a/internal/config/config.go b/internal/config/config.go
index dc14fb7..c77e25f 100644
--- a/internal/config/config.go
+++ b/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
 	}
diff --git a/internal/config/config_test.go b/internal/config/config_test.go
index 0218fe1..97bb592 100644
--- a/internal/config/config_test.go
+++ b/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)
+	}
+}