Refactor Mutable State Transitions to Pure Functions

[jwilger]

Priority: 🟡 HIGH

Problem

Current implementation uses mutable state transitions (e.g., &mut self methods) which violates functional programming principles and makes testing/reasoning harder.

Expert Analysis (Rich Hickey - Functional Architecture Expert)

The LlmRequest type and similar domain objects contain mutable state transition methods that should be pure functions returning new values.

Current Anti-Pattern

impl LlmRequest {
    pub fn start(&mut self) { self.status = RequestStatus::InProgress; }
    pub fn complete(&mut self) { self.status = RequestStatus::Completed; }
    pub fn fail(&mut self) { self.status = RequestStatus::Failed; }
    pub fn cancel(&mut self) { self.status = RequestStatus::Cancelled; }
}

Recommended Pure Approach

// Pure state transition functions
pub mod request_transitions {
    use super::{LlmRequest, RequestStatus};
    
    pub fn start(request: LlmRequest) -> LlmRequest {
        LlmRequest { status: RequestStatus::InProgress, ..request }
    }
    
    pub fn complete(request: LlmRequest) -> LlmRequest {
        LlmRequest { status: RequestStatus::Completed, ..request }
    }
    
    pub fn fail(request: LlmRequest) -> LlmRequest {
        LlmRequest { status: RequestStatus::Failed, ..request }
    }
}

Areas to Refactor

• LlmRequest state transitions
• Session status updates
• TestCase state machine
• TrackedVersion mutations
• EventCore command state applications

Benefits

• Easier testing with pure functions
• Better composition of operations
• Clearer reasoning about state changes
• Immutable data throughout domain
• Simplified concurrent access

Success Criteria

• All domain types use immutable state transitions
• No &mut self methods in domain layer
• State changes return new values
• Tests simplified without mocking
• Documentation updated

References

• Functional Core, Imperative Shell pattern
• CLAUDE.md functional architecture principles