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, canonicalization,
remote network access, graphical world, and VS Code extension are not
implemented yet. The code library now supports an in-memory versioned behavior
registry, and the CLI exposes publishing, history, rollback, safe-boundary
installation, pause/resume, and cancellation through a trusted in-process image
API. A versioned transport-neutral protocol contract is now defined, but no
authentication is implemented. The dispatcher is available through local
JSON-lines stdio and an unauthenticated TCP listener restricted to localhost;
both use a bounded request size. The interactive CLI now uses the versioned
protocol and dispatcher rather than calling the image API directly.

The prototype uses worker-local invocation stacks and cooperative instruction
slices, and actor snapshots report basic active-execution progress. Native
callbacks are not preemptible; source-level debugging and persistent storage
are not implemented.

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

For a local child-process protocol endpoint, run `mise run serve` and exchange
one JSON request per line on stdin; responses are written to stdout. Request
lines are limited to 1 MiB.

For a TCP endpoint, run `mise run serve-network`. It listens on
`127.0.0.1:3737` and accepts the same JSON-lines protocol, with up to 16
simultaneous clients sharing one live image. The listener rejects non-loopback
addresses and has no authentication; any local process that can connect has
full access to the development API. Use it only on a trusted local machine.

The `runa-client` crate can launch the stdio process and exchange typed
protocol requests with request/response correlation. The VS Code extension is
intended to connect over the network to this same live image; actors remain in
the image regardless of how clients connect. Remote network access requires
authentication and authorization, which are not implemented.

The CLI 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`. 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](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
│   ├── runa-image-api/   # Trusted in-process image operations
│   ├── runa-protocol/    # Versioned transport-neutral wire DTOs
│   ├── runa-server/      # Protocol dispatcher and local JSON-lines transport
│   └── runa-client/      # Local child-process protocol client
├── docs/
│   ├── architecture.md
│   ├── protocol.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.