escher-execution-engine 0.1.2

# Claude Code Implementation Prompt: Execution Engine

**Target Repository**: `v2-desktop-app-tauri` (Rust crate: `src-tauri/crates/execution-engine/`)
**Language**: Rust
**Framework**: Tokio (async runtime)
**Status**: Design Complete → Ready for Implementation
**Implementation Phases**: 5 phases, ~12-15 hours total

---

## **CRITICAL UNDERSTANDING**

You are implementing a **production-ready Rust crate** that:

1. **Executes system commands asynchronously** (bash, AWS CLI, scripts)
2. **Streams output in real-time** (line-by-line, non-blocking)
3. **Manages concurrency** (Semaphore-based limiting)
4. **Prevents memory leaks** (automatic cleanup system)
5. **Enforces resource limits** (output size, timeouts, concurrency)
6. **Provides event-driven updates** (pluggable event handlers)

**This is NOT:**
- A simple command wrapper
- A synchronous execution library
- A standalone service

**This IS:**
- An embedded async library for Tauri/Axum/CLI apps
- A production-grade execution engine with operational features
- A reusable crate with zero framework dependencies

---

## **Architecture Documents Available**

**Read these FIRST before starting:**

1. **[architecture.md](architecture.md)** - Complete system architecture, 1,177 lines
   - Core components and responsibilities
   - Execution flow diagrams
   - Operational features (cleanup, concurrency, output limiting)
   - Code examples with full implementations

2. **[api.md](api.md)** - Public API specification
   - All public methods with signatures
   - Request/response types
   - Error handling patterns

3. **[types.md](types.md)** - Complete type definitions
   - Command enum (Shell, Exec, Script, AwsCli)
   - ExecutionRequest, ExecutionResult, ExecutionStatus
   - Event types and error types

4. **[configuration.md](configuration.md)** - Configuration guide, 542 lines
   - All 11 config fields documented
   - 5 configuration examples (Production, Development, Testing, etc.)
   - Validation rules and best practices

5. **[error-handling.md](error-handling.md)** - Error handling strategy
   - ExecutionError enum with all variants
   - ValidationError patterns
   - Recovery strategies

6. **[testing.md](testing.md)** - Testing strategy, 922 lines
   - Unit, integration, and performance tests
   - 30+ test examples
   - Benchmark suite

7. **[security.md](security.md)** - Security guide, 643 lines
   - Threat mitigations
   - Input validation patterns
   - Output sanitization

8. **[performance.md](performance.md)** - Performance guide, 788 lines
   - Resource usage analysis
   - Optimization strategies
   - Monitoring and metrics

---

## **Repository Structure**

```
v2-desktop-app-tauri/
└── src-tauri/
    └── crates/
        ├── common/                        # Already exists (shared types)
        │   └── src/
        │       └── lib.rs                 # Re-export types from here
        │
        └── execution-engine/              # YOU WILL CREATE THIS
            ├── Cargo.toml                 # Dependencies
            ├── src/
            │   ├── lib.rs                 # Public API exports
            │   ├── engine.rs              # ExecutionEngine (main entry point)
            │   ├── executor.rs            # Command execution logic
            │   ├── config.rs              # ExecutionConfig
            │   ├── types.rs               # Request/Result types
            │   ├── events.rs              # Event system
            │   ├── errors.rs              # Error types
            │   ├── commands.rs            # Command builder
            │   ├── cleanup.rs             # Memory cleanup system
            │   └── tests/                 # Unit tests
            │       ├── engine_tests.rs
            │       ├── executor_tests.rs
            │       ├── cleanup_tests.rs
            │       └── concurrency_tests.rs
            │
            ├── tests/                     # Integration tests
            │   ├── integration_tests.rs
            │   ├── concurrency_tests.rs
            │   ├── cleanup_tests.rs
            │   └── output_limiting_tests.rs
            │
            └── benches/                   # Performance benchmarks
                └── execution_benchmarks.rs
```

