Justify epoll_instances config existing

design.md

@@ -203,6 +203,34 @@ CommitRequest {
 
 > **Note**: Call `conn->reset()` periodically to reclaim arena memory. Best practice is after all outgoing bytes have been written.
 
+#### Threading Model and EPOLLONESHOT
+
+**EPOLLONESHOT Design Rationale:**
+WeaselDB uses `EPOLLONESHOT` for all connection file descriptors to enable safe multi-threaded ownership transfer without complex synchronization:
+
+**Key Benefits:**
+1. **Automatic fd disarming** - When epoll triggers an event, the fd is automatically removed from epoll monitoring
+2. **Race-free ownership transfer** - Handlers can safely take connection ownership and move to other threads
+3. **Zero-coordination async processing** - No manual synchronization needed between network threads and handler threads
+
+**Threading Flow:**
+1. **Event Trigger**: Network thread gets epoll event → connection auto-disarmed via ONESHOT
+2. **Safe Transfer**: Handler can take ownership (`std::move(conn_ptr)`) with no epoll interference
+3. **Async Processing**: Connection processed on handler thread while epoll cannot trigger spurious events
+4. **Return & Re-arm**: `Server::receiveConnectionBack()` re-arms fd with `epoll_ctl(EPOLL_CTL_MOD)`
+
+**Performance Trade-off:**
+- **Cost**: One `epoll_ctl(MOD)` syscall per connection return (~100-200ns)
+- **Benefit**: Eliminates complex thread synchronization and prevents race conditions
+- **Alternative cost**: Manual `EPOLL_CTL_DEL`/`ADD` + locking would be significantly higher
+
+**Without EPOLLONESHOT risks:**
+- Multiple threads processing same fd simultaneously
+- Use-after-move when network thread accesses transferred connection
+- Complex synchronization between epoll events and ownership transfers
+
+This design enables the async handler pattern where connections can be safely moved between threads for background processing while maintaining high performance and thread safety.
+
 ### API Endpoints
 
 The system implements a RESTful API: