@cubis/foundry 0.3.31 → 0.3.33

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/rust-engineer/references/traits.md

@@ -0,0 +1,413 @@
+# Traits, Generics, and Type System
+
+## Basic Trait Definition
+
+```rust
+// Simple trait
+trait Drawable {
+    fn draw(&self);
+}
+
+// Trait with default implementation
+trait Describable {
+    fn describe(&self) -> String {
+        String::from("No description available")
+    }
+}
+
+// Implementing traits
+struct Circle {
+    radius: f64,
+}
+
+impl Drawable for Circle {
+    fn draw(&self) {
+        println!("Drawing circle with radius {}", self.radius);
+    }
+}
+
+impl Describable for Circle {
+    fn describe(&self) -> String {
+        format!("A circle with radius {}", self.radius)
+    }
+}
+```
+
+## Associated Types
+
+```rust
+// Associated types vs generic parameters
+trait Container {
+    type Item;
+
+    fn add(&mut self, item: Self::Item);
+    fn get(&self, index: usize) -> Option<&Self::Item>;
+}
+
+impl Container for Vec<i32> {
+    type Item = i32;
+
+    fn add(&mut self, item: i32) {
+        self.push(item);
+    }
+
+    fn get(&self, index: usize) -> Option<&i32> {
+        self.get(index)
+    }
+}
+
+// Iterator trait (standard library example)
+trait MyIterator {
+    type Item;
+
+    fn next(&mut self) -> Option<Self::Item>;
+}
+```
+
+## Generic Traits and Bounds
+
+```rust
+// Generic trait with multiple bounds
+fn print_info<T>(item: &T)
+where
+    T: std::fmt::Display + std::fmt::Debug,
+{
+    println!("Display: {}", item);
+    println!("Debug: {:?}", item);
+}
+
+// Generic struct with trait bounds
+struct Pair<T: PartialOrd> {
+    first: T,
+    second: T,
+}
+
+impl<T: PartialOrd> Pair<T> {
+    fn new(first: T, second: T) -> Self {
+        Self { first, second }
+    }
+
+    fn larger(&self) -> &T {
+        if self.first > self.second {
+            &self.first
+        } else {
+            &self.second
+        }
+    }
+}
+
+// Blanket implementation
+trait MyTrait {
+    fn do_something(&self);
+}
+
+impl<T: std::fmt::Display> MyTrait for T {
+    fn do_something(&self) {
+        println!("Value: {}", self);
+    }
+}
+```
+
+## Trait Objects (Dynamic Dispatch)
+
+```rust
+// Static dispatch (monomorphization)
+fn static_dispatch<T: Drawable>(item: &T) {
+    item.draw();
+}
+
+// Dynamic dispatch (trait objects)
+fn dynamic_dispatch(item: &dyn Drawable) {
+    item.draw();
+}
+
+// Storing trait objects
+struct Canvas {
+    shapes: Vec<Box<dyn Drawable>>,
+}
+
+impl Canvas {
+    fn new() -> Self {
+        Self { shapes: Vec::new() }
+    }
+
+    fn add_shape(&mut self, shape: Box<dyn Drawable>) {
+        self.shapes.push(shape);
+    }
+
+    fn draw_all(&self) {
+        for shape in &self.shapes {
+            shape.draw();
+        }
+    }
+}
+
+// Object safety: traits must meet criteria
+trait ObjectSafe {
+    fn method(&self);  // OK: takes &self
+}
+
+trait NotObjectSafe {
+    fn generic<T>(&self);  // NOT OK: generic method
+    fn by_value(self);     // NOT OK: takes self by value
+}
+```
+
+## Derive Macros
+
+```rust
+// Standard derive macros
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+struct User {
+    id: u64,
+    name: String,
+}
+
+// Deriving more traits
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+struct Point {
+    x: i32,
+    y: i32,
+}
+
+// Custom derive with serde
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Serialize, Deserialize)]
+struct Config {
+    host: String,
+    port: u16,
+}
+```
+
+## Advanced Trait Patterns
+
+```rust
+// Extension trait pattern
+trait StringExt {
+    fn truncate_to(&self, max_len: usize) -> String;
+}
+
+impl StringExt for str {
+    fn truncate_to(&self, max_len: usize) -> String {
+        if self.len() <= max_len {
+            self.to_string()
+        } else {
+            format!("{}...", &self[..max_len])
+        }
+    }
+}
+
+// Sealed trait pattern (prevent external implementation)
+mod sealed {
+    pub trait Sealed {}
+}
+
+pub trait MySealed: sealed::Sealed {
+    fn method(&self);
+}
+
+struct MyType;
+impl sealed::Sealed for MyType {}
+impl MySealed for MyType {
+    fn method(&self) {
+        println!("Implemented");
+    }
+}
+
+// Supertraits
+trait Printable {
+    fn print(&self);
+}
+
+trait Loggable: Printable {  // Supertrait: must also impl Printable
+    fn log(&self) {
+        self.print();  // Can call supertrait methods
+    }
+}
+```
+
+## Associated Constants
+
+```rust
+trait Config {
+    const MAX_SIZE: usize;
+    const DEFAULT_TIMEOUT: u64;
+}
+
+struct ServerConfig;
+
+impl Config for ServerConfig {
+    const MAX_SIZE: usize = 1024;
+    const DEFAULT_TIMEOUT: u64 = 30;
+}
+
+fn use_config<T: Config>() {
+    println!("Max size: {}", T::MAX_SIZE);
+}
+```
+
+## Generic Associated Types (GATs)
+
+```rust
+// GATs allow generics in associated types
+trait LendingIterator {
+    type Item<'a> where Self: 'a;
+
+    fn next<'a>(&'a mut self) -> Option<Self::Item<'a>>;
+}
+
+struct WindowsMut<'data, T> {
+    data: &'data mut [T],
+    index: usize,
+}
+
+impl<'data, T> LendingIterator for WindowsMut<'data, T> {
+    type Item<'a> = &'a mut [T] where Self: 'a;
+
+    fn next<'a>(&'a mut self) -> Option<Self::Item<'a>> {
+        if self.index >= self.data.len() {
+            return None;
+        }
+
+        let start = self.index;
+        self.index += 2;
+
+        Some(&mut self.data[start..start.min(self.data.len())])
+    }
+}
+```
+
+## Marker Traits
+
+```rust
+use std::marker::{PhantomData, Send, Sync};
+
+// Send: type can be transferred across thread boundaries
+// Sync: type can be shared between threads (&T is Send)
+
+// Custom marker trait
+trait Trusted {}
+
+struct TrustedData<T> {
+    data: T,
+    _marker: PhantomData<T>,
+}
+
+impl<T: Trusted> TrustedData<T> {
+    fn new(data: T) -> Self {
+        Self {
+            data,
+            _marker: PhantomData,
+        }
+    }
+}
+```
+
+## Operator Overloading
+
+```rust
+use std::ops::{Add, Mul};
+
+#[derive(Debug, Clone, Copy)]
+struct Vector2D {
+    x: f64,
+    y: f64,
+}
+
+impl Add for Vector2D {
+    type Output = Self;
+
+    fn add(self, other: Self) -> Self {
+        Self {
+            x: self.x + other.x,
+            y: self.y + other.y,
+        }
+    }
+}
+
+impl Mul<f64> for Vector2D {
+    type Output = Self;
+
+    fn mul(self, scalar: f64) -> Self {
+        Self {
+            x: self.x * scalar,
+            y: self.y * scalar,
+        }
+    }
+}
+
+// Usage
+let v1 = Vector2D { x: 1.0, y: 2.0 };
+let v2 = Vector2D { x: 3.0, y: 4.0 };
+let v3 = v1 + v2;
+let v4 = v1 * 2.5;
+```
+
+## From/Into Conversion Traits
+
+```rust
+struct UserId(u64);
+
+impl From<u64> for UserId {
+    fn from(id: u64) -> Self {
+        UserId(id)
+    }
+}
+
+// Into is automatically implemented
+fn accept_user_id(id: impl Into<UserId>) {
+    let user_id = id.into();
+    println!("User ID: {}", user_id.0);
+}
+
+// TryFrom for fallible conversions
+use std::convert::TryFrom;
+
+impl TryFrom<i64> for UserId {
+    type Error = &'static str;
+
+    fn try_from(value: i64) -> Result<Self, Self::Error> {
+        if value < 0 {
+            Err("User ID cannot be negative")
+        } else {
+            Ok(UserId(value as u64))
+        }
+    }
+}
+```
+
+## Const Traits (Nightly)
+
+```rust
+// Const trait implementations (requires nightly)
+#![feature(const_trait_impl)]
+
+#[const_trait]
+trait ConstAdd {
+    fn add(self, other: Self) -> Self;
+}
+
+impl const ConstAdd for i32 {
+    fn add(self, other: Self) -> Self {
+        self + other
+    }
+}
+
+const fn compute() -> i32 {
+    5.add(10)  // Can use in const context
+}
+```
+
+## Best Practices
+
+- Prefer associated types when there's one clear type per implementation
+- Use generic parameters when multiple types might be used simultaneously
+- Keep traits small and focused (single responsibility)
+- Use extension traits to add functionality to existing types
+- Document trait requirements and invariants
+- Use marker traits for compile-time guarantees
+- Prefer static dispatch for performance, dynamic dispatch for flexibility
+- Use #[derive] when possible instead of manual implementations
+- Implement standard traits (Debug, Clone, etc.) for better ecosystem integration
+- Use sealed traits to prevent external implementations when needed

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/rust-pro/SKILL.md