---

## **Implementation Phases**

### **Phase 1: Project Setup & Core Types** (1-2 hours)

**Goal**: Create crate structure, define all types, implement config validation.

**Tasks**:
1. Create `execution-engine` crate with Cargo.toml
2. Define all types in `types.rs`:
   - Command enum (Shell, Exec, Script, AwsCli)
   - ExecutionRequest, ExecutionResult
   - ExecutionState, ExecutionStatus
   - ExecutionSummary
3. Define error types in `errors.rs`:
   - ExecutionError (with thiserror)
   - ValidationError
4. Define config in `config.rs`:
   - ExecutionConfig struct (11 fields)
   - Default implementation
   - Validation logic
5. Define events in `events.rs`:
   - ExecutionEvent enum (Started, Stdout, Stderr, Completed, Failed, Cancelled, Progress)
   - EventHandler trait

**Cargo.toml dependencies:**
```toml
[dependencies]
tokio = { version = "1", features = ["full"] }
tokio-util = "0.7"
serde = { version = "1", features = ["derive"] }
serde_json = "1"
uuid = { version = "1", features = ["v4", "serde"] }
chrono = { version = "0.4", features = ["serde"] }
thiserror = "1"
async-trait = "0.1"
futures = "0.3"
tracing = "0.1"

[dev-dependencies]
tokio = { version = "1", features = ["full", "test-util"] }
criterion = "0.5"
tempfile = "3"
```

**Validation checkpoint:**
```bash
cargo build
cargo test
```

---

### **Phase 2: Command Executor** (2-3 hours)

**Goal**: Implement core command execution with output streaming.

**Tasks**:
1. Implement `commands.rs`:
   - `build_command()` - Convert Command enum to tokio::process::Command
   - Handle Shell, Exec, Script, AwsCli variants
   - Set environment variables
   - Set working directory

2. Implement `executor.rs`:
   - `execute_command_internal()` - Main execution logic
   - `stream_output()` - Async line-by-line streaming
   - `wait_with_timeout_and_cancel()` - Timeout + cancellation handling
   - `write_log()` - Async log file writing
   - `get_log_path()` - Log path generation

**Key patterns to implement:**

```rust
// Streaming pattern (from architecture.md)
async fn stream_output(
    &self,
    execution_id: Uuid,
    output: ChildStdout,
    output_type: OutputType,
) -> Result<String> {
    let reader = BufReader::new(output);
    let mut lines = reader.lines();
    let mut collected = Vec::new();

    while let Some(line) = lines.next_line().await? {
        // Write to log
        self.write_log(execution_id, &line).await?;

        // Emit event (if handler present)
        if let Some(handler) = &self.event_handler {
            handler.on_event(/* ... */).await;
        }

        collected.push(line);
    }

    Ok(collected.join("\n"))
}

// Timeout + cancellation pattern (from architecture.md)
async fn wait_with_timeout_and_cancel(
    &self,
    mut child: Child,
    timeout_ms: Option<u64>,
    cancel_token: CancellationToken,
) -> Result<ExitStatus> {
    let timeout_duration = Duration::from_millis(
        timeout_ms.unwrap_or(self.config.default_timeout_ms)
    );

    tokio::select! {
        result = child.wait() => result.map_err(Into::into),
        _ = tokio::time::sleep(timeout_duration) => {
            child.kill().await?;
            Err(ExecutionError::Timeout(timeout_duration.as_millis() as u64))
        }
        _ = cancel_token.cancelled() => {
            child.kill().await?;
            Err(ExecutionError::Cancelled)
        }
    }
}
```

**Validation checkpoint:**
```bash
cargo test executor_tests
```

---

### **Phase 3: ExecutionEngine Core** (2-3 hours)

**Goal**: Implement main ExecutionEngine with state management and concurrency control.

