@polderlabs/bizar 8.0.0 → 9.0.0

package/.claude/worktrees/kanban-overhaul/.claude/skills/cpp-coding-standards/references/concurrency.md

@@ -0,0 +1,320 @@
+# Concurrency in Modern C++
+
+This reference covers mutexes, atomics, threads, and common concurrency patterns.
+
+## Core Principle: No Data Races
+
+A **data race** is simultaneous, unsynchronized access to the same memory location where at least one access is a write. It is **undefined behavior**.
+
+Every shared variable must be:
+1. Protected by a mutex (`std::lock_guard`), OR
+2. Declared `std::atomic`, OR
+3. Never modified concurrently (read-only after initialization)
+
+## Mutex and Lock Guards
+
+### `std::lock_guard` — Simplest Guard
+
+RAII lock — unlocks on scope exit.
+
+```cpp
+#include <mutex>
+
+std::mutex mtx;
+int counter = 0;
+
+void increment() {
+    std::lock_guard<std::mutex> lock(mtx);  // acquires lock
+    ++counter;  // safe: only one thread here at a time
+}  // destructor releases lock
+```
+
+### `std::unique_lock` — Flexible Guard
+
+Supports deferred locking, timed locking, and manual unlock.
+
+```cpp
+std::mutex mtx;
+std::unique_lock<std::mutex> lock(mtx);  // locks immediately
+lock.unlock();   // temporarily unlock
+lock.lock();     // relock
+// ...
+// automatically unlocks when lock goes out of scope
+
+// Deferred — lock is not acquired yet
+std::unique_lock<std::mutex> deferred(mtx, std::defer_lock);
+// ... other code ...
+deferred.lock();  // now lock
+deferred.unlock(); // unlock early if needed
+```
+
+### `std::scoped_lock` (C++17) — Multiple Mutexes
+
+Locks multiple mutexes without deadlock (uses the deadlock-avoidance algorithm).
+
+```cpp
+std::mutex m1, m2, m3;
+
+// GOOD: locks all three safely — avoids deadlock
+std::scoped_lock lock(m1, m2, m3);
+// ... access protected data ...
+```
+
+### The Deadlock Problem
+
+Lock mutexes in a **fixed order** if using multiple `lock_guard`/`unique_lock`. Or prefer `scoped_lock`.
+
+```cpp
+// DANGEROUS: different threads lock in opposite orders → deadlock
+void transfer(Account& from, Account& to, int amount) {
+    std::lock_guard<std::mutex> l1(from.mtx);
+    std::lock_guard<std::mutex> l2(to.mtx);  // deadlock if another thread does to→from
+    from.balance -= amount;
+    to.balance += amount;
+}
+
+// SAFE: scoped_lock locks both simultaneously
+void transfer(Account& from, Account& to, int amount) {
+    std::scoped_lock lock(from.mtx, to.mtx);  // no deadlock
+    from.balance -= amount;
+    to.balance += amount;
+}
+```
+
+## Atomics
+
+Use `std::atomic` for simple shared values where the type supports lock-free operations.
+
+```cpp
+#include <atomic>
+
+// Basic types
+std::atomic<int> counter{0};
+counter.fetch_add(1);           // returns old value
+counter++;                       // simple ops also work
+int old = counter.exchange(42);  // read and write
+
+// Memory ordering
+counter.store(1, std::memory_order_relaxed);   // only use for counters
+counter.store(1, std::memory_order_release);  // release semantics
+int x = counter.load(std::memory_order_acquire);  // acquire semantics
+
+// Default memory_order_seq_cst is safest and the default — use it unless you
+// have measured that relaxed/acq_rel gives meaningful gains
+
+// Boolean flag
+std::atomic<bool> ready{false};
+void producer() { ready.store(true, std::memory_order_release); }
+void consumer() {
+    while (!ready.load(std::memory_order_acquire)) {
+        std::this_thread::yield();
+    }
+    // consume
+}
+```
+
+## `std::atomic` with User-Defined Types
+
+A `std::atomic<T>` requires `T` to be trivially copyable and lock-free for the operations to be available.
+
+```cpp
+struct Point { int x; int y; };
+
+// std::atomic<Point> — only works if Point is trivially copyable and
+// the platform provides lock-free atomics for its size
+static_assert(std::is_trivially_copyable_v<Point>);
+static_assert(std::atomic<Point>::is_always_lock_free());
+```
+
+## Threads
+
+### `std::thread` Lifecycle — Critical Rule
+
+**Every `std::thread` must be either joined (`.join()`) or detached (`.detach()`) before destruction.** A `std::thread` that is neither joined nor detached calls `std::terminate`.
+
+```cpp
+#include <thread>
+
+void background_task(int param) { /* ... */ }
+
+// GOOD — explicit join
+std::thread t(background_task, 42);
+t.join();   // wait for completion
+
+// GOOD — detached (fire and forget, but lose ability to synchronize)
+std::thread t(background_task, 42);
+t.detach(); // thread continues running independently
+
+// DANGEROUS — terminate() called
+{
+    std::thread t(background_task, 42);
+    // t not joined or detached here
+} // std::terminate() called
+```
+
+### `std::jthread` (C++20) — Auto-Join
+
+Automatically joins on destruction. Prefer `std::jthread` over `std::thread` in C++20.
+
+```cpp
+#include <thread>
+
+void cancellable_work(std::stop_token token) {
+    while (!token.stop_requested()) {
+        do_step();
+    }
+}
+
+std::jthread jt(cancellable_work);
+// ... work happens in background ...
+// jt destroyed here → automatically requests stop and joins
+```
+
+### Stop Tokens (C++20)
+
+Gracefully stop a `jthread` without polling a flag.
+
+```cpp
+void long_task(std::stop_token token) {
+    for (size_t i = 0; i < 1000; ++i) {
+        if (token.stop_requested()) {
+            std::cout << "Stopped at " << i << '\n';
+            return;  // clean exit
+        }
+        compute_step(i);
+    }
+}
+
+std::jthread worker(long_task);
+std::this_thread::sleep_for(std::chrono::milliseconds(10));
+worker.request_stop();  // signals stop_requested()
+```
+
+## `std::condition_variable`
+
+Used to block a thread until another thread signals that a condition is true.
+
+```cpp
+#include <condition_variable>
+#include <queue>
+
+std::mutex mtx;
+std::condition_variable cv;
+std::queue<int> q;
+
+void producer() {
+    for (int i = 0; i < 10; ++i) {
+        {
+            std::lock_guard<std::mutex> lock(mtx);
+            q.push(i);
+        }
+        cv.notify_one();  // wake one waiting consumer
+    }
+}
+
+void consumer() {
+    while (true) {
+        std::unique_lock<std::mutex> lock(mtx);
+        cv.wait(lock, [&] { return !q.empty() || /* done signal */; });
+        if (q.empty()) break;  // producer done
+        int val = q.front();
+        q.pop();
+        lock.unlock();  // unlock while processing (optional)
+        // process val
+    }
+}
+```
+
+## `std::future` and `std::promise`
+
+One-shot communication from a background thread to a caller.
+
+```cpp
+#include <future>
+
+std::promise<int> p;
+std::future<int> f = p.get_future();
+
+std::thread t([&p]() {
+    // compute result
+    p.set_value(42);
+    // or on error: p.set_exception(std::make_exception_ptr(std::runtime_error("fail")));
+});
+
+int result = f.get();  // blocks until value is set
+t.join();
+```
+
+### `std::async` — Simpler Parallelism
+
+Launch a task asynchronously and get a future.
+
+```cpp
+#include <future>
+
+// LaunchPolicy::async = run in separate thread
+// LaunchPolicy::deferred = lazy evaluation in calling thread
+auto fut = std::async(std::launch::async, []() {
+    return compute_expensive_result();
+});
+
+int result = fut.get();  // blocks until ready
+```
+
+## Common Concurrency Mistakes
+
+```cpp
+// WRONG: Forgetting to protect shared data
+std::string shared;  // data race: multiple threads write
+void writer() { shared = "hello"; }
+void reader() { std::cout << shared; }
+std::thread t1(writer), t2(reader);  // DATA RACE
+
+// RIGHT: Protect with mutex
+std::mutex mtx;
+std::string shared;
+void writer() {
+    std::lock_guard<std::mutex> lock(mtx);
+    shared = "hello";
+}
+void reader() {
+    std::lock_guard<std::mutex> lock(mtx);
+    std::cout << shared;
+}
+
+// WRONG: Passing references to local variables to threads
+void bad() {
+    std::string s = "data";
+    std::thread t([&s]() { use(s); });  // reference to local — DANGER
+    t.detach();  // s destroyed, thread still uses it
+}
+
+// RIGHT: Move or copy into the thread
+void good() {
+    std::string s = "data";
+    std::thread t([s]() { use(s); });  // copy into thread's closure
+    t.join();  // or jthread
+}
+
+// WRONG: Locking a mutex and calling an unknown function (potential deadlock)
+// If the function tries to lock the same mutex → deadlock
+void dangerous(std::mutex& m) {
+    std::lock_guard<std::mutex> lock(m);
+    call_unknown_function();  // might lock m again
+}
+```
+
+## Summary Table
+
+| Primitive | Use When |
+|---|---|
+| `std::mutex` | Protect a single variable or small critical section |
+| `std::lock_guard` | Simple RAII lock (most common) |
+| `std::unique_lock` | Deferred/timed locking, condition variables |
+| `std::scoped_lock` | Locking multiple mutexes at once |
+| `std::atomic` | Simple shared counters, flags, lock-free data |
+| `std::thread` | Create a thread (remember join/detach) |
+| `std::jthread` | Thread that should auto-join and support stop tokens |
+| `std::condition_variable` | Block until a condition is signaled |
+| `std::future`/`std::promise` | One-shot result from background task |
+| `std::async` | Simple parallel task without explicit thread management |

