99 lines
3.4 KiB
Markdown
99 lines
3.4 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. Persistence, the graphical world, and development API are not
|
|
implemented yet.
|
|
|
|
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
|
|
```
|
|
|
|
It prints the feasibility results and local compilation/VM creation measurements.
|
|
See [the feasibility report](docs/rune-feasibility.md) for verified capabilities,
|
|
limitations, and [the runtime guide](docs/runtime.md) for the two-actor demo.
|
|
|
|
## 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-actor/ # Actor value contracts
|
|
│ ├── 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.
|