@cubis/foundry 0.3.70 → 0.3.72

package/workflows/powers/c-pro/references/common-ub-and-portability.md

@@ -0,0 +1,166 @@
+# Common Undefined Behavior and Portability
+
+## Undefined Behavior Catalog
+
+These are the most common sources of UB in C code. Sanitizers catch many at runtime, but prevention through coding discipline is the primary defense.
+
+### Signed Integer Overflow
+
+```c
+// UB — signed overflow is undefined in C
+int x = INT_MAX;
+x += 1; // UB: compiler may assume this never happens and optimize accordingly
+
+// SAFE — check before arithmetic
+if (x <= INT_MAX - 1) {
+    x += 1;
+}
+
+// SAFE — use unsigned for wrapping arithmetic
+unsigned int y = UINT_MAX;
+y += 1; // defined: wraps to 0
+```
+
+### Null Pointer Dereference
+
+```c
+// UB — dereferencing NULL
+int *p = NULL;
+int val = *p; // UB
+
+// SAFE — check before dereference
+if (p != NULL) {
+    int val = *p;
+}
+
+// Gotcha: compiler may remove NULL checks after dereference
+int val = *p;        // if this executes, compiler assumes p != NULL
+if (p == NULL) { ... } // compiler may optimize this away as "unreachable"
+```
+
+### Buffer Overflow and Out-of-Bounds Access
+
+```c
+// UB — reading/writing past allocation
+int arr[10];
+arr[10] = 42; // UB: index 10 is one past the end
+
+// UB — string function overflow
+char buf[8];
+strcpy(buf, "this string is too long"); // UB: writes past buf
+
+// SAFE — use bounded functions
+char buf[8];
+strncpy(buf, source, sizeof(buf) - 1);
+buf[sizeof(buf) - 1] = '\0'; // ensure null termination
+
+// Better: use snprintf for formatted strings
+snprintf(buf, sizeof(buf), "%s", source);
+```
+
+### Use After Free and Double Free
+
+```c
+// UB — use after free
+char *data = malloc(100);
+free(data);
+data[0] = 'x'; // UB: data is freed
+
+// UB — double free
+free(data);
+free(data); // UB: second free on already-freed pointer
+
+// SAFE — NULL after free
+free(data);
+data = NULL; // prevents use-after-free (dereference NULL → crash, not silent corruption)
+```
+
+### Strict Aliasing Violations
+
+```c
+// UB — accessing memory through incompatible pointer type
+float f = 3.14f;
+int *ip = (int *)&f;
+int bits = *ip; // UB: strict aliasing violation
+
+// SAFE — use memcpy for type punning
+float f = 3.14f;
+int bits;
+memcpy(&bits, &f, sizeof(bits)); // defined behavior
+
+// SAFE — union-based type punning (C99+, implementation-defined but widely supported)
+union { float f; int i; } u;
+u.f = 3.14f;
+int bits = u.i;
+```
+
+### Uninitialized Variable Reads
+
+```c
+// UB — reading uninitialized automatic variable
+int x;
+printf("%d\n", x); // UB: x has indeterminate value
+
+// SAFE — always initialize
+int x = 0;
+```
+
+## Implementation-Defined Behavior Traps
+
+These are defined by the compiler/platform but differ across implementations:
+
+| Behavior                      | Varies by           | Recommendation                                                    |
+| ----------------------------- | ------------------- | ----------------------------------------------------------------- |
+| `sizeof(int)`                 | Platform            | Use fixed-width types (`int32_t`, `uint64_t`) for data structures |
+| Bit-shift of negative values  | Compiler            | Avoid shifting signed integers; use unsigned                      |
+| Struct padding and alignment  | Compiler + platform | Use `offsetof`, `_Alignof`; pack with attributes only when needed |
+| Char signedness (`char`)      | Compiler            | Use `signed char` or `unsigned char` explicitly for arithmetic    |
+| Evaluation order of arguments | Compiler            | Avoid side effects in function argument expressions               |
+
+## Cross-Platform Portability
+
+```c
+// Use fixed-width integers for portable data structures
+#include <stdint.h>
+
+typedef struct {
+    uint32_t id;
+    int64_t timestamp;
+    uint16_t flags;
+} __attribute__((packed)) WireMessage; // packed for network protocol
+
+// Endianness-safe serialization
+#include <arpa/inet.h> // or use manual byte swapping
+
+void serialize(const WireMessage *msg, uint8_t *buf) {
+    uint32_t id_be = htonl(msg->id);
+    memcpy(buf, &id_be, sizeof(id_be));
+    // ... continue for other fields
+}
+
+// Feature detection with preprocessor
+#if defined(__linux__)
+    #include <sys/epoll.h>
+#elif defined(__APPLE__)
+    #include <sys/event.h>
+#elif defined(_WIN32)
+    #include <winsock2.h>
+#endif
+```
+
+## Compiler Warning Flags for UB Detection
+
+```bash
+# GCC — maximum diagnostic coverage
+gcc -Wall -Wextra -Wpedantic -Werror \
+    -Wformat=2 -Wformat-overflow -Wformat-truncation \
+    -Wconversion -Wsign-conversion \
+    -Wshadow -Wdouble-promotion \
+    -Wnull-dereference -Wuninitialized \
+    -Wstrict-aliasing=2 \
+    -fstack-protector-strong
+
+# Clang — additional checks
+clang -Weverything -Wno-padded -Wno-disabled-macro-expansion \
+      -fsanitize=undefined,address
+```

