systems-rust

name	systems-rust
description	Deliver Rust systems work across services, CLIs, WASM, and FFI while keeping ownership, async runtime, safety, and performance constraints explicit.

Systems Rust

Use this pack for Rust systems work: performance-sensitive services, async runtimes, command-line tools, WebAssembly modules, native extensions, and cross-language boundaries where memory safety and throughput both matter.

Defer first-pass route choice and lane selection to ../../reference/routing-guidance.md.

This is the general Rust family pack for the repo. Use reference/axum-actix-wasm.md for Axum, Actix, and broad browser-facing WASM delivery. Use reference/wasm-browser-3d-performance.md only when browser-3D work already owned by frontend-web crosses a measured compute or transfer bottleneck and needs a narrow Rust/WASM escalation path.

Setup posture

• Prefer modernizing, refining, or extending an existing project in place.
• Treat scaffold, create, init, or new flows as greenfield-only and explicit-request-only. Defer to reference/project-setup-policy.md.

Core focus

• Design ownership, borrowing, lifetimes, and crate boundaries so the data flow stays readable under change.
• Keep async runtime choices, task cancellation, channels, and backpressure explicit instead of hiding them behind helper layers.
• Treat WASM and FFI boundaries as contracts with typed inputs, serialization choices, and memory ownership rules.
• Optimize for high performance with zero-copy paths, predictable memory layout, profiling, and measured concurrency decisions.
• Keep error handling, tracing, testing, and release builds aligned with safe operational delivery.

Shared Rust systems standards

• Keep unsafe blocks, FFI shims, and boundary conversions narrow, visible, and easy to audit.
• Separate transport, runtime, and platform glue from reusable domain or library code.
• Use wasm-bindgen, PyO3, cbindgen, uniffi, or similar boundary tooling deliberately, keeping ownership and type conversion explicit.
• Make target-specific code, feature flags, and cross-compilation assumptions visible in workspace or crate boundaries.
• Use benchmarks, tracing, and representative load tests before claiming a performance win.

Default workflow

1. Inspect the workspace layout, crate graph, toolchain pinning, target platforms, and runtime model.
2. Choose the Rust-specific overlay in reference/axum-actix-wasm.md or, for measured browser-3D escalation work owned by frontend-web, reference/wasm-browser-3d-performance.md.
3. Define ownership, async behavior, boundary contracts, and target assumptions before broad implementation.
4. Implement crates, boundary code, tests, and benchmarks together so safety and performance stay aligned.
5. Run review skill after substantial Rust systems changes.

Collaboration in this repo

• Use research tools or the built-in Explore behavior before editing so new work matches local crate, module, and target-platform patterns.
• Use research tools, Context7, or equivalent knowledge retrieval when framework APIs, interop details, or platform constraints need a source-of-truth check.
• Use review skill when Rust, WASM, or FFI changes materially affect safety, throughput, or integration behavior.

Overlays

• reference/axum-actix-wasm.md for extractor and middleware choices in Rust HTTP services plus WASM boundary guidance for browser-facing performance work.
• reference/wasm-browser-3d-performance.md for escalation-only browser-3D WASM bottlenecks where measured geometry, simulation, parsing, or transfer pressure justifies the boundary.

Guardrails

• Do not hide ownership transfers or allocation-heavy boundary conversions inside convenience helpers.
• Do not mix runtimes, blocking calls, and async assumptions casually across the same request or worker path.
• Do not cross WASM or FFI boundaries with unstable layouts, implicit copies, or poorly defined error contracts.