@cubis/foundry 0.3.66 → 0.3.68

package/workflows/skills/rust-pro/references/error-handling-design.md

@@ -0,0 +1,222 @@
+# Error Handling Design
+
+## Layered Error Strategy
+
+Use `thiserror` for library error types (public API), `anyhow` for application-level propagation.
+
+```rust
+// LIBRARY LAYER — structured error enum with thiserror
+use thiserror::Error;
+
+#[derive(Debug, Error)]
+pub enum StorageError {
+    #[error("record not found: {id}")]
+    NotFound { id: String },
+
+    #[error("connection failed: {source}")]
+    Connection {
+        #[source]
+        source: tokio_postgres::Error,
+    },
+
+    #[error("serialization failed")]
+    Serialization(#[from] serde_json::Error),
+
+    #[error("query timeout after {duration:?}")]
+    Timeout { duration: Duration },
+}
+
+// APPLICATION LAYER — anyhow for aggregating across libraries
+use anyhow::{Context, Result};
+
+async fn handle_request(req: Request) -> Result<Response> {
+    let user = db.get_user(req.user_id)
+        .await
+        .context("failed to fetch user")?;     // adds context
+
+    let profile = cache.get_profile(user.id)
+        .await
+        .context("failed to load profile")?;
+
+    Ok(Response::ok(profile))
+}
+```
+
+## Error Enum Design Principles
+
+- **One error enum per crate or module boundary.** Do not create a god enum for the whole application.
+- **Include context fields**, not just string messages. This makes errors actionable in logs.
+- **Use `#[from]` sparingly** — only when the conversion is unambiguous and the source error is always the cause.
+- **Derived errors must implement `Display` and `Debug`.** `thiserror` handles this automatically.
+
+```rust
+// GOOD — specific variants with context
+#[derive(Debug, Error)]
+pub enum AuthError {
+    #[error("invalid credentials for user {username}")]
+    InvalidCredentials { username: String },
+
+    #[error("token expired at {expired_at}")]
+    TokenExpired { expired_at: DateTime<Utc> },
+
+    #[error("insufficient permissions: requires {required}, has {actual}")]
+    Forbidden { required: String, actual: String },
+}
+
+// BAD — stringly-typed errors lose structure
+#[derive(Debug, Error)]
+pub enum AuthError {
+    #[error("{0}")]
+    General(String), // useless for programmatic handling
+}
+```
+
+## Context Chain with `anyhow`
+
+Build error chains that tell the full story of what went wrong and where:
+
+```rust
+use anyhow::{bail, ensure, Context, Result};
+
+async fn sync_user_data(user_id: u64) -> Result<()> {
+    let user = fetch_user(user_id)
+        .await
+        .with_context(|| format!("failed to fetch user {user_id}"))?;
+
+    ensure!(!user.is_deleted, "user {user_id} is soft-deleted");
+
+    let external = fetch_external_profile(&user.email)
+        .await
+        .context("external profile fetch failed")?;
+
+    merge_profiles(&user, &external)
+        .context("profile merge failed")?;
+
+    Ok(())
+}
+
+// The resulting error chain reads:
+// Error: profile merge failed
+// Caused by:
+//   0: field mapping conflict on 'email'
+//   1: source type mismatch: expected String, got Vec<String>
+```
+
+## Mapping Foreign Errors at Crate Boundaries
+
+Never expose dependency error types in your public API — they leak implementation details.
+
+```rust
+// BAD — leaking sqlx::Error in public API
+pub async fn get_user(id: i64) -> Result<User, sqlx::Error> { ... }
+
+// GOOD — map to domain error at the boundary
+pub async fn get_user(id: i64) -> Result<User, StorageError> {
+    sqlx::query_as::<_, User>("SELECT * FROM users WHERE id = $1")
+        .bind(id)
+        .fetch_optional(&self.pool)
+        .await
+        .map_err(|e| StorageError::Connection { source: e })?
+        .ok_or(StorageError::NotFound { id: id.to_string() })
+}
+```
+
+## Result Combinators
+
+```rust
+// Use map_err for error transformation
+let user = db.find(id)
+    .map_err(|e| AppError::Database(e))?;
+
+// Use ok_or / ok_or_else for Option → Result
+let config = env::var("API_KEY")
+    .ok()
+    .ok_or_else(|| AppError::Config("API_KEY not set".into()))?;
+
+// Use and_then for chained fallible operations
+let result = parse_input(raw)
+    .and_then(|input| validate(input))
+    .and_then(|valid| transform(valid));
+```
+
+## When to Panic vs Return Error
+
+| Use                       | Panic (`unwrap`, `expect`, `panic!`)         | Error (`Result`, `?`)                       |
+| ------------------------- | -------------------------------------------- | ------------------------------------------- |
+| **Test code**             | Yes — tests should panic on unexpected state | Also fine                                   |
+| **Infallible operations** | Yes — `"constant".parse::<u32>().unwrap()`   | Unnecessary                                 |
+| **Programmer bugs**       | Yes — violated invariants, unreachable code  | No                                          |
+| **Input validation**      | Never                                        | Yes — return error to caller                |
+| **I/O failures**          | Never                                        | Yes — network, disk, external APIs          |
+| **Business logic errors** | Never                                        | Yes — not found, invalid state, auth failed |
+
+```rust
+// PANIC is correct here — this is a programmer bug if it fails
+let regex = Regex::new(r"^\d{4}-\d{2}-\d{2}$").expect("hardcoded regex is valid");
+
+// ERROR is correct here — user input may be invalid
+fn parse_date(input: &str) -> Result<NaiveDate, ParseError> {
+    NaiveDate::parse_from_str(input, "%Y-%m-%d")
+}
+```
+
+## Error Logging Best Practices
+
+```rust
+use tracing::{error, warn, info, instrument};
+
+#[instrument(skip(db), err)]
+async fn process_order(db: &Database, order_id: u64) -> Result<()> {
+    let order = db.get_order(order_id)
+        .await
+        .map_err(|e| {
+            error!(order_id, error = %e, "failed to fetch order");
+            e
+        })?;
+
+    // Use warn for recoverable situations
+    if order.items.is_empty() {
+        warn!(order_id, "order has no items, skipping");
+        return Ok(());
+    }
+
+    Ok(())
+}
+```
+
+## Custom Error with HTTP Status Mapping
+
+```rust
+use axum::response::{IntoResponse, Response};
+use axum::http::StatusCode;
+
+#[derive(Debug, Error)]
+pub enum ApiError {
+    #[error("not found: {0}")]
+    NotFound(String),
+
+    #[error("validation failed: {0}")]
+    Validation(String),
+
+    #[error("unauthorized")]
+    Unauthorized,
+
+    #[error(transparent)]
+    Internal(#[from] anyhow::Error),
+}
+
+impl IntoResponse for ApiError {
+    fn into_response(self) -> Response {
+        let (status, message) = match &self {
+            ApiError::NotFound(msg) => (StatusCode::NOT_FOUND, msg.clone()),
+            ApiError::Validation(msg) => (StatusCode::BAD_REQUEST, msg.clone()),
+            ApiError::Unauthorized => (StatusCode::UNAUTHORIZED, "unauthorized".into()),
+            ApiError::Internal(e) => {
+                tracing::error!(error = %e, "internal error");
+                (StatusCode::INTERNAL_SERVER_ERROR, "internal error".into())
+            }
+        };
+        (status, axum::Json(serde_json::json!({ "error": message }))).into_response()
+    }
+}
+```