package/workflows/powers/c-pro/references/debugging-with-sanitizers.md

@@ -0,0 +1,205 @@
+# Debugging with Sanitizers
+
+## AddressSanitizer (ASan)
+
+Detects: buffer overflow, use-after-free, use-after-return, double-free, memory leaks.
+
+```bash
+# Compile with ASan
+gcc -fsanitize=address -fno-omit-frame-pointer -g -O1 -o myapp myapp.c
+clang -fsanitize=address -fno-omit-frame-pointer -g -O1 -o myapp myapp.c
+
+# Run — crashes with detailed report on first error
+./myapp
+# Output shows: error type, stack trace, shadow memory state
+```
+
+```c
+// ASan catches this at runtime
+void trigger_heap_overflow(void) {
+    int *arr = malloc(10 * sizeof(int));
+    arr[10] = 42; // heap-buffer-overflow detected
+    free(arr);
+}
+
+// ASan catches use-after-free
+void trigger_uaf(void) {
+    int *p = malloc(sizeof(int));
+    free(p);
+    *p = 42; // heap-use-after-free detected
+}
+```
+
+### ASan Options
+
+```bash
+# Environment variable to control ASan behavior
+export ASAN_OPTIONS="detect_leaks=1:halt_on_error=0:print_stats=1"
+
+# detect_leaks=1    — also report memory leaks at exit
+# halt_on_error=0   — continue after first error (find multiple issues)
+# print_stats=1     — show memory allocation statistics
+# suppressions=file — suppress known false positives
+```
+
+## UndefinedBehaviorSanitizer (UBSan)
+
+Detects: signed integer overflow, null pointer dereference, misaligned access, shift overflow, division by zero.
+
+```bash
+# Compile with UBSan
+gcc -fsanitize=undefined -fno-omit-frame-pointer -g -o myapp myapp.c
+
+# Common sub-sanitizers (can be selected individually)
+gcc -fsanitize=signed-integer-overflow,null,alignment,shift -g -o myapp myapp.c
+```
+
+```c
+// UBSan detects signed overflow
+int overflow(void) {
+    int x = INT_MAX;
+    return x + 1; // runtime error: signed integer overflow
+}
+
+// UBSan detects misaligned access
+void misaligned(void) {
+    char buf[8] = {0};
+    int *p = (int *)(buf + 1); // misaligned pointer
+    *p = 42; // runtime error: misaligned access
+}
+```
+
+## ThreadSanitizer (TSan)
+
+Detects: data races, lock-order violations, deadlocks.
+
+```bash
+# Compile with TSan (cannot combine with ASan)
+gcc -fsanitize=thread -fno-omit-frame-pointer -g -o myapp myapp.c -lpthread
+```
+
+```c
+// TSan detects this data race
+static int counter = 0;
+
+void *increment(void *arg) {
+    (void)arg;
+    for (int i = 0; i < 1000; i++) {
+        counter++; // data race: unsynchronized access
+    }
+    return NULL;
+}
+
+// Fix: use mutex or atomic
+#include <stdatomic.h>
+static atomic_int counter = 0;
+
+void *increment_safe(void *arg) {
+    (void)arg;
+    for (int i = 0; i < 1000; i++) {
+        atomic_fetch_add(&counter, 1); // no race
+    }
+    return NULL;
+}
+```
+
+## MemorySanitizer (MSan) — Clang Only
+
+Detects: reads of uninitialized memory.
+
+```bash
+# Clang-only (not available in GCC)
+clang -fsanitize=memory -fno-omit-frame-pointer -g -O1 -o myapp myapp.c
+
+# All linked libraries must also be compiled with MSan
+# Use with libc++ compiled with MSan for best results
+```
+
+## GDB / LLDB Debugging Workflow
+
+```bash
+# Compile for debugging
+gcc -g -O0 -o myapp myapp.c
+
+# GDB basics
+gdb ./myapp
+(gdb) break main            # set breakpoint
+(gdb) run                   # start execution
+(gdb) next                  # step over
+(gdb) step                  # step into
+(gdb) print variable        # inspect variable
+(gdb) backtrace             # show call stack
+(gdb) watch *ptr            # break when memory changes
+(gdb) info threads          # list threads
+(gdb) thread 2              # switch to thread 2
+
+# LLDB equivalents
+lldb ./myapp
+(lldb) breakpoint set -n main
+(lldb) run
+(lldb) thread step-over
+(lldb) thread step-in
+(lldb) frame variable
+(lldb) thread backtrace
+(lldb) watchpoint set variable counter
+```
+
+## Core Dump Analysis
+
+```bash
+# Enable core dumps
+ulimit -c unlimited
+
+# Set core dump pattern (Linux)
+echo "/tmp/core.%e.%p" | sudo tee /proc/sys/kernel/core_pattern
+
+# Analyze core dump
+gdb ./myapp /tmp/core.myapp.12345
+(gdb) backtrace          # see where it crashed
+(gdb) frame 3            # examine specific frame
+(gdb) info locals        # see local variables
+```
+
+## Valgrind (Alternative to ASan)
+
+```bash
+# Memory error detection
+valgrind --tool=memcheck --leak-check=full --show-leak-kinds=all ./myapp
+
+# Cache profiling
+valgrind --tool=cachegrind ./myapp
+cg_annotate cachegrind.out.<pid>
+
+# Call graph profiling
+valgrind --tool=callgrind ./myapp
+kcachegrind callgrind.out.<pid>
+```
+
+## Sanitizer Compatibility Matrix
+
+| Sanitizer        | GCC | Clang | Combinable with         |
+| ---------------- | --- | ----- | ----------------------- |
+| AddressSanitizer | Yes | Yes   | UBSan                   |
+| UBSan            | Yes | Yes   | ASan, MSan, TSan        |
+| ThreadSanitizer  | Yes | Yes   | UBSan                   |
+| MemorySanitizer  | No  | Yes   | UBSan                   |
+| LeakSanitizer    | Yes | Yes   | ASan (often integrated) |
+
+Cannot combine: ASan + TSan, ASan + MSan, TSan + MSan.
+
+## CI Integration
+
+```bash
+# Run multiple sanitizer builds in CI
+# Build 1: ASan + UBSan
+cmake -B build-asan -DCMAKE_C_FLAGS="-fsanitize=address,undefined -g -O1"
+cmake --build build-asan && ctest --test-dir build-asan
+
+# Build 2: TSan (separate because incompatible with ASan)
+cmake -B build-tsan -DCMAKE_C_FLAGS="-fsanitize=thread -g -O1"
+cmake --build build-tsan && ctest --test-dir build-tsan
+
+# Build 3: Regular optimized build (for performance tests)
+cmake -B build-release -DCMAKE_BUILD_TYPE=Release
+cmake --build build-release && ctest --test-dir build-release
+```

