runact 1.3.3

A Rust-native actor runtime with BEAM-style processes
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
# Runact Roadmap

## Overview

This document outlines the development phases for Runact. Runact is the runtime; PaperOS is a separate editor project built on top of it.

---

## Current Status

| Component | Status | Tests |
|-----------|--------|-------|
| **Runact** (runtime) | v1.3.3 | 110 tests across lib unit, actor_task_integration, async_executor, async_timers, basic, cancellation, compute, observability, process_runtime, reactor, resource, scheduler, stress, tcp_api, timer (119 with `hot_code_loading`) |
| **runact-web** (HTTP) | v0.3.0 | 89 tests: HTTP request, response, headers, router, middleware/extractors; WebSocket frames, async I/O, server, chat, runact bridge, fragmentation, agent server/API |
| **Supervision** | ๐ŸŸก Partial | policy types + internal restart accounting; runtime child spawning/exit wiring pending |
| **Phase 9** (Runtime + Networking) | โœ… Complete | cancellation, timers, actor-async integration, process runtime, TCP reactor, TCP API, stress tests |
| **Phase 10** (HTTP) | โœ… Complete | HTTP/1.1 parsing, request/response types, headers |
| **Phase 12** (WebSocket) | โœ… Complete | Upgrade, frames, connection lifecycle, async I/O, heartbeats, runact TCP bridge, examples |

**Paper** (editor) โ€” Separate project, tracked at `paper/docs/roadmap.md`

Full development plan: [Development Plan](development-plan.md)

---

## Phase 0 โ€” Architecture โœ…

### Deliverables

- โœ… `docs/architecture.md` โ€” Full architectural document (v1.0.0)
- โœ… `docs/actors.md` โ€” Actor trait, ActorId, ActorContext
- โœ… `docs/actor-communication.md` โ€” 24 communication principles
- โœ… `docs/scheduler.md` โ€” BEAM-style scheduler with work stealing
- โœ… `docs/supervision.md` โ€” Supervision trees, restart strategies
- โœ… `docs/runtime.md` โ€” Runtime API, RequestHandle, RuntimeConfig
- โœ… `docs/vision.md` โ€” Vision and design priorities
- โœ… `docs/roadmap.md` โ€” This document
- โœ… `docs/async-runtime.md` โ€” Async runtime boundary: what Runact owns vs. what I/O libraries provide
- โœ… `docs/security.md` โ€” Capability-based security
- โœ… `docs/adr/0001-beam-style-scheduler.md` โ€” ADR for scheduler choice
- โœ… `docs/adr/0002-dual-scheduler-architecture.md` โ€” ADR for dual scheduler
- โœ… `docs/adr/0003-native-async-runtime.md` โ€” ADR for native Future executor (no Tokio core dependency)
- โœ… Single-crate structure

---

## Phase 1 โ€” Runtime Core โœ…

### Deliverables

- โœ… `src/actor/` โ€” ActorId, Actor trait, ActorContext
- โœ… `src/mailbox/` โ€” Mailbox with backpressure policies
- โœ… `src/scheduler/` โ€” BEAM-style scheduler with work stealing
- โœ… `src/runtime.rs` โ€” Top-level coordinator
- โœ… Message passing (fire-and-forget, request/reply)
- โœ… Actor-to-actor communication
- โœ… Graceful shutdown
- โœ… Reduction counting (cooperative preemption)

---

## Phase 2 โ€” Reliability ๐ŸŸก

### Deliverables

- โœ… `src/supervision/` โ€” Supervisor, ChildSpec, RestartStrategy
- โœ… One-for-one restart accounting with exponential backoff (`SupervisorActor`, internal)
- โœ… Restart limits (`max_restarts`, `within` window)
- โฌœ Runtime wiring: supervised child spawning and exit notification
- โฌœ Restart policy enforcement (`Permanent`/`Transient`/`Temporary`)
- โœ… Crash isolation for compute tasks

---

## Phase 3 โ€” Compute โœ…

### Deliverables