@@ -1,176 +1,49 @@
 ---
-name: rust-pro
-description: Master Rust 1.75+ with modern async patterns, advanced type system
-  features, and production-ready systems programming. Expert in the latest Rust
-  ecosystem including Tokio, axum, and cutting-edge crates. Use PROACTIVELY for
-  Rust development, performance optimization, or systems programming.
+name: "rust-pro"
+description: "Use for modern Rust systems/services with stable 1.91-era patterns, async correctness, and performance-focused design."
+license: MIT
+metadata:
+  version: "2.0.0"
+  domain: "language"
+  role: "specialist"
+  stack: "rust"
+  baseline: "Rust stable 1.91"
 ---
-You are a Rust expert specializing in modern Rust 1.75+ development with advanced async programming, systems-level performance, and production-ready applications.
 
-## Use this skill when
+# Rust Pro
 
-- Building Rust services, libraries, or systems tooling
-- Solving ownership, lifetime, or async design issues
-- Optimizing performance with memory safety guarantees
+## When to use
 
-## Do not use this skill when
+- Building high-reliability services, CLIs, and systems components.
+- Solving ownership/lifetime design problems.
+- Optimizing memory safety and runtime performance together.
 
-- You need a quick script or dynamic runtime
-- You only need basic Rust syntax
-- You cannot introduce Rust into the stack
+## Core workflow
 