**Tasks**:
1. Implement `engine.rs`:
   - `ExecutionEngine` struct with:
     - `config: ExecutionConfig`
     - `executions: Arc<RwLock<HashMap<Uuid, ExecutionState>>>`
     - `event_handler: Option<Arc<dyn EventHandler>>`
     - `semaphore: Arc<Semaphore>` (NEW - for concurrency control)

2. Implement core methods:
   - `new(config)` - Constructor with Semaphore initialization
   - `with_event_handler(handler)` - Builder pattern
   - `execute(request)` - Main execution entry point
   - `get_status(id)` - Query execution status
   - `get_result(id)` - Get execution result (blocks if not complete)
   - `cancel(id)` - Cancel running execution
   - `list_executions()` - List all in-memory executions
   - `read_logs(id)` - Read log file

**Critical implementation details:**

```rust
pub struct ExecutionEngine {
    config: ExecutionConfig,
    executions: Arc<RwLock<HashMap<Uuid, ExecutionState>>>,
    event_handler: Option<Arc<dyn EventHandler>>,
    semaphore: Arc<Semaphore>,  // CRITICAL: Concurrency limiter
}

impl ExecutionEngine {
    pub fn new(config: ExecutionConfig) -> Self {
        Self {
            semaphore: Arc::new(Semaphore::new(config.max_concurrent_executions)),
            config,
            executions: Arc::new(RwLock::new(HashMap::new())),
            event_handler: None,
        }
    }

    pub async fn execute(&self, request: ExecutionRequest) -> Result<Uuid> {
        // 1. Validate
        request.validate(&self.config)?;

        // 2. Create state
        let execution_id = Uuid::new_v4();
        let cancel_token = CancellationToken::new();

        let state = ExecutionState {
            id: execution_id,
            status: ExecutionStatus::Pending,
            started_at: Utc::now(),
            completed_at: None,
            result: None,
            cancel_token: cancel_token.clone(),
            log_path: self.get_log_path(execution_id),
        };

        // 3. Store state
        self.executions.write().await.insert(execution_id, state);

        // 4. Acquire permit (BLOCKS if at limit)
        let permit = self.semaphore.clone().acquire_owned().await
            .map_err(|_| ExecutionError::ConcurrencyLimitReached)?;

        // 5. Spawn background task
        let engine = self.clone();
        tokio::spawn(async move {
            let result = engine.execute_internal(execution_id, request, cancel_token).await;

            // 6. Release permit when done (via drop)
            drop(permit);

            result
        });

        Ok(execution_id)
    }
}
```

**Validation checkpoint:**
```bash
cargo test engine_tests
cargo test integration_tests
```

---

### **Phase 4: Operational Features** (3-4 hours)

**Goal**: Implement memory cleanup, output limiting, and monitoring.

**Tasks**:

#### **4.1 Memory Cleanup System**

Implement `cleanup.rs`:
```rust
impl ExecutionEngine {
    /// Remove old executions from memory
    pub async fn cleanup_old_executions(&self) -> usize {
        let mut executions = self.executions.write().await;
        let now = Utc::now();
        let retention = Duration::from_secs(self.config.execution_retention_secs);

        let initial_count = executions.len();

        // Remove by age
        executions.retain(|_, state| {
            let age = now.signed_duration_since(state.started_at);
            age < retention
        });

        // Remove by count (keep most recent)
        if executions.len() > self.config.max_in_memory_executions {
            let mut entries: Vec<_> = executions.iter()
                .map(|(id, state)| (*id, state.started_at))
                .collect();

            entries.sort_by(|a, b| b.1.cmp(&a.1)); // Newest first

            let to_remove: Vec<_> = entries
                .iter()
                .skip(self.config.max_in_memory_executions)
                .map(|(id, _)| *id)
                .collect();

            for id in to_remove {
                executions.remove(&id);
            }
        }

        let removed = initial_count - executions.len();

        if removed > 0 {
            tracing::info!(
                "Cleaned up {} executions (retention: {}s, max: {})",
                removed,
                self.config.execution_retention_secs,
                self.config.max_in_memory_executions
            );
        }

        removed
    }

    /// Start automatic cleanup background task (runs every 5 minutes)
    pub fn start_cleanup_task(self: &Arc<Self>) {
        if !self.config.enable_auto_cleanup {
            return;
        }

        let engine = Arc::clone(self);
        tokio::spawn(async move {
            let mut interval = tokio::time::interval(Duration::from_secs(300)); // 5 min

            loop {
                interval.tick().await;

                let cleaned = engine.cleanup_old_executions().await;

                if cleaned > 0 {
                    tracing::info!("Auto-cleanup removed {} executions", cleaned);
                }
            }
        });

        tracing::info!("Started auto-cleanup background task (interval: 5 minutes)");
    }
}
```

