sdr-wideband-suite/ROADMAP.md

SDR Wideband Suite - Persisted Roadmap

This file is the durable architectural roadmap and phase memory for the project. It exists so a context reset, model switch, or new coding agent can continue from the real project state without reconstructing the entire plan from chat history.

Current Project Status

The project has progressed through four major milestones:

• Phase 1 complete: architecture foundation
• Phase 2 complete: multi-resolution surveillance semantics
• Phase 3 complete: conservative runtime prioritization / admission / rebalance intelligence
• Phase 4 complete: monitor-window operating model

This roadmap reflects the actual code state as of the latest landed Phase-4 work.

---

Phase 1 - Architecture Foundation (Complete)

Intent

Turn the original SDR visualizer into a scalable, policy-driven wideband SDR engine.

Delivered

• explicit config model for pipeline, surveillance, refinement, resources, profiles
• separation of surveillance / refinement / presentation concerns
• explicit candidate / refinement model
• centralized arbitration / admission surface for refinement / record / decode
• budget / hold / queue scaffolding
• profile and policy surface established

Meaning

Phase 1 established the architecture so later scaling would not require another ground-up rewrite.

---

Phase 2 - Multi-Resolution Surveillance Semantics (Complete)

Intent

Make surveillance genuinely multi-level and connect those levels to candidate behavior.

Delivered

• operational surveillance level sets
• derived / decimated surveillance spectra
• primary / derived / support / presentation level roles
• derived detection governance
• candidate evidence model across levels
• primary/derived fusion
• level-aware refinement scoring
• debug/API visibility for surveillance levels and evidence

Meaning

Phase 2 moved the system from a single-spectrum mentality toward a real multi-resolution surveillance engine.

---

Phase 3 - Runtime Prioritization / Admission / Rebalance (Complete)

Intent

Move from architecture + heuristics to conservative runtime intelligence.

Delivered

• priority tiers and admission classes
• richer reason taxonomy across refinement / record / decode
• budget preference and effective budget semantics
• pressure summaries
• hold / protection / opportunistic displacement semantics
• intent-aware hold behavior
• family-aware tier floors
• conservative adaptive cross-resource rebalance
• debug/API visibility for admission / pressure / rebalance state

Meaning

Phase 3 created a real runtime decision layer rather than just a scoring layer. It is intentionally conservative, explainable, and incremental rather than a full adaptive scheduler.

---

Phase 4 - Monitor-Window Operating Model (Complete)

Intent

Turn monitor windows from simple goal/gating objects into operational monitoring zones inside a capture span.

Delivered

• monitor_windows in config/goals/policy/runtime
• monitor-window candidate gating
• per-window candidate attribution
• per-window stats
• monitor-window priority bias
• window-based record/decode actions
• lightweight zone hints:
  • focus
  • record
  • decode
  • background
• consolidated window_summary
• per-window pressure / outcome summaries
• overlap and zone/action tests
• debug/API visibility for monitor-window behavior

Meaning

Phase 4 delivered a practical operating model for multiple monitoring zones within a single capture span, without requiring full hardware multi-span orchestration.

---

Next Planned Phases

Phase 5 - Span / Operating-Orchestration

Core idea

Move from monitor windows inside one capture span to richer orchestration across operational spans / span groups / monitoring areas.

Target outcomes

• explicit span / zone groups
• span-aware resource allocation
• stronger profile-driven operating modes
• retune / dwell / revisit semantics where hardware or mode requires it
• more operational behavior across multiple monitoring regions, not just one captured span

Likely sub-areas

• span orchestration model
• span-aware resource allocation
• profile-driven operating modes
• retune / scan / dwell semantics

Important note

Phase 5 should still avoid unnecessary premature hardware-specific complexity, but it is the logical next step after the monitor-window model.

---

Future Architecture Note - Observation/Track Reconciliation

A likely later improvement is an explicit reconciliation layer between:

• raw surveillance observations / candidates
• stable tracked signals / identities

This is intentionally NOT the first fix for live-audio regressions. For now, stable-ID-carrying signal sources should be used for stream/session-sensitive paths. If needed later, a dedicated observation-to-track reconciliation layer can be introduced as its own architecture block.

Phase 6 - Adaptive QoS / Scheduler Intelligence

Core idea

Make the engine more adaptive under changing load and signal density.

Target outcomes

• deeper QoS model
• adaptive runtime rebalance beyond the conservative Phase-3 layer
• richer priority ecology (decay, revisit, persistence, overload behavior)
• broader operating-state behavior under calm / dense / overload conditions

Important note

This should build on the operational structures from Phase 5 rather than bypass them.

---

Phase 7 - Performance / Scale / Hardware Depth

Core idea

Turn the architecture into a genuinely high-bandwidth, high-throughput system.

Target outcomes

• GPU spectral pyramid / multi-resolution acceleration
• better batching / buffering / async processing
• larger stable operating bandwidths
• profiling / benchmark / regression discipline for throughput

Important note

Performance work should follow the behavioral model, not lead it.

---

Phase 8 - Productization / Operator Workflow / Polish

Core idea

Turn the powerful engine into a polished operator product.

Target outcomes

• better UX and status visibility
• reusable monitoring plans / templates
• export / review / workflow polish
• safer and clearer autonomous behavior
• polished docs, defaults, and examples

---

Practical Continuation Guidance

If a future agent resumes work, the recommended order is:

1. Start with Phase 5, not Phase 6/7/8.
2. Treat Phases 1-4 as completed milestones.
3. Avoid reopening already-closed phase work unless there is a concrete bug or mismatch.
4. Before starting a new major block, inspect the current repo state and confirm the roadmap still matches the code.
5. Prefer milestone-sized coherent blocks over broad speculative redesigns.

---

Current Default Testing / Operator Context

A valid FM/UKW-oriented test config was intentionally introduced for easier local testing. Current default direction:

• FM broadcast band (87.5-108 MHz)
• centered around 99.5 MHz
• wideband-balanced
• broadcast-monitoring
• WFM/RDS-friendly priorities

If that changes later, update this file when the default operator/testing posture changes materially.

---

Why this file exists

This file is meant to survive:

• context resets
• model changes
• agent swaps
• long pauses in development

It should be kept updated whenever a phase is meaningfully completed or the roadmap changes materially.