68 lines
2.9 KiB
Markdown
68 lines
2.9 KiB
Markdown
# 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.
|