#### **4.2 Output Size Limiting**

Update `executor.rs` `stream_output()` to add size checks:

```rust
async fn stream_output(
    &self,
    execution_id: Uuid,
    output: ChildStdout,
    output_type: OutputType,
) -> Result<String> {
    let reader = BufReader::new(output);
    let mut lines = reader.lines();
    let mut collected = Vec::new();
    let mut total_bytes: usize = 0;
    let max_bytes = self.config.max_output_size_bytes;

    while let Some(line) = lines.next_line().await? {
        let line_bytes = line.len();

        // Check size limit
        if total_bytes + line_bytes > max_bytes {
            match self.config.oversized_output_strategy {
                OversizedOutputStrategy::TruncateWithWarning => {
                    let warning = format!(
                        "\n[... output truncated at {} MB ...]",
                        max_bytes / 1_048_576
                    );
                    collected.push(warning);

                    tracing::warn!(
                        "Execution {} output truncated at {} bytes",
                        execution_id,
                        max_bytes
                    );

                    break; // Stop reading
                }

                OversizedOutputStrategy::FailExecution => {
                    return Err(ExecutionError::OversizedOutput {
                        execution_id,
                        bytes: total_bytes + line_bytes,
                        limit: max_bytes,
                    });
                }

                OversizedOutputStrategy::StreamToFile => {
                    // Stream remaining output to file
                    return self.stream_output_to_file(
                        execution_id,
                        output_type,
                        collected,
                        lines,
                    ).await;
                }
            }
        }

        total_bytes += line_bytes;

        // Continue with normal processing...
        self.write_log(execution_id, &line).await?;

        if let Some(handler) = &self.event_handler {
            // Emit event...
        }

        collected.push(line);
    }

    Ok(collected.join("\n"))
}
```

#### **4.3 Monitoring Metrics**

Add to `engine.rs`:

```rust
impl ExecutionEngine {
    /// Get current concurrency metrics
    pub async fn get_concurrency_metrics(&self) -> ConcurrencyMetrics {
        let executions = self.executions.read().await;

        let running_count = executions.values()
            .filter(|s| s.status == ExecutionStatus::Running)
            .count();

        let pending_count = executions.values()
            .filter(|s| s.status == ExecutionStatus::Pending)
            .count();

        ConcurrencyMetrics {
            max_concurrent: self.config.max_concurrent_executions,
            currently_running: running_count,
            currently_pending: pending_count,
            available_slots: self.semaphore.available_permits(),
        }
    }
}

pub struct ConcurrencyMetrics {
    pub max_concurrent: usize,
    pub currently_running: usize,
    pub currently_pending: usize,
    pub available_slots: usize,
}
```

**Validation checkpoint:**
```bash
cargo test cleanup_tests
cargo test output_limiting_tests
cargo test concurrency_tests
```

---

### **Phase 5: Testing & Documentation** (2-3 hours)

**Goal**: Comprehensive test coverage and examples.

**Tasks**:

1. **Unit Tests** (`src/tests/`):
   - Config validation tests
   - Command building tests
   - Error handling tests

