Integration dashboard architecture

Lifecycle

current

Owner

Ownership decision required

Review

2026-08-18 · 6feaba98e48a2cedb4688d3d0cc9a214716a8677

Freshness

review-due

Evidence

Not an evidence record

Verified scopes

• gammaloop_api::commands::integrate::dashboard_event_loop
  crates/gammaloop-api/src/commands/integrate.rs · digest 0bdb5ccde106
  entire file
• gammalooprs::integrate::RatatuiDashboardState
  crates/gammalooprs/src/integrate/render_ratatui.rs · digest 566f096dcc09
  entire file
• gammalooprs::integrate
  crates/gammalooprs/src/integrate/mod.rs · digest 96a529380419
  entire file

Reviewed: 2026-08-18 against the current command, event-loop, renderer, and renderer-test sources

Lifecycle: Current implementation contract. The earlier implementation plan and its chronological status notes are retained separately as an archived record.

User-facing boundary

The integrate command selects ratatui by default for live interactive updates and retains tabled as the plain streaming renderer. --no-stream-updates disables in-iteration updates; --no-stream-iterations disables end-of-iteration summaries. Both renderers consume the same semantic StatusUpdate data, so choosing a terminal presentation must not change integration state, convergence, results, or persisted artifacts.

The authoritative CLI arguments and renderer controller live in the integrate command. Use the generated CLI reference for the exact flags accepted by a particular build.

Ownership and data flow

The application layer owns terminal and command concerns:

1. StreamingDisplayController decides whether updates and iteration summaries are streamed.
2. RatatuiStreamRenderer sends semantic updates and lifecycle commands to one dashboard thread.
3. RatatuiTerminal owns raw mode, the alternate screen, cursor visibility, drawing, and cleanup.
4. dashboard_event_loop handles terminal input, redraws, suspend acknowledgements, and shutdown.

The domain layer owns renderer-independent integration status and the state needed to present it. RatatuiDashboardState consumes StatusUpdate, retains bounded chart history, and renders the overview, discrete-contribution, and max-weight views. Its implementation is in the Ratatui renderer, while status assembly and renderer fixtures live in the integration module.

integration workers
  -> renderer-neutral StatusUpdate
  -> StreamingDisplayController
       -> tabled stream
       -> dashboard command channel
            -> terminal event loop
            -> RatatuiDashboardState
            -> stderr alternate screen

This boundary keeps terminal dependencies and input handling out of the numerical workers. The dashboard is a view over status snapshots, not a second integration state machine.

Signed and componentwise absolute views

The dashboard starts in the signed view. a / A switches every tab to componentwise absolute monitoring, ⟨|Re I|⟩ and ⟨|Im I|⟩, including chart history, uncertainties, discrete-bin sorting, and max-weight panels. The selected view and logical discrete bin survive tab changes, sorting, and suspend/resume. Absolute panels omit targets and target differences; ETA to ⟨I⟩ target remains the signed stopping estimate in both views.

The integration worker first sums physical cuts, counterterms, orientations, and group members at each sampled channel point, then takes componentwise absolute values. Explicit channel sums add these positive contributions before one outer-cube statistics update. The monitored quantity is neither the complex modulus nor the absolute value of the final signed channel sum. Shallow discrete monitor accumulators copy only the monitored level’s probabilities; they do not sample, adapt, copy descendants, or alter the production RNG sequence.

Terminal lifecycle and failure containment

The alternate screen is entered lazily on the first update. Before a canonical tabled summary is printed, the controller synchronously suspends the dashboard and waits until the dashboard thread has restored the terminal. Shutdown follows the same acknowledged path. With streaming enabled, a panic during integration is caught at the command boundary: the controller shuts the dashboard down through that path and returns the panic message as an ordinary command error, so the message is not lost on the alternate screen. When streaming is disabled, the original panic report remains visible and the command resumes unwinding without producing a second error report. Drop handlers attempt cleanup as a final safeguard, and the event loop disables raw mode on exit.

Ctrl-C requests integration interruption; x requests aborting the current iteration. Other keys only mutate dashboard view state: tab and slot selection, discrete-row sorting, metric visibility, chart component/history/range, statistics scope, and help. View-state actions must not mutate the scientific result.

Verification contract

The maintained checks cover command parsing, keyboard action mapping, overview/slot metrics, global versus focused statistics, chart phase and history behavior, ETA display, discrete-bin detail, max-weight formatting, and narrow terminal layouts. Changes to status fields must update both renderers and their fixtures; changes to terminal lifecycle must retain cleanup on normal shutdown, suspension, interruption, error, and panic paths.

The old plan proposed features and recorded intermediate states. It is available as the archived dashboard implementation history, but it is not an API or freshness authority.

Raised-energy integration updates

The numerical-stability panel includes the median and processed percentage for each precision. An interrupted run may write diagnostic stability and observable previews, but resume state still represents the last completed iteration. Integration workspace manifests carry an explicit version; resume and summary reject an unsupported version before decoding state. Read-only sessions use sanitized state names for their current-directory output paths.