AstrBot/openspec/changes/rust-core-runtime-migration/design.md

## Context

AstrBot's core runtime is currently implemented in Python. While Python provides flexibility and rapid development, performance-critical components (orchestration, protocol management, message processing) would benefit from Rust's:
- Memory safety without garbage collection
- Zero-cost abstractions
- Native performance for concurrent operations
- Strong type safety at compile time

The Rust implementation provides a high-performance foundation that can be exposed to Python via pyo3 bindings.

## Goals / Non-Goals

**Goals:**
- Create a `astrbot-core` Rust crate with core runtime components
- Implement thread-safe Orchestrator using RwLock
- Define ProtocolClient trait for LSP, MCP, ACP, ABP clients
- Provide TOML-based configuration management
- Expose Python bindings via pyo3
- CLI binary using clap

**Non-Goals:**
- Not replacing the Python implementation immediately (coexistence)
- Not implementing anyio (uses native Rust async/tokio)
- Not creating a full ABP protocol implementation in Rust
- Not implementing platform adapters or message pipeline

## Decisions

### 1. Architecture: Stub with Python Integration

The initial Rust implementation is a **stub** that provides:
- Structural definitions matching the expected interfaces
- Thread-safe state management (RwLock)
- Python bindings verification via pyo3

This allows:
- Validating the pyo3 integration works
- Ensuring clippy pedantic compliance
- Establishing the project structure

### 2. Concurrency Model: RwLock for Thread Safety

```rust
pub struct Orchestrator {
    running: RwLock<bool>,
    stars: RwLock<HashMap<String, String>>,
    protocol_lsp: RwLock<ProtocolStatus>,
    // ...
}
```

Using `RwLock` allows:
- Multiple readers concurrently (most operations are reads)
- Exclusive writer (state changes)
- No deadlocks (standard read-write lock pattern)

### 3. Error Handling: thiserror for Ergonomic Errors

```rust
#[derive(Error, Debug)]
pub enum AstrBotError {
    #[error("Not connected: {0}")]
    NotConnected(String),
    // ...
}
```

Using `thiserror` provides:
- Compile-time error message generation
- `?` operator compatibility
- Debug output for development

### 4. Python Bindings: GILOnceCell Singleton

```rust
static ORCHESTRATOR: GILOnceCell<Py<PythonOrchestrator>> = GILOnceCell::new();

#[pyfunction]
pub fn get_orchestrator(py: Python<'_>) -> PyResult<&'static Py<PythonOrchestrator>> {
    if ORCHESTRATOR.get(py).is_none() {
        ORCHESTRATOR.set(py, Py::new(py, PythonOrchestrator::new())?)?;
    }
    Ok(ORCHESTRATOR.get(py).expect("initialized"))
}
```

Using `GILOnceCell` provides:
- Thread-safe global singleton
- GIL-aware initialization
- Lazy initialization on first Python access

### 5. Rust Rules Enforcement

```rust
#![deny(unsafe_code)]
#![deny(clippy::all)]
#![deny(clippy::pedantic)]
```

- **No unsafe**: All memory access is safe by construction
- **No unwrap()**: Errors propagated via `?` or expect with messages
- **Clippy pedantic**: Catches style issues and potential bugs

### 6. ProtocolClient Trait: Static Lifetime for Names

```rust
#[async_trait]
pub trait ProtocolClient: Send + Sync {
    fn name(&self) -> &'static str;
    // ...
}
```

Using `&'static str` ensures:
- No lifetime issues from borrowed data
- Compile-time guaranteed string validity
- Simple implementation for hardcoded client names

## Risks / Trade-offs

| Risk | Mitigation |
|------|------------|
| pyo3 compatibility with Python 3.14 | Use `PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1` |
| Two implementations to maintain | Rust is opt-in via feature flag |
| Performance overhead of bindings | Rust called only for core operations |
| Clippy pedantic false positives | Use `#[allow(...)]` for intentional patterns |

## File Structure

```
rust/
├── Cargo.toml
├── src/
│   ├── lib.rs           # Crate root with module declarations
│   ├── main.rs          # CLI binary
│   ├── error.rs         # AstrBotError enum
│   ├── orchestrator.rs  # Core orchestrator
│   ├── message.rs       # Message types
│   ├── stats.rs         # RuntimeStats
│   ├── protocol.rs      # ProtocolClient trait + implementations
│   ├── config.rs        # Configuration structs
│   └── python.rs        # pyo3 bindings
└── target/              # Build output (gitignored)
```

## Cargo Features

```toml
[features]
default = ["python"]
python = ["pyo3"]
```

- Default enables Python bindings
- Can build pure Rust library without Python

## Verification

| Check | Command |
|-------|---------|
| Clippy | `PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 cargo clippy` |
| Build | `PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 cargo build` |
| Python import | `python -c "from astrbot_core import PythonOrchestrator"` |
| CLI help | `cargo run -- --help` |

## Current Implementation Status

| Component | Status | Notes |
|-----------|--------|-------|
| error.rs | ✅ Complete | thiserror-based errors |
| orchestrator.rs | ✅ Complete | Thread-safe with RwLock |
| message.rs | ✅ Complete | serde serialization |
| stats.rs | ✅ Complete | AtomicU64 message count |
| protocol.rs | ✅ Complete | Trait + 4 client stubs |
| config.rs | ✅ Complete | TOML load/save |
| python.rs | ✅ Complete | pyo3 bindings |
| main.rs | ✅ Complete | clap CLI |
| lib.rs | ✅ Complete | Module declarations |
| Clippy | ✅ Passing | No warnings |
| Build | ✅ Passing | Compiles successfully |

## Next Steps (Future Work)

1. **Real Protocol Implementations**: Replace stub clients with actual LSP/MCP/ACP/ABP implementations
2. **Python Integration**: Connect Rust orchestrator to Python platform adapters
3. **Performance Benchmarking**: Compare Python vs Rust performance
4. **Feature Parity**: Match all Python orchestrator functionality
5. **Production Readiness**: Add more tests, error handling, edge cases