2. **Integration Tests** (`tests/`):
   - Basic execution flow
   - Timeout handling
   - Cancellation
   - Event emission
   - See [testing.md](testing.md) for 30+ test examples

3. **Concurrency Tests**:
   - Semaphore limit enforcement
   - Permit release on completion/error
   - Queue behavior

4. **Cleanup Tests**:
   - Manual cleanup
   - Auto cleanup
   - Age-based removal
   - Count-based removal

5. **Output Limiting Tests**:
   - Truncation strategy
   - Fail strategy
   - StreamToFile strategy

6. **Benchmarks** (`benches/`):
   - Execution overhead
   - Concurrent execution throughput
   - Cleanup performance

7. **Examples** (`examples/`):
   - Basic usage example
   - Event handler example
   - Tauri integration example

**Example test structure:**
```rust
// tests/integration_tests.rs
use cloudops_execution_engine::*;

#[tokio::test]
async fn test_basic_execution() {
    let config = ExecutionConfig::default();
    let engine = ExecutionEngine::new(config);

    let request = ExecutionRequest {
        id: Uuid::new_v4(),
        command: Command::Shell {
            command: "echo 'Hello World'".to_string(),
            shell: "/bin/bash".to_string(),
        },
        timeout_ms: Some(5000),
        env: HashMap::new(),
        working_dir: None,
    };

    let execution_id = engine.execute(request).await.unwrap();

    // Wait for completion
    tokio::time::sleep(Duration::from_secs(1)).await;

    let result = engine.get_result(execution_id).await.unwrap();

    assert!(result.success);
    assert_eq!(result.exit_code, 0);
    assert!(result.stdout.contains("Hello World"));
}
```

**Validation checkpoint:**
```bash
cargo test --all
cargo bench
cargo clippy -- -D warnings
cargo fmt -- --check
```

---

## **Critical Implementation Details**

### **1. Semaphore Usage (Concurrency Control)**

**MUST implement exactly as specified:**
```rust
// In new():
semaphore: Arc::new(Semaphore::new(config.max_concurrent_executions))

// In execute():
let permit = self.semaphore.clone().acquire_owned().await?;

// In background task:
tokio::spawn(async move {
    let result = engine.execute_internal(...).await;
    drop(permit);  // CRITICAL: Release permit
    result
});
```

**Why this matters:**
- Prevents resource exhaustion
- Automatic queueing when limit reached
- FIFO ordering
- No manual queue management needed

---

### **2. Background Execution Pattern**

**MUST return immediately, don't block:**
```rust
pub async fn execute(&self, request: ExecutionRequest) -> Result<Uuid> {
    // Do synchronous work (validation, state creation)
    // ...

    // Spawn background task
    tokio::spawn(async move {
        // Actual execution happens here
    });

    // Return immediately
    Ok(execution_id)
}
```

**Why this matters:**
- User never blocks on command execution
- Can submit many requests quickly
- Query status/results asynchronously

---

### **3. Output Streaming (Line-by-Line)**

**MUST stream, don't buffer:**
```rust
let mut lines = reader.lines();

while let Some(line) = lines.next_line().await? {
    // Process immediately:
    // 1. Check size limit
    // 2. Write to log
    // 3. Emit event
    // 4. Collect
}
```

**Why this matters:**
- Low memory usage
- Real-time updates
- Early truncation if oversized

---

### **4. Cleanup Strategy**

**MUST implement both age and count limits:**
```rust
// 1. Remove by age
executions.retain(|_, state| {
    let age = now.signed_duration_since(state.started_at);
    age < retention
});

// 2. Remove by count (if still over limit)
if executions.len() > max_in_memory {
    // Sort by timestamp, keep newest
    // Remove oldest
}
```

**Why this matters:**
- Prevents unbounded memory growth
- Configurable retention policies
- Production-ready

---

### **5. Error Propagation**

