See also: ROADMAP.md

v1.6.0 — TUI Self-Monitoring Integration

Status: Planned. See plans/ui/PLAN_TUI_PART_3.md for the full design.

Release Theme This release wires the v0.20.0 self-monitoring stream tables (df_*) into the TUI, giving operators live visibility into anomaly signals, CDC buffer trends, scheduling interference, and efficiency metrics — all driven by the same incremental refresh engine. Alongside the new views, the TUI architecture is refactored: AppState is split into 8 domain-scoped sub-structs, polling becomes subscription-based (only active-view data is fetched), and CLI/TUI command logic is unified into a shared domain layer. Four backend enhancements (DF-21–DF-24) and two new CLI subcommands complete the milestone.

See plans/ui/PLAN_TUI_PART_3.md for the full architecture, feature specifications, and phased implementation plan.

Phase 1 — Architecture Foundation (T15–T16)

Item Description Effort Ref
T15 AppState domain decomposition. Split AppState into 8 domain structs: StreamTableDomain, CdcDomain, DiagnosticsDomain, MonitoringDomain, SchedulingDomain, WatermarkDomain, ConfigDomain, DogFeedingDomain. 1d PLAN_TUI_PART_3.md §T15
T15 Selective polling. DataSubscriptions::for_view() gates Phase 2 queries behind the active view; reduces wasted queries on average. 0.5d PLAN_TUI_PART_3.md §T15
T15 Poller logic extraction. Extract poller/fetchers.rs (21 fetch_*() functions) and poller/updaters.rs (21 apply_*() functions) for testability. 1d PLAN_TUI_PART_3.md §T15
T15 CLI/TUI command unification. Introduce commands/domain.rs with shared logic for refresh, pause, resume, fuse reset, repair, and gate/ungate. 0.5d PLAN_TUI_PART_3.md §T15
T16 Dog-feeding data layer. Add DogFeedingDomain state types, polling queries for all 5 df_* stream tables, fixture builders, and contract stubs. 1d PLAN_TUI_PART_3.md §T16

Phase 2 — Self-Monitoring TUI Views (T17)

Item Description Effort Ref
TUI-1 Anomaly Detection view (a key). New view showing df_anomaly_signals with severity colors, anomaly type, count, and first/last-seen timestamps. 4h PLAN_TUI_PART_3.md §TUI-1
TUI-2 Dashboard anomaly badge. Status ribbon shows active anomaly count in red when df_anomaly_signals is non-empty. 1h PLAN_TUI_PART_3.md §TUI-2
TUI-3 CDC Health sparkline column. Braille sparkline in CDC Health view showing buffer row-count trend from df_cdc_buffer_trends. 3h PLAN_TUI_PART_3.md §TUI-3
TUI-4 CDC Health spill-risk badge. ⚠ spill badge when df_cdc_buffer_trends growth rate extrapolates to a breach within 2 cycles. 1h PLAN_TUI_PART_3.md §TUI-4
TUI-5 Workers Interference sub-tab. Second tab in Workers view showing df_scheduling_interference overlap pairs. 3h PLAN_TUI_PART_3.md §TUI-5
TUI-6 Workers scheduler overhead bar. Busy-time ratio bar from scheduler_overhead() in the Workers view. 1h PLAN_TUI_PART_3.md §TUI-6
TUI-7 Dependencies Mermaid/DOT export (x key). Scrollable overlay showing explain_dag() Mermaid output; Ctrl+E writes to file. 2h PLAN_TUI_PART_3.md §TUI-7
TUI-8 Header self-monitoring status badge. df:N/M pill in the TUI header bar; turns amber on retention warning. 1h PLAN_TUI_PART_3.md §TUI-8
TUI-9 Command palette self-monitoring commands. self-monitoring enable / disable / status in palette with confirmation dialogs. 2h PLAN_TUI_PART_3.md §TUI-9
TUI-10 Detail view anomaly summary. Active anomaly count row in the Properties section of the detail overlay. 1h PLAN_TUI_PART_3.md §TUI-10
TUI-11 Refresh Log [auto] tag. Annotate rows with initiated_by = 'SELF_MONITOR' in the Refresh Log view. 1h PLAN_TUI_PART_3.md §TUI-11
TUI-12 First-launch self-monitoring toast. 10-second hint toast on first launch when self-monitoring is not set up. 1h PLAN_TUI_PART_3.md §TUI-12
TUI-13 Anomaly signals as Issues. detect_issues() maps active anomaly signals to the Issues view with category “Anomaly”. 1h PLAN_TUI_PART_3.md §TUI-13
TUI-14 self_monitor_anomaly alert styling. Cyan 🔍 icon for anomaly alert type in the Alerts view. 0.5h PLAN_TUI_PART_3.md §TUI-14
TUI-15 Dashboard snapshot tests. 5 snapshot branches: standard, wide, empty, anomalies-present, narrow. 2h PLAN_TUI_PART_3.md §TUI-15
TUI-16 Diagnostics df_efficiency_rolling panel. Aggregate speedup ratio and DIFF/FULL counts from df_efficiency_rolling. 2h PLAN_TUI_PART_3.md §TUI-16
TUI-D1 docs/TUI.md documentation update. Document Anomaly view, CDC sparklines, Workers interference tab, Mermaid export, header badge, and command palette additions. 2h PLAN_TUI_PART_3.md §T20