package/workflows/powers/c-pro/references/memory-safety-and-build-checklist.md

@@ -0,0 +1,60 @@
+# Memory Safety and Build Checklist
+
+## Ownership rules
+
+- Every heap allocation has exactly one owner. Document who allocates and who frees.
+- Functions that return allocated memory must document whether the caller owns the result.
+- Functions that receive pointers must document whether they borrow or take ownership.
+- Use naming conventions to signal ownership: `create_*` allocates (caller frees), `get_*` borrows (caller must not free).
+
+## Buffer safety
+
+- Always pass buffer size alongside buffer pointer. Never rely on null terminators for binary data.
+- Check return values of `snprintf`, `read`, `recv` — they may write fewer bytes than requested.
+- Use `sizeof(array)` only on stack-allocated arrays, never on decayed pointers.
+- Prefer bounded variants: `strnlen` over `strlen`, `snprintf` over `sprintf`, `strncpy` with explicit termination.
+
+## Initialization
+
+- Initialize all stack variables at declaration. Uninitialized reads are undefined behavior.
+- Zero-initialize structs with `= {0}` or `memset` before populating fields.
+- Use compound literals `(struct Foo){.field = val}` for partial initialization — remaining fields are zero.
+
+## Arena allocator pattern
+
+```c
+// Simple arena: bump allocator with single free at scope end
+typedef struct { char *base; size_t offset; size_t capacity; } Arena;
+void *arena_alloc(Arena *a, size_t size);  // bump offset, return pointer
+void arena_reset(Arena *a);                // reset offset to 0
+```
+
+- Allocate arena at scope entry, reset or free at scope exit. No per-object free needed.
+- Useful for request-scoped or frame-scoped allocations (servers, games, parsers).
+
+## Sanitizer configuration
+
+| Sanitizer                  | Flag                             | Catches                                                       |
+| -------------------------- | -------------------------------- | ------------------------------------------------------------- |
+| AddressSanitizer           | `-fsanitize=address`             | Use-after-free, buffer overflow, stack overflow, memory leaks |
+| UndefinedBehaviorSanitizer | `-fsanitize=undefined`           | Signed overflow, null deref, alignment, shift out of range    |
+| ThreadSanitizer            | `-fsanitize=thread`              | Data races, lock order violations                             |
+| MemorySanitizer            | `-fsanitize=memory` (Clang only) | Reads of uninitialized memory                                 |
+
+- Run ASAN + UBSAN together in CI debug builds. TSAN requires a separate build (incompatible with ASAN).
+- Set `ASAN_OPTIONS=detect_leaks=1:halt_on_error=1` for strict leak detection.
+
+## Build system hygiene
+
+- Pin compiler version in CI (e.g., `gcc-13`, `clang-17`). Document minimum required version.
+- Use `-Wall -Wextra -Werror -Wpedantic -Wconversion -Wshadow` for maximum diagnostic coverage.
+- Run builds on at least GCC + Clang. They catch different issues.
+- Use `compile_commands.json` (CMake: `-DCMAKE_EXPORT_COMPILE_COMMANDS=ON`) for IDE and static analyzer integration.
+- Enable LTO (`-flto`) for release builds. Verify with tests — LTO can expose bugs that per-TU compilation hides.
+
+## ABI boundary review
+
+- Export only the minimum necessary symbols. Use `__attribute__((visibility("default")))` or export maps.
+- Keep struct layouts stable across versions. Add fields at the end, never reorder.
+- Use opaque pointers (`typedef struct Foo Foo;`) for types whose layout callers should not depend on.
+- Version-check shared libraries at load time when ABI stability is critical.

