ralph_workflow/app/event_loop/mod.rs
1//! Event loop for reducer-based pipeline architecture.
2//!
3//! This module implements the main event loop that coordinates reducer,
4//! effect handlers, and orchestration logic. It provides a unified way to
5//! run the pipeline using the event-sourced architecture from RFC-004.
6//!
7//! # Non-Terminating Pipeline Architecture
8//!
9//! The pipeline is designed to be **non-terminating by default** for unattended operation.
10//! It must NEVER exit early due to internal failures, budget exhaustion, or agent errors.
11//!
12//! ## Failure Handling Flow
13//!
14//! 1. Any terminal failure (Status: Failed, budget exhausted, agent chain exhausted)
15//! transitions to `AwaitingDevFix` phase
16//! 2. `TriggerDevFixFlow` effect writes completion marker to `.agent/tmp/completion_marker`
17//! 3. Dev-fix agent is optionally dispatched for remediation attempt
18//! 4. `CompletionMarkerEmitted` event transitions to `Interrupted` phase
19//! 5. `SaveCheckpoint` effect saves state for resume
20//! 6. Event loop returns `EventLoopResult { completed: true, ... }`
21//!
22//! ## Acceptable Termination Reasons
23//!
24//! The ONLY acceptable reasons for pipeline termination are catastrophic external events:
25//! - Process termination (SIGKILL)
26//! - Machine outage / power loss
27//! - OS kill signal
28//! - Unrecoverable panic in effect handler (caught and logged)
29//!
30//! All internal errors route through the failure handling flow above.
31//!
32//! # Module Organization
33//!
34//! - `config` - Event loop configuration and initialization
35//! - `trace` - Event trace buffer and diagnostics
36//! - `error_handling` - Panic recovery and error extraction
37//! - `driver` - Main iteration loop implementing orchestrate→handle→reduce cycle
38//! - `recovery` - Defensive completion and max iterations handling
39//! - `core` - Public API and convenience functions
40
41mod cloud_progress;
42mod config;
43mod core;
44mod driver;
45mod error_handling;
46mod iteration;
47mod logging;
48mod recovery;
49mod trace;
50
51// Re-export public API
52pub use config::{EventLoopConfig, EventLoopResult, MAX_EVENT_LOOP_ITERATIONS};
53pub use core::{run_event_loop, run_event_loop_with_handler, StatefulHandler};
54
55// Re-export for internal use within app module
56pub(crate) use config::{
57 create_initial_state_with_config, overlay_checkpoint_progress_onto_base_state,
58};
59
60#[cfg(test)]
61mod tests_checkpoint;
62#[cfg(test)]
63mod tests_iteration_control;
64#[cfg(test)]
65mod tests_review_flow;
66#[cfg(test)]
67mod tests_trace_dump;