Lumotia/docs/issues/run-live-session-monolith.md

RB-04 MAJOR: run_live_session is a 200+ line multi-responsibility monolith

Severity: MAJOR Path: src-tauri/src/commands/live.rs:349-579 Source: 2026-04-22 code review Labels: release-blocker, major, refactor, concurrency Status: RESOLVED (2026-04-22)

Resolution

run_live_session was split around two explicit state holders:

• ActiveCapture owns the cpal stream handle, audio receiver, and optional runtime-error channel.
• LiveLoopState owns the mutable per-session loop state: resampler, capture buffer, WAV writer, buffer offsets, dropped-audio accounting, in-flight inference task, and duplicate-history buffer.

The top-level worker is now LiveSessionRuntime, with focused methods for:

• polling in-flight inference
• draining microphone runtime warnings
• receiving + resampling an audio chunk
• dropping pending-buffer overflow
• flushing the resampler tail when stop is requested
• dispatching inference when enough audio is buffered
• draining the last in-flight task
• finalising the progressive WAV writer

This keeps behaviour intact but removes the "everything in one mutable loop" shape that made concurrency review hard. The refactor also made RB-01 straightforward enough to land immediately afterward.

Problem

run_live_session owns mic startup, runtime error draining, resampling, progressive WAV persistence, overload dropping, inference scheduling, and shutdown/finalisation in one 200-line function. The state machine is spread across mutable locals — hard to audit, hard to reason about under concurrency, and already contributing to lifecycle bugs nearby (RB-01, RB-05, RB-06).

Acceptance

• Split into focused types / functions: capture setup, streaming state, inference scheduler, WAV writer lifecycle, shutdown handler.
• Each function ≤ 30 lines, single responsibility.
• State machine explicit — not implicit in the interleaved mutable locals.
• Lock discipline documented: what must be held when, across what await boundaries.
• Existing behaviour preserved — 193 workspace lib tests still green; manual dogfood smoke test of a 30-second live dictation.

Fix scope

Large. Probably one dedicated session.

Dependencies

• Unblocks: RB-01 (live session race fix becomes tractable once the state machine is small).
• Related: RB-05, RB-06 (both lifecycle bugs in the same function).