sdr-wideband-suite/PLAN.md

SDR Wideband Suite -- Umbauplan

Zielbild

Aus sdr-visual-suite wird eine skalierbare, policy-gesteuerte Wideband-SDR-Engine.

Ziel ist:

• gleiche Grundfunktionen wie heute: Live-Spectrum, Waterfall, Events, Tracking, Classification, Live-Listen, Recording, Decoder
• aber deutlich flexibler und zukunftsfähig
• Bandbreite soll konfigurierbar skalieren: von ~2.5 MHz bis zu den Grenzen von SDR, I/O, GPU und gewähltem Modus
• spätere Nutzung soll über Konfiguration/Profiles/Policies erfolgen, nicht über Code-Umbau

Leitprinzipien

1. UI entkoppelt von Analysequalität
   • Anzeigeparameter dürfen nicht mehr direkt die Kernanalyse verschlechtern/ändern.
2. Multi-Resolution statt Ein-FFT-für-alles
   • Globaler Surveillance-Layer mittelfein
   • lokale Refinement-Layer hoch / sehr hoch aufgelöst
3. Candidate-driven Processing
   • Detectoren erzeugen Kandidaten
   • Refiner verfeinert Kandidaten lokal
   • Classifier/PLL/Decoder arbeiten auf verfeinerten Kandidaten
4. Policy-driven Operation
   • gewünschtes Verhalten über Betriebsprofile steuerbar
5. Ressourcenbewusst
   • GPU/CPU/Storage/Latency-Budgets sind Teil der Architektur

Nicht-Ziele in Phase 1

• Keine vollständige 20-80 MHz-Endlösung in einem Schritt
• Keine perfekte neue GPU-Pipeline über Nacht
• Kein Big-Bang-Delete der bisherigen Pipeline

Phase 1 baut die Architekturgrundlage, so dass spätere Skalierung ohne erneuten Komplettumbau möglich ist.

---

Zielarchitektur

1. Acquisition Layer

Verantwortung:

• IQ aus Quelle lesen
• Source-Config anwenden
• Ringbuffer/Chunking verwalten

2. Spectrum Engine

Verantwortung:

• Surveillance-Spectrum erzeugen
• später mehrere Resolution-Levels erzeugen
• UI-geeignete decimierte Views ableiten

3. Candidate Detection Layer

Verantwortung:

• breitbandig Aktivität/Kandidaten finden
• coarse estimates liefern: center/bw/snr/type-hints

4. Refinement Layer

Verantwortung:

• Kandidaten lokal höher aufgelöst nachanalysieren
• center/bw/snr stabilisieren
• IQ-/Feature-Snippets für Classifier vorbereiten

5. Classification + Decode Layer

Verantwortung:

• Signaltypen klassifizieren
• PLL / Stereo / RDS / Decoder anwenden
• hochwertige Signalmetadaten erzeugen

6. Tracking/Event Layer

Verantwortung:

• Kandidaten über Zeit stabil tracken
• Events erzeugen/schließen
• UI und Recorder mit stabilen Signalen füttern

7. Presentation Layer

Verantwortung:

• Overview Spectrum
• decimierte WS-Frames
• Detail-Views
• UI-State ohne Einfluss auf Kernanalyse

---

Phase-1-Umbau

Phase-1 Status

• Architekturgrundlage, Config-Modell und Arbitration/Admission-Surface sind umgesetzt.
• Phase 1 ist als Meilenstein abgeschlossen.

Kernpunkte

• Projektname auf sdr-wideband-suite umgestellt
• neues Konfigurationsmodell für pipeline, surveillance, refinement, resources, profiles
• Analyse klarer von Presentation getrennt
• explizites Candidate-/Refinement-Modell eingeführt
• runDSP() in klarere Schritte zerlegt
• gemeinsame Arbitration-/Budget-Sicht für refinement/record/decode zentralisiert
• initiale Betriebsprofile dokumentiert
• Tests/Build grün gehalten

---

Phase-2-Umbau

Phase-2 Status

• Phase 2 ist als Meilenstein abgeschlossen.

Gelandete Wellen

• Wave A: operative Surveillance-Level, decimated/derived spectra, Level-Set und API-Sicht
• Wave B: derived candidate pass, primary/derived fusion, candidate evidence
• Wave C: level-aware candidate semantics und konservatives evidence-aware scoring
• Wave D: detection governance, Rollen für detection/support/presentation, derived-detection policy
• Wave E: Konsolidierung von detection/support semantics, fused candidate summaries, Debug/API/Docs

Ergebnis

• echte mehrstufige Surveillance-Resolution-Grundlage
• derived detection governance und support-only Semantik
• fused candidate evidence summaries
• Level-Rollen und Debug-Sicht sind operativ sichtbar

---

Phase-3-Umbau

Phase-3 Status

• Phase 3 ist als konservativer Runtime-Intelligence-Meilenstein abgeschlossen.

Gelandete Wellen

• Wave 3A: Priority-Tiers, Admission-Classes, reichere Reason-Familien
• Wave 3B: Budget-Preferences, Effective-Budgets, Pressure-Summaries
• Wave 3C: Hold-Protection, opportunistic displacement, displaced-by-hold, harmonisierte Reason-Taxonomie
• Wave 3D: family-aware tier floors, intent-aware hold behavior, family-priority Runtime-Semantik
• Wave 3E: konservative cross-resource Rebalance für refinement/record/decode mit profil-/intent-spezifischem Schutz

Ergebnis

• refinement / record / decode sprechen eine gemeinsame Admission-/Priority-Sprache
• pressure ist sichtbar und verhaltenswirksam
• hold / protection / displacement sind erklärbar
• signal-family priorities greifen in echte Runtime-Entscheidungen ein
• conservative adaptive rebalance verschiebt Ressourcen zwischen refinement / record / decode

---

Spätere Phasen

Phase 4

• breitbandige Multi-Span-Profile
• 20-80 MHz konkrete Betriebsmodi
• adaptive Quality-of-Service
• weitere Scheduler-/Betriebsintelligenz über die konservative Phase-3-Rebalance hinaus

---

Arbeitsmodus

Umbau erfolgt autonom im Fork.

Guardrails:

• Keine Pushes vor erfolgreichen Tests/Build
• Schrittweise Migration statt Big-Bang
• Bestehende Funktionalität möglichst erhalten