/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, 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.

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. Baseline as of mid-2026: a recent stable Rust toolchain (verify the current release at blog.rust-lang.org), edition 2024 (next edition expected ~2027), tokio still 1.x. 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, or spawning an external program? Load 05. Writing any `unsafe`? Load 03 — no exceptions. 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, `#[allow(lint, reason = "...")]`). 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 §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 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

When reviewing or auditing existing Rust:

1. **Recon first:** `cargo metadata`/workspace layout, `Cargo.toml` profiles and features, CI config, `rg 'unsafe' --count-matches`, dependency tree (`cargo tree -d`). 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 on untrusted lengths, cancellation data loss, deadlock (`block_on` in async, lock across await), unbounded channels fed by network, missing dep-audit in deployed-service CI | | **Medium** | Latent defect or eroded defense | missing SAFETY comments, no Miri CI on unsafe crate, swallowed errors (`.ok()`, `filter_map(Result::ok)`) uncommented, untested MSRV, non-additive features, orphaned spawned tasks | | **Low** | Hygiene, idiom, maintainability | clone-to-satisfy-borrowck, index loops, missing `#[non_exhaustive]`, missing `# Errors` docs, blanket `#[allow]` without reason |

Severity scales with **reachability** (attacker-controlled > user > operator > build-time) and **blast radius** (process death > request failure > slow).

Finding format

[SEVERITY] short title
  Where: path/to/file.rs:123 (fn name / module)
  What:  the defect, in one or two sentences
  Why:   concrete consequence (exploit path, failure mode, cost)
  Fix:   specific change — code sketch or named pattern from rules/NN
  Effort: trivial | small | medium | large
  Refs:  rules/NN §M; clippy lint or RUSTSEC id if applicable

Group findings by severity, Critical first. End with: checklist coverage (which rules files were applied), what was *not* reviewed, and quick wins (one-line fixes with outsized value).

Rules index

| File | Read this when... | |---|---| | [rules/01-ownership-and-api-design.md](rules/01-ownership-and-api-design.md) | Designing structs/traits/modu