agentic-team-templates 0.9.2 → 0.11.0

package/templates/rust-expert/.cursorrules/ownership-and-borrowing.md

@@ -0,0 +1,204 @@
+# Rust Ownership and Borrowing
+
+Ownership is Rust's defining feature. It's not a constraint — it's a design tool that eliminates entire classes of bugs at compile time. Every memory safety guarantee flows from these rules.
+
+## The Three Rules
+
+1. Each value has exactly one owner
+2. When the owner goes out of scope, the value is dropped
+3. You can have either one mutable reference OR any number of shared references — never both
+
+## Ownership Patterns
+
+### Move Semantics
+
+```rust
+// Values are moved by default — this is the foundation
+let s = String::from("hello");
+let t = s; // s is MOVED into t
+// println!("{s}"); // Compile error: s has been moved
+
+// Functions take ownership unless they borrow
+fn consume(s: String) { /* s is dropped at end of function */ }
+fn borrow(s: &str) { /* s is borrowed — caller keeps ownership */ }
+
+// Return values transfer ownership back
+fn create() -> String {
+    String::from("created") // Ownership moves to caller
+}
+```
+
+### Borrowing
+
+```rust
+// Shared references: &T — read-only, multiple allowed
+fn len(s: &str) -> usize {
+    s.len()
+}
+
+// Mutable references: &mut T — exclusive access
+fn push_greeting(s: &mut String) {
+    s.push_str(", world!");
+}
+
+// The borrow checker enforces at compile time:
+let mut s = String::from("hello");
+let r1 = &s;      // Fine: shared borrow
+let r2 = &s;      // Fine: multiple shared borrows
+println!("{r1} {r2}");
+// r1 and r2 are no longer used after this point (NLL)
+let r3 = &mut s;  // Fine: no shared borrows are active
+r3.push_str("!");
+```
+
+### Lifetimes
+
+```rust
+// Lifetimes tell the compiler how long references are valid
+// Most of the time, elision handles this automatically
+
+// When the compiler needs help:
+fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
+    if x.len() > y.len() { x } else { y }
+}
+// Meaning: the returned reference lives at least as long as
+// the shorter of x and y
+
+// Structs that hold references need lifetime annotations
+struct Excerpt<'a> {
+    text: &'a str,
+}
+
+// If your struct has many lifetime parameters, consider
+// owning the data instead — complexity isn't always worth it
+struct Article {
+    title: String,    // Owned — simpler, no lifetime tracking
+    body: String,
+}
+```
+
+### Interior Mutability
+
+```rust
+// When you need mutation behind a shared reference
+
+// Cell<T> — for Copy types, single-threaded
+use std::cell::Cell;
+let counter = Cell::new(0);
+counter.set(counter.get() + 1); // Mutation through shared reference
+
+// RefCell<T> — runtime borrow checking, single-threaded
+use std::cell::RefCell;
+let data = RefCell::new(vec![1, 2, 3]);
+data.borrow_mut().push(4); // Panics if already borrowed
+
+// Mutex<T> / RwLock<T> — thread-safe interior mutability
+use std::sync::Mutex;
+let shared = Mutex::new(Vec::new());
+shared.lock().unwrap().push(42);
+
+// Choose the right tool:
+// Cell       — Copy types, no overhead, single-threaded
+// RefCell    — any type, runtime cost, single-threaded, panics on violation
+// Mutex      — any type, blocking, multi-threaded
+// RwLock     — any type, read-heavy workloads, multi-threaded
+// Atomic*    — primitives, lock-free, multi-threaded
+```
+
+## Smart Pointers
+
+```rust
+// Box<T> — heap allocation with single ownership
+let boxed: Box<dyn Error> = Box::new(MyError::new("failed"));
+// Use for: trait objects, recursive types, large values you want on heap
+
+// Rc<T> — reference-counted, single-threaded shared ownership
+use std::rc::Rc;
+let shared = Rc::new(ExpensiveData::new());
+let clone = Rc::clone(&shared); // Increments count, doesn't clone data
+// Use for: graph structures, multiple owners in single-threaded code
+
+// Arc<T> — atomic reference-counted, thread-safe shared ownership
+use std::sync::Arc;
+let shared = Arc::new(Config::load());
+let handle = {
+    let shared = Arc::clone(&shared);
+    thread::spawn(move || process(&shared))
+};
+// Use for: shared immutable data across threads
+
+// Cow<T> — clone-on-write
+use std::borrow::Cow;
+fn process(input: &str) -> Cow<'_, str> {
+    if input.contains("bad") {
+        Cow::Owned(input.replace("bad", "good"))
+    } else {
+        Cow::Borrowed(input) // No allocation when not needed
+    }
+}
+// Use for: avoiding allocation when mutation is conditional
+```
+
+## Common Borrow Checker Patterns
+
+### Splitting Borrows
+
+```rust
+// The borrow checker tracks borrows per-field, not per-struct
+struct State {
+    buffer: Vec<u8>,
+    index: usize,
+}
+
+impl State {
+    fn process(&mut self) {
+        // This works because buffer and index are separate fields
+        let buf = &self.buffer[self.index..];
+        self.index += buf.len();
+    }
+}
+```
+
+### Temporary Lifetimes
+
+```rust
+// Bad: temporary dropped while borrowed
+// let r = &String::from("temp"); // Won't compile — temporary is dropped
+
+// Good: bind to a variable to extend the lifetime
+let s = String::from("temp");
+let r = &s; // s lives as long as the scope
+```
+
+### Entry API for Maps
+
+```rust
+use std::collections::HashMap;
+
+let mut map = HashMap::new();
+
+// Entry API avoids double lookup and borrow conflicts
+map.entry("key")
+    .and_modify(|v| *v += 1)
+    .or_insert(0);
+```
+
+## Anti-Patterns
+
+```rust
+// Never: Clone to satisfy the borrow checker without understanding why
+let data = expensive_data.clone(); // Are you sure this is necessary?
+// If you're cloning to fix a borrow error, first ask: can I restructure the code?
+
+// Never: Leaking memory to avoid lifetimes
+let leaked: &'static str = Box::leak(Box::new(String::from("forever")));
+// This is almost never the right solution
+
+// Never: Rc<RefCell<T>> as a default — it's a code smell
+// If everything is Rc<RefCell<T>>, you've recreated garbage-collected mutable state
+// Restructure to use ownership and borrowing properly first
+
+// Never: Ignoring the borrow checker by reaching for unsafe
+// If the borrow checker rejects your code, the design usually needs to change
+// unsafe doesn't fix design problems — it hides them
+```