package/.claude/worktrees/kanban-overhaul/.claude/skills/cpp-coding-standards/references/error-handling.md

@@ -0,0 +1,229 @@
+# Error Handling in Modern C++
+
+This reference covers when to use exceptions, error codes, or `std::expected`.
+
+## Decision Guide
+
+| Scenario | Recommended Approach |
+|---|---|
+| Constructor failure that leaves object in invalid state | Exception |
+| Expected failure (element not found, invalid input format) | `std::optional`, error code, or `std::expected` |
+| Library with many failure modes | `std::error_code` or `std::expected<T, E>` |
+| Performance-critical hot path where exceptions are unacceptable | Error codes |
+| Impossible failure (e.g., `std::terminate`) | Let it crash |
+| Memory allocation failure | `std::bad_alloc` exception (let it propagate) |
+
+**Golden rule:** Throw exceptions for *exceptional* conditions — things that should not happen in normal operation and from which the caller cannot reasonably recover. Do not use exceptions for expected failure cases (file not found, invalid user input).
+
+## Exceptions
+
+### Throwing and Catching
+
+```cpp
+#include <stdexcept>
+
+class ConfigError : public std::runtime_error {
+public:
+    explicit ConfigError(const std::string& msg) : std::runtime_error(msg) {}
+};
+
+void load_config(const std::string& path) {
+    std::ifstream in(path);
+    if (!in) {
+        throw ConfigError("Cannot open config: " + path);
+    }
+    // ...
+}
+
+// Caller
+try {
+    load_config("app.cfg");
+} catch (const ConfigError& e) {
+    std::cerr << "Config error: " << e.what() << '\n';
+} catch (const std::exception& e) {
+    std::cerr << "Unexpected: " << e.what() << '\n';
+}
+```
+
+### Constructor Failure
+
+Prefer to signal constructor failure via:
+1. A `static` factory function that returns `std::optional` or `std::expected`
+2. Throwing an exception (acceptable if construction failure is truly exceptional)
+
+```cpp
+// Approach 1: Factory returning optional
+class Widget {
+    Widget(int param) {}  // private or non-public
+public:
+    static std::optional<Widget> create(int param) {
+        if (param < 0) return std::nullopt;
+        return Widget(param);
+    }
+};
+
+// Approach 2: Exception for truly unexpected failure
+class NetworkConnection {
+public:
+    NetworkConnection(const std::string& host, int port) {
+        if (port < 0 || port > 65535)
+            throw std::invalid_argument("Invalid port: " + std::to_string(port));
+    }
+};
+```
+
+## Error Codes
+
+Traditional C-style error handling via return values. Works well in performance-sensitive code and for system-level APIs.
+
+```cpp
+#include <system_error>
+
+enum class MyError { NotFound = 1, InvalidInput, Timeout };
+
+// Return std::error_code — idiomatic C++ error code
+std::error_code read_data(const std::string& path, std::vector<char>& out) {
+    std::ifstream in(path, std::ios::binary);
+    if (!in) return std::errc::no_such_file_or_directory;
+    out.assign(std::istreambuf_iterator<char>(in), {});
+    return {};  // empty error_code = success
+}
+
+// Usage
+std::vector<char> data;
+std::error_code ec = read_data("file.bin", data);
+if (ec) {
+    std::cerr << "Read failed: " << ec.message() << '\n';
+    return;
+}
+// use data
+```
+
+## `std::expected<T, E>` (C++23)
+
+The preferred way to handle expected failures in modern C++. Available in C++23; use the `std::expected` proposal or the `tl::expected` library for C++17/20.
+
+```cpp
+// C++23 std::expected
+#include <expected>
+
+std::expected<int, std::error_code> parse_int(std::string_view s) {
+    int result = 0;
+    for (char c : s) {
+        if (!std::isdigit(c))
+            return std::unexpected(std::errc::invalid_argument);
+        result = result * 10 + (c - '0');
+    }
+    return result;
+}
+
+// Usage
+auto opt = parse_int("123abc");
+if (opt) {
+    std::cout << "Value: " << *opt << '\n';
+} else {
+    std::cerr << "Parse failed: " << opt.error().message() << '\n';
+}
+
+// Transform with .and_then (monadic interface in C++23)
+auto doubled = parse_int("42").transform([](int x) { return x * 2; });
+// doubled == 84
+```
+
+### Monadic Operations (C++23)
+
+```cpp
+// and_then — chain operations that can fail
+auto result = read_config()
+    .and_then([](const Config& c) -> std::expected<Settings, E> {
+        return validate(c);
+    })
+    .transform([](const Settings& s) {
+        return process(s);  // successful transform
+    });
+
+// or_else — handle failure
+auto with_fallback = read_config().or_else([](auto) {
+    return read_default_config();
+});
+
+// transform_error — map error type
+auto with_err_msg = parse_int("abc").transform_error([](std::errc e) {
+    return std::string(std::strerror(std::make_error_code(e).value()));
+});
+```
+
+## `std::optional` for Expected Absence
+
+When the only "failure" is that a value is not present, `std::optional` is the right tool.
+
+```cpp
+std::optional<int> find_user(const std::string& name) {
+    for (auto& [n, id] : user_db) {
+        if (n == name) return {id};
+    }
+    return std::nullopt;
+}
+
+if (auto uid = find_user("Bob")) {
+    std::cout << "User ID: " << *uid << '\n';
+} else {
+    std::cout << "User not found\n";
+}
+```
+
+## Exception Safety Guarantees
+
+Four levels of exception safety:
+
+| Level | Guarantee | Use When |
+|---|---|---|
+| **Nothrow** (`noexcept`) | Operation never throws | Move constructors, swap, essential operations |
+| **Strong** | Failed op leaves state unchanged | Most business logic |
+| **Basic** | Failed op leaves object valid | Destructors, `operator=` |
+| **No guarantee** | Any behavior on failure | Avoid |
+
+```cpp
+class Widget {
+    std::vector<int> data_;
+public:
+    // Strong exception safety — copy-on-write pattern
+    void replace(std::vector<int> new_data) {
+        std::vector<int> tmp = std::move(new_data);  // copy into temp
+        data_.swap(tmp);  // noexcept swap
+        // old data_ is in tmp, destroyed when tmp goes out of scope
+    }
+
+    // noexcept on functions that cannot fail
+    void clear() noexcept { data_.clear(); }
+    bool empty() const noexcept { return data_.empty(); }
+};
+```
+
+## noexcept — When to Use
+
+Use `noexcept` on functions that **cannot** throw by design. This enables optimizations and documents API contracts.
+
+```cpp
+// Destructors should be noexcept (the default)
+class Resource {
+    int* ptr_ = nullptr;
+public:
+    ~Resource() { delete[] ptr_; }  // implicitly noexcept
+};
+
+// Move constructors of containers are noexcept — this matters
+// A vector will use move() instead of copy() if the move ctor is noexcept
+struct Important {
+    std::vector<int> big_data;
+    Important(Important&&) noexcept = default;  // ensure noexcept
+};
+
+// Mark observers noexcept
+template <typename T>
+bool is_empty(const std::vector<T>& v) noexcept {
+    return v.empty();  // cannot throw — .empty() is noexcept
+}
+```
+
+**Do NOT mark a function `noexcept` if it can throw.** Misleading `noexcept` violates caller expectations and can cause `std::terminate` to be called unexpectedly.