122 lines
4.2 KiB
Markdown
122 lines
4.2 KiB
Markdown
# 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](docs/architecture.md) 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:
|
|
|
|
```sh
|
|
cargo run -p runa
|
|
```
|
|
|
|
This opens an interactive runtime session using the default counter behavior:
|
|
|
|
```text
|
|
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`. Use `help` in the session for the complete command list.
|
|
See [the feasibility report](docs/rune-feasibility.md) for verified Rune
|
|
capabilities and limitations, and [the runtime guide](docs/runtime.md) for
|
|
the runtime contract.
|
|
|
|
## Development
|
|
|
|
Install [mise](https://mise.jdx.dev/) and run `mise install` to install Tombi.
|
|
Rust, rustfmt, and Clippy must also be available on your PATH.
|
|
|
|
```sh
|
|
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
|
|
|
|
```text
|
|
.
|
|
├── 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.
|