package/workflows/powers/c-pro/references/posix-and-platform-apis.md

@@ -0,0 +1,244 @@
+# POSIX and Platform APIs
+
+## File I/O
+
+```c
+#include <fcntl.h>
+#include <unistd.h>
+#include <sys/stat.h>
+
+// Open with explicit permissions
+int fd = open("data.bin", O_RDWR | O_CREAT | O_TRUNC, 0644);
+if (fd == -1) {
+    perror("open");
+    return -1;
+}
+
+// Read with retry on EINTR
+ssize_t safe_read(int fd, void *buf, size_t count) {
+    ssize_t n;
+    do {
+        n = read(fd, buf, count);
+    } while (n == -1 && errno == EINTR);
+    return n;
+}
+
+// Write all bytes (handle partial writes)
+ssize_t write_all(int fd, const void *buf, size_t count) {
+    const uint8_t *p = buf;
+    size_t remaining = count;
+    while (remaining > 0) {
+        ssize_t n = write(fd, p, remaining);
+        if (n == -1) {
+            if (errno == EINTR) continue;
+            return -1;
+        }
+        p += n;
+        remaining -= n;
+    }
+    return count;
+}
+
+// Always close file descriptors
+close(fd);
+```
+
+## Memory-Mapped I/O
+
+```c
+#include <sys/mman.h>
+#include <sys/stat.h>
+#include <fcntl.h>
+
+// Map file for read-only access
+void *map_file_readonly(const char *path, size_t *out_size) {
+    int fd = open(path, O_RDONLY);
+    if (fd == -1) return NULL;
+
+    struct stat st;
+    if (fstat(fd, &st) == -1) { close(fd); return NULL; }
+
+    void *addr = mmap(NULL, st.st_size, PROT_READ, MAP_PRIVATE, fd, 0);
+    close(fd); // fd can be closed after mmap
+    if (addr == MAP_FAILED) return NULL;
+
+    *out_size = st.st_size;
+    return addr;
+}
+
+// Clean up
+munmap(addr, size);
+```
+
+## Signal Handling
+
+```c
+#include <signal.h>
+#include <stdatomic.h>
+
+// Use sig_atomic_t or atomics for signal flags
+static volatile sig_atomic_t shutdown_requested = 0;
+
+void handle_signal(int sig) {
+    (void)sig;
+    shutdown_requested = 1;
+    // ONLY async-signal-safe functions are allowed here:
+    // write(), _exit(), signal(), abort()
+    // DO NOT use printf, malloc, free, etc.
+}
+
+void setup_signals(void) {
+    struct sigaction sa = {
+        .sa_handler = handle_signal,
+        .sa_flags = 0,
+    };
+    sigemptyset(&sa.sa_mask);
+    sigaction(SIGTERM, &sa, NULL);
+    sigaction(SIGINT, &sa, NULL);
+}
+
+// Main loop checks the flag
+while (!shutdown_requested) {
+    process_next_item();
+}
+```
+
+## Process and Fork
+
+```c
+#include <sys/wait.h>
+
+// Fork with proper error handling
+pid_t pid = fork();
+if (pid == -1) {
+    perror("fork");
+    exit(EXIT_FAILURE);
+} else if (pid == 0) {
+    // Child process
+    execvp(argv[0], argv); // replaces child image
+    perror("exec");        // only reached on error
+    _exit(127);            // use _exit, not exit, in child after fork
+} else {
+    // Parent process
+    int status;
+    waitpid(pid, &status, 0);
+    if (WIFEXITED(status)) {
+        int exit_code = WEXITSTATUS(status);
+    }
+}
+```
+
+## Socket Programming
+
+```c
+#include <sys/socket.h>
+#include <netinet/in.h>
+#include <arpa/inet.h>
+
+// TCP server setup
+int create_server(uint16_t port) {
+    int fd = socket(AF_INET, SOCK_STREAM, 0);
+    if (fd == -1) return -1;
+
+    int opt = 1;
+    setsockopt(fd, SOL_SOCKET, SO_REUSEADDR, &opt, sizeof(opt));
+
+    struct sockaddr_in addr = {
+        .sin_family = AF_INET,
+        .sin_port = htons(port),
+        .sin_addr.s_addr = INADDR_ANY,
+    };
+
+    if (bind(fd, (struct sockaddr *)&addr, sizeof(addr)) == -1) {
+        close(fd);
+        return -1;
+    }
+
+    if (listen(fd, SOMAXCONN) == -1) {
+        close(fd);
+        return -1;
+    }
+
+    return fd;
+}
+```
+
+## Platform Abstraction Layer Pattern
+
+```c
+// platform.h — unified interface
+#pragma once
+
+typedef struct platform_file platform_file;
+
+platform_file *platform_open(const char *path, int flags);
+ssize_t platform_read(platform_file *f, void *buf, size_t count);
+void platform_close(platform_file *f);
+uint64_t platform_monotonic_time_ns(void);
+
+// platform_posix.c — POSIX implementation
+#if defined(__linux__) || defined(__APPLE__)
+#include <time.h>
+
+uint64_t platform_monotonic_time_ns(void) {
+    struct timespec ts;
+    clock_gettime(CLOCK_MONOTONIC, &ts);
+    return (uint64_t)ts.tv_sec * 1000000000ULL + ts.tv_nsec;
+}
+#endif
+
+// platform_win32.c — Windows implementation
+#if defined(_WIN32)
+#include <windows.h>
+
+uint64_t platform_monotonic_time_ns(void) {
+    LARGE_INTEGER freq, count;
+    QueryPerformanceFrequency(&freq);
+    QueryPerformanceCounter(&count);
+    return (uint64_t)(count.QuadPart * 1000000000LL / freq.QuadPart);
+}
+#endif
+```
+
+## Error Handling Patterns
+
+```c
+// Return error codes with context struct
+typedef struct {
+    int code;
+    const char *message;
+    const char *file;
+    int line;
+} error_t;
+
+#define ERROR(code, msg) ((error_t){ (code), (msg), __FILE__, __LINE__ })
+#define OK ((error_t){ 0, NULL, NULL, 0 })
+
+error_t process_file(const char *path) {
+    int fd = open(path, O_RDONLY);
+    if (fd == -1) return ERROR(errno, "failed to open file");
+
+    // ...
+    close(fd);
+    return OK;
+}
+
+// Goto-based cleanup (idiomatic C error handling)
+int init_system(void) {
+    int ret = -1;
+    void *buf = malloc(BUF_SIZE);
+    if (!buf) goto out;
+
+    int fd = open("config", O_RDONLY);
+    if (fd == -1) goto cleanup_buf;
+
+    // ... use buf and fd ...
+    ret = 0;
+
+    close(fd);
+cleanup_buf:
+    free(buf);
+out:
+    return ret;
+}
+```