Phase 3 — Backend Enhancements (T18)

Item Description Effort Ref
DF-21 sla_breach_risk column in df_threshold_advice. Boolean: true when avg_diff_ms > freshness_deadline_ms. 2h PLAN_TUI_PART_3.md §DF-21
DF-22 self_monitoring_auto_apply = 'full' mode. Widen dispatch interval when df_scheduling_interference detects high overlap. 4h PLAN_TUI_PART_3.md §DF-22
DF-23 self_monitoring_status() retention warning. retention_warning column when history_retention_days is below the minimum window. 2h PLAN_TUI_PART_3.md §DF-23
DF-24 recommend_refresh_mode() reads from df_threshold_advice. Returns consistent results with the incremental view when self-monitoring is active. 3h PLAN_TUI_PART_3.md §DF-24
TEST-21 Proptest for df_threshold_advice bounds. 10,000 cases verifying [0.01, 0.80] clamping invariant. 2h PLAN_TUI_PART_3.md §TEST-21

Phase 4 — CLI Integration (T19)

Item Description Effort Ref
CLI-1 pgtrickle self-monitoring subcommand group. enable / disable / status subcommands with --format json|table|csv for status. 4h PLAN_TUI_PART_3.md §CLI-1
CLI-2 pgtrickle graph --format flag. ascii (existing) / mermaid / dot format options for the graph subcommand. 2h PLAN_TUI_PART_3.md §CLI-2

Phase 5 — Documentation & Polish (T20)

Item Description Effort Ref
DOC-21 docs/GETTING_STARTED.md Day 2 update. Document self-monitoring CLI and TUI integration for new users. 1h PLAN_TUI_PART_3.md §T20
DOC-22 docs/SQL_REFERENCE.md update. Document df_threshold_advice.sla_breach_risk column. 0.5h PLAN_TUI_PART_3.md §T20

Phase 6 — TUI/CLI Visualization Polish

TUI/CLI visualization enhancement for the self-monitoring views. Recommended from PLAN_OVERALL_ASSESSMENT.md §9.11.

Item Description Effort Ref
OP-1 DAG runtime overlay in explain_dag(). Colour nodes by p95 latency, width by rows/refresh using pgt_refresh_history. Enhances explain_dag() visualization for TUI/CLI. XS (2d) PLAN_OVERALL_ASSESSMENT.md §9.11

Implementation Phases

Phase Description Duration
T15 Architecture Foundation — AppState decomp, selective polling, poller extraction, CLI unification Days 1–3
T16 Self-Monitoring Data Layer — types, polling queries, fixtures, contract stubs Days 3–5
T17 Self-Monitoring TUI Views — all 16 TUI items, snapshot + unit tests Days 5–9
T18 Backend Enhancements — DF-21 through DF-24, proptest, upgrade SQL Days 9–12
T19 CLI Integration — pgtrickle self-monitoring, pgtrickle graph --format Days 12–13
T20 Documentation, Polish & Final Testing — docs, cross-cutting tests, coverage audit Days 13–15
T21 (OP) TUI/CLI Polish — DAG runtime overlay in explain_dag() Days 15–16 (parallel or interleaved)

v1.6.0 total: ~3–4 weeks (TUI self-monitoring integration + DAG visualization polish: architecture + 16 views + 4 backend items + 2 CLI commands + tests + docs)

Exit criteria: - [ ] T15: AppState uses 8 domain structs; all existing tests pass; just lint clean - [ ] T15: Selective polling reduces Phase 2 query count for non-subscribed views - [ ] TUI-1: Anomaly Detection view renders; severity colors correct; empty-state hint shown - [ ] TUI-2: Dashboard ribbon shows anomaly count; turns red when anomalies present - [ ] TUI-3: CDC Health sparkline column renders for all sources with trend data - [ ] TUI-4: Spill-risk badge appears when df_cdc_buffer_trends growth rate extrapolates to breach - [ ] TUI-5: Workers view has Interference sub-tab; overlap pairs render - [ ] TUI-6: Scheduler overhead bar visible in Workers view after ≥ 5 refresh cycles - [ ] TUI-7: x key on Dependencies view opens Mermaid overlay; Ctrl+E exports to file - [ ] TUI-8: Header df:N/M badge reflects active self-monitoring stream tables - [ ] TUI-9: Command palette self-monitoring enable/disable completes with confirmation - [ ] TUI-15/TUI-T1: All new snapshot tests pass; dashboard snapshots cover 5 branches - [ ] DF-21: sla_breach_risk = true when avg_diff_ms > freshness_deadline_ms - [ ] DF-22: Dispatch interval widens after synthetic interference insertion - [ ] DF-23: retention_warning column non-null when retention below minimum - [ ] DF-24: recommend_refresh_mode() consistent with df_threshold_advice when self-monitoring active - [ ] TEST-21: Proptest passes 10,000 iterations - [ ] CLI-1: pgtrickle self-monitoring enable/disable/status functional - [ ] CLI-2: pgtrickle graph --format mermaid outputs valid Mermaid - [ ] TUI-D1/DOC-21/DOC-22: Documentation updated - [ ] Extension upgrade path tested (1.5.0 → 1.6.0) - [ ] just check-version-sync passes