@cubis/foundry 0.3.66 → 0.3.68

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/cpp-pro/references/move-semantics-and-value-types.md

@@ -0,0 +1,149 @@
+# Move Semantics and Value Types
+
+## Move Constructor and Assignment
+
+```cpp
+class Buffer {
+    std::unique_ptr<uint8_t[]> data_;
+    size_t size_;
+
+public:
+    // Move constructor — steal resources
+    Buffer(Buffer&& other) noexcept
+        : data_(std::move(other.data_))
+        , size_(std::exchange(other.size_, 0)) {}
+
+    // Move assignment — release current, steal from other
+    Buffer& operator=(Buffer&& other) noexcept {
+        if (this != &other) {
+            data_ = std::move(other.data_);
+            size_ = std::exchange(other.size_, 0);
+        }
+        return *this;
+    }
+
+    // Rule of Five: if you define move ops, define or delete all five
+    Buffer(const Buffer&) = delete;            // expensive copy not needed
+    Buffer& operator=(const Buffer&) = delete;
+    ~Buffer() = default;
+};
+```
+
+## When to `std::move`
+
+```cpp
+// MOVE when transferring ownership
+void process(std::vector<int> data) { /* owns data */ }
+std::vector<int> v = {1, 2, 3};
+process(std::move(v)); // v is now in moved-from state
+
+// DO NOT move from const objects — silently copies instead
+const std::string s = "hello";
+std::string t = std::move(s); // copies! const prevents move
+
+// DO NOT move return values — defeats copy elision (NRVO)
+std::string make_string() {
+    std::string result = "hello";
+    return result;         // GOOD: NRVO applies
+    // return std::move(result); // BAD: prevents NRVO
+}
+
+// DO NOT use after move — object is in valid but unspecified state
+std::vector<int> v = {1, 2, 3};
+auto w = std::move(v);
+// v.size() — legal but unspecified
+// v.push_back(4) — legal, v is usable again
+```
+
+## Perfect Forwarding
+
+```cpp
+// Forward arguments preserving value category (lvalue/rvalue)
+template<typename... Args>
+auto make_unique_wrapper(Args&&... args) {
+    return std::make_unique<Widget>(std::forward<Args>(args)...);
+}
+
+// Forwarding reference (T&& with template deduction) vs rvalue reference
+template<typename T>
+void forward_ref(T&& arg) {         // forwarding reference: T is deduced
+    inner(std::forward<T>(arg));
+}
+
+void rvalue_ref(Widget&& arg) {      // rvalue reference: type is fixed
+    inner(std::move(arg));           // use move, not forward
+}
+```
+
+## Value Categories
+
+| Category    | Can take address? | Can move from?        | Examples                                          |
+| ----------- | ----------------- | --------------------- | ------------------------------------------------- |
+| **lvalue**  | Yes               | Only with `std::move` | `x`, `*p`, `a[i]`, function returning `T&`        |
+| **prvalue** | No                | Yes (implicit)        | `42`, `std::string("hi")`, function returning `T` |
+| **xvalue**  | Yes\*             | Yes                   | `std::move(x)`, function returning `T&&`          |
+
+## Copy Elision (Guaranteed since C++17)
+
+```cpp
+// Guaranteed copy elision — no copy/move constructor call
+Widget make_widget() {
+    return Widget(42); // prvalue: directly constructed in caller's storage
+}
+
+Widget w = make_widget(); // no copy, no move — guaranteed
+
+// NRVO (Named Return Value Optimization) — not guaranteed but common
+Widget make_named() {
+    Widget w(42);
+    w.configure();
+    return w; // NRVO: likely elided, but not guaranteed
+}
+```
+
+## `std::exchange` for Clean Moves
+
+```cpp
+// std::exchange replaces value and returns old value — ideal for moves
+class Socket {
+    int fd_;
+public:
+    Socket(Socket&& other) noexcept
+        : fd_(std::exchange(other.fd_, -1)) {} // steal fd, leave -1
+
+    ~Socket() {
+        if (fd_ != -1) ::close(fd_);
+    }
+};
+```
+
+## Reference Wrappers
+
+```cpp
+// std::reference_wrapper for storing references in containers
+std::vector<std::reference_wrapper<Widget>> widgets;
+Widget w1, w2;
+widgets.push_back(std::ref(w1));
+widgets.push_back(std::ref(w2));
+
+// Useful with algorithms that copy elements
+std::sort(widgets.begin(), widgets.end(),
+    [](const Widget& a, const Widget& b) { return a.id() < b.id(); });
+```
+
+## Moved-From State Obligations
+
+A moved-from object must be in a valid state that supports:
+
+1. Destruction (destructor runs)
+2. Assignment (can be reused)
+
+No other guarantees are required. Standard library types guarantee "valid but unspecified" state.
+
+```cpp
+// GOOD — reuse after move
+std::string s = "hello";
+std::string t = std::move(s);
+s = "world"; // valid: assign new value
+s.clear();   // valid: explicit reset
+```

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/cpp-pro/references/performance-and-profiling.md

