runa/AGENTS.md

# 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 contains a minimal Rust executable and a Rune adapter
scaffold; Rune integration and the actor runtime are not implemented yet.

The architecture, design goals, constraints, and implementation roadmap are
documented in [docs/architecture.md](docs/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.
- `crates/runa-rune/`: Phase 0 Rune compilation and execution adapter scaffold.
- `docs/architecture.md`: architecture, roadmap, risks, and acceptance scenario.
- `docs/decisions/`: architectural decisions.
- `runa-std/`: default Rune scripts for an image.
- `scripts/`: general-purpose development automation.
- `tests/`: system and end-to-end tests; require an explicit runner rather than
  assuming Cargo discovers tests at a virtual workspace root.
- `examples/` and `vscode/`: reserved for examples and the VS Code extension.
- `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.