@cubis/foundry 0.3.10

package/Ai Agent Workflow/skills/rust-engineer/references/error-handling.md

@@ -0,0 +1,334 @@
+# Error Handling in Rust
+
+## Result and Option Basics
+
+```rust
+// Result: operation that can fail
+fn divide(a: f64, b: f64) -> Result<f64, String> {
+    if b == 0.0 {
+        Err("Division by zero".to_string())
+    } else {
+        Ok(a / b)
+    }
+}
+
+// Option: value that might be absent
+fn find_user(id: u64) -> Option<User> {
+    if id == 1 {
+        Some(User { id, name: "Alice".to_string() })
+    } else {
+        None
+    }
+}
+
+// Using ? operator for propagation
+fn calculate(a: f64, b: f64, c: f64) -> Result<f64, String> {
+    let x = divide(a, b)?;  // Returns Err early if division fails
+    let y = divide(x, c)?;
+    Ok(y)
+}
+```
+
+## Custom Error Types
+
+```rust
+use std::fmt;
+
+// Manual error type
+#[derive(Debug)]
+enum AppError {
+    NotFound(String),
+    InvalidInput(String),
+    DatabaseError(String),
+}
+
+impl fmt::Display for AppError {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        match self {
+            AppError::NotFound(msg) => write!(f, "Not found: {}", msg),
+            AppError::InvalidInput(msg) => write!(f, "Invalid input: {}", msg),
+            AppError::DatabaseError(msg) => write!(f, "Database error: {}", msg),
+        }
+    }
+}
+
+impl std::error::Error for AppError {}
+
+// Usage
+fn get_user(id: u64) -> Result<User, AppError> {
+    if id == 0 {
+        return Err(AppError::InvalidInput("ID cannot be zero".to_string()));
+    }
+    // ... fetch user
+    Err(AppError::NotFound(format!("User {} not found", id)))
+}
+```
+
+## Using thiserror
+
+```rust
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+enum DataError {
+    #[error("Data not found: {0}")]
+    NotFound(String),
+
+    #[error("Invalid ID: {id}, reason: {reason}")]
+    InvalidId { id: u64, reason: String },
+
+    #[error("IO error")]
+    Io(#[from] std::io::Error),
+
+    #[error("Parse error")]
+    Parse(#[from] std::num::ParseIntError),
+
+    #[error("Database error: {0}")]
+    Database(#[from] sqlx::Error),
+}
+
+// Usage with automatic conversions
+fn read_config(path: &str) -> Result<Config, DataError> {
+    let content = std::fs::read_to_string(path)?;  // Auto-converts io::Error
+    let port: u16 = content.parse()?;  // Auto-converts ParseIntError
+    Ok(Config { port })
+}
+```
+
+## Using anyhow for Applications
+
+```rust
+use anyhow::{Result, Context, bail, ensure};
+
+// Simple error handling for applications
+fn process_file(path: &str) -> Result<()> {
+    let content = std::fs::read_to_string(path)
+        .context(format!("Failed to read file: {}", path))?;
+
+    ensure!(!content.is_empty(), "File is empty");
+
+    if content.len() > 1000 {
+        bail!("File too large");
+    }
+
+    // Process content...
+    Ok(())
+}
+
+// Adding context to errors
+fn main() -> Result<()> {
+    process_file("config.txt")
+        .context("Failed to process configuration")?;
+    Ok(())
+}
+```
+
+## Option Combinators
+
+```rust
+// map: transform Option<T> to Option<U>
+let num: Option<i32> = Some(5);
+let doubled = num.map(|n| n * 2);  // Some(10)
+
+// and_then: chain operations
+let result = Some(5)
+    .and_then(|n| if n > 0 { Some(n * 2) } else { None })
+    .and_then(|n| Some(n + 1));  // Some(11)
+
+// or: provide alternative
+let value = None.or(Some(42));  // Some(42)
+
+// unwrap_or: provide default
+let value = None.unwrap_or(42);  // 42
+
+// unwrap_or_else: compute default lazily
+let value = None.unwrap_or_else(|| expensive_computation());
+
+// filter: conditional None
+let num = Some(5).filter(|&n| n > 10);  // None
+
+// Pattern matching
+match find_user(1) {
+    Some(user) => println!("Found: {}", user.name),
+    None => println!("User not found"),
+}
+
+// if let for simple cases
+if let Some(user) = find_user(1) {
+    println!("Found: {}", user.name);
+}
+```
+
+## Result Combinators
+
+```rust
+// map: transform Ok value
+let result: Result<i32, String> = Ok(5);
+let doubled = result.map(|n| n * 2);  // Ok(10)
+
+// map_err: transform error
+let result: Result<i32, &str> = Err("error");
+let mapped = result.map_err(|e| e.to_uppercase());  // Err("ERROR")
+
+// and_then: chain fallible operations
+fn parse_then_double(s: &str) -> Result<i32, std::num::ParseIntError> {
+    s.parse::<i32>()
+        .and_then(|n| Ok(n * 2))
+}
+
+// or_else: provide alternative computation
+let result = Err("error").or_else(|_| Ok(42));  // Ok(42)
+
+// unwrap_or: provide default
+let value = Err("error").unwrap_or(42);  // 42
+
+// expect: unwrap with custom panic message
+let value = result.expect("Failed to parse number");
+
+// Pattern matching
+match divide(10.0, 2.0) {
+    Ok(result) => println!("Result: {}", result),
+    Err(e) => eprintln!("Error: {}", e),
+}
+```
+
+## Error Conversion and From Trait
+
+```rust
+use std::io;
+use std::num::ParseIntError;
+
+#[derive(Debug)]
+enum MyError {
+    Io(io::Error),
+    Parse(ParseIntError),
+}
+
+impl From<io::Error> for MyError {
+    fn from(err: io::Error) -> Self {
+        MyError::Io(err)
+    }
+}
+
+impl From<ParseIntError> for MyError {
+    fn from(err: ParseIntError) -> Self {
+        MyError::Parse(err)
+    }
+}
+
+// Now ? operator works with automatic conversion
+fn read_and_parse(path: &str) -> Result<i32, MyError> {
+    let content = std::fs::read_to_string(path)?;  // io::Error -> MyError
+    let number = content.trim().parse()?;  // ParseIntError -> MyError
+    Ok(number)
+}
+```
+
+## Advanced Error Patterns
+
+```rust
+// Multiple error sources with Box<dyn Error>
+use std::error::Error;
+
+fn complex_operation() -> Result<String, Box<dyn Error>> {
+    let file = std::fs::read_to_string("data.txt")?;
+    let number: i32 = file.trim().parse()?;
+    Ok(format!("Number: {}", number))
+}
+
+// Error with backtrace (nightly)
+#[derive(Debug)]
+struct DetailedError {
+    message: String,
+    backtrace: std::backtrace::Backtrace,
+}
+
+impl DetailedError {
+    fn new(message: impl Into<String>) -> Self {
+        Self {
+            message: message.into(),
+            backtrace: std::backtrace::Backtrace::capture(),
+        }
+    }
+}
+
+// Recoverable vs unrecoverable errors
+fn might_fail(value: i32) -> Result<i32, String> {
+    if value < 0 {
+        Err("Negative value".to_string())  // Recoverable
+    } else if value > 1000 {
+        panic!("Value too large!");  // Unrecoverable
+    } else {
+        Ok(value * 2)
+    }
+}
+```
+
+## Try Blocks (Nightly)
+
+```rust
+#![feature(try_blocks)]
+
+// Try block for localized error handling
+let result: Result<i32, Box<dyn Error>> = try {
+    let file = std::fs::read_to_string("config.txt")?;
+    let num: i32 = file.trim().parse()?;
+    num * 2
+};
+```
+
+## Error Context Pattern
+
+```rust
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+#[error("{message}")]
+struct ContextError {
+    message: String,
+    #[source]
+    source: Option<Box<dyn Error + Send + Sync>>,
+}
+
+impl ContextError {
+    fn new(message: impl Into<String>) -> Self {
+        Self {
+            message: message.into(),
+            source: None,
+        }
+    }
+
+    fn with_source(mut self, source: impl Error + Send + Sync + 'static) -> Self {
+        self.source = Some(Box::new(source));
+        self
+    }
+}
+
+// Extension trait for adding context
+trait Context<T> {
+    fn context(self, message: impl Into<String>) -> Result<T, ContextError>;
+}
+
+impl<T, E: Error + Send + Sync + 'static> Context<T> for Result<T, E> {
+    fn context(self, message: impl Into<String>) -> Result<T, ContextError> {
+        self.map_err(|e| ContextError::new(message).with_source(e))
+    }
+}
+```
+
+## Best Practices
+
+- Use Result for recoverable errors, panic! for unrecoverable bugs
+- Prefer ? operator over unwrap() in production code
+- Use expect() with descriptive messages instead of unwrap()
+- Use thiserror for libraries (structured errors)
+- Use anyhow for applications (simple error handling)
+- Implement std::error::Error trait for custom error types
+- Add context to errors as they propagate up the stack
+- Use #[from] in thiserror for automatic conversions
+- Document error conditions in function documentation
+- Use Option::ok_or() to convert Option to Result
+- Use Result::ok() to convert Result to Option (discarding error)
+- Avoid String as error type (use custom types instead)
+- Use ensure! and bail! from anyhow for cleaner checks
+- Log errors at boundaries, return them in library code

