# 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 current repository contains a minimal
Rust executable and a scaffold for the Rune adapter library; the actor runtime,
Rune integration, graphical world, and
development API described in the architecture spec are planned, not yet
implemented.

The first milestone is to evaluate Rune's embedding, async execution,
interruptibility, and debugging capabilities before building the actor kernel.

## 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
```

At this stage, it prints `Hello, world!`.

## 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-rune/        # Phase 0 Rune adapter scaffold
├── 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 crates are scaffolded. The remaining crates in the spec will
be added as their functionality is implemented.