Document the two-level handle and object registry design

Add REGISTRY_DESIGN.md explaining how the C++ HandleRegistry (Level 1)
and Cython _node_registry (Level 2) work together to preserve Python
object identity through driver round-trips. Add cross-references at
each registry instantiation site.

Made-with: Cursor

Author: Andy-Jost

cuda_core/cuda/core/_cpp/REGISTRY_DESIGN.md

@@ -0,0 +1,51 @@
+# Handle and Object Registries
+
+When Python-managed objects round-trip through the CUDA driver (e.g.,
+querying a graph's nodes and getting back raw `CUgraphNode` pointers),
+we need to recover the original Python object rather than creating a
+duplicate.
+
+This document describes the approach used to achieve this. The pattern
+is driven mainly by needs arising in the context of CUDA graphs, but
+it is general and can be extended to other object types as needs arise.
+
+This solves the same problem as pybind11's `registered_instances` map
+and is sometimes called the Identity Map pattern. Two registries work
+together to map a raw driver handle all the way back to the original
+Python object. Both use weak references so they
+do not prevent cleanup. Entries are removed either explicitly (via
+`destroy()` or a Box destructor) or implicitly when the weak reference
+expires.
+
+## Level 1: Driver Handle -> Resource Handle (C++)
+
+`HandleRegistry` in `resource_handles.cpp` maps a raw CUDA handle
+(e.g., `CUevent`, `CUkernel`, `CUgraphNode`) to the `weak_ptr` that
+owns it. When a `_ref` constructor receives a raw handle, it
+checks the registry first. If found, it returns the existing
+`shared_ptr`, preserving the Box and its metadata (e.g., `EventBox`
+carries timing/IPC flags, `KernelBox` carries the library dependency).
+
+Without this level, a round-tripped handle would produce a new Box
+with default metadata, losing information that was set at creation.
+
+Instances: `event_registry`, `kernel_registry`, `graph_node_registry`.
+
+## Level 2: Resource Handle -> Python Object (Cython)
+
+`_node_registry` in `_graph_node.pyx` is a `WeakValueDictionary`
+mapping a resource address (`shared_ptr::get()`) to a Python
+`GraphNode` object. When `GraphNode._create` receives a handle from
+Level 1, it checks this registry. If found, it returns the existing
+Python object.
+
+Without this level, each driver round-trip would produce a distinct
+Python object for the same logical node, resulting in surprising
+behavior:
+
+```python
+a = g.empty()
+a.succ = {b}
+b2, = a.succ     # queries driver, gets back CUgraphNode for b
+assert b2 is b   # fails without Level 2 registry
+```

cuda_core/cuda/core/_cpp/resource_handles.cpp

@@ -388,6 +388,7 @@ ContextHandle get_event_context(const EventHandle& h) noexcept {
     return h ? get_box(h)->h_context : ContextHandle{};
 }
 
+// See REGISTRY_DESIGN.md (Level 1: Driver Handle -> Resource Handle)
 static HandleRegistry<CUevent, EventHandle> event_registry;
 
 EventHandle create_event_handle(const ContextHandle& h_ctx, unsigned int flags,
@@ -894,6 +895,7 @@ static const KernelBox* get_box(const KernelHandle& h) {
     );
 }
 
+// See REGISTRY_DESIGN.md (Level 1: Driver Handle -> Resource Handle)
 static HandleRegistry<CUkernel, KernelHandle> kernel_registry;
 
 KernelHandle create_kernel_handle(const LibraryHandle& h_library, const char* name) {
@@ -964,6 +966,7 @@ static const GraphNodeBox* get_box(const GraphNodeHandle& h) {
     );
 }
 
+// See REGISTRY_DESIGN.md (Level 1: Driver Handle -> Resource Handle)
 static HandleRegistry<CUgraphNode, GraphNodeHandle> graph_node_registry;
 
 GraphNodeHandle create_graph_node_handle(CUgraphNode node, const GraphHandle& h_graph) {

cuda_core/cuda/core/_graph/_graph_def/_graph_node.pyx

@@ -63,6 +63,7 @@ from cuda.core import Device
 from cuda.core._graph._graph_def._adjacency_set_proxy import AdjacencySetProxy
 from cuda.core._utils.cuda_utils import driver, handle_return
 
+# See _cpp/REGISTRY_DESIGN.md (Level 2: Resource Handle -> Python Object)
 _node_registry = weakref.WeakValueDictionary()