Rust style rules

When you write or change Rust code in this project:

Tooling

• Code must pass cargo fmt and cargo clippy --all-targets with no warnings under the project's lint settings.
• Never silence a lint crate-wide. Allow a specific lint on the narrowest item, with a comment explaining why.
• Use the edition and minimum Rust version in Cargo.toml. Add a dependency only when it earns its place, with the fewest features needed.

Ownership and APIs

• Borrow in parameters when the function does not keep the value: &str, &[T], &Path or impl AsRef<Path>. Take ownership (String, Vec<T>) when the value is stored.
• Do not add .clone() just to satisfy the borrow checker. Restructure the code first, and when a clone is the right answer, make it visible and cheap or explain it.
• Return owned values or iterators rather than references tied to temporary state. Use Cow when a value is only sometimes owned.
• Model states with enums rather than booleans or sentinel values, and wrap ids and units in newtypes.
• Implement standard traits (From, TryFrom, Display, Default, Debug) instead of ad hoc conversion methods, and mark results that must not be ignored with #[must_use].

Errors

• Return Result for anything that can fail at runtime, and propagate with ?.
• Do not call unwrap() in library or request-handling code. Use expect("reason this cannot fail") only for real invariants.
• Follow the project's error approach. Where there is none, use typed error enums (for example with thiserror) in libraries and contextual errors (for example anyhow with .context(...)) in binaries.
• Never panic across an FFI boundary or in a Drop implementation.

Unsafe

• Avoid unsafe. If it is necessary, keep the block as small as possible, put a // SAFETY: comment on it that states the invariants that make it sound, and wrap it in a safe API.
• Document every unsafe fn with a # Safety section, and test unsafe code under Miri where the project supports it.

Concurrency and async

• Prefer message passing or owned data over shared mutable state. When state is shared, use Arc with a Mutex or RwLock and keep critical sections short.
• Never hold a std::sync::Mutex guard across .await. Use the runtime's async mutex or restructure.
• Never block inside async code. Move blocking or CPU-heavy work to spawn_blocking or a dedicated thread.

Style

• Prefer iterator chains to index loops when they read clearly, and avoid collecting into a Vec only to iterate it again.
• Keep items private by default, and use pub(crate) before pub.
• Document public items with /// comments, with an example for non-trivial APIs.
• Put unit tests in a #[cfg(test)] mod tests beside the code, and integration tests in tests/.