- โœ… `src/compute/` โ€” ComputeScheduler, ComputeHandle, ComputeError
- โœ… Bounded queue (soft limit via `queue_capacity`)
- โœ… Task submission from actors via `ctx.spawn_compute`
- โœ… Panic isolation at worker boundary
- โœ… `try_recv`/`recv_timeout` for non-blocking polling
- โœ… Cooperative cancellation via `ComputeHandle::cancel()`

---

## Phase 4 โ€” Timers โœ…

### Deliverables

- โœ… `src/timer/` โ€” TimerService, TimerHandle, TimerId
- โœ… One-shot timers (`schedule_timer`)
- โœ… Periodic timers (`schedule_interval`)
- โœ… Timer cancellation (`cancel_timer`)
- โœ… Actor-context timer scheduling (`ctx.schedule_timer`)
- โœ… Drift correction for periodic timers

---

## Phase 5 โ€” Resources and Capabilities โœ…

### Deliverables

- โœ… `src/resource/` โ€” ResourceHandle, Capability, ResourceRegistry
- โœ… Generic capability wrapper with owner tracking
- โœ… Type-safe resource registry (`TypeId`-based)
- โœ… Thread-safe resources (`Send + Sync`)

---

## Phase 6 โ€” Editor Runtime (PaperOS)

PaperOS is a separate project. Runact provides the foundation.

- โœ… Runact is runtime-independent of any editor
- โœ… APIs are stable and documented

---

## Phase 7 โ€” Async Runtime โœ…

Complete. Runact extends the runtime with a native async task system executing standard Rust `Future`s on its own executor, within the strict boundary defined by [Async Runtime](async-runtime.md): Runact schedules asynchronous work; I/O libraries define asynchronous work. See also [ADR-0003](adr/0003-native-async-runtime.md).

Implemented in the order defined by async-runtime.md ยง20:

### Deliverables

- โœ… Phase 1 โ€” `Task`, `TaskHandle`, Executor, future polling
- โœ… Phase 2 โ€” Runact waker, runnable queue, wake deduplication (atomic task state)
- โœ… Phase 3 โ€” Async task scheduler integration
- โœ… Phase 4 โ€” Cancellation (`CancellationToken`, task cancellation)
- โœ… Phase 5 โ€” Timers (`sleep()`, `timeout()`)
- ๐ŸŸก Phase 6 โ€” Actor โ†” async integration: tasks are spawned with `Runtime::spawn_task` from outside the actor; `ActorContext` has no `spawn`, so the actor receives results as ordinary messages (no direct `ctx.spawn` yet)
- โœ… Phase 7 โ€” Task groups (structured concurrency)
- โœ… Phase 8 โ€” Compute pool separation (CPU-heavy work off the async/actor workers)
- Phase 9 โ€” Optional runtime adapters (e.g. Tokio) only when a concrete library requires one (not implemented; no library requires it)

Success criteria:

- Pending async task consumes no worker execution time (async-runtime.md ยง22, invariant 7)
- Cancel 10,000 tasks without leaks; rapid spawn/cancel cycles stable
- 10,000-task and 100,000-wakeup stress tests pass (test list in async-runtime.md ยง21)
- Shutdown deterministically terminates all owned tasks within `shutdown_timeout`
- Fair mixed actor/async/compute workloads (invariant 9: CPU-heavy work never starves actors or async I/O)

---

## Phase 8 โ€” Programmability

Future work:

- Extension API
- Scripting integration
- Distributed actors (local semantics must be stable first)

---

## Phase 10 โ€” HTTP โœ…

Build:

```text
runact-web
```

Implemented:

- โœ… HTTP/1.1 `Request` parsing and encoding
- โœ… HTTP/1.1 `Response` parsing and encoding
- โœ… Case-insensitive `Headers` type
- โœ… `Method` enum (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)
- โœ… `StatusCode` enum with known codes + `Custom(u16)`
- โœ… 34 acceptance tests (headers, request, response)

See [Development Plan](development-plan.md) ยง48 Phase 9.

---

## Phase 11 โ€” Web Framework

Add:

```text
Router
Handlers
Middleware
Extractors
Streaming
Static files
```

### Status: ๐ŸŸก Partial

Implemented in `runact-web`:
- โœ… `Router` with path parameters (`:id`) โ€” `tests/router.rs` (11)
- โœ… Middleware chain and extractors โ€” `tests/middleware_extractors.rs` (8)
- โฌœ Streaming responses
- โฌœ Static file serving