@@ -0,0 +1,191 @@
+# Performance and Profiling
+
+## Profiling Workflow
+
+1. **Measure first** — never optimize without profiling evidence.
+2. **Identify hotspots** — focus on the 5% of code that takes 95% of time.
+3. **Change one thing** — benchmark before and after each change.
+4. **Verify correctness** — run tests after every optimization.
+
+## Profiling Tools
+
+```bash
+# perf (Linux) — sampling profiler
+perf record -g ./myapp          # record call graph
+perf report                      # interactive analysis
+perf stat ./myapp                # hardware counters summary
+
+# Google Benchmark — microbenchmarks
+# CMakeLists.txt
+find_package(benchmark REQUIRED)
+add_executable(bench bench.cpp)
+target_link_libraries(bench benchmark::benchmark)
+
+# VTune (Intel) — detailed CPU analysis
+vtune -collect hotspots -- ./myapp
+vtune -collect memory-access -- ./myapp
+
+# Instruments (macOS)
+xcrun xctrace record --instrument "Time Profiler" --launch ./myapp
+```
+
+## Google Benchmark Patterns
+
+```cpp
+#include <benchmark/benchmark.h>
+
+static void BM_VectorPush(benchmark::State& state) {
+    for (auto _ : state) {
+        std::vector<int> v;
+        for (int i = 0; i < state.range(0); ++i) {
+            v.push_back(i);
+        }
+        benchmark::DoNotOptimize(v.data()); // prevent dead-code elimination
+    }
+    state.SetItemsProcessed(state.iterations() * state.range(0));
+}
+BENCHMARK(BM_VectorPush)->Range(8, 1 << 20);
+
+static void BM_VectorReserved(benchmark::State& state) {
+    for (auto _ : state) {
+        std::vector<int> v;
+        v.reserve(state.range(0)); // pre-allocate
+        for (int i = 0; i < state.range(0); ++i) {
+            v.push_back(i);
+        }
+        benchmark::DoNotOptimize(v.data());
+    }
+    state.SetItemsProcessed(state.iterations() * state.range(0));
+}
+BENCHMARK(BM_VectorReserved)->Range(8, 1 << 20);
+
+BENCHMARK_MAIN();
+```
+
+## Cache-Friendly Data Layout
+
+```cpp
+// Array of Structs (AoS) — good when you access all fields together
+struct Particle_AoS {
+    float x, y, z;
+    float vx, vy, vz;
+    float mass;
+};
+std::vector<Particle_AoS> particles; // each particle contiguous
+
+// Struct of Arrays (SoA) — good when you access one field across many elements
+struct Particles_SoA {
+    std::vector<float> x, y, z;
+    std::vector<float> vx, vy, vz;
+    std::vector<float> mass;
+};
+// Iterating over just x,y,z is cache-efficient — no vx,vy,vz,mass pollution
+
+// When to use which:
+// AoS: random access to individual particles, insertion/deletion
+// SoA: SIMD operations on one field, physics simulation, GPU uploads
+```
+
+## Allocation Reduction
+
+```cpp
+// Avoid repeated heap allocations in hot paths
+// BAD — allocates string each iteration
+for (const auto& item : items) {
+    std::string key = "prefix_" + item.name(); // allocation
+    cache.lookup(key);
+}
+
+// GOOD — reuse string buffer
+std::string key;
+key.reserve(64);
+for (const auto& item : items) {
+    key = "prefix_";
+    key += item.name(); // may reuse existing buffer
+    cache.lookup(key);
+}
+
+// string_view to avoid copies
+void process(std::string_view input) {  // no copy
+    auto pos = input.find(':');
+    auto key = input.substr(0, pos);    // no copy — just a view
+    auto val = input.substr(pos + 1);
+}
+
+// Small Buffer Optimization (SBO) — many types use it
+// std::string: typically 15-22 chars stored inline (no heap)
+// std::function: small callables stored inline
+// std::any: small types stored inline
+// pmr allocators: customize allocation strategy
+
+// Pre-allocate containers
+std::vector<int> v;
+v.reserve(expected_size); // avoids repeated reallocation
+```
+
+## Avoiding Virtual Dispatch in Hot Paths
+
+```cpp
+// Virtual dispatch: ~3-5ns per call (cache miss: ~100ns)
+// For tight loops with millions of iterations, this matters
+
+// std::variant + std::visit — static dispatch
+using Shape = std::variant<Circle, Rectangle, Triangle>;
+
+double total_area(const std::vector<Shape>& shapes) {
+    double sum = 0;
+    for (const auto& s : shapes) {
+        sum += std::visit([](const auto& shape) {
+            return shape.area(); // statically dispatched
+        }, s);
+    }
+    return sum;
+}
+
+// CRTP for static polymorphism (see template-and-concepts-patterns.md)
+```
+
+## Compiler Hints
+
+```cpp
+// [[likely]] and [[unlikely]] for branch prediction hints
+if (result == SUCCESS) [[likely]] {
+    process(result);
+} else [[unlikely]] {
+    handle_error(result);
+}
+
+// [[assume]] (C++23) — optimizer hint
+void process(int x) {
+    [[assume(x > 0)]]; // optimizer can assume this is true
+    // ... code that benefits from knowing x > 0
+}
+
+// Prefetch for known access patterns
+for (size_t i = 0; i < n; ++i) {
+    __builtin_prefetch(&data[i + 16], 0, 1); // prefetch ahead
+    process(data[i]);
+}
+```
+
+## Link-Time Optimization (LTO)
+
+```bash
+# Enable LTO
+g++ -flto -O2 -o myapp *.cpp
+clang++ -flto=thin -O2 -o myapp *.cpp  # thin LTO: faster build, similar gains
+
+# CMake
+set(CMAKE_INTERPROCEDURAL_OPTIMIZATION TRUE)
+```
+
+## Common Performance Anti-Patterns
+
+| Anti-pattern                     | Cost                      | Fix                                          |
+| -------------------------------- | ------------------------- | -------------------------------------------- |
+| `std::map` for lookup            | O(log n) + cache misses   | `std::unordered_map` or sorted `std::vector` |
+| `std::list` traversal            | Cache miss per node       | `std::vector` or `std::deque`                |
+| `std::shared_ptr` in hot path    | Atomic ref-count per copy | `unique_ptr` or raw observer pointer         |
+| String concatenation in loop     | O(n²) total allocations   | `std::string::reserve` + append              |
+| `virtual` dispatch in tight loop | Vtable indirection        | `std::variant` + `visit` or CRTP             |
+| Exceptions for control flow      | Stack unwinding cost      | Error codes or `expected<T, E>`              |

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/cpp-pro/references/raii-and-modern-cpp-checklist.md

