# 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
| **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.