# Project Guidelines

## Project overview

Runa (short for **Rune Actors**) is an experimental Rust project whose long-term
goal is a persistent, live programming world built around isolated Rune actors.
The current workspace is a minimal Rust executable; Rune integration and the
actor runtime are not implemented yet.

The architecture, design goals, constraints, and implementation roadmap are
documented in [runa-spec-architecture.md](runa-spec-architecture.md). Treat
proposed capabilities as plans, not existing behavior.

## Architecture and constraints

- Keep actor identity, mailbox, private state, behavior implementation, and
  incarnation distinct as runtime work begins.
- Use message passing for normal actor interaction; do not introduce shared
  mutable actor state.
- Keep behavior implementations immutable and install updates at safe
  boundaries. Do not mutate active execution frames in place.
- Start with the Rune feasibility work in Phase 0. Verify APIs and capabilities
  against the actual Rune version before relying on them; do not claim
  interruption, preemption, durability, or delivery guarantees without tests.
- Build only the smallest workspace structure needed for the current milestone;
  the crate layout in the spec is proposed, not a requirement to create empty
  crates.

## Repository structure

- `Cargo.toml`: Rust workspace definition.
- `crates/runa/`: current executable crate and entry point.
- `runa-spec-architecture.md`: architecture, roadmap, risks, and acceptance
  scenario.
- `README.md`: project overview and current getting-started instructions.

## Commands

Run these from the repository root:

```sh
cargo fmt --all -- --check
cargo check --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
```

The current project is a minimal executable and may not yet have tests.

## Conventions

- Keep changes focused and follow existing Rust formatting and workspace
  conventions.
- Prefer verified Rune APIs and explicit runtime guarantees over assumptions.
- Keep the README and architecture spec aligned with implemented behavior;
  label planned capabilities as planned.
- Do not push changes unless explicitly asked.
- Check the current branch before committing. Use conventional commit messages
  and include the repository's configured Copilot co-author trailer.
- Run relevant formatting, build, lint, and test checks before committing code
  changes. Documentation-only changes do not require code checks.