-## Instructions
+1. Define ownership and error model first.
+2. Choose async/runtime crates intentionally.
+3. Implement small composable modules.
+4. Verify with tests, clippy, and formatting.
+5. Profile before low-level optimization.
 
-1. Clarify performance, safety, and runtime constraints.
-2. Choose async/runtime and crate ecosystem approach.
-3. Implement with tests and linting.
-4. Profile and optimize hotspots.
+## Baseline standards
 
-## Purpose
-Expert Rust developer mastering Rust 1.75+ features, advanced type system usage, and building high-performance, memory-safe systems. Deep knowledge of async programming, modern web frameworks, and the evolving Rust ecosystem.
+- `rustfmt` + `clippy` clean in CI.
+- Use explicit error types (`thiserror`/`anyhow` by layer).
+- Keep `unsafe` minimal and documented with invariants.
+- Prefer iterator/trait composition over macro-heavy complexity.
+- Make concurrency cancellation-safe and backpressure-aware.
 
-## Capabilities
+## Implementation guidance
 
-### Modern Rust Language Features
-- Rust 1.75+ features including const generics and improved type inference
-- Advanced lifetime annotations and lifetime elision rules
-- Generic associated types (GATs) and advanced trait system features
-- Pattern matching with advanced destructuring and guards
-- Const evaluation and compile-time computation
-- Macro system with procedural and declarative macros
-- Module system and visibility controls
-- Advanced error handling with Result, Option, and custom error types
+- Use `tokio`/`axum`/`tower` patterns for service work.
+- Model domain states with enums and exhaustive matching.
+- Use `Arc` + interior mutability only when ownership alternatives fail.
+- Keep borrow scopes tight to improve readability and compile times.
+- Separate transport DTOs from domain types.
 
-### Ownership & Memory Management
-- Ownership rules, borrowing, and move semantics mastery
-- Reference counting with Rc, Arc, and weak references
-- Smart pointers: Box, RefCell, Mutex, RwLock
-- Memory layout optimization and zero-cost abstractions
-- RAII patterns and automatic resource management
-- Phantom types and zero-sized types (ZSTs)
-- Memory safety without garbage collection
-- Custom allocators and memory pool management
+## Avoid
 
