feat: [#164] implement ReentrantMutex<RefCell<UserOutput>> pattern

[josecelano]

Overview

This PR implements the ReentrantMutex<RefCell<UserOutput>> pattern to resolve same-thread deadlock issues described in #164. The implementation allows nested calls to UserOutput methods within the same thread while maintaining thread safety.

Problem Statement

The previous Arc<Mutex<UserOutput>> pattern caused deadlocks when:

• A command handler acquired the UserOutput mutex
• Called a step that also needed to acquire the same mutex
• The second acquisition blocked indefinitely on the same thread

Solution

Replaced Arc<Mutex<UserOutput>> with Arc<ReentrantMutex<RefCell<UserOutput>>> throughout the codebase:

• ReentrantMutex: Allows same-thread multiple acquisitions (from parking_lot crate)
• RefCell: Provides runtime borrow checking for interior mutability
• Arc: Enables sharing across threads

Key Changes

Core Implementation

• 🔄 Type Pattern: Arc<Mutex<UserOutput>> → Arc<ReentrantMutex<RefCell<UserOutput>>>
• 🔄 Access Pattern: .lock().unwrap() → .lock().borrow_mut() for mutable operations
• 📦 Dependency: Added parking_lot = { version = "0.12.3", features = ["std"] }

Updated Components

• Bootstrap Container (src/bootstrap/container.rs)
• Application Layer (command handlers, steps, services)
• Presentation Layer (controllers, dispatch, progress reporting)
• Documentation Examples (19 doctests updated with correct type patterns)

Testing

• ✅ Reentrancy Tests: Added comprehensive tests in tests/user_output_reentrancy.rs
• ✅ Unit Tests: 1,196 tests passing
• ✅ Integration Tests: 30 tests passing
• ✅ Documentation Tests: 271 tests passing (all doctest examples fixed)
• ✅ E2E Tests: Both provision/destroy and configuration test suites passing

Technical Details

Access Patterns

// Before (deadlock-prone)
let output = self.user_output.lock().unwrap();
output.success("Done!");

// After (reentrant-safe)  
let output = self.user_output.lock();
output.borrow_mut().success("Done!");

Type Definitions

// Container provides reentrant-wrapped UserOutput
pub fn user_output(&self) -> Arc<ReentrantMutex<RefCell<UserOutput>>> {
    self.user_output.clone()
}

Architecture Decision

This change is documented in docs/decisions/reentrant-mutex-useroutput-pattern.md with:

• Problem analysis and root cause identification
• Solution evaluation and trade-offs
• Implementation approach and patterns
• Testing strategy and validation

Quality Validation

✅ All pre-commit checks passed:

• Dependencies: No unused dependencies (cargo machete)
• Linting: All linters passed (stable & nightly toolchains)
• Tests: All test suites passing
• Documentation: All examples compile and demonstrate correct usage
• E2E Tests: Infrastructure and configuration validation complete

Breaking Changes

❌ None - This is an internal implementation change that maintains all existing public APIs.

Migration Notes

No migration required for users of the application. The change is transparent to:

• Command-line interface users
• External integrations
• Existing workflows and scripts

Future Considerations

• Performance: ReentrantMutex has minimal overhead compared to standard Mutex
• Maintainability: RefCell borrow checking provides runtime safety guarantees
• Extensibility: Pattern supports future nested UserOutput scenarios

Related Issues

Closes #164

Checklist

• Implementation complete and tested
• All tests passing (unit, integration, documentation, E2E)
• Documentation examples updated and validated
• Architecture decision recorded
• Pre-commit checks passed
• No breaking changes to public APIs
• Performance impact minimal

[josecelano]

ACK f071644