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. 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:

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.