runact 1.0.0

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

## Overview

Actors are the fundamental unit of computation in Runact. An actor owns its mutable state and communicates through messages.

## Core Principle

> **An actor owns its mutable state; communication transfers messages and ownership rather than shared mutable state.**

## Actor Trait

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

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

### Requirements

- `Send` — Actor can be sent between threads
- `'static` — Actor owns all its data
- `Message: Send + 'static` — Messages can be sent between threads

### Why Synchronous?

Rust code cannot safely be arbitrarily preempted at any instruction boundary. Runact uses cooperative scheduling at safe execution boundaries.

## ActorId

Stable, unique identifier for an actor.

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

- Created at spawn time
- Never reused within a runtime instance
- Serializable
- Orderable (for debugging)

## ActorContext

Provided to actor handlers.

```rust
pub struct ActorContext {
    actor_id: ActorId,
    sender: MessageSender,
}
```

### Capabilities

- Send messages to other actors
- Access own ActorId
- (Future) Schedule timers
- (Future) Spawn child actors

## Actor Lifecycle

```text
spawned → running → stopping → stopped
    │                  │
    │                  └──→ terminated
    │
    └──→ failed → restarting → running
```

### States

- **spawned** — Actor created, not yet scheduled
- **running** — Actor is executing
- **stopping** — Graceful shutdown initiated
- **stopped** — Actor completed normally
- **terminated** — Actor was forcibly stopped
- **failed** — Actor crashed or returned error
- **restarting** — Supervisor is restarting the actor

## Ownership Model

### Actor Owns State

```rust
struct BufferActor {
    content: String,  // Owned by this actor
    lines: Vec<String>,  // Owned by this actor
}

impl Actor for BufferActor {
    type Message = BufferMessage;

    fn handle(&mut self, msg: BufferMessage, _ctx: &mut ActorContext) -> Result<(), ActorError> {
        match msg {
            BufferMessage::Insert(text) => {
                self.content.push_str(&text);  // ✅ Exclusive access
            }
            BufferMessage::Delete(range) => {
                self.content.drain(range);  // ✅ Exclusive access
            }
        }
        Ok(())
    }
}
```

### Communication Transfers Ownership

```rust
// Sender: ownership moves into channel
actor.send(BufferMessage::Insert("hello".to_string()));

// Receiver: ownership moves out of channel
let msg = receiver.recv();  // msg owns the data
```

### No Shared Mutable State

```rust
// ❌ FORBIDDEN by design
let shared_state = Arc::Mutex::new(0);
let state1 = shared_state.clone();
let state2 = shared_state.clone();

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

## Message Design

### Good Messages

```rust
// Simple, clear, ownership-transferable
enum BufferMessage {
    Insert(String),
    Delete(Range),
    Save,
    GetSnapshot,
}

// Request-response pattern
enum Request {
    GetData,
    GetStatus,
}

enum Response {
    Data(String),
    Status(StatusInfo),
}
```

### Bad Messages

```rust
// ❌ Sharing references
enum BadMessage {
    GetData(&mut String),  // Can't send mutable references
    Process(&[u8]),  // Lifetime issues
}

// ❌ Cloning everything
enum BadMessage {
    GetData(String),  // Forces cloning
}
```

## Examples

### Simple Counter

```rust
struct CounterActor {
    count: u64,
}

enum CounterMessage {
    Increment,
    Decrement,
    GetValue,
}

impl Actor for CounterActor {
    type Message = CounterMessage;

    fn handle(&mut self, msg: CounterMessage, ctx: &mut ActorContext) -> Result<(), ActorError> {
        match msg {
            CounterMessage::Increment => {
                self.count += 1;
            }
            CounterMessage::Decrement => {
                self.count = self.count.saturating_sub(1);
            }
            CounterMessage::GetValue => {
                // Send response back
                ctx.send(Box::new(self.count))?;
            }
        }
        Ok(())
    }
}
```

### Buffer Actor

```rust
struct BufferActor {
    content: String,
    modified: bool,
}

enum BufferMessage {
    Insert { position: usize, text: String },
    Delete { range: Range<usize> },
    Save,
    GetContent,
}

impl Actor for BufferActor {
    type Message = BufferMessage;

    fn handle(&mut self, msg: BufferMessage, ctx: &mut ActorContext) -> Result<(), ActorError> {
        match msg {
            BufferMessage::Insert { position, text } => {
                self.content.insert_str(position, &text);
                self.modified = true;
            }
            BufferMessage::Delete { range } => {
                self.content.drain(range);
                self.modified = true;
            }
            BufferMessage::Save => {
                // Save to disk
                self.modified = false;
            }
            BufferMessage::GetContent => {
                ctx.send(Box::new(self.content.clone()))?;
            }
        }
        Ok(())
    }
}
```

## Best Practices

1. **Keep messages simple** — Easy to understand, easy to handle
2. **Transfer ownership** — Don't share references
3. **One message, one action** — Each message should do one thing
4. **Handle all cases** — Use exhaustive matching
5. **Don't block** — Process message and yield back
6. **Design for failure** — What happens if handler panics?