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
mise run format
mise run lint
mise run test
mise run pre-commit
```

`mise run pre-commit` runs format, lint, and test sequentially, stopping on
failure. Formatting uses the repository's Tombi and rustfmt configurations.
Clippy checks all workspace targets and treats warnings as errors.

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.
- Add user-visible changes to the project's Unreleased changelog section using
  its established format before you commit something, creating that section if needed.
- Before every commit, including documentation-only commits, run
  `mise run pre-commit` and require a successful exit. Fix all reported
  formatting, lint, and test problems, then rerun the task until it passes.
  Do not bypass checks or suppress diagnostics merely to make a commit pass.
- Review and stage formatter changes before committing. If further changes
  are made after validation, rerun `mise run pre-commit` before committing.