runact 1.0.0

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

## Overview

This document defines the core runtime objects in Runact. These objects form the public API surface. Implementation details must not leak through these types.

## Core Identifiers

### ProcessId

Stable, unique identifier for a process.

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

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

### MessageId

Unique identifier for a message.

```rust
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct MessageId(u128);
```

- Generated for each message
- Used for correlation and deduplication

### CorrelationId

Links request/response pairs.

```rust
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct CorrelationId(u128);
```

- Set by sender
- Propagated through message chain
- Used for tracing and debugging

### TimerId

Stable identifier for a timer.

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

## Message Model

### MessageEnvelope

Container for all messages passing through the system.

```rust
pub struct MessageEnvelope {
    pub message_id: MessageId,
    pub correlation_id: Option<CorrelationId>,
    pub sender: ProcessId,
    pub recipient: ProcessId,
    pub protocol: ProtocolId,
    pub version: ProtocolVersion,
    pub priority: Priority,
    pub timestamp: Timestamp,
    pub payload: Vec<u8>,
}
```

### Priority

Message priority levels.

```rust
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum Priority {
    Low = 0,
    Normal = 1,
    High = 2,
    Critical = 3,
}
```

### ProtocolId

Identifies the message protocol.

```rust
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct ProtocolId(u32);
```

### ProtocolVersion

Version of the protocol.

```rust
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ProtocolVersion {
    pub major: u16,
    pub minor: u16,
    pub patch: u16,
}
```

## Process

### ProcessInfo

Public view of a process.

```rust
pub struct ProcessInfo {
    pub id: ProcessId,
    pub name: Option<String>,
    pub state: ProcessState,
    pub parent: Option<ProcessId>,
    pub children: Vec<ProcessId>,
    pub mailbox_depth: usize,
    pub started_at: Timestamp,
    pub messages_processed: u64,
}
```

### ProcessState

```rust
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ProcessState {
    Spawned,
    Running,
    Stopping,
    Stopped,
    Terminated,
    Failed,
    Restarting,
}
```

## Supervisor

### SupervisorInfo

```rust
pub struct SupervisorInfo {
    pub id: ProcessId,
    pub strategy: RestartStrategy,
    pub children: Vec<ChildInfo>,
    pub restart_counts: HashMap<ProcessId, usize>,
}
```

### ChildInfo

```rust
pub struct ChildInfo {
    pub id: ProcessId,
    pub name: String,
    pub state: ProcessState,
    pub restart_policy: RestartPolicy,
    pub restart_count: usize,
}
```

### RestartStrategy

```rust
pub enum RestartStrategy {
    OneForOne,
    OneForAll,
    RestForOne,
}
```

### RestartPolicy

```rust
pub enum RestartPolicy {
    Permanent,
    Temporary,
    Transient,
}
```

## Mailbox

### MailboxInfo

```rust
pub struct MailboxInfo {
    pub capacity: usize,
    pub depth: usize,
    pub backpressure: BackpressurePolicy,
}
```

### BackpressurePolicy

```rust
pub enum BackpressurePolicy {
    Reject,
    Block,
    DropLowPriority,
}
```

## Timer

### TimerInfo

```rust
pub struct TimerInfo {
    pub id: TimerId,
    pub process_id: ProcessId,
    pub scheduled_at: Timestamp,
    pub interval: Option<Duration>,
}
```

## Design Principles

1. **No leaked types** — Tokio, serde, or other crate types must not appear in public APIs.
2. **Serializable** — All public types must be serializable for persistence.
3. **Cloneable** — All public types must be cloneable for inspection.
4. **Debuggable** — All public types must implement Debug.
5. **Stable IDs** — All identifiers must be stable across restarts.