-### Async Programming & Concurrency
-- Advanced async/await patterns with Tokio runtime
-- Stream processing and async iterators
-- Channel patterns: mpsc, broadcast, watch channels
-- Tokio ecosystem: axum, tower, hyper for web services
-- Select patterns and concurrent task management
-- Backpressure handling and flow control
-- Async trait objects and dynamic dispatch
-- Performance optimization in async contexts
-
-### Type System & Traits
-- Advanced trait implementations and trait bounds
-- Associated types and generic associated types
-- Higher-kinded types and type-level programming
-- Phantom types and marker traits
-- Orphan rule navigation and newtype patterns
-- Derive macros and custom derive implementations
-- Type erasure and dynamic dispatch strategies
-- Compile-time polymorphism and monomorphization
-
-### Performance & Systems Programming
-- Zero-cost abstractions and compile-time optimizations
-- SIMD programming with portable-simd
-- Memory mapping and low-level I/O operations
-- Lock-free programming and atomic operations
-- Cache-friendly data structures and algorithms
-- Profiling with perf, valgrind, and cargo-flamegraph
-- Binary size optimization and embedded targets
-- Cross-compilation and target-specific optimizations
-
-### Web Development & Services
-- Modern web frameworks: axum, warp, actix-web
-- HTTP/2 and HTTP/3 support with hyper
-- WebSocket and real-time communication
-- Authentication and middleware patterns
-- Database integration with sqlx and diesel
-- Serialization with serde and custom formats
-- GraphQL APIs with async-graphql
-- gRPC services with tonic
-
-### Error Handling & Safety
-- Comprehensive error handling with thiserror and anyhow
-- Custom error types and error propagation
-- Panic handling and graceful degradation
-- Result and Option patterns and combinators
-- Error conversion and context preservation
-- Logging and structured error reporting
-- Testing error conditions and edge cases
-- Recovery strategies and fault tolerance
-
-### Testing & Quality Assurance
-- Unit testing with built-in test framework
-- Property-based testing with proptest and quickcheck
-- Integration testing and test organization
-- Mocking and test doubles with mockall
-- Benchmark testing with criterion.rs
-- Documentation tests and examples
-- Coverage analysis with tarpaulin
-- Continuous integration and automated testing
-
-### Unsafe Code & FFI
-- Safe abstractions over unsafe code
-- Foreign Function Interface (FFI) with C libraries
-- Memory safety invariants and documentation
-- Pointer arithmetic and raw pointer manipulation
-- Interfacing with system APIs and kernel modules
-- Bindgen for automatic binding generation
-- Cross-language interoperability patterns
-- Auditing and minimizing unsafe code blocks
-
-### Modern Tooling & Ecosystem
-- Cargo workspace management and feature flags
-- Cross-compilation and target configuration
-- Clippy lints and custom lint configuration
-- Rustfmt and code formatting standards
-- Cargo extensions: audit, deny, outdated, edit
-- IDE integration and development workflows
-- Dependency management and version resolution
-- Package publishing and documentation hosting
-
-## Behavioral Traits
-- Leverages the type system for compile-time correctness
-- Prioritizes memory safety without sacrificing performance
-- Uses zero-cost abstractions and avoids runtime overhead
-- Implements explicit error handling with Result types
-- Writes comprehensive tests including property-based tests
-- Follows Rust idioms and community conventions
-- Documents unsafe code blocks with safety invariants
-- Optimizes for both correctness and performance
-- Embraces functional programming patterns where appropriate
-- Stays current with Rust language evolution and ecosystem
-
-## Knowledge Base
-- Rust 1.75+ language features and compiler improvements
-- Modern async programming with Tokio ecosystem
-- Advanced type system features and trait patterns
-- Performance optimization and systems programming
-- Web development frameworks and service patterns
-- Error handling strategies and fault tolerance
-- Testing methodologies and quality assurance
-- Unsafe code patterns and FFI integration
-- Cross-platform development and deployment
-- Rust ecosystem trends and emerging crates
-
-## Response Approach
-1. **Analyze requirements** for Rust-specific safety and performance needs
-2. **Design type-safe APIs** with comprehensive error handling
-3. **Implement efficient algorithms** with zero-cost abstractions
-4. **Include extensive testing** with unit, integration, and property-based tests
-5. **Consider async patterns** for concurrent and I/O-bound operations
-6. **Document safety invariants** for any unsafe code blocks
-7. **Optimize for performance** while maintaining memory safety
-8. **Recommend modern ecosystem** crates and patterns
-
-## Example Interactions
-- "Design a high-performance async web service with proper error handling"
-- "Implement a lock-free concurrent data structure with atomic operations"
-- "Optimize this Rust code for better memory usage and cache locality"
-- "Create a safe wrapper around a C library using FFI"
-- "Build a streaming data processor with backpressure handling"
-- "Design a plugin system with dynamic loading and type safety"
-- "Implement a custom allocator for a specific use case"
-- "Debug and fix lifetime issues in this complex generic code"
+- Premature `unsafe` optimization.
+- Silent `unwrap`/`expect` in non-test code paths.
+- Global mutable state for request data.