Effective Rust
Write clean, idiomatic, and robust Rust aligned with Sjel doctrine, Effective Rust principles, and high-performance systems engineering (Polars, Tokio, Vector standards).
Zero-context ground truth: verify with cargo check --workspace and cargo test -p <crate>.
Core Invariants
- Safe Rust by Default: The root workspace is 100% safe Rust (
unsafe_code = "deny"). Nounsafecode without a benchmark proving necessity, an explicit authorization, and a documented// SAFETY:contract (PRD Q77). - Backend Logic Defaults to Rust: New backend logic is written in Rust before shell, Python, or TypeScript.
- One Database, Table Prefixes: Persistent capabilities open SQLite through
sjel-storeusing assigned table prefixes (<prefix>_<table>) andmigrate_once. Never run unpooled, unmigrated raw DDL. - Mechanical Sympathy: Pre-allocate known capacities (
Vec::with_capacity), avoid false sharing with cache line padding, and write branchless code for autovectorization. - Resilient Concurrency: Bounded channels only; cancel-safe
tokio::select!branches; no synchronous blocking calls on async worker threads; no blindOrdering::SeqCst.
The 5 Systems Disciplines
1. Soundness & Unsafe Guardrails (The Rustonomicon Standard)
- Default to 100% safe Rust.
- Every
unsafeblock must have an explicit// SAFETY:comment detailing:- Preconditions (pointer validity, non-null, alignment).
- Invariants preserved.
- Aliasing & Provenance (Stacked/Tree Borrows proof).
- No raw uninitialized memory (
mem::zeroed); mandatestd::mem::MaybeUninit<T>. - Use strict pointer provenance APIs (
.wrapping_add(),.with_addr(),.cast()) overusize as *mut T. - Validate unsafe code with
cargo miri test. - Read
references/unsafe-and-soundness.md.
2. Hardware-Sympathetic & Data-Oriented Design (The Polars Standard)
- Use Struct of Arrays (SoA) over Array of Structs (AoS) for analytics and batch engines.
- Align hot data and shared atomics to 64 bytes using
crossbeam_utils::CachePaddedto prevent false sharing. - Forbid hidden allocations in hot loops; always pre-allocate with
Vec::with_capacity(N)when bounds are known. - Leverage Apache Arrow columnar layouts (
arrow,parquet) for structured data. - Read
references/data-oriented-and-cache.md.
3. High-Throughput Async & Backpressure (The Vector Standard)
- Never use unbounded channels (
tokio::sync::mpsc::unbounded_channel). Always use bounded channels to propagate backpressure. - Ensure all branches in
tokio::select!are cancellation-safe. - Offload blocking I/O (SQLite, disk, CPU-heavy operations) strictly via
tokio::task::spawn_blocking. - Avoid blind
Ordering::SeqCst; specify explicitAcquire,Release, orRelaxedordering with rationale. - Never hold
std::sync::MutexGuardacross an.awaitboundary; preferparking_lot::Mutexortokio::sync::Mutex. - Read
references/async-and-concurrency.md.
4. Ergonomic Type-System Modeling & Zero-Cost Abstractions
- Model state machines using the Type-State pattern (
Order<Draft>->Order<Confirmed>) to make illegal states unrepresentable. - Parse, don't validate: wrap primitives into Newtypes (
StationId,PlanId). - Maximize zero-copy transformations with
Cow<'a, str>and#[serde(borrow)]. - Define fine-grained error hierarchies with
thiserrorand convert them into Axum HTTP responses withIntoResponse. - Read
references/type-state-and-modeling.mdandreferences/error-architecture.md.
5. Automated Verification & Adversarial Testing
- Write property-based tests using
proptestfor parsers, numerical routines, and state machines. - Validate lock-free primitives and atomic interleavings with
loom. - Run fuzz testing (
cargo-fuzz) on untrusted data boundaries. - Verify clean compiler and linter passes with
cargo clippy --workspace --testsandcargo check --workspace. - Read
references/verification-and-testing.md. - Keep panics out of fallible input and runtime paths; use checked arithmetic when overflow is a meaningful failure. See
references/error-architecture.md. - Measure performance changes against a repeatable baseline before optimizing; profile to find the cost first. See
references/data-and-performance.md.
Reference Routing
| Topic | Reference |
|---|---|
| Sjel placement, workspace dependencies, safety rules | references/core-doctrine.md |
Unsafe rules, // SAFETY:, provenance, MaybeUninit, Miri |
references/unsafe-and-soundness.md |
| Cache alignment, SoA, capacity budgets, SIMD, Arrow | references/data-oriented-and-cache.md |
| Bounded channels, cancellation safety, thread budgeting, atomics | references/async-and-concurrency.md |
Typestates, Newtypes, Cow, #[serde(borrow)] |
references/type-state-and-modeling.md |
Domain errors, thiserror, Axum IntoResponse |
references/error-architecture.md |
Property testing (proptest), loom, cargo-fuzz, verification |
references/verification-and-testing.md |
| Panics, checked arithmetic, performance measurement | references/error-architecture.md · references/data-and-performance.md |
For GPUI-specific view, entity, event, platform, or source-version questions, use the sibling gpui skill. Keep this skill responsible for Rust safety and general Rust quality.