@@ -0,0 +1,87 @@
+# RAII and Modern C++ Checklist
+
+## RAII ownership patterns
+
+### Smart pointer selection
+
+| Pattern             | Type                 | When to use                                                                   |
+| ------------------- | -------------------- | ----------------------------------------------------------------------------- |
+| Exclusive ownership | `std::unique_ptr<T>` | Default choice. One owner, zero overhead, move-only.                          |
+| Shared ownership    | `std::shared_ptr<T>` | Multiple owners with shared lifetime. Use sparingly — adds refcount overhead. |
+| Non-owning observer | `T*` or `T&`         | Borrowing without ownership. Never delete through a raw pointer.              |
+| Weak observer       | `std::weak_ptr<T>`   | Observing shared-owned object without preventing destruction.                 |
+
+- Prefer `std::make_unique` and `std::make_shared` over raw `new`. They are exception-safe and more efficient.
+- Use custom deleters for non-memory resources: `unique_ptr<FILE, decltype(&fclose)> f(fopen(...), fclose);`
+
+### Rule of five / zero
+
+- **Rule of zero**: If a class only contains RAII members (smart pointers, containers), don't write any special member functions.
+- **Rule of five**: If you must write a destructor, also write or delete: copy constructor, copy assignment, move constructor, move assignment.
+- Use `= default` and `= delete` explicitly. Never leave special members implicitly generated when the class manages resources.
+
+## Value semantics
+
+- Prefer passing by value for small types (<= 2 words) and types you need to move from.
+- Pass large types by `const&` for reading, by `&&` for consuming.
+- Use `std::string_view` and `std::span<T>` for non-owning views of contiguous data.
+- Return by value — compilers apply NRVO/RVO. Avoid `std::move` on return statements in most cases.
+
+## Move correctness
+
+- After `std::move`, the source object is in a valid-but-unspecified state. Only assign to it or destroy it.
+- Mark move constructors and move assignment operators `noexcept` — this enables `std::vector` to use moves on reallocation.
+- Test that moved-from objects don't leak resources or crash when destroyed.
+
+## Concepts and constraints (C++20/23)
+
+```cpp
+template<typename T>
+concept Hashable = requires(T a) {
+    { std::hash<T>{}(a) } -> std::convertible_to<std::size_t>;
+};
+
+template<Hashable Key, typename Value>
+class HashMap { /* ... */ };
+```
+
+- Use concepts to replace SFINAE. They produce clear error messages and are readable.
+- Define concepts in terms of required expressions, not just type traits.
+- Combine concepts with `requires` clauses for complex constraints.
+
+## std::variant and pattern matching
+
+```cpp
+using Shape = std::variant<Circle, Rectangle, Triangle>;
+
+double area(const Shape& s) {
+    return std::visit(overloaded{
+        [](const Circle& c)    { return std::numbers::pi * c.r * c.r; },
+        [](const Rectangle& r) { return r.w * r.h; },
+        [](const Triangle& t)  { return 0.5 * t.base * t.height; }
+    }, s);
+}
+```
+
+- Use `std::variant` over inheritance for closed type sets. Adding a new alternative causes compile errors at all visit sites.
+- Use the `overloaded` pattern (aggregate of lambdas) for exhaustive visiting.
+
+## std::expected (C++23)
+
+```cpp
+std::expected<User, Error> find_user(int id) {
+    if (auto it = db.find(id); it != db.end())
+        return *it;
+    return std::unexpected(Error::NotFound);
+}
+```
+
+- Use `std::expected<T, E>` for recoverable errors in performance-sensitive paths instead of exceptions.
+- Chain operations with `.and_then()`, `.transform()`, `.or_else()` for monadic error handling.
+
+## Concurrency checklist
+
+- Use `std::jthread` + `std::stop_token` for threads that need cancellation.
+- Use `std::scoped_lock` for multi-mutex locking — prevents deadlocks from inconsistent lock order.
+- Use `std::atomic` with `memory_order_relaxed` only when you can prove no ordering dependency exists.
+- Run ThreadSanitizer (`-fsanitize=thread`) on all concurrent tests in CI.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/cpp-pro/references/template-and-concepts-patterns.md

