ralph_workflow/reducer/
mod.rs

1//! Reducer-based pipeline architecture.
2//!
3//! This module implements the event-sourced reducer architecture from RFC-004.
4//! It provides:
5//! - Pure state reduction with explicit event transitions
6//! - Immutable pipeline state that doubles as checkpoint
7//! - Event log for debugging and replay
8//! - Effect handlers for side effects (git operations, agent execution)
9//!
10//! # Architecture
11//!
12//! ```
13//! ┌──────────────────────────────────────────────────┐
14//! │                     Pipeline State                        │
15//! │  (immutable: phase, iteration, agent_chain, history)     │
16//! └──────────────────────────────────────────────────┘
17//!                           │
18//!                           ▼
19//! ┌──────────────────────────────────────────────────┐
20//! │                        Reducer                            │
21//! │       fn reduce(state: State, event: Event) -> State     │
22//! │                   [Pure, no side effects]                │
23//! └──────────────────────────────────────────────────┘
24//!                           ▲
25//!                           │
26//! ┌──────────────────────────────────────────────────┐
27//! │                        Events                             │
28//! │  DevelopmentIterationCompleted | AgentFailed |           │
29//! │  ReviewPassCompleted | RebaseSucceeded | ...             │
30//! └──────────────────────────────────────────────────┘
31//!                           ▲
32//!                           │
33//! ┌──────────────────────────────────────────────────┐
34//! │                   Effect Handlers                         │
35//! │  (Agent execution, file I/O, git operations)             │
36//! │       [Side effects isolated here]                       │
37//! └──────────────────────────────────────────────────┘
38//! ```
39//!
40//! # Quick Start
41//!
42//! Run pipeline with reducer:
43//!
44//! ```ignore
45//! use ralph_workflow::reducer::{run_event_loop, PipelineState};
46//!
47//! let state = PipelineState::initial(developer_iters, reviewer_reviews);
48//! let result = run_event_loop(&mut phase_ctx, Some(state), Default::default())?;
49//! ```
50//!
51//! # State Inspection
52//!
53//! Inspect pipeline state at any point:
54//!
55//! ```ignore
56//! println!("Current phase: {}", state.phase);
57//! println!("Iteration: {}/{}", state.iteration, state.total_iterations);
58//! println!("Current agent: {:?}", state.agent_chain.current_agent());
59//! ```
60//!
61//! # Event Replay
62//!
63//! Replay events from log:
64//!
65//! ```ignore
66//! let final_state = events.into_iter()
67//!     .fold(initial_state, |s, e| reduce(s, e));
68//! ```
69//!
70//! # Testing Strategy
71//!
72//! The reducer architecture is designed for extensive testability:
73//!
74//! ## Unit Tests
75//!
76//! - **Pure reducer**: `reduce()` function has no side effects, 100% testable
77//! - **State transitions**: Each event → state transition tested in state_reduction.rs tests
78//! - **Agent chain**: Fallback logic tested via AgentChainState methods
79//! - **Error classification**: All error kinds tested in fault_tolerant_executor.rs
80//!
81//! ## Integration Tests
82//!
83//! - **State machine**: Real pipeline execution verifies correct phase transitions
84//! - **Event replay**: Event logs can reproduce final state deterministically
85//!
86//! # Testing Reducer Purity
87//!
88//! Reducer is easy to test - pure function with no side effects:
89//!
90//! ```ignore
91//! #[test]
92//! fn test_agent_fallback() {
93//!     let state = create_test_state();
94//!     let event = PipelineEvent::AgentInvocationFailed { ... };
95//!     let new_state = reduce(state, event);
96//!     assert_eq!(new_state.agent_chain.current_agent_index, 1);
97//! }
98//! ```
99//!
100//! # Running Tests
101//!
102//! ```bash
103//! # Unit tests only
104//! cargo test -p ralph-workflow --lib --all-features
105//!
106//! # Integration tests
107//! cargo test -p ralph-workflow-tests --all-targets
108//!
109//! # With coverage
110//! cargo test -p ralph-workflow --lib --all-features -- --nocapture
111//! ```
112
113pub mod effect;
114pub mod event;
115pub mod fault_tolerant_executor;
116pub mod handler;
117pub mod migration;
118#[cfg(any(test, feature = "test-utils"))]
119pub mod mock_effect_handler;
120pub mod orchestration;
121pub mod state;
122pub mod state_reduction;
123
124#[cfg(test)]
125mod orchestration_tests;
126
127#[cfg(test)]
128mod tests;
129
130pub use effect::EffectHandler;
131pub use event::PipelineEvent;
132pub use handler::MainEffectHandler;
133pub use orchestration::determine_next_effect;
134pub use state::PipelineState;
135pub use state_reduction::reduce;
136
137// Re-export CheckpointTrigger for external use
138pub use event::CheckpointTrigger;
ralph_workflow/reducer/mod.rs

ralph_workflow/reducer/
mod.rs
