refactor(arch): architecture deepening round 3 - improve testability

Changes:
- Remove duplicate SPSCQueue definition in concurrency_properties.cpp
- Unify allocator naming: aligned_allocator -> AlignedAllocator (PascalCase)
- Add core module tests (15 tests for cache_line_size, page_size, hardware_concurrency)
- Add lock-free queue stress tests (high throughput, MPMC contention, random interleaving)
- Add overflow protection to AlignedAllocator::allocate()
- Fix compile_time.hpp missing #include <cstddef>
- Document header-only design decision in AGENTS.md
- Add teaching example note to particle_types.hpp

Test count: 65 -> 84 (+19)
All tests pass with Debug, ASan, TSan builds.

Author: LessUp

AGENTS.md

@@ -11,6 +11,7 @@ This repository is in **closure and hardening mode** (archive-ready for low-freq
 - **Memory safety**: prefer RAII, smart pointers, avoid raw `new/delete`
 - **Performance**: always measure with benchmarks before claiming improvement
 - **Concurrency**: use `std::atomic` with explicit memory ordering
+- **Header-only design**: all library code in `include/hpc/` and `examples/*/include/` is header-only. Platform-specific code (Windows/POSIX, compiler intrinsics) is hidden behind preprocessor conditionals within headers. This design choice prioritizes ease of integration over compilation speed.
 
 ## Canonical sources of truth
 

examples/02-memory-cache/include/memory_utils.hpp

@@ -81,7 +81,8 @@ using aligned_unique_ptr = std::unique_ptr<T, AlignedDeleter>;
  * @brief Create aligned unique pointer
  */
 template <typename T>
-aligned_unique_ptr<T> make_aligned(std::size_t count, std::size_t alignment = hpc::core::CACHE_LINE_SIZE) {
+aligned_unique_ptr<T> make_aligned(std::size_t count,
+                                   std::size_t alignment = hpc::core::CACHE_LINE_SIZE) {
     void* ptr = aligned_alloc(count * sizeof(T), alignment);
     if (!ptr) {
         throw std::bad_alloc();

examples/02-memory-cache/include/particle_types.hpp

@@ -2,6 +2,13 @@
  * @file particle_types.hpp
  * @brief Particle data structures for AOS vs SOA comparison
  *
+ * **Note: This is a teaching example module, not production-ready code.**
+ * The data structures and algorithms here are intentionally simple to
+ * demonstrate memory layout concepts. For production use, consider:
+ * - Adding bounds checking and validation
+ * - Using aligned allocators for SIMD operations
+ * - Implementing parallel processing for large datasets
+ *
  * Validates:
  *   - Requirement 2.1: AOS vs SOA Comparison
  *

examples/03-modern-cpp/include/compile_time.hpp

@@ -14,6 +14,7 @@
 #pragma once
 
 #include <array>
+#include <cstddef>
 #include <cstdint>
 
 namespace hpc::compile_time {

examples/03-modern-cpp/src/compile_time.cpp

@@ -12,12 +12,12 @@
  * - Template metaprogramming vs constexpr
  */
 
+#include "compile_time.hpp"
+
 #include <chrono>
 #include <cmath>
 #include <iostream>
 
-#include "compile_time.hpp"
-
 namespace hpc::compile_time {
 
 //------------------------------------------------------------------------------

examples/03-modern-cpp/src/vector_reserve.cpp

@@ -11,12 +11,12 @@
  * - Counting allocations with custom allocator
  */
 
+#include "vector_reserve.hpp"
+
 #include <chrono>
 #include <iostream>
 #include <vector>
 
-#include "vector_reserve.hpp"
-
 namespace hpc::vector_reserve {
 
 //------------------------------------------------------------------------------

examples/04-simd-vectorization/include/simd_utils.hpp

@@ -21,6 +21,7 @@
 #include <cstddef>
 #include <cstdint>
 #include <cstdlib>
+#include <limits>
 #include <memory>
 #include <new>
 #include <vector>
@@ -93,27 +94,32 @@ inline size_t get_simd_alignment() {
  * different purposes: SIMD optimization vs cache-line alignment.
  */
 template <typename T>
-class aligned_allocator {
+class AlignedAllocator {
 public:
     using value_type = T;
-    using pointer = T*;
-    using const_pointer = const T*;
-    using reference = T&;
-    using const_reference = const T&;
     using size_type = std::size_t;
     using difference_type = std::ptrdiff_t;
 
     template <typename U>
     struct rebind {
-        using other = aligned_allocator<U>;
+        using other = AlignedAllocator<U>;
     };
 
-    aligned_allocator() = default;
+    AlignedAllocator() = default;
 
     template <typename U>
-    aligned_allocator(const aligned_allocator<U>&) {}
+    AlignedAllocator(const AlignedAllocator<U>&) {}
+
+    T* allocate(size_type n) {
+        // Overflow protection
+        if (n > std::numeric_limits<size_type>::max() / sizeof(T)) {
+            throw std::bad_alloc();
+        }
+
+        if (n == 0) {
+            return nullptr;
+        }
 
-    pointer allocate(size_type n) {
         const size_t alignment = get_simd_alignment();
         const size_t size = n * sizeof(T);
 
@@ -128,10 +134,13 @@ class aligned_allocator {
         if (!ptr) {
             throw std::bad_alloc();
         }
-        return static_cast<pointer>(ptr);
+        return static_cast<T*>(ptr);
     }
 
-    void deallocate(pointer p, size_type) {
+    void deallocate(T* p, size_type) {
+        if (p == nullptr) {
+            return;
+        }
 #if defined(_MSC_VER)
         _aligned_free(p);
 #else
@@ -140,37 +149,34 @@ class aligned_allocator {
     }
 
     template <typename U>
-    bool operator==(const aligned_allocator<U>&) const {
+    bool operator==(const AlignedAllocator<U>&) const {
         return true;
     }
 
     template <typename U>
-    bool operator!=(const aligned_allocator<U>&) const {
+    bool operator!=(const AlignedAllocator<U>&) const {
         return false;
     }
 };
 
 /**
- * @brief Alias for aligned_allocator with clearer SIMD-specific naming
- *
- * This alias provides a more intuitive name for the SIMD-aligned allocator,
- * distinguishing it from hpc::memory::AlignedAllocator which uses cache-line
- * alignment (compile-time constant).
- *
- * Key differences from hpc::memory::AlignedAllocator:
- * - Uses runtime SIMD detection for alignment (16/32/64 bytes based on CPU)
- * - hpc::memory::AlignedAllocator uses compile-time CACHE_LINE_SIZE
- *
- * Both names (aligned_allocator and simd_allocator) are equivalent.
+ * @brief Backward-compatible alias for AlignedAllocator
+ * @deprecated Use AlignedAllocator<T> directly
+ */
+template <typename T>
+using aligned_allocator [[deprecated("Use AlignedAllocator<T> directly")]] = AlignedAllocator<T>;
+
+/**
+ * @brief Alias for AlignedAllocator with SIMD-specific naming
  */
 template <typename T>
-using simd_allocator = aligned_allocator<T>;
+using simd_allocator = AlignedAllocator<T>;
 
 /**
  * @brief Aligned vector type for SIMD operations
  */
 template <typename T>
-using aligned_vector = std::vector<T, aligned_allocator<T>>;
+using aligned_vector = std::vector<T, AlignedAllocator<T>>;
 
 /**
  * @brief Aligned buffer type alias for compatibility