runact 1.0.0

A Rust-native actor runtime with BEAM-style processes
Documentation
# Runact Architecture

## Overview

Runact is a single Rust crate that provides a BEAM-style actor runtime. The runtime combines lightweight processes, messaging, scheduling, and supervision with Rust's ownership model.

## Core Definition

> **Runact is a Rust-native actor runtime that combines BEAM-style lightweight processes, messaging, scheduling and supervision with Rust's ownership model, providing the foundation for a programmable editor-centric computing environment.**

## Project Structure

```
runact/
├── Cargo.toml
├── README.md
├── LICENSE
├── docs/
│   ├── architecture.md
│   ├── actors.md
│   ├── actor-communication.md
│   ├── scheduler.md
│   ├── supervision.md
│   └── roadmap.md
│
├── src/
│   ├── lib.rs
│   ├── actor/
│   │   ├── mod.rs
│   │   ├── id.rs          # ActorId
│   │   ├── actor.rs       # Actor trait
│   │   ├── context.rs     # ActorContext
│   │   └── error.rs       # ActorError
│   ├── scheduler/
│   │   ├── mod.rs
│   │   ├── scheduler.rs   # BEAM-style scheduler
│   │   ├── worker.rs      # Per-core worker
│   │   ├── run_queue.rs   # Lock-free queue
│   │   └── reduction.rs   # Reduction counter
│   ├── mailbox/
│   │   ├── mod.rs
│   │   └── mailbox.rs     # crossbeam-channel wrapper
│   ├── supervision/
│   │   ├── mod.rs
│   │   ├── supervisor.rs  # Supervisor
│   │   ├── strategy.rs    # Restart strategies
│   │   └── child.rs       # Child specification
│   ├── compute/
│   │   ├── mod.rs
│   │   ├── scheduler.rs   # Compute pool
│   │   ├── task.rs        # Task abstraction
│   │   └── handle.rs      # ComputeHandle
│   ├── timer/
│   │   ├── mod.rs
│   │   └── timer.rs       # Timer wheel
│   └── runtime.rs         # Top-level coordinator
│
└── examples/
    ├── counter.rs
    └── supervisor.rs
```

## Layer Architecture

```
┌─────────────────────────────────────────────────────┐
│                   Applications                      │
│         TUI │ GUI │ CLI │ Web │ Editor │ Server     │
└─────────────────────┬───────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────┐
│               Runtime Layer                         │
│     Runtime (top-level coordinator)                 │
└─────────────────────┬───────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────┐
│              Core Components                        │
├─────────────────────┬───────────────────────────────┤
│    Actor System     │      Compute System           │
├─────────────────────┼───────────────────────────────┤
│ • Actor trait       │ • Compute pool                │
│ • ActorId           │ • Task submission             │
│ • Mailbox           │ • Oneshot result              │
│ • Supervision       │ • Panic isolation             │
│ • Timers            │ • Bounded queue               │
└───────────┬─────────┴─────────────┬─────────────────┘
            │                       │
┌───────────▼───────────────────────▼─────────────────┐
│              Scheduler Layer                        │
├─────────────────────────────────────────────────────┤
│    BEAM-style Scheduler with Work Stealing          │
├─────────────┬─────────────┬─────────────┬───────────┤
│   Worker 0  │   Worker 1  │   Worker 2  │  Worker 3 │
└─────────────┴─────────────┴─────────────┴───────────┘
                      │
┌─────────────────────▼───────────────────────────────┐
│              Platform Layer                         │
│     Threads (OS) │ Atomics │ crossbeam-channel      │
└─────────────────────────────────────────────────────┘
```

## Core Components

### Actor

The fundamental unit of computation.

```rust
pub trait Actor: Send + 'static {
    type Message: Send + 'static;

    fn handle(
        &mut self,
        message: Self::Message,
        context: &mut ActorContext,
    ) -> Result<(), ActorError>;
}
```

### ActorId

Stable, unique identifier for an actor.

```rust
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct ActorId(u64);
```

### Mailbox

Typed message queue for an actor.

- Uses `crossbeam-channel` internally
- Hidden behind abstraction
- Supports bounded capacity
- Ownership transfer on send

### Scheduler

BEAM-style scheduler with work stealing.

- Per-core worker threads
- Lock-free run queues
- Work stealing between workers
- Reduction counting for fairness

### Compute Pool

Separate execution domain for CPU-intensive tasks.

- Bounded queue
- Oneshot result channel
- Panic isolation
- Never blocks actors

### Supervision

BEAM-inspired supervision tree.

- One-for-one restart strategy
- Child specifications
- Backoff configuration
- Failure propagation

### Timers

Scheduled message delivery.

- One-shot timers
- Periodic timers
- Integrated with scheduler

## Design Principles

### 1. Ownership is Fundamental

```rust
// Actor owns its state
struct MyActor {
    data: Vec<String>,  // Owned by this actor
}

// Communication transfers ownership
actor.send(MyMessage { data });  // Ownership moves
```

### 2. No Shared Mutable State

```rust
// ❌ FORBIDDEN
let shared = Arc<Mutex<State>>();

// ✅ CORRECT
// Each actor owns its state
// Communication via messages
```

### 3. Implementation Details Hidden

```rust
// ✅ Public API
actor.send(message);

// ❌ Not exposed
crossbeam_sender.send(message);
```

### 4. Cooperative Scheduling

```rust
fn handle(&mut self, msg: Message, ctx: &mut ActorContext) -> Result<(), ActorError> {
    // Process one message
    // Yield back to scheduler
    // Don't monopolize worker
    Ok(())
}
```

## Dependencies

Minimal dependencies, each with clear architectural reason:

```toml
[dependencies]
crossbeam-channel = "0.5"  # Mailbox implementation
serde = { version = "1", features = ["derive"] }  # Serialization
tracing = "0.1"  # Observability
thiserror = "1"  # Error handling
```

**No Tokio.** Runact owns its runtime semantics.

## Development Phases

### Phase 1 — Runtime Core
- ActorId, Actor trait
- Mailbox, Scheduler
- Actor spawning, messaging
- Lifecycle, graceful shutdown

### Phase 2 — Reliability
- Panic isolation
- Supervisors, restart strategies
- Failure propagation

### Phase 3 — Compute
- Bounded compute pool
- Task submission, oneshot result
- Panic isolation

### Phase 4 — Timers and I/O
- Timers
- Filesystem, process spawning
- Basic networking

### Phase 5 — Resources and Capabilities
- Resource handles
- Capability-oriented access

### Phase 6 — Editor Runtime
- First minimal editor on Runact

### Phase 7 — Programmability
- Extension API
- Scripting integration

## First Demonstration

```text
Runtime
│
├── CounterActor
├── LoggerActor
├── ComputeActor
└── Supervisor
```

Demonstrate:
1. Spawning actors
2. Sending messages
3. Actor state isolation
4. Scheduler execution
5. Actor failure
6. Supervisor restart
7. Compute task execution
8. Graceful shutdown

## See Also

- [Actor Communication Principles]actor-communication.md — 24 principles governing message flow, request/reply, backpressure, cancellation, and the fundamental invariant: actors must never block scheduler workers.