runa/README.md

Runa — Rune Actors

Runa (short for Rune Actors) is an experimental project to build a persistent, live programming world around isolated actors written in Rune. The long-term vision combines an inspectable graphical environment with a programmatic API and a VS Code extension, all connected to the same running image.

Status

Runa is at an early prototype stage. The executable runs a Phase 0 feasibility experiment using Rune 0.14.2: script execution, native calls, async suspension, instruction budgets, stepping, and compiled-code sharing. It also runs a minimal single-worker actor demonstration with bounded mailboxes and explicit message effects. Source and compiled implementation identities are BLAKE3 content addresses with an in-memory compile cache. Persistence, interactive behavior editing, canonicalization, the graphical world, and development API are not implemented yet. The code library now supports an in-memory versioned behavior registry, and the runtime can install an implementation at an idle handler boundary; these operations are not yet exposed in the CLI.

The prototype uses worker-local invocation stacks and cooperative instruction slices. Native callbacks are not preemptible.

Design goals

• Keep actor identity, mailbox, private state, behavior, and incarnation separate.
• Use message passing rather than shared mutable state for actor interaction.
• Keep behavior implementations immutable and support safe, versioned updates.
• Expose the same runtime capabilities to in-world tools and external clients.
• Be explicit about execution, delivery, and persistence guarantees.

See the architecture spec for the full vision, architecture, roadmap, and open questions.

Getting started

You need a Rust toolchain that supports the workspace's Rust 2024 edition.

Run the current executable from the repository root:

mise run run

This opens an interactive runtime session using the default counter behavior:

runa> spawn 0
spawned ActorId(1)
runa> spawn 10
spawned ActorId(2)
runa> send 1 1 2
message queued
runa> tick 100
runa> inspect 1
runa> inspect 2
runa> events

The sender commits state 1 and sends a message to actor 2, which commits state 15. The CLI also supports publishing Rune source files as named, versioned behaviors, viewing history, rolling back a behavior reference, installing the current version on an idle actor, and cooperatively pausing and resuming or cancelling actor invocations between scheduler ticks. Runtime users can also supply an explicit state migration closure during installation; the CLI's install command preserves state as-is. Use help in the session for the complete command list. See the feasibility report for verified Rune capabilities and limitations, and the runtime guide for the runtime contract.

Development

Install mise and run mise install to install Tombi. Rust, rustfmt, and Clippy must also be available on your PATH.

mise run format
mise run lint
mise run test
mise run pre-commit

The pre-commit task runs formatting, linting, and tests in that order, stopping on the first failure. Run it successfully before committing and review any formatter changes. This is a task, not an automatically installed Git hook.

Tombi formats TOML files offline; rustfmt formats all workspace Rust code. Clippy checks all workspace targets with warnings treated as errors, and the test task runs cargo test --workspace.

Project structure

.
├── Cargo.toml
├── crates/
│   ├── runa/             # Main binary
│   ├── runa-core/        # Shared stable identity types
│   ├── runa-actor/       # Actor value contracts
│   ├── runa-code/        # Source identities and compile cache
│   ├── runa-rune/        # Phase 0 Rune experiments
│   └── runa-runtime/     # Single-worker actor prototype
├── docs/
│   ├── architecture.md
│   └── decisions/
├── runa-std/
│   ├── core/
│   ├── actors/
│   ├── ui/
│   └── tools/
├── scripts/
├── vscode/
├── examples/
└── tests/

runa-std/ is reserved for the default Rune scripts loaded into an image. scripts/ is for general-purpose development automation. Root-level tests/ is reserved for system and end-to-end tests; it is not automatically discovered by Cargo. Add an explicit runner when those tests are introduced, keeping Rust crate integration tests within each crate.

Only the Phase 0 and minimal Phase 1 crates are present. Remaining crates will be added as their functionality is implemented.