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 config;
42mod core;
43mod driver;
44mod error_handling;
45mod iteration;
46mod recovery;
47mod trace;
48
49// Re-export public API
50pub use config::{EventLoopConfig, EventLoopResult, MAX_EVENT_LOOP_ITERATIONS};
51pub use core::{run_event_loop, run_event_loop_with_handler, StatefulHandler};
52
53// Re-export for internal use within app module
54pub(crate) use config::create_initial_state_with_config;
55
56#[cfg(test)]
57mod tests_checkpoint;
58#[cfg(test)]
59mod tests_iteration_control;
60#[cfg(test)]
61mod tests_review_flow;
62#[cfg(test)]
63mod tests_trace_dump;