IAmHardliner
/
runa
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
runa/AGENTS.md

2.4 KiB
Raw Blame History

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

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.