package/templates/rust-expert/.cursorrules/performance-and-unsafe.md

@@ -0,0 +1,256 @@
+# Rust Performance and Unsafe
+
+Rust's zero-cost abstractions mean you rarely need to choose between ergonomics and performance. When you do need to go lower, `unsafe` is the mechanism — and it comes with strict obligations.
+
+## Performance
+
+### Measure First
+
+```bash
+# Profile before optimizing
+cargo bench                          # Run benchmarks
+cargo flamegraph                     # Generate flamegraph (needs cargo-flamegraph)
+cargo instruments -t "Time Profiler" # macOS Instruments
+
+# Check binary size
+cargo bloat --release --crates       # Which crates contribute to binary size
+cargo bloat --release --filter "my_"  # Your functions by size
+
+# Check compile times
+cargo build --timings                # HTML report of compile times per crate
+```
+
+### Allocation Patterns
+
+```rust
+// Preallocate collections when size is known
+let mut results = Vec::with_capacity(items.len());
+for item in items {
+    results.push(process(item));
+}
+
+// Use iterators — they often avoid allocation entirely
+let sum: i64 = items.iter()
+    .filter(|x| x.is_valid())
+    .map(|x| x.value())
+    .sum();
+
+// Avoid unnecessary clones
+fn process(data: &str) -> Result<Output> { ... }     // Borrow when possible
+fn consume(data: String) -> Result<Output> { ... }   // Take ownership when needed
+
+// Cow for conditional ownership
+use std::borrow::Cow;
+fn normalize(input: &str) -> Cow<'_, str> {
+    if input.contains('\t') {
+        Cow::Owned(input.replace('\t', "    "))
+    } else {
+        Cow::Borrowed(input) // Zero allocation when no tabs
+    }
+}
+
+// SmallVec for small, stack-allocated collections
+use smallvec::SmallVec;
+let mut tags: SmallVec<[Tag; 4]> = SmallVec::new();
+// Up to 4 tags on the stack, spills to heap only if exceeded
+```
+
+### String Performance
+
+```rust
+// String concatenation: use a builder pattern
+use std::fmt::Write;
+let mut output = String::with_capacity(estimated_size);
+for item in items {
+    write!(output, "{}: {}\n", item.key, item.value).unwrap();
+}
+
+// For byte-level work, operate on &[u8] instead of &str
+// Converting to str requires UTF-8 validation — skip it when you can
+
+// Interning for repeated strings
+// Use string interning crates (lasso, string_cache) for heavy deduplication
+```
+
+### Iterator Optimization
+
+```rust
+// Iterators compile to the same code as manual loops — use them freely
+
+// Collect into specific types
+let map: HashMap<_, _> = pairs.into_iter().collect();
+let set: HashSet<_> = items.into_iter().collect();
+
+// Avoid collect() when you don't need a collection
+// Bad: allocates a Vec just to iterate it
+let filtered: Vec<_> = items.iter().filter(|x| x.active).collect();
+for item in &filtered { ... }
+
+// Good: iterate directly
+for item in items.iter().filter(|x| x.active) { ... }
+
+// chunks/windows for batch processing
+for chunk in data.chunks(1024) {
+    process_batch(chunk)?;
+}
+```
+
+### Data Layout
+
+```rust
+// Field ordering affects struct size due to padding
+// Bad: 24 bytes (with padding)
+struct Padded {
+    a: u8,   // 1 byte + 7 padding
+    b: u64,  // 8 bytes
+    c: u8,   // 1 byte + 7 padding
+}
+
+// Good: 16 bytes (reordered to minimize padding)
+struct Compact {
+    b: u64,  // 8 bytes
+    a: u8,   // 1 byte
+    c: u8,   // 1 byte + 6 padding
+}
+
+// repr(C) for FFI — disables Rust's field reordering
+#[repr(C)]
+struct FfiStruct { ... }
+
+// The compiler may reorder fields automatically in default repr(Rust),
+// but being explicit about layout helps readability and FFI correctness
+```
+
+## Unsafe
+
+### The Contract
+
+Every `unsafe` block is a proof obligation. You are telling the compiler: "I have verified that the safety invariants hold here, and I accept responsibility."
+
+```rust
+// ALWAYS document the safety invariant
+// SAFETY: We've verified that `index` is within bounds via the
+// length check on line 42, and the slice is valid for the lifetime
+// of this function.
+unsafe {
+    *ptr.add(index) = value;
+}
+```
+
+### Valid Uses of Unsafe
+
+```rust
+// 1. Calling unsafe functions (FFI)
+extern "C" {
+    fn external_function(ptr: *const u8, len: usize) -> i32;
+}
+
+pub fn safe_wrapper(data: &[u8]) -> Result<i32> {
+    // SAFETY: data.as_ptr() is valid for data.len() bytes,
+    // and the external function only reads from the pointer.
+    let result = unsafe { external_function(data.as_ptr(), data.len()) };
+    if result < 0 {
+        Err(Error::ExternalFailure(result))
+    } else {
+        Ok(result)
+    }
+}
+
+// 2. Implementing unsafe traits
+// SAFETY: MyType is Send because its internal raw pointer
+// is only accessed from the thread that owns MyType.
+// The pointer is never shared or aliased.
+unsafe impl Send for MyType {}
+
+// 3. Accessing mutable statics
+static mut COUNTER: u64 = 0;
+// SAFETY: This is only called from a single thread during initialization.
+unsafe { COUNTER += 1; }
+// Prefer AtomicU64 or OnceLock instead — this is almost always avoidable.
+
+// 4. Unchecked operations for performance (after profiling proves it matters)
+// SAFETY: We've validated that all bytes in `data` are valid UTF-8
+// in the validation pass on line 30.
+let s = unsafe { std::str::from_utf8_unchecked(data) };
+```
+
+### Minimizing Unsafe Surface
+
+```rust
+// Wrap unsafe in safe abstractions with narrow interfaces
+pub struct AlignedBuffer {
+    ptr: *mut u8,
+    len: usize,
+    cap: usize,
+}
+
+impl AlignedBuffer {
+    pub fn new(capacity: usize, alignment: usize) -> Self {
+        let layout = Layout::from_size_align(capacity, alignment).unwrap();
+        // SAFETY: layout is valid (non-zero size, power-of-two alignment)
+        let ptr = unsafe { alloc::alloc(layout) };
+        if ptr.is_null() {
+            alloc::handle_alloc_error(layout);
+        }
+        Self { ptr, len: 0, cap: capacity }
+    }
+
+    // Public API is fully safe — unsafe is encapsulated
+    pub fn push(&mut self, byte: u8) {
+        assert!(self.len < self.cap, "buffer full");
+        // SAFETY: We've verified len < cap, so ptr.add(len) is within allocation
+        unsafe { self.ptr.add(self.len).write(byte); }
+        self.len += 1;
+    }
+
+    pub fn as_slice(&self) -> &[u8] {
+        // SAFETY: ptr is valid for len bytes, all initialized by push()
+        unsafe { std::slice::from_raw_parts(self.ptr, self.len) }
+    }
+}
+
+impl Drop for AlignedBuffer {
+    fn drop(&mut self) {
+        let layout = Layout::from_size_align(self.cap, /* alignment */).unwrap();
+        // SAFETY: ptr was allocated with this layout in new()
+        unsafe { alloc::dealloc(self.ptr, layout); }
+    }
+}
+```
+
+### Miri
+
+```bash
+# Miri detects undefined behavior in unsafe code
+cargo +nightly miri test
+
+# Miri catches:
+# - Out-of-bounds memory access
+# - Use-after-free
+# - Invalid use of uninitialized data
+# - Violations of aliasing rules (Stacked Borrows)
+# - Data races
+
+# Run Miri in CI for any crate with unsafe code
+```
+
+## Anti-Patterns
+
+```rust
+// Never: unsafe to "shut up the borrow checker"
+// If the borrow checker rejects it, there's a reason. Redesign.
+
+// Never: unsafe without a SAFETY comment
+unsafe { ptr::write(dst, src) } // WHY is this safe? Document it.
+
+// Never: transmute as a first resort
+let x: u32 = unsafe { std::mem::transmute(my_float) };
+// Use to_bits() / from_bits() instead — safe, clear, correct
+
+// Never: Assuming layout without repr(C)
+// Rust's default repr can reorder fields — don't assume memory layout
+
+// Never: Dereferencing raw pointers without proving validity
+// A raw pointer might be null, dangling, or misaligned.
+// Prove all three are impossible before dereferencing.
+```