2 zmienionych plików z 395 dodań i 0 usunięć
-
+211 -0ROADMAP.md
-
+184 -0STATE.md
+ 211
- 0
ROADMAP.md
Wyświetl plik
| @@ -0,0 +1,211 @@ | |||
| # 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. | |||
| --- | |||
| ## 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. | |||
+ 184
- 0
STATE.md
Wyświetl plik
| @@ -0,0 +1,184 @@ | |||
| # SDR Wideband Suite - Current State | |||
| This file is the practical handoff / resume state for future work. | |||
| Use it together with `ROADMAP.md`. | |||
| - `ROADMAP.md` = long-term architecture and phase roadmap | |||
| - `STATE.md` = current repo state, working conventions, and next recommended entry point | |||
| ## Current Milestone State | |||
| - **Phase 1 complete** | |||
| - **Phase 2 complete** | |||
| - **Phase 3 complete** | |||
| - **Phase 4 complete** | |||
| Current project state should be treated as: | |||
| - Phase 1 = architecture foundation landed | |||
| - Phase 2 = multi-resolution surveillance semantics landed | |||
| - Phase 3 = conservative runtime prioritization/admission/rebalance landed | |||
| - Phase 4 = monitor-window operating model landed | |||
| Do not reopen these phases unless there is a concrete bug, mismatch, or regression. | |||
| --- | |||
| ## Most Recent Relevant Commits | |||
| These are the most important recent milestone commits that define the current state: | |||
| ### Phase 4 monitor-window operating model | |||
| - `efe137b` Add monitor window goals for multi-span gating | |||
| - `ac64d6b` Add monitor window matches and stats | |||
| - `d7e457d` Expose monitor window summaries in runtime debug | |||
| - `c520423` Add monitor window priority bias | |||
| - `838c941` Add window-based record/decode actions | |||
| - `962cf06` Add window zone biases for record/decode actions | |||
| - `402a772` Consolidate monitor window summary in debug outputs | |||
| - `8545b62` Add per-window outcome summaries for admission pressure | |||
| - `65b9845` test: cover overlapping monitor windows | |||
| - `efe3215` docs: capture Phase-4 monitor-window status | |||
| ### Phase 3 runtime intelligence milestone | |||
| - `4ebd51d` Add priority tiers and admission classes to pipeline | |||
| - `18b179b` Expose admission metadata in debug output and tests | |||
| - `ba9adca` Add budget preference and pressure modeling | |||
| - `7a75367` Expose arbitration pressure summary | |||
| - `592fa03` pipeline: deepen hold/displacement semantics | |||
| - `30a5d11` pipeline: apply intent holds and family tier floors | |||
| - `1f5d4ab` pipeline: add intent and family priority tests | |||
| - `822829c` Add conservative budget rebalance layer | |||
| - `da5fa22` Update Phase-3 Wave 3E status | |||
| ### Documentation / stable defaults | |||
| - `fd718d5` docs: finalize phase milestones and ukf test config | |||
| If resuming after a long pause, inspect the current `git log` around these commits first. | |||
| --- | |||
| ## Current Important Files / Subsystems | |||
| ### Long-term guidance | |||
| - `ROADMAP.md` - durable roadmap across phases | |||
| - `STATE.md` - practical resume/handoff state | |||
| - `PLAN.md` - project plan / narrative (may be less pristine than ROADMAP.md) | |||
| - `README.md` - user-facing/current feature status | |||
| ### Config / runtime surface | |||
| - `config.yaml` - current committed default config | |||
| - `config.autosave.yaml` - local autosave; intentionally not tracked in git | |||
| - `internal/config/config.go` | |||
| - `internal/runtime/runtime.go` | |||
| ### Phase 3 core runtime intelligence | |||
| - `internal/pipeline/arbiter.go` | |||
| - `internal/pipeline/arbitration.go` | |||
| - `internal/pipeline/arbitration_state.go` | |||
| - `internal/pipeline/priority.go` | |||
| - `internal/pipeline/budget.go` | |||
| - `internal/pipeline/pressure.go` | |||
| - `internal/pipeline/rebalance.go` | |||
| - `internal/pipeline/decision_queue.go` | |||
| ### Phase 2 surveillance/evidence model | |||
| - `internal/pipeline/types.go` | |||
| - `internal/pipeline/evidence.go` | |||
| - `internal/pipeline/candidate_fusion.go` | |||
| - `internal/pipeline/scheduler.go` | |||
| - `cmd/sdrd/pipeline_runtime.go` | |||
| ### Phase 4 monitor-window model | |||
| - `internal/pipeline/monitor_rules.go` | |||
| - `cmd/sdrd/window_summary.go` | |||
| - `cmd/sdrd/level_summary.go` | |||
| - `cmd/sdrd/http_handlers.go` | |||
| - `cmd/sdrd/decision_compact.go` | |||
| - `cmd/sdrd/dsp_loop.go` | |||
| --- | |||
| ## Current Default Operator / Test Posture | |||
| The repo was intentionally switched to an FM/UKW-friendly default test posture. | |||
| ### Current committed config defaults | |||
| - band: `87.5-108.0 MHz` | |||
| - center: `99.5 MHz` | |||
| - sample rate: `2.048 MHz` | |||
| - FFT: `4096` | |||
| - profile: `wideband-balanced` | |||
| - intent: `broadcast-monitoring` | |||
| - priorities include `wfm`, `rds`, `broadcast`, `digital` | |||
| ### Important config note | |||
| - `config.yaml` is committed and intended as the stable default reference | |||
| - `config.autosave.yaml` is **not** git-tracked and may diverge locally | |||
| - if behavior seems odd, compare the active runtime config against `config.yaml` | |||
| --- | |||
| ## Working Conventions That Matter | |||
| ### Codex invocation on Windows | |||
| Preferred stable flow: | |||
| 1. write prompt to `codex_prompt.txt` | |||
| 2. create/use `run_codex.ps1` containing: | |||
| - read prompt file | |||
| - pipe to `codex exec --yolo` | |||
| 3. run with PTY/background from the repo root | |||
| 4. remove `codex_prompt.txt` and `run_codex.ps1` after the run | |||
| This was adopted specifically to avoid PowerShell quoting failures. | |||
| ### Expectations for coding runs | |||
| - before every commit: `go test ./...` and `go build ./cmd/sdrd` | |||
| - commit in coherent blocks with clear messages | |||
| - push after successful validation | |||
| - avoid reopening already-closed phase work without a concrete reason | |||
| --- | |||
| ## Known Practical Caveats | |||
| - `PLAN.md` has had encoding/character issues in some reads; treat `ROADMAP.md` + `STATE.md` as the cleaner authoritative continuity docs. | |||
| - README is generally useful, but `ROADMAP.md`/`STATE.md` are better for architectural continuity. | |||
| - `config.autosave.yaml` can become misleading because it is local/autosaved and not tracked. | |||
| --- | |||
| ## Recommended Next Entry Point | |||
| If resuming technical work after this checkpoint: | |||
| ### Start with **Phase 5** | |||
| Do **not** reopen Phase 1-4 unless there is a concrete bug or regression. | |||
| ### Recommended Phase 5 direction | |||
| Move from monitor windows inside a single capture span toward richer span / operating orchestration: | |||
| - span / zone groups | |||
| - span-aware resource allocation | |||
| - stronger profile-driven operating modes | |||
| - retune / scan / dwell semantics where needed | |||
| ### Avoid jumping ahead prematurely to | |||
| - full adaptive QoS engine (Phase 6) | |||
| - major GPU/performance re-architecture (Phase 7) | |||
| - heavy UX/product polish (Phase 8) | |||
| Those should build on Phase 5, not bypass it. | |||
| --- | |||
| ## Resume Checklist For A Future Agent | |||
| 1. Read `ROADMAP.md` | |||
| 2. Read `STATE.md` | |||
| 3. Check current `git log` near the commits listed above | |||
| 4. Inspect `config.yaml` | |||
| 5. Confirm current repo state with: | |||
| - `go test ./...` | |||
| - `go build ./cmd/sdrd` | |||
| 6. Then start Phase 5 planning from the actual repo state | |||
| If these steps still match the repo, continuation should be seamless enough even after a hard context reset. | |||