diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..48cfcf8 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,221 @@ +# 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.