---
name: rust
description: Implements and tests Rust changes with ownership, Cargo, feature, and async checks. Use when editing or creating .rs files, Cargo.toml, Cargo.lock, or when the user mentions Rust, borrow errors, crates, or an async runtime.
---

1. Before editing, run `rustc -Vv` and `cargo -V` from the workspace. Read `rust-toolchain.toml` or its legacy equivalent, `Cargo.toml`, `Cargo.lock`, `.cargo/config.toml`, and CI. Establish edition, minimum supported Rust version (MSRV), workspace default members, targets, features, and async runtime versions. The local compiler and edition do not establish the MSRV. Do not raise `rust-version` or use newer APIs to make a patch easier.

2. For implementation or Cargo changes, read [the shared procedure](../python/references/common.md). Trace ownership, borrows, and public error contracts through consumers. Prefer borrowing when ownership is unnecessary and `Result` or `Option` with propagation for expected failures. Do not silence a borrow error with gratuitous clones, `Arc<Mutex<_>>`, leaked values, or `unsafe`. Preserve public trait bounds, lifetimes, and `Send`/`Sync` behavior. Avoid `unwrap` or `expect` on external input.

3. For async code, identify the executor, task owner, cancellation, and shutdown behavior. Do not hold blocking mutex guards across `.await` or perform blocking I/O on the executor. Use the runtime's established blocking-work mechanism. Dropping an ordinary future stops polling it but does not undo external side effects. Tokio detaches a spawned task when its `JoinHandle` is dropped. Verify the installed runtime's abort and join contract, including non-abortable blocking work, and test cancellation, early failure, and resource release. Do not assume Rust's `Drop` can await asynchronous cleanup.

4. For unsafe or FFI changes, establish pointer validity, aliasing, ownership, ABI, and lifetime invariants at the caller boundary. Prefer an existing safe interface and minimize the unsafe region. Use Miri or sanitizers only when the risk and supported environment justify them. Compilation does not prove unsafe invariants or freedom from deadlock.

5. Preserve the workspace's lockfile policy. For locked projects use `--locked` for Cargo check, build, and test commands to reject silent resolution changes. It errors if the lock is absent. For an authorized dependency change, update the manifest and resolve through Cargo, limiting an update to `cargo update -p PACKAGE` when appropriate. Review transitive changes, features, target-specific dependencies, and MSRV. Do not regenerate the whole graph or use `--ignore-rust-version` to conceal incompatibility.

6. Before reporting, run `cargo fmt --check`, configured `cargo clippy`, `cargo check --locked`, `cargo build --locked`, and `cargo test --locked`, scoped to affected workspace packages and material target/feature combinations using the repository's flags. Use the applicable non-locked form only when the project intentionally has no lock. Honor existing warning policy. Do not enable all features unless they can coexist. Check consumers and documentation tests for library API changes, using `cargo test --doc --locked` when other target selection excluded them. `cargo check` skips final code generation and cannot replace a build or executed tests. Confirm filtered tests actually ran.

Consult [ownership](https://doc.rust-lang.org/book/ch04-01-what-is-ownership.html), [Cargo tests](https://doc.rust-lang.org/cargo/commands/cargo-test.html), [Clippy](https://doc.rust-lang.org/clippy/usage.html), and the installed runtime's documentation when those contracts change.