@@ -0,0 +1,205 @@
+# Template and Concepts Patterns
+
+## Concepts (C++20/23)
+
+Concepts replace SFINAE with readable, composable constraints.
+
+```cpp
+#include <concepts>
+
+// Basic concept usage
+template<std::integral T>
+T add(T a, T b) { return a + b; }
+
+// Custom concept
+template<typename T>
+concept Serializable = requires(T t, std::ostream& os) {
+    { t.serialize(os) } -> std::same_as<void>;
+    { T::deserialize(os) } -> std::same_as<T>;
+};
+
+// Use in function template
+template<Serializable T>
+void save(const T& obj, const std::filesystem::path& path) {
+    std::ofstream file(path);
+    obj.serialize(file);
+}
+
+// Concept with multiple requirements
+template<typename T>
+concept Hashable = requires(T a) {
+    { std::hash<T>{}(a) } -> std::convertible_to<std::size_t>;
+    requires std::equality_comparable<T>;
+};
+
+// Constrained auto
+void process(std::ranges::range auto&& r) {
+    for (auto&& elem : r) {
+        // works with any range
+    }
+}
+```
+
+## Concept Composition
+
+```cpp
+// Combine concepts with &&, ||
+template<typename T>
+concept Numeric = std::integral<T> || std::floating_point<T>;
+
+template<typename T>
+concept OrderedNumeric = Numeric<T> && std::totally_ordered<T>;
+
+// Subsumption — more constrained overload wins
+template<std::integral T>
+void process(T val) { /* integral-specific */ }
+
+template<Numeric T>
+void process(T val) { /* fallback for floating point */ }
+
+// int → matches std::integral (more constrained), calls first overload
+// double → matches Numeric, calls second overload
+```
+
+## Variadic Templates
+
+```cpp
+// Fold expressions (C++17) — clean variadic operations
+template<typename... Args>
+auto sum(Args... args) {
+    return (args + ...); // right fold
+}
+
+// Print all arguments
+template<typename... Args>
+void print_all(Args&&... args) {
+    ((std::cout << args << " "), ...); // comma fold
+    std::cout << "\n";
+}
+
+// Constrained variadic
+template<std::convertible_to<std::string_view>... Args>
+std::string join(std::string_view sep, Args&&... args) {
+    std::string result;
+    ((result += std::string(args) + std::string(sep)), ...);
+    if (!result.empty()) result.resize(result.size() - sep.size());
+    return result;
+}
+```
+
+## `constexpr` and `consteval`
+
+```cpp
+// constexpr — evaluable at compile time or runtime
+constexpr int factorial(int n) {
+    if (n <= 1) return 1;
+    return n * factorial(n - 1);
+}
+
+constexpr int ct = factorial(10);  // computed at compile time
+int rt = factorial(runtime_val);    // computed at runtime
+
+// consteval — MUST be evaluated at compile time
+consteval int compile_time_only(int n) {
+    return n * n;
+}
+
+constexpr int x = compile_time_only(5); // OK
+// int y = compile_time_only(runtime_val); // ERROR: not a constant expression
+
+// constexpr containers (C++20)
+constexpr auto make_primes() {
+    std::array<int, 5> primes{};
+    // ... sieve algorithm
+    return primes;
+}
+constexpr auto primes = make_primes(); // computed at compile time
+
+// if constexpr — compile-time branching
+template<typename T>
+auto to_string(const T& val) {
+    if constexpr (std::is_arithmetic_v<T>) {
+        return std::to_string(val);
+    } else if constexpr (std::is_same_v<T, std::string>) {
+        return val;
+    } else {
+        static_assert(false, "unsupported type");
+    }
+}
+```
+
+## CTAD (Class Template Argument Deduction)
+
+```cpp
+// Deduction guides — compiler deduces template arguments
+std::vector v = {1, 2, 3};        // deduces vector<int>
+std::pair p = {"hello", 42};      // deduces pair<const char*, int>
+std::optional o = 3.14;           // deduces optional<double>
+
+// Custom deduction guide
+template<typename T>
+struct Wrapper {
+    T value;
+    Wrapper(T v) : value(std::move(v)) {}
+};
+
+// Deduction guide for string literals
+Wrapper(const char*) -> Wrapper<std::string>;
+
+auto w = Wrapper("hello"); // deduces Wrapper<std::string>, not Wrapper<const char*>
+```
+
+## Type Traits and `static_assert`
+
+```cpp
+#include <type_traits>
+
+// Compile-time type validation
+template<typename T>
+class Container {
+    static_assert(std::is_nothrow_move_constructible_v<T>,
+        "Container requires nothrow movable types for exception safety");
+    static_assert(!std::is_reference_v<T>,
+        "Container cannot store references — use reference_wrapper");
+    // ...
+};
+
+// Conditional types
+template<typename T>
+using storage_type = std::conditional_t<
+    sizeof(T) <= sizeof(void*),
+    T,                    // small: store by value
+    std::unique_ptr<T>    // large: store by pointer
+>;
+```
+
+## CRTP (Curiously Recurring Template Pattern)
+
+Static polymorphism without virtual dispatch overhead.
+
+```cpp
+template<typename Derived>
+class Comparable {
+public:
+    bool operator!=(const Derived& other) const {
+        return !(static_cast<const Derived&>(*this) == other);
+    }
+    bool operator>(const Derived& other) const {
+        return other < static_cast<const Derived&>(*this);
+    }
+    // Derived must implement operator== and operator<
+};
+
+class Temperature : public Comparable<Temperature> {
+    double celsius_;
+public:
+    explicit Temperature(double c) : celsius_(c) {}
+
+    bool operator==(const Temperature& other) const {
+        return celsius_ == other.celsius_;
+    }
+    bool operator<(const Temperature& other) const {
+        return celsius_ < other.celsius_;
+    }
+};
+```