package/workflows/skills/rust-pro/references/ownership-and-borrowing.md

@@ -0,0 +1,175 @@
+# Ownership and Borrowing Patterns
+
+## Ownership Transfer
+
+```rust
+// Prefer moving into constructors — caller surrenders ownership
+struct Service {
+    db: DatabasePool,
+    cache: CacheClient,
+}
+
+impl Service {
+    fn new(db: DatabasePool, cache: CacheClient) -> Self {
+        Self { db, cache }
+    }
+}
+
+// Return owned types from factory functions
+fn create_config() -> Config {
+    Config {
+        timeout: Duration::from_secs(30),
+        retries: 3,
+    }
+}
+```
+
+## Borrow Scope Tightening
+
+Keep borrows as short as possible. Release them before calling functions that need `&mut self`.
+
+```rust
+// BAD — borrow lives across the mutation point
+fn process(data: &mut HashMap<String, Vec<u8>>) {
+    let entry = data.get("key"); // immutable borrow starts
+    if entry.is_some() {
+        data.insert("key".into(), vec![1, 2, 3]); // ERROR: mutable borrow while immutable active
+    }
+}
+
+// GOOD — clone or extract what you need, then release the borrow
+fn process(data: &mut HashMap<String, Vec<u8>>) {
+    let has_key = data.contains_key("key"); // borrow released immediately
+    if has_key {
+        data.insert("key".into(), vec![1, 2, 3]); // no conflict
+    }
+}
+```
+
+## When to Use `Cow`
+
+Use `Cow<'_, T>` when a function sometimes allocates and sometimes borrows.
+
+```rust
+use std::borrow::Cow;
+
+// Returns borrowed data for ASCII, owned for non-ASCII
+fn normalize_name(input: &str) -> Cow<'_, str> {
+    if input.is_ascii() {
+        Cow::Borrowed(input) // zero allocation
+    } else {
+        Cow::Owned(input.to_lowercase()) // allocates only when needed
+    }
+}
+
+// Useful for config values that may come from static strings or environment
+fn get_base_url() -> Cow<'static, str> {
+    match std::env::var("BASE_URL") {
+        Ok(url) => Cow::Owned(url),
+        Err(_) => Cow::Borrowed("https://api.example.com"),
+    }
+}
+```
+
+## `Arc` vs Move vs Clone Tradeoffs
+
+| Strategy            | When to use                                                                             | Cost                                |
+| ------------------- | --------------------------------------------------------------------------------------- | ----------------------------------- |
+| **Move**            | Value has one consumer. Constructor, spawn, channel send.                               | Zero runtime cost                   |
+| **Clone**           | Value is cheap to copy (small structs, `Arc`). Each consumer owns independent copy.     | Copy cost, separate lifetimes       |
+| **`Arc<T>`**        | Multiple owners need shared read access. Immutable shared state.                        | Atomic ref-count on clone/drop      |
+| **`Arc<Mutex<T>>`** | Multiple owners need mutable access. Use only when channel-based design is impractical. | Lock contention risk                |
+| **`&T` borrow**     | Caller retains ownership, callee only reads temporarily.                                | Zero cost, adds lifetime constraint |
+
+```rust
+// Move into spawned task — cleanest ownership
+let config = load_config();
+tokio::spawn(async move {
+    use_config(config).await; // config moved, no sharing
+});
+
+// Arc for shared immutable state across tasks
+let shared_config = Arc::new(load_config());
+for _ in 0..num_workers {
+    let cfg = Arc::clone(&shared_config);
+    tokio::spawn(async move {
+        use_config(&cfg).await; // shared read, no lock
+    });
+}
+
+// Channel-based transfer instead of Arc<Mutex>
+let (tx, mut rx) = tokio::sync::mpsc::channel(32);
+tokio::spawn(async move {
+    while let Some(item) = rx.recv().await {
+        process(item).await; // exclusive ownership per item
+    }
+});
+```
+
+## Lifetime Annotations — When Required
+
+Only add lifetime annotations when the compiler cannot infer them. Common cases:
+
+```rust
+// Struct holding a reference — lifetime required
+struct Parser<'input> {
+    source: &'input str,
+    position: usize,
+}
+
+impl<'input> Parser<'input> {
+    fn next_token(&mut self) -> &'input str {
+        // Returns slice of the original input — same lifetime
+        let start = self.position;
+        // ... parsing logic
+        &self.source[start..self.position]
+    }
+}
+
+// Function returning a reference to one of its inputs
+fn longer<'a>(a: &'a str, b: &'a str) -> &'a str {
+    if a.len() >= b.len() { a } else { b }
+}
+
+// AVOID: lifetimes in public API when owned return is cleaner
+// BAD — forces caller to manage lifetimes
+fn get_name<'a>(user: &'a User) -> &'a str { &user.name }
+
+// GOOD — return owned String if the caller needs independent ownership
+fn get_name(user: &User) -> String { user.name.clone() }
+```
+
+## Interior Mutability Hierarchy
+
+Choose the lightest tool that satisfies the requirement:
+
+1. **`Cell<T>`** — Single-threaded, `Copy` types. Zero overhead.
+2. **`RefCell<T>`** — Single-threaded, runtime borrow checking. Panics on double mutable borrow.
+3. **`Mutex<T>`** — Multi-threaded, blocking. Use for rare writes.
+4. **`RwLock<T>`** — Multi-threaded, concurrent reads. Use when reads dominate.
+5. **`Atomic*`** — Lock-free counters and flags. Use for simple integer/bool state.
+
+```rust
+use std::cell::RefCell;
+use std::sync::{Arc, Mutex, RwLock};
+use std::sync::atomic::{AtomicU64, Ordering};
+
+// RefCell for single-threaded caches
+thread_local! {
+    static CACHE: RefCell<HashMap<String, String>> = RefCell::new(HashMap::new());
+}
+
+// RwLock for read-heavy shared config
+struct AppState {
+    config: RwLock<Config>,         // many readers, rare writes
+    request_count: AtomicU64,       // simple counter, lock-free
+    sessions: Mutex<HashMap<String, Session>>, // mutation on every request
+}
+```
+
+## Common Ownership Pitfalls
+
+- **Borrowing across `.await`**: Borrows held across `.await` points make futures `!Send`. Extract owned data before awaiting.
+- **Self-referential structs**: Rust doesn't support structs that borrow from themselves. Use indices, `Pin`, or arena allocators instead.
+- **Over-cloning**: Cloning to satisfy the borrow checker is a code smell. Restructure ownership or use references.
+- **Lifetime variance confusion**: `&'a mut T` is invariant in `'a`. Storing mutable references in containers requires exact lifetime matching.

