/sota-rust

name: sota-rust
description: >-
  State-of-the-art Rust engineering (2026) for writing and auditing Rust code.
  Covers idiomatic ownership and API design, error handling and panic policy,
  unsafe discipline with Miri, formal verification (Kani proof harnesses, Flux
  refinement types), async/tokio (cancellation safety, structured
  concurrency, graceful shutdown), security and supply chain (cargo
  audit/deny/vet, integer overflow, serde hardening, zeroize), performance
  (profiling, allocation reduction, release profiles), and tooling/CI (clippy
  policy, nextest, MSRV, feature hygiene, edition 2024). Use when writing new
  Rust code, reviewing or auditing existing Rust, designing crate APIs,
  debugging borrow checker or Send/Sync errors, or hardening Rust services.
  Triggers: Rust, cargo, crate, tokio, unsafe, lifetime, borrow checker,
  clippy, async Rust, Cargo.toml, thiserror, anyhow, serde, Miri, MSRV,
  std::process::Command, subprocess, spawn a process, Kani, cargo kani, flux-rs,
  formal verification, proof harness.

SOTA Rust (2026)

Purpose

This skill encodes the 2026 state of the art for production Rust: the idioms, security posture, performance discipline, and CI baseline expected of an expert Rust codebase. It assumes a recent stable Rust toolchain, edition 2024 (Rust ≥1.85; next edition expected ~2027), and the tokio 1.x API. Verify the latest toolchain release at blog.rust-lang.org. It serves two modes — **BUILD** (write new code to this standard) and **AUDIT** (find where existing code falls short, with severity and evidence). The detailed rules live in `rules/*.md`; load only the files relevant to the task (see index below). Every rules file ends with an "Audit checklist" of grep/clippy patterns — use those verbatim in AUDIT mode.

BUILD mode

When writing or modifying Rust code:

1. **Scope the work, load the rules.** Pick the relevant `rules/` files from the index. Touching async code? Load 04. Adding a dependency, parsing network input? Load 05. Spawning an external program? Load 08. Writing any `unsafe`? Load 03 — no exceptions. Proving a parser, decoder or arithmetic function panic- and overflow-free, or touching any `#[kani::*]` or Flux `#[spec]`? Load 09. 2. **Design types first.** Newtypes for domain primitives, errors per subsystem (thiserror for libs, anyhow for apps), ownership tree before `Arc<Mutex<_>>`, public API minimal and borrowed (`&str`/`&[T]` params). Parse, don't validate: constructors enforce invariants. 3. **Write to the non-negotiables** (bottom of this file) without being asked. They are defaults, not suggestions; deviations carry a written justification at the site (e.g. `expect` with invariant message, `#[expect(lint, reason = "...")]`, which fails once the exception is stale; [rules/07](rules/07-tooling-ci.md) §1). 4. **Wire the scaffolding with the code**, not after: lints in `[lints]`, `deny.toml` + `cargo deny` in CI for anything deployed, Miri job if unsafe exists, nextest, MSRV declared and tested, benches for claimed-hot paths. See [rules/07](rules/07-tooling-ci.md) §9 for the CI shape to copy. 5. **Verify before claiming done:** `cargo fmt --check`, `cargo clippy --all-targets --all-features -- -D warnings`, `cargo nextest run` + `cargo test --doc`, and `cargo doc` warning-free for libraries. If you wrote unsafe: `cargo +nightly miri test` over it. If the crate has Kani harnesses: run them (no `cargo kani` here? ask the operator to install it, router principle 6, rather than skip) through the cover gate ([rules/09](rules/09-formal-verification.md) §4) — a bare `cargo kani` passes vacuous proofs. If you claimed performance: show the benchmark. 6. **Comment intent at decision points** the next reader will question: justified clones, cancel-safety of `select!` arms, SAFETY comments, channel-capacity choices, poisoning policy.

AUDIT mode

**Coverage:** every `rules/` file's Audit checklist applies in AUDIT mode. Mark one *not applicable* only with its reason in the report — never skip a file because the thing it checks for is absent, since that absence may be the finding.

When reviewing or auditing existing Rust:

1. **Recon first:** `cargo metadata`/workspace layout (in a checkout you do not trust, every cargo command runs its `rustc-wrapper` and `[build] rustc`, a toolchain its `rust-toolchain.toml` names by path, and a registry credential provider: pin `RUSTUP_TOOLCHAIN` first, then both, and read with `--no-deps`, [rules/07](rules/07-tooling-ci.md) §4a), `Cargo.toml` profiles and features, CI config, `rg 'unsafe' --count-matches`, dependency tree (`cargo tree -d`), and `rg -c 'kani::|flux_rs' -t rust .`. Load 09 when proofs are present (audit them as controls that can pass vacuously) **or** when a security-critical crate parses untrusted input or wraps `unsafe` behind a safe API (§1 decides whether a missing harness is a finding). This decides which rules files to load and where risk concentrates (network input? unsafe? async service?). 2. **Run the audit checklists** at the end of each loaded rules file — they are ordered grep/clippy hunts with pre-calibrated severities. 3. **Validate every finding**: read the surrounding code; a grep hit is a lead, not a finding. Confirm reachability (is the unwrap on an attacker-influenced path?) before assigning severity. 4. **Report with the finding format below.** Prefer few, true, prioritized findings over volume. Note positive observations where the code is already SOTA (prevents "fixes" that regress good decisions).

Severity conventions

| Severity | Meaning | Examples | |---|---|---| | **Critical** | Exploitable now, or UB | reachable UB, unsound safe API, SQLi/path traversal, authn bypass, unwinding across FFI, secrets in logs+repo | | **High** | Exploitable under realistic conditions, or correctness loss | attacker-reachable panic/OOM (DoS), wrapped arithmetic o