---
applyTo: "**/*.rs,**/Cargo.toml,**/Cargo.lock"
---

# Rust Instructions — Syn_OS Development

## Project Context

Syn_OS is a sovereign AI-assisted Cognitive Hyper-OS built on Arch Linux.
Current state: v21 "First Breath" — 92 crates, custom kernel modules, GRIMOIRE gamified training system.
Repo path on <node>: `<repo-path> Lib\stuff\Development\Syn_OS{Master Repo}`

## Rust Edition and Toolchain

- Rust 2021 edition
- Stable toolchain preferred, nightly only for documented features
- Target: `x86_64-unknown-linux-gnu` (primary), cross-compile configs for ARCANUM nodes

## Code Style

- Run `cargo fmt` before every commit — no exceptions
- Enable `clippy::pedantic` in all crates
- Prefer `thiserror` for library errors, `anyhow` for binary/CLI errors
- Use `tracing` over `log` for structured logging
- Prefer `tokio` for async runtime (single-threaded where possible to conserve resources)

## Safety Rules

- No `unsafe` blocks without:
  1. A documented justification comment explaining why safe alternatives are insufficient
  2. An Aegis (SAST agent) audit pass
  3. A `// SAFETY:` comment block per Rust convention
- Minimize FFI surface area — wrap all C interop in safe abstractions
- Use `cargo deny` for license and vulnerability audits on all dependencies
- Use `cargo audit` in CI for known vulnerability detection

## Performance Constraints

- <node> has <ram> RAM and <cpu> — be memory-conscious
- Prefer `cargo check` over `cargo build` during development iteration
- Use incremental compilation (default, but don't disable it)
- Profile before optimizing — use `cargo flamegraph` for hot path analysis
- Avoid unnecessary allocations in hot paths — prefer stack allocation and borrowing

## Crate Organization

- Each crate must have a clear single responsibility documented in its Cargo.toml description
- Workspace-level dependency management via `[workspace.dependencies]`
- Feature flags for optional functionality — don't compile what you don't need
- Internal crates use path dependencies, external crates use version pinning

## Testing

- Unit tests in the same file (`#[cfg(test)]` module)
- Integration tests in `tests/` directory
- Use `proptest` or `quickcheck` for property-based testing on parsers and data structures
- Minimum code coverage target: 60% for new crates, improving over time
- Vanguard (QA agent) runs test suites as part of the /audit pipeline

## Documentation

- All public items must have doc comments (`///`)
- Include `# Examples` section in doc comments for non-trivial functions
- Run `cargo doc --no-deps` to verify documentation builds cleanly
- README.md in each crate root with architecture overview

## Dependency Policy

- Audit all new dependencies with `cargo deny check` before adding
- Prefer crates with: >1000 downloads, active maintenance, permissive license (MIT/Apache-2.0)
- Document the reason for each dependency in Cargo.toml comments
- No pre-1.0 crates in critical paths without stability justification