Rust patterns

Errors

• Library crates: thiserror::Error-derived enum named Error, type alias pub type Result<T> = std::result::Result<T, Error>;. Variants tagged with #[error("…")].
• Binary crates (pf-cli only): anyhow::Result is acceptable at the command-handler boundary. Internals still use typed errors.
• Never unwrap() / expect() outside #[cfg(test)] and examples/.
• Use ? everywhere. If you find yourself writing match res { Err(e) => return Err(e.into()), Ok(v) => v }, write res? instead.

Async

• tokio multi-thread runtime; #[tokio::main] only in binaries.
• Use tokio::task::JoinSet for fan-out/fan-in instead of spawn + await loops.
• tokio::fs for I/O paths in async contexts; std::fs only in clearly- sync contexts.

Tracing

• use tracing::{debug, info, warn, error, instrument};
• Annotate every pub async function with #[instrument(skip(self))] or similar (skip large args).
• Spans MUST carry meaningful field names: tracing::info!(image=%cid, "snapshot complete"). Never log opaque Debug structs at info level.

API surface

• Every pub symbol gets a doc-comment that compiles as a doctest where meaningful. cargo test --doc runs these in CI.
• Prefer borrowed parameters (&str, &[u8], &Path); accept impl AsRef<Path> only at the outermost API boundary.
• Newtype the digest types — never expose raw String for content IDs.

Workspace lints

• pedantic is on, module_name_repetitions and must_use_candidate are off. Fix every other clippy warning before committing.