rust-pro

What I do

• •Guide ownership and borrowing decisions with a deterministic decision tree
• •Provide error handling protocols for libraries, applications, and CLIs
• •Define an unsafe audit protocol for verifying memory safety invariants
• •Cover async programming patterns, concurrency selection, and essential tooling

When to use me

Use this skill when writing, reviewing, or optimizing Rust code. It covers ownership decisions, error handling, trait design, unsafe auditing, and async patterns. Pair with perf-core for profiling methodology and benchmarking workflow.

Ownership Decision Tree

Need to own the data?
  NO  --> &T (shared borrow) or &mut T (exclusive borrow)
  YES |
      v
Need heap allocation? (large, recursive, or trait object)
  YES --> Box<T>
  NO  |
      v
Need shared ownership?
  NO  --> T (move semantics)
  YES |
      v
Shared across threads?
  YES --> Arc<T> (read-only) or Arc<Mutex<T>> (read-write)
  NO  --> Rc<T> (read-only) or Rc<RefCell<T>> (read-write)

Sometimes owned, sometimes borrowed?
  --> Cow<'_, T>

Every type has a drop story. Before creating a type that holds resources (file handles, connections, locks), decide what happens when it is dropped. If cleanup is needed, implement Drop.

• •Clone is correct for: small Copy types, prototyping, when ownership semantics require it
• •Clone is a smell when: silencing the borrow checker, in hot loops, on large allocations
• •Prefer: &T, Cow<'_, T>, or restructured ownership over reflexive cloning

Error Handling Protocol

1. •Never .unwrap() in library code -- use ? or return Result
2. •Never .unwrap() in async code -- panics in tasks are hard to debug
3. •.unwrap() is acceptable in: tests, provably infallible cases (with comment), and early prototyping
4. •Prefer .expect("reason") over .unwrap() when unwrapping is justified
5. •Use map_err to convert between error types at module boundaries
6. •Preserve error chains -- do not discard inner errors

Lifetime Complexity Budget

• •Always try the cheaper level first. Escalate only when the compiler requires it.
• •If you are fighting the borrow checker at level 3+, restructure your data model to use owned data or Arc.
• •Most code stays at level 1-2. Level 4-5 should be rare and always documented.

Trait Design Patterns

• •Default to static dispatch (generics). Use dyn Trait only when you need heterogeneous collections or to reduce compile times.
• •Use supertraits to compose behavior: trait Service: Send + Sync + 'static.
• •Implement From<T> instead of custom conversion methods for type conversions.

Unsafe Audit Protocol

Valid reasons for unsafe:

1. •FFI -- calling C libraries or exposing Rust to C
2. •Performance primitive -- implementing a safe abstraction over raw pointers (e.g., custom collection)
3. •Compiler limitation -- working around borrow checker where you can prove safety (rare, document extensively)

Audit checklist:

• • Safety invariant documented in // SAFETY: comment above every unsafe block
• • cargo +nightly miri test passes for all tests exercising unsafe code
• • Unsafe code encapsulated behind a safe public API (no unsafe in public interface)
• • Adversarial inputs tested (null pointers, out-of-bounds, concurrent access)
• • Code review explicitly acknowledges unsafe and verifies invariant

Unsafe internals, safe externals. Every unsafe block should be wrapped in a function or module that exposes a safe API. Users of your code should never need to write unsafe.

Async & Concurrency

Async Patterns

Concurrency Selection Matrix

Prefer message passing (channels) over shared state (Mutex). Channels make ownership transfer explicit and avoid deadlocks.

Tooling

Run clippy, fmt --check, nextest, and deny check in CI on every pull request. Add miri for crates with unsafe code.

Anti-Patterns

Companion Skills