package/workflows/skills/rust-pro/references/trait-design-patterns.md

@@ -0,0 +1,234 @@
+# Trait Design Patterns
+
+## Enum vs Trait Object Dispatch
+
+Choose based on whether the type set is closed or open:
+
+| Design          | When to use                                              | Tradeoffs                                          |
+| --------------- | -------------------------------------------------------- | -------------------------------------------------- |
+| **Enum**        | Known, fixed set of variants                             | Zero-cost dispatch, exhaustive matching, inlinable |
+| **`dyn Trait`** | Plugin boundaries, user-extensible types                 | Heap allocation, vtable indirection, no inlining   |
+| **Generics**    | Performance-critical, single concrete type per call site | Monomorphized — fast but increases binary size     |
+
+```rust
+// ENUM — known set of message types
+enum Command {
+    Start { task_id: u64 },
+    Stop { task_id: u64 },
+    Status,
+}
+
+fn execute(cmd: Command) {
+    match cmd {
+        Command::Start { task_id } => start_task(task_id),
+        Command::Stop { task_id } => stop_task(task_id),
+        Command::Status => print_status(),
+    }
+}
+
+// TRAIT OBJECT — plugin-style extensibility
+trait Processor: Send + Sync {
+    fn process(&self, input: &[u8]) -> Vec<u8>;
+    fn name(&self) -> &str;
+}
+
+struct Pipeline {
+    processors: Vec<Box<dyn Processor>>, // open set, unknown at compile time
+}
+```
+
+## Newtype Pattern
+
+Wrap primitives to prevent type confusion and add domain semantics.
+
+```rust
+// Without newtypes — easy to swap arguments
+fn transfer(from: u64, to: u64, amount: u64) { ... }
+transfer(amount, from_id, to_id); // compiles, but wrong!
+
+// With newtypes — compiler catches mistakes
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+struct AccountId(u64);
+
+#[derive(Debug, Clone, Copy, PartialEq, PartialOrd)]
+struct Money(u64);
+
+fn transfer(from: AccountId, to: AccountId, amount: Money) { ... }
+// transfer(amount, from_id, to_id); // won't compile
+
+// Add Display and FromStr for convenience
+impl std::fmt::Display for AccountId {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "acct-{}", self.0)
+    }
+}
+```
+
+## Trait Design Principles
+
+Keep trait surfaces small. Split large traits into focused capabilities.
+
+```rust
+// BAD — monolithic trait forces implementors to provide everything
+trait Database {
+    fn query(&self, sql: &str) -> Result<Rows>;
+    fn execute(&self, sql: &str) -> Result<u64>;
+    fn begin_transaction(&self) -> Result<Transaction>;
+    fn health_check(&self) -> Result<()>;
+    fn migrate(&self) -> Result<()>;
+}
+
+// GOOD — focused traits, compose as needed
+trait Queryable {
+    fn query(&self, sql: &str) -> Result<Rows>;
+    fn execute(&self, sql: &str) -> Result<u64>;
+}
+
+trait Transactional: Queryable {
+    fn begin(&self) -> Result<Transaction>;
+}
+
+trait HealthCheckable {
+    fn health_check(&self) -> Result<()>;
+}
+
+// Implementor only provides what it supports
+impl Queryable for ReadReplica { ... }
+// ReadReplica doesn't implement Transactional — compile-time safety
+```
+
+## `From` / `Into` Conversion Design
+
+```rust
+// Implement From for unambiguous, infallible conversions
+impl From<CreateUserRequest> for User {
+    fn from(req: CreateUserRequest) -> Self {
+        User {
+            id: Uuid::new_v4(),
+            name: req.name,
+            email: req.email,
+            created_at: Utc::now(),
+        }
+    }
+}
+
+// Use TryFrom for fallible conversions
+impl TryFrom<RawConfig> for ValidatedConfig {
+    type Error = ConfigError;
+
+    fn try_from(raw: RawConfig) -> Result<Self, Self::Error> {
+        if raw.port == 0 {
+            return Err(ConfigError::InvalidPort);
+        }
+        Ok(ValidatedConfig {
+            host: raw.host,
+            port: raw.port,
+        })
+    }
+}
+
+// Usage
+let user: User = request.into();
+let config = ValidatedConfig::try_from(raw_config)?;
+```
+
+## Extension Traits
+
+Add methods to foreign types without modifying them.
+
+```rust
+// Extend Result with domain-specific helpers
+trait ResultExt<T> {
+    fn or_not_found(self, resource: &str) -> Result<T, ApiError>;
+}
+
+impl<T, E: std::fmt::Display> ResultExt<T> for Result<T, E> {
+    fn or_not_found(self, resource: &str) -> Result<T, ApiError> {
+        self.map_err(|e| ApiError::NotFound(format!("{resource}: {e}")))
+    }
+}
+
+// Usage
+let user = db.find_user(id).or_not_found("user")?;
+```
+
+## Builder Pattern with Type State
+
+Use the type system to enforce build step ordering at compile time.
+
+```rust
+// Type-state markers
+struct NoHost;
+struct HasHost(String);
+struct NoPort;
+struct HasPort(u16);
+
+struct ServerBuilder<H, P> {
+    host: H,
+    port: P,
+}
+
+impl ServerBuilder<NoHost, NoPort> {
+    fn new() -> Self {
+        ServerBuilder { host: NoHost, port: NoPort }
+    }
+}
+
+impl<P> ServerBuilder<NoHost, P> {
+    fn host(self, host: impl Into<String>) -> ServerBuilder<HasHost, P> {
+        ServerBuilder { host: HasHost(host.into()), port: self.port }
+    }
+}
+
+impl<H> ServerBuilder<H, NoPort> {
+    fn port(self, port: u16) -> ServerBuilder<H, HasPort> {
+        ServerBuilder { host: self.host, port: HasPort(port) }
+    }
+}
+
+// build() only available when both host AND port are set
+impl ServerBuilder<HasHost, HasPort> {
+    fn build(self) -> Server {
+        Server {
+            host: self.host.0,
+            port: self.port.0,
+        }
+    }
+}
+
+// Usage — compile error if host or port is missing
+let server = ServerBuilder::new()
+    .host("0.0.0.0")
+    .port(8080)
+    .build();
+```
+
+## Async Traits
+
+```rust
+// Use async-trait crate or native async fn in traits (Rust 1.75+)
+trait Repository: Send + Sync {
+    async fn find(&self, id: u64) -> Result<Option<Entity>>;
+    async fn save(&self, entity: &Entity) -> Result<()>;
+}
+
+// For trait objects, you still need Send bounds on the future:
+#[async_trait::async_trait]
+trait DynRepository: Send + Sync {
+    async fn find(&self, id: u64) -> Result<Option<Entity>>;
+}
+```
+
+## Derive Macro Hygiene
+
+```rust
+// Derive the minimum set of traits needed
+#[derive(Debug)]              // Always: needed for error messages and logging
+#[derive(Clone)]              // When values are shared or cached
+#[derive(PartialEq, Eq)]     // When used as hash map keys or compared
+#[derive(Hash)]               // When used in HashSet or HashMap keys
+#[derive(serde::Serialize, serde::Deserialize)] // When crossing serialization boundaries
+
+// DON'T derive Serialize/Deserialize on domain types — use separate DTOs
+// DON'T derive Clone on types that hold exclusive resources (connections, file handles)
+```