Document OWN_GIL safety mechanisms and lock ordering

- CHANGELOG: Add OWN_GIL safety fixes section for 2.2.0
- owngil_internals.md: Add Safety Mechanisms section covering interp_id
  validation, lock ordering (ABBA prevention), callback re-entry limitation
- event_loop_architecture.md: Add Per-Process Namespace Management section
  with lock ordering and cleanup behavior documentation
- process-bound-envs.md: Add Interpreter ID Validation and Cleanup Safety
  sections explaining cross-interpreter protection

Author: benoitc

CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## 2.2.0 (unreleased)
 
+### Fixed
+
+- **OWN_GIL Safety Fixes** - Critical fixes for OWN_GIL subinterpreter mode
+  - **Mutex leak in erlang module** - `async_futures_mutex` now always destroyed in
+    `erlang_module_free()` regardless of `pipe_initialized` flag
+  - **ABBA deadlock prevention** - Fixed lock ordering in `event_loop_down()` and
+    `event_loop_destructor()` to acquire GIL before `namespaces_mutex`, matching the
+    normal execution path and preventing deadlocks
+  - **Dangling env pointer detection** - Added `interp_id` validation in
+    `owngil_execute_*_with_env()` functions to detect and reject env resources
+    created by a different interpreter, returning `{error, env_wrong_interpreter}`
+  - **OWN_GIL callback documentation** - Documented that `erlang.call()` from OWN_GIL
+    contexts uses `thread_worker_call()` rather than suspension/resume protocol;
+    re-entrant calls to the same OWN_GIL context are not supported
+
 ### Added
 
 - **PyBuffer API** - Zero-copy WSGI input buffer for streaming HTTP bodies

docs/event_loop_architecture.md

@@ -242,3 +242,45 @@ pthread_mutex_unlock               PyGILState_Release
 | GIL acquisitions | 1 per batch | Not per-task |
 | Handle allocations | ~0 (pooled) | After warmup |
 | Time syscalls | 1 per iteration | Cached within iteration |
+
+## Per-Process Namespace Management
+
+Each Erlang process can have an isolated Python namespace within an event loop. These namespaces are tracked in a linked list protected by `namespaces_mutex`.
+
+### Lock Ordering
+
+To prevent ABBA deadlocks, locks must always be acquired in this order:
+
+```
+1. GIL (PyGILState_Ensure)
+2. namespaces_mutex (pthread_mutex_lock)
+```
+
+This ordering is enforced in:
+- `ensure_process_namespace()` - Called with GIL held, then acquires mutex
+- `event_loop_down()` - Acquires GIL first, then mutex for cleanup
+- `event_loop_destructor()` - Acquires GIL first, then mutex for cleanup
+
+### Cleanup Behavior
+
+When a monitored process dies (`event_loop_down`) or the event loop is destroyed:
+
+**For main interpreter (`interp_id == 0`):**
+```c
+PyGILState_STATE gstate = PyGILState_Ensure();
+pthread_mutex_lock(&loop->namespaces_mutex);
+// Py_XDECREF(ns->globals), etc.
+pthread_mutex_unlock(&loop->namespaces_mutex);
+PyGILState_Release(gstate);
+```
+
+**For subinterpreters (`interp_id != 0`):**
+```c
+pthread_mutex_lock(&loop->namespaces_mutex);
+// Skip Py_XDECREF - cannot safely acquire subinterpreter GIL
+// Objects freed when interpreter is destroyed
+enif_free(ns);
+pthread_mutex_unlock(&loop->namespaces_mutex);
+```
+
+This design accepts a minor memory leak (Python dicts not decrefd) to avoid the complexity and risk of acquiring a subinterpreter's GIL from an arbitrary thread.

docs/owngil_internals.md

@@ -395,11 +395,65 @@ Use shared-GIL (subinterp) when:
 - High call frequency
 - Resource constraints
 