See [Development Plan](development-plan.md) ยง48 Phase 10.

---

## Phase 12 โ€” WebSocket

Add:

```text
Upgrade
Frames
Connection lifecycle
Streaming
Backpressure
Cancellation
```

### Status: โœ… Complete

Implemented:
- โœ… RFC 6455 frame parsing/encoding (all opcodes, masking, extended lengths)
- โœ… WebSocket handshake (`Sec-WebSocket-Accept` with SHA-1 + base64)
- โœ… `WebSocketServer` โ€” generic over `S: Read + Write + SetReadTimeout + Send + 'static`
- โœ… `AsyncWebSocket` โ€” non-blocking frame I/O with reader/writer/ping threads
- โœ… `ConnectionWriter` with `send_text`, `send_binary`, `send_close`, `send_ping`, `send_pong`
- โœ… `WebSocketConfig` with `ping_interval` for heartbeat support
- โœ… `RunactTcpStream` adapter bridging `runact::net::tcp_api::TcpStream` to `Read`/`Write`
- โœ… `ServerEvent` enum (`Connected`, `Frame`, `Closed`, `Error`)
- โœ… Example binaries: `websocket_echo.rs`, `websocket_chat.rs`
- โœ… Tests: `ws_server.rs` (4), `async_websocket.rs` (5), `websocket.rs` (21), `ws_chat.rs` (1), `ws_runact_bridge.rs` (1)

See [Development Plan](development-plan.md) ยง48 Phase 11.

---

## Phase 13 โ€” Real Applications

Build:

```text
REST API
WebSocket server
AI agent server
Remote PaperOS server
```

### Status: โœ… Complete

**AI agent server** โ€” `examples/agent_server.rs` demonstrates the full agent lifecycle over WebSocket:
- `AgentActor` (runact `Actor`) wraps a pluggable `ModelAdapter`
- `RuntimeSender` delivers user messages from WebSocket callbacks to the actor
- Built on the `RunactTcpStream` bridge from Phase 12
- Integration test `ws_agent_server.rs` verifies end-to-end WebSocket echo through the actor

**REST API** โ€” `examples/agent_api.rs` demonstrates a REST API server using `Router` with runact's `TcpListener`:
- CRUD endpoints for agent sessions (`GET/POST /api/agents`, `GET/DELETE /api/agents/:id`)
- Shared `SessionStore` behind `Arc<Mutex<...>>` (would be an Actor in production)
- Integration test `ws_agent_api.rs` verifies all endpoints (status, create, get, delete, 404)

See [Development Plan](development-plan.md) ยง48 Phase 12.

---

## Phase 9 โ€” Runtime + Networking Extension โœ…

See [Runtime + Networking Plan](runtime-networking-plan.md) for the full design document.

This phase extends Runact into a small, Rust-native concurrency runtime for PaperOS desktop applications, remote AI-agent servers, and async network services.

### Core Principle

> Runact manages execution, concurrency, lifecycle, and low-level I/O readiness. Higher-level libraries implement protocols and applications.

### Deliverables

**Phase 9a โ€” Cancellation & Task Groups** โœ…
- `CancellationToken` โ€” cooperative cancellation
- `TaskGroup` โ€” structured concurrency
- Parent โ†’ child cancellation propagation

**Phase 9b โ€” Timers** โœ…
- `Runtime::sleep(duration)` โ€” associated function
- `Runtime::timeout(duration, future)` โ€” associated function
- Crossbeam channel-based implementation

**Phase 9c โ€” Actor โ†” Async Integration** โœ…
- `actor โ†’ spawn_task โ†’ result message`
- Actor remains responsive while async task waits

**Phase 9d โ€” Process Runtime** โœ…
- `src/process/` โ€” spawn processes, stdin/stdout/stderr
- Exit status, timeout, cancellation, graceful termination
- Prevent orphaned processes on agent cancellation

**Phase 9e โ€” TCP Reactor** โœ…
- `src/net/` โ€” native TCP with an `epoll` reactor
- Linux `epoll` first, abstraction for future platforms
- `TcpListener`, `TcpStream`, read/write/connect/accept

