Refactor oversized harness files (starting with check_model.py) and add repo-wide size guardrails

[SystemicVoid]

Context

parakeet-stt-daemon/check_model.py has grown into a large mixed-responsibility file. We should defer structural refactor until current worktree efforts are complete, but capture this as planned technical debt.

Problem

• check_model.py currently mixes CLI parsing, benchmark case loading, runtime execution (offline + stream-seal), metrics, gating, baseline IO, and reporting.
• This raises maintenance risk and slows safe changes.
• We do not currently enforce broad checks to catch other files crossing practical complexity/size thresholds.

Goal

Refactor the benchmark harness into smaller modules with no behavior regressions, and add repo-wide checks to surface oversized files early.

Scope (later, not now)

1. Split check_model.py into focused modules (suggested):
   • benchmark/io.py (manifest/transcripts loading)
   • benchmark/metrics.py (WER/token/punctuation/thresholds)
   • benchmark/runtime.py (offline + stream-seal execution)
   • benchmark/reporting.py (JSON payload/baseline IO)
   • Keep check_model.py as thin CLI entrypoint.
2. Add compatibility coverage so existing just eval and check_model.py CLI usage remain unchanged.
3. Add broader checks to detect large/complex files across repo:
   • Size threshold check (lines per file), initially warn-only.
   • Optional complexity indicators (function length/cyclomatic) where practical.
   • Integrate in local quality flow (prek) and/or CI as non-blocking first.
4. Document policy and thresholds in harness docs.

Acceptance Criteria

• Behavior parity verified by existing benchmark harness tests plus added regression tests for refactor boundaries.
• just eval flows remain stable (offline/stream compare + baseline calibrations).
• Repo-wide size check exists and reports offenders beyond configured thresholds.
• Documentation updated with rationale and maintenance path.

Notes

This issue is intentionally deferred until active worktree changes settle.

[SystemicVoid]

Code Analysis: LOC and SRP Violations

Python Files

File	LOC	Responsibilities
check_model.py	2,111	Model inference probing, offline benchmark harness, transcript evaluation, WER scoring, command/dictation scoring, audio waveform analysis, baseline comparison
server.py	1,223	FastAPI WebSocket server, session management, audio input handling, model loading, streaming transcription, message routing, client protocol
test_overlay_event_stream.py	846	Test suite: session events, incremental transcription, failure modes, overlay emission, context windowing
test_session_cleanup.py	708	Test suite: disconnect/error handling, session abort, resource cleanup invariants
test_offline_benchmark_harness.py	555	Test suite: audio loading, profile-based benchmarking, transcript validation
build_personal_eval_candidates.py	502	Manifest generation, dataset construction
model.py	407	Model loading, device resolution, transcriber classes (ParakeetTranscriber, ParakeetStreamingSession, ParakeetStreamingTranscriber), TDT model detection
test_streaming_truth.py	330	Test suite: ground truth comparison, chunk boundary testing
audio.py	270	Microphone capture, streaming, session management
main.py	248	CLI entry point, argument parsing, settings building

Python total: ~8,206 LOC

Rust Files

File	LOC	Responsibilities
overlay_renderer.rs	4,339	Wayland overlay rendering: graphics rendering, font/text handling, animations (breathing/fade/slide), waveform visualization, glyph caching, Wayland protocol (SHM/layer shell/xdg), surface management, framebuffer operations, design system constants
main.rs	3,640	Push-to-talk client main: hotkey handling (EVDEV), LLM integration (chat completions/streaming), injection pipeline (clipboard/shortcuts/backend), overlay routing, event loop management, metrics collection, error classification, CLI parsing
injector.rs	1,707	Text injection pipeline: clipboard operations (wl-copy), route shortcut injection, backend injection, subprocess management, timeout handling, metrics tracking (clipboard_ready/route_shortcut/backend stages)
overlay_process.rs	1,254	Overlay process management: OverlayProcessManager, subprocess spawning, IPC sink, message replay, process lifecycle
hotkey.rs	1,163	Hotkey handling: EVDEV device handling, key event processing, listener management, device path discovery, input access validation
surface_focus.rs	708	Wayland surface focus tracking: focus observation, cache management, Wayland registry handling
config.rs	566	Configuration management: ClientConfig, InjectionConfig, OverlayMode, CLI argument parsing, environment variable resolution
overlay_state.rs	562	Overlay state machine: OverlayStateMachine, render phases, visibility states, transition logic
protocol.rs	380	Client-server protocol: message encoding/decoding, WebSocket communication
routing.rs	289	Text routing logic: decide_route function, target application routing

Rust total: ~15,041 LOC

Summary

• Python total: ~8,206 LOC
• Rust total: ~15,041 LOC
• Largest Python: check_model.py (2,111 LOC) - 26% of Python
• Largest Rust: overlay_renderer.rs (4,339 LOC) - 29% of Rust

Analysis date: 2026-03-08