package/Ai Agent Workflow/skills/rust-engineer/references/ownership.md

@@ -0,0 +1,278 @@
+# Ownership, Borrowing, and Lifetimes
+
+## Ownership Patterns
+
+```rust
+// Move semantics (ownership transfer)
+fn take_ownership(s: String) {
+    println!("{}", s);
+} // s dropped here
+
+// Borrowing (immutable reference)
+fn borrow(s: &String) {
+    println!("{}", s);
+} // s NOT dropped, caller still owns
+
+// Mutable borrowing
+fn borrow_mut(s: &mut String) {
+    s.push_str(" world");
+}
+
+// Usage
+let s = String::from("hello");
+borrow(&s);           // OK, immutable borrow
+let mut s2 = s;       // Move, s no longer valid
+borrow_mut(&mut s2);  // OK, mutable borrow
+```
+
+## Lifetime Annotations
+
+```rust
+// Explicit lifetime: returned reference lives as long as input
+fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
+    if x.len() > y.len() { x } else { y }
+}
+
+// Multiple lifetimes
+fn first_word<'a, 'b>(s: &'a str, _other: &'b str) -> &'a str {
+    s.split_whitespace().next().unwrap_or("")
+}
+
+// Lifetime in structs
+struct Excerpt<'a> {
+    part: &'a str,
+}
+
+impl<'a> Excerpt<'a> {
+    fn announce_and_return(&self, announcement: &str) -> &'a str {
+        println!("Attention: {}", announcement);
+        self.part
+    }
+}
+
+// Static lifetime (lives for entire program)
+const GREETING: &'static str = "Hello, world!";
+```
+
+## Smart Pointers
+
+```rust
+use std::rc::Rc;
+use std::cell::RefCell;
+use std::sync::{Arc, Mutex};
+
+// Box: heap allocation, single owner
+let b = Box::new(5);
+
+// Rc: reference counting (single-threaded)
+let rc1 = Rc::new(vec![1, 2, 3]);
+let rc2 = Rc::clone(&rc1);  // Increment count
+println!("Count: {}", Rc::strong_count(&rc1));  // 2
+
+// Arc: atomic reference counting (thread-safe)
+let arc1 = Arc::new(vec![1, 2, 3]);
+let arc2 = Arc::clone(&arc1);
+std::thread::spawn(move || {
+    println!("{:?}", arc2);
+});
+
+// RefCell: interior mutability (runtime borrow checking)
+let data = RefCell::new(5);
+*data.borrow_mut() += 1;  // Mutable borrow at runtime
+
+// Combining Rc + RefCell for shared mutable state
+let shared = Rc::new(RefCell::new(vec![1, 2, 3]));
+shared.borrow_mut().push(4);
+
+// Combining Arc + Mutex for thread-safe shared state
+let counter = Arc::new(Mutex::new(0));
+let counter_clone = Arc::clone(&counter);
+std::thread::spawn(move || {
+    let mut num = counter_clone.lock().unwrap();
+    *num += 1;
+});
+```
+
+## Interior Mutability
+
+```rust
+use std::cell::{Cell, RefCell};
+
+// Cell: Copy types only
+let c = Cell::new(5);
+c.set(10);
+let val = c.get();
+
+// RefCell: runtime borrow checking
+let data = RefCell::new(vec![1, 2, 3]);
+data.borrow_mut().push(4);
+
+// Pattern: mock objects with interior mutability
+struct MockLogger {
+    messages: RefCell<Vec<String>>,
+}
+
+impl MockLogger {
+    fn new() -> Self {
+        Self { messages: RefCell::new(Vec::new()) }
+    }
+
+    fn log(&self, msg: &str) {
+        self.messages.borrow_mut().push(msg.to_string());
+    }
+
+    fn get_messages(&self) -> Vec<String> {
+        self.messages.borrow().clone()
+    }
+}
+```
+
+## Pin and Self-Referential Types
+
+```rust
+use std::pin::Pin;
+use std::marker::PhantomPinned;
+
+// Self-referential struct (requires Pin)
+struct SelfReferential {
+    data: String,
+    pointer: *const String,
+    _pin: PhantomPinned,
+}
+
+impl SelfReferential {
+    fn new(data: String) -> Pin<Box<Self>> {
+        let mut boxed = Box::pin(Self {
+            data,
+            pointer: std::ptr::null(),
+            _pin: PhantomPinned,
+        });
+
+        // Safe: we're not moving the data after this
+        let ptr = &boxed.data as *const String;
+        unsafe {
+            let mut_ref = Pin::as_mut(&mut boxed);
+            Pin::get_unchecked_mut(mut_ref).pointer = ptr;
+        }
+
+        boxed
+    }
+}
+
+// Pin in async contexts
+async fn pinned_future() {
+    // Futures are often self-referential, hence Pin
+    let fut = async { 42 };
+    let pinned = Box::pin(fut);
+    pinned.await;
+}
+```
+
+## Cow (Clone on Write)
+
+```rust
+use std::borrow::Cow;
+
+fn process_text(input: &str) -> Cow<str> {
+    if input.contains("bad") {
+        // Need to modify: allocate new String
+        Cow::Owned(input.replace("bad", "good"))
+    } else {
+        // No modification needed: just borrow
+        Cow::Borrowed(input)
+    }
+}
+
+// Usage
+let text1 = "hello world";
+let result1 = process_text(text1);  // Borrowed (no allocation)
+
+let text2 = "bad word";
+let result2 = process_text(text2);  // Owned (allocated)
+```
+
+## Drop Trait and RAII
+
+```rust
+struct FileGuard {
+    name: String,
+}
+
+impl FileGuard {
+    fn new(name: String) -> Self {
+        println!("Opening {}", name);
+        Self { name }
+    }
+}
+
+impl Drop for FileGuard {
+    fn drop(&mut self) {
+        println!("Closing {}", self.name);
+    }
+}
+
+// Usage: automatic cleanup
+{
+    let _file = FileGuard::new("data.txt".to_string());
+    // Use file...
+} // Drop called automatically here
+```
+
+## Common Patterns
+
+```rust
+// Builder pattern with ownership
+struct Config {
+    host: String,
+    port: u16,
+}
+
+impl Config {
+    fn builder() -> ConfigBuilder {
+        ConfigBuilder::default()
+    }
+}
+
+struct ConfigBuilder {
+    host: Option<String>,
+    port: Option<u16>,
+}
+
+impl ConfigBuilder {
+    fn host(mut self, host: impl Into<String>) -> Self {
+        self.host = Some(host.into());
+        self
+    }
+
+    fn port(mut self, port: u16) -> Self {
+        self.port = Some(port);
+        self
+    }
+
+    fn build(self) -> Result<Config, &'static str> {
+        Ok(Config {
+            host: self.host.ok_or("host required")?,
+            port: self.port.unwrap_or(8080),
+        })
+    }
+}
+
+// Usage
+let config = Config::builder()
+    .host("localhost")
+    .port(3000)
+    .build()?;
+```
+
+## Best Practices
+
+- Prefer borrowing (&T) over ownership transfer when possible
+- Use &str over String for function parameters
+- Use &[T] over Vec<T> for function parameters
+- Clone only when necessary (profile first)
+- Use Cow<'a, T> for conditional cloning
+- Document lifetime relationships in complex cases
+- Use Arc<Mutex<T>> for shared mutable state across threads
+- Use Rc<RefCell<T>> for shared mutable state in single thread
+- Implement Drop for RAII patterns
+- Use PhantomData to constrain variance when needed