> **Implementation status (v1.3.3):** the reactor exists and sockets are
> registered with it, but stream I/O polls the socket (`read`/`read_exact`)
> rather than waiting on reactor readiness; `Reactor::wait` is not yet wired
> into `TcpStream`.

**Phase 9f โ€” Stress Testing** โœ…
- 500 concurrent TCP connections
- Mixed workloads (actors + tasks + TCP + compute)
- Slow/fast clients, partial writes, cancellation

### Architectural Invariants

1. Runact is NOT an HTTP/WebSocket/TLS framework
2. Runact is NOT an AI framework
3. Runact executes standard Rust futures
4. Actors and async tasks remain distinct concepts
5. CPU-heavy work uses the compute pool
6. Async I/O never blocks an actor worker
7. Cancellation is cooperative
8. Structured concurrency prevents orphaned tasks
9. TCP is the lowest-level network primitive
10. HTTP/WebSocket remain outside Runact
11. Tokio is optional, not fundamental
12. Runact must remain useful independently of PaperOS

### Success Criteria

- Parent cancellation reaches all children
- Pending timers consume no worker time
- Actor remains responsive while async task waits
- Cancelled agent cannot leave orphaned processes
- TcpStream can asynchronously wait for readiness
- Multiple concurrent TCP connections work without blocking workers
- No orphaned tasks, no orphaned processes

### Crate Architecture (future)

```text
runact/
โ”œโ”€โ”€ runact-core/      # actors, mailbox, scheduler, supervision
โ”œโ”€โ”€ runact-runtime/   # executor, tasks, wakers, cancellation, timers
โ”œโ”€โ”€ runact-compute/   # CPU-heavy work pool
โ”œโ”€โ”€ runact-net/       # TCP, reactor, readiness, sockets
โ””โ”€โ”€ runact-process/   # process lifecycle, stdin/stdout/stderr
```

---

## Timeline

```text
Now โ”€โ”€โ”€โ”€โ”€โ”€โ”€ v0.5 โ”€โ”€โ”€โ”€ v0.6 โ”€โ”€โ”€โ”€ v0.7 โ”€โ”€โ”€โ”€ v0.8 โ”€โ”€โ”€โ”€ v0.9 โ”€โ”€โ”€โ”€ v1.0
            โ”‚         โ”‚         โ”‚         โ”‚         โ”‚         โ”‚
            โ”‚         โ”‚         โ”‚         โ”‚         โ”‚         โ””โ”€ Runact v1.0
            โ”‚         โ”‚         โ”‚         โ”‚         โ””โ”€ Benchmarks
            โ”‚         โ”‚         โ”‚         โ””โ”€ Documentation
            โ”‚         โ”‚         โ””โ”€ Robustness (backpressure, restart)
            โ”‚         โ””โ”€ Observability (tracing, metrics)
            โ””โ”€ API Hardening (typed messages, error types)
```

---

## Success Metrics

### Runtime

- 100K+ concurrent actors (benchmarked in `benches/runact_bench.rs`)
- Message latency < 10ฮผs (request-reply benchmarked)
- Work stealing across cores (scheduler tests)
- No starvation (reduction counting)
- Memory per actor < 1KB (RSS tracking benchmarked)
- Supervisor restart accounting: verified by `supervisor_actor.rs` unit tests (runtime-level restart wiring pending)
- Crash isolation: verified (compute tests)

---

## Long-Term Evolution

```text
Runtime Core
    โ†“
Reliability (Supervision)
    โ†“
Compute Pool
    โ†“
Timers and Cancellation
    โ†“
Resources and Capabilities
    โ†“
Async Runtime (Future Executor, Task Groups)
    โ†“
Process Runtime
    โ†“
TCP Networking (Reactor, TcpListener, TcpStream)
    โ†“
HTTP (runact-web)
    โ†“
Web Framework (Router, Middleware, Extractors)
    โ†“
WebSocket
    โ†“
Real Applications (REST API, AI Agent Server, PaperOS)
```

The runtime must earn every layer of complexity.

See [Development Plan](development-plan.md) for the full 53-section architecture document.