+## Safety Mechanisms
+
+### Interpreter ID Validation
+
+Process-local environments (`py_env_resource_t`) store the Python interpreter ID when created. Before execution, OWN_GIL functions validate that the env belongs to the current interpreter:
+
+```c
+PyInterpreterState *current_interp = PyInterpreterState_Get();
+if (current_interp != NULL && penv->interp_id != PyInterpreterState_GetID(current_interp)) {
+    // Return {error, env_wrong_interpreter}
+}
+```
+
+This prevents dangling pointer access when an env resource outlives its interpreter.
+
+### Lock Ordering (ABBA Deadlock Prevention)
+
+Lock ordering must be consistent to prevent deadlocks:
+
+**Correct order: GIL first, then namespaces_mutex**
+
+Normal execution path:
+```
+PyGILState_Ensure()     // 1. Acquire GIL
+pthread_mutex_lock()     // 2. Acquire mutex
+// ... work ...
+pthread_mutex_unlock()   // 3. Release mutex
+PyGILState_Release()     // 4. Release GIL
+```
+
+Cleanup paths (`event_loop_down`, `event_loop_destructor`) follow the same order:
+```c
+// For main interpreter: GIL first, then mutex
+PyGILState_STATE gstate = PyGILState_Ensure();
+pthread_mutex_lock(&loop->namespaces_mutex);
+// ... cleanup with Py_XDECREF ...
+pthread_mutex_unlock(&loop->namespaces_mutex);
+PyGILState_Release(gstate);
+```
+
+For subinterpreters (where `PyGILState_Ensure` cannot be used), cleanup skips `Py_DECREF` - the objects will be freed when the interpreter is destroyed.
+
+### Callback Re-entry Limitation
+
+OWN_GIL contexts do not support the suspension/resume protocol used for `erlang.call()` callbacks. When Python code in an OWN_GIL context calls `erlang.call()`:
+
+1. The call is routed to `thread_worker_call()` (not the OWN_GIL thread)
+2. The call executes on a thread worker, not the calling OWN_GIL context
+3. Re-entrant calls back to the same OWN_GIL context are not supported
+
+This is because the OWN_GIL thread cannot be suspended - it owns its GIL and must remain responsive to process requests.
+
 ## Files
 
 | File | Description |
 |------|-------------|
 | `c_src/py_nif.h` | Structure definitions, request types |
 | `c_src/py_nif.c` | Thread main, dispatch, execute functions |
+| `c_src/py_callback.c` | Callback handling, thread worker dispatch |
+| `c_src/py_event_loop.c` | Event loop and namespace management |
 | `src/py_context.erl` | Erlang API for context management |
 | `test/py_owngil_features_SUITE.erl` | Test suite |

docs/process-bound-envs.md

@@ -249,6 +249,32 @@ Environments are stored as NIF resources with the following lifecycle:
 
 For subinterpreters, environments are created inside the target interpreter using its memory allocator - critical for memory safety.
 
+### Interpreter ID Validation
+
+Each `py_env_resource_t` stores the Python interpreter ID (`interp_id`) when created. For OWN_GIL contexts, before any operation using a process-local env, the system validates that the env belongs to the current interpreter:
+
+```c
+PyInterpreterState *current_interp = PyInterpreterState_Get();
+if (penv->interp_id != PyInterpreterState_GetID(current_interp)) {
+    return {error, env_wrong_interpreter};
+}
+```
+
+This prevents:
+- Using an env from a destroyed interpreter (dangling pointer)
+- Using an env created for a different OWN_GIL context
+- Memory corruption from cross-interpreter dict access
+
+### Cleanup Safety
+
+For the main interpreter (`interp_id == 0`), the destructor acquires the GIL and decrefs the Python dicts normally.
+
+For subinterpreters, the destructor skips `Py_DECREF` because:
+1. `PyGILState_Ensure` cannot safely acquire a subinterpreter's GIL
+2. The Python objects will be freed when the subinterpreter is destroyed via `Py_EndInterpreter`
+
+This design prioritizes safety over avoiding minor memory leaks during edge cases.
+
 ## See Also
 
 - [Context Affinity](context-affinity.md) - Context binding and routing