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

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

3.3 KiB Raw Blame History