Add thread safety documentation

src/arena_allocator.hpp

@@ -12,7 +12,6 @@
 #include <type_traits>
 #include <typeinfo>
 #include <utility>
-#include <vector>
 
 /**
  * @brief A high-performance arena allocator for bulk allocations.
@@ -52,8 +51,37 @@
  * - Move semantics transfer ownership of all blocks
  *
  * ## Thread Safety:
- * Not thread-safe. Use separate instances per thread or external
- * synchronization.
+ * ArenaAllocator is **not thread-safe** - concurrent access from multiple
+ * threads requires external synchronization. However, this design is
+ * intentional for performance reasons and the WeaselDB architecture ensures
+ * thread safety through ownership patterns:
+ *
+ * ### Safe Usage Patterns in WeaselDB:
+ * - **Per-Connection Instances**: Each Connection owns its own ArenaAllocator
+ *   instance, accessed only by the thread that currently owns the connection
+ * - **Single Owner Principle**: Connection ownership transfers atomically
+ * between threads using unique_ptr, ensuring only one thread accesses the arena
+ * at a time
+ *
+ * ### Thread Ownership Model:
+ * 1. **Network Thread**: Claims connection ownership, accesses arena for I/O
+ * buffers
+ * 2. **Handler Thread**: Can take ownership via unique_ptr.release(), uses
+ * arena for request parsing and response generation
+ * 3. **Background Thread**: Can receive ownership for async processing, uses
+ * arena for temporary data structures
+ * 4. **Return Path**: Connection (and its arena) safely returned via
+ *    Server::releaseBackToServer()
+ *
+ * ### Why This Design is Thread-Safe:
+ * - **Exclusive Access**: Only the current owner thread should access the arena
+ * - **Transfer Points**: Ownership transfers happen at well-defined
+ * synchronization points with proper memory barriers.
+ * - **No Shared State**: Each arena is completely isolated - no shared data
+ *   between different arena instances
+ *
+ * @warning Do not share ArenaAllocator instances between threads. Use separate
+ * instances per thread or per logical unit of work.
  */
 class ArenaAllocator {
 private: