Se han modificado 2 ficheros con 395 adiciones y 0 borrados
Unificar vista
Opciones de diferencias
-
+211 -0ROADMAP.md
-
+184 -0STATE.md
+ 211
- 0
ROADMAP.md
Ver fichero
| @@ -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
Ver fichero
| @@ -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. | |||||