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