**Use `thiserror` for all errors:**
```rust
#[derive(Debug, thiserror::Error)]
pub enum ExecutionError {
    #[error("Validation error: {0}")]
    Validation(#[from] ValidationError),

    #[error("Execution not found: {0}")]
    NotFound(Uuid),

    #[error("Execution timeout after {0}ms")]
    Timeout(u64),

    #[error("Execution cancelled")]
    Cancelled,

    #[error("Command failed with exit code {0}")]
    CommandFailed(i32),

    #[error("Oversized output: {bytes} bytes exceeds limit {limit}")]
    OversizedOutput {
        execution_id: Uuid,
        bytes: usize,
        limit: usize,
    },

    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),
}
```

---

## **Testing Strategy**

### **Required Test Coverage**

1. **Unit Tests** (>80% code coverage)
   - All public methods
   - Config validation
   - Command building
   - Error cases

2. **Integration Tests**
   - Complete execution flows
   - Timeout scenarios
   - Cancellation
   - Concurrency limits
   - Cleanup behavior
   - Output limiting

3. **Performance Tests**
   - Execution overhead (<50ms)
   - Concurrent throughput (100+)
   - Cleanup performance (<1s for 1000 executions)

### **Test Checklist**

- [ ] Basic execution (echo command)
- [ ] Command failure (exit 1)
- [ ] Timeout handling
- [ ] Cancellation
- [ ] Event emission
- [ ] Concurrency limit enforcement
- [ ] Semaphore permit release
- [ ] Manual cleanup
- [ ] Auto cleanup
- [ ] Age-based cleanup
- [ ] Count-based cleanup
- [ ] Output truncation
- [ ] Output fail strategy
- [ ] Output file streaming
- [ ] AWS CLI command
- [ ] Script execution
- [ ] Environment variables
- [ ] Working directory
- [ ] Log file writing
- [ ] Status queries
- [ ] Result retrieval
- [ ] List executions
- [ ] Concurrency metrics

---

## **Common Pitfalls to Avoid**

### **❌ DON'T: Block on execution**
```rust
// WRONG: This blocks the caller
pub async fn execute(&self, request: ExecutionRequest) -> Result<ExecutionResult> {
    let child = Command::new(&request.command).spawn()?;
    let output = child.wait_with_output().await?; // BLOCKS!
    Ok(output)
}
```

### **✅ DO: Return immediately, execute in background**
```rust
// CORRECT: Returns execution_id immediately
pub async fn execute(&self, request: ExecutionRequest) -> Result<Uuid> {
    let execution_id = Uuid::new_v4();

    tokio::spawn(async move {
        // Background execution
    });

    Ok(execution_id) // Returns immediately
}
```

---

### **❌ DON'T: Buffer entire output**
```rust
// WRONG: Loads entire output in memory
let output = child.wait_with_output().await?;
let stdout = String::from_utf8_lossy(&output.stdout).to_string();
```

### **✅ DO: Stream line-by-line**
```rust
// CORRECT: Streams line-by-line
let stdout = child.stdout.take().unwrap();
let reader = BufReader::new(stdout);
let mut lines = reader.lines();

while let Some(line) = lines.next_line().await? {
    // Process immediately
}
```

---

### **❌ DON'T: Forget to release Semaphore permit**
```rust
// WRONG: Permit never released, deadlock!
let permit = self.semaphore.acquire().await?;

tokio::spawn(async move {
    // Do work
    // Forgot to drop(permit)!
});
```

### **✅ DO: Use owned permit with automatic drop**
```rust
// CORRECT: Permit released when task completes
let permit = self.semaphore.clone().acquire_owned().await?;

tokio::spawn(async move {
    // Do work
    drop(permit); // Explicit drop (or automatic at end of scope)
});
```

---

### **❌ DON'T: Store unbounded executions**
```rust
// WRONG: Never cleans up, memory leak!
impl ExecutionEngine {
    pub async fn execute(&self, request: ExecutionRequest) -> Result<Uuid> {
        // Store execution
        self.executions.write().await.insert(execution_id, state);

        // Never removes from map!
    }
}
```

### **✅ DO: Implement cleanup**
```rust
// CORRECT: Periodic cleanup
engine.start_cleanup_task(); // Runs every 5 minutes
```

---

## **Integration with Tauri**

Once the crate is complete, integrate with Tauri:

```rust
// src-tauri/src/main.rs

use execution_engine::{ExecutionEngine, ExecutionConfig};
use std::sync::Arc;

#[tokio::main]
async fn main() {
    // Create engine
    let config = ExecutionConfig::default();
    let engine = Arc::new(ExecutionEngine::new(config));

    // Start cleanup
    engine.start_cleanup_task();

    // Create Tauri app
    tauri::Builder::default()
        .manage(engine)  // Share with commands
        .invoke_handler(tauri::generate_handler![
            execute_command,
            get_execution_status,
            get_execution_result,
            cancel_execution,
            list_executions,
            get_concurrency_metrics,
        ])
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

// Tauri commands
#[tauri::command]
async fn execute_command(
    request: ExecutionRequest,
    engine: State<'_, Arc<ExecutionEngine>>,
) -> Result<String, String> {
    let execution_id = engine.execute(request).await
        .map_err(|e| e.to_string())?;

    Ok(execution_id.to_string())
}

#[tauri::command]
async fn get_execution_status(
    execution_id: String,
    engine: State<'_, Arc<ExecutionEngine>>,
) -> Result<ExecutionStatus, String> {
    let id = Uuid::parse_str(&execution_id).map_err(|e| e.to_string())?;

    engine.get_status(id).await
        .map_err(|e| e.to_string())
}

// ... other commands
```

---

## **Success Criteria**

Before considering this complete:

### **Functionality**
- [ ] All phases implemented
- [ ] All public APIs working
- [ ] Background execution non-blocking
- [ ] Concurrency limit enforced
- [ ] Cleanup system working
- [ ] Output limiting working
- [ ] Event system working

### **Quality**
- [ ] All tests passing
- [ ] >80% code coverage
- [ ] No clippy warnings
- [ ] Formatted with rustfmt
- [ ] No unsafe code (unless justified)
- [ ] All unwraps replaced with proper error handling

### **Performance**
- [ ] Execution overhead <50ms
- [ ] Can handle 100+ concurrent executions
- [ ] Cleanup <1s for 1000 executions
- [ ] Memory bounded by config

### **Documentation**
- [ ] All public APIs documented
- [ ] Examples provided
- [ ] README with usage
- [ ] Architecture documented

---

## **Timeline Estimate**

| Phase | Duration | Complexity |
|-------|----------|------------|
| Phase 1: Setup & Types | 1-2 hours | Low |
| Phase 2: Command Executor | 2-3 hours | Medium |
| Phase 3: ExecutionEngine Core | 2-3 hours | Medium |
| Phase 4: Operational Features | 3-4 hours | High |
| Phase 5: Testing & Docs | 2-3 hours | Medium |
| **Total** | **10-15 hours** | **Medium-High** |

---

## **Support Resources**

If you encounter issues:

1. **Read the architecture docs** (1,177 lines of implementation details)
2. **Check testing.md** (30+ test examples)
3. **Review security.md** (input validation patterns)
4. **Reference performance.md** (optimization strategies)

All patterns are fully documented with code examples in the architecture documentation.

---

## **Final Notes**

This is a **production-grade** crate. Focus on:
1. **Correctness** - No race conditions, proper error handling
2. **Performance** - Async, non-blocking, bounded resources
3. **Reliability** - Cleanup, limits, monitoring
4. **Testability** - High coverage, all edge cases

The design is complete. Your job is to translate the architecture documents into working Rust code. Follow the patterns exactly as documented.

**Good luck!** 🚀