Graph node follow-ups: repr, containment, empty(), registry docs (#1859)

* Reorganize graph test files for clarity

Rename test files to reflect what they actually test:
- test_basic -> test_graph_builder (stream capture tests)
- test_conditional -> test_graph_builder_conditional
- test_advanced -> test_graph_update (moved child_graph and
  stream_lifetime tests into test_graph_builder)
- test_capture_alloc -> test_graph_memory_resource
- test_explicit* -> test_graphdef*

Made-with: Cursor

* Enhance Graph.update() and add whole-graph update tests

- Extend Graph.update() to accept both GraphBuilder and GraphDef sources
- Surface CUgraphExecUpdateResultInfo details on update failure instead
  of a generic CUDA_ERROR_GRAPH_EXEC_UPDATE_FAILURE message
- Release the GIL during cuGraphExecUpdate via nogil block
- Add parametrized happy-path test covering both GraphBuilder and GraphDef
- Add error-case tests: unfinished builder, topology mismatch, wrong type

Made-with: Cursor

* Add AdjacencySet proxy for pred/succ and GraphNode.remove()

Replace cached tuple-based pred/succ with mutable AdjacencySet backed
by direct CUDA driver calls. Add GraphNode.remove() wrapping
cuGraphDestroyNode.

Made-with: Cursor

* Add edge mutation support and MutableSet interface for GraphNode adjacencies

Enable adding/removing edges between graph nodes via AdjacencySet (a
MutableSet proxy on GraphNode.pred/succ), node removal via discard(),
and property setters for bulk edge replacement. Includes comprehensive
mutation and interface tests.

Closes part of #1330 (step 2: edge mutation on GraphDef).

Made-with: Cursor

* Use requires_module mark for numpy version checks in mutation tests

Replace inline skipif version check with requires_module(np, "2.1")
from the shared test helpers, consistent with other test files.

Made-with: Cursor

* Fix empty-graph return type: return set() instead of () for nodes/edges

Made-with: Cursor

* Rename AdjacencySet to AdjacencySetProxy, add bulk ops and safety guards

Rename class and file to AdjacencySetProxy to clarify write-through
semantics. Add bulk-efficient clear(), __isub__(), __ior__() overrides
and remove_edges() on the Cython core. Guard GraphNode.discard() against
double-destroy via membership check. Filter duplicates in update(). Add
error-path tests for wrong types, cross-graph edges, and self-edges.

Made-with: Cursor

* Add destroy() method with handle invalidation, remove GRAPH_NODE_SENTINEL

Replace discard() with destroy() which calls cuGraphDestroyNode and then
zeroes the CUgraphNode resource in the handle box via
invalidate_graph_node_handle. This prevents stale memory access on
destroyed nodes. Properties (type, pred, succ, handle) degrade gracefully
to None/empty for destroyed nodes.

Remove the GRAPH_NODE_SENTINEL (0x1) approach in favor of using NULL for
both sentinels and destroyed nodes, which is simpler and avoids the risk
of passing 0x1 to driver APIs that treat it as a valid pointer.

Made-with: Cursor

* Add GraphNode identity cache for stable Python object round-trips

Nodes retrieved via GraphDef.nodes(), edges(), or pred/succ traversal
now return the same Python object that was originally created, enabling
identity checks with `is`. A C++ HandleRegistry deduplicates
CUgraphNode handles, and a Cython WeakValueDictionary caches the
Python wrapper objects.

Made-with: Cursor

* Purge node cache on destroy to prevent stale identity lookups

Made-with: Cursor

* Skip NULL nodes in graph_node_registry to fix sentinel identity collision

Sentinel (entry) nodes use NULL as their CUgraphNode, so caching them
under a NULL key caused all sentinels across different graphs to share
the same handle. This made nodes built from the wrong graph's entry
point, causing CUDA_ERROR_INVALID_VALUE for conditional nodes and hash
collisions in equality tests.

Made-with: Cursor

* Unregister destroyed nodes from C++ graph_node_registry

When a node is destroyed, the driver may reuse its CUgraphNode pointer
for a new node. Without unregistering the old entry, the registry
returns a stale handle pointing to the wrong node type and graph.

Made-with: Cursor

* Add dedicated test for node identity preservation through round-trips

Made-with: Cursor

* Add handle= to all GraphNode subclass __repr__ for debugging

Every subclass repr now starts with handle=0x... (the CUgraphNode
pointer) followed by type-specific identity/parameter data. Dynamic
queries (pred counts, subnode counts) are removed in favor of
deterministic, cheap fields. This makes set comparison failures in
test output readable when debugging graph mutation tests.

Made-with: Cursor

* Rename _node_cache/_cached to _node_registry/_registered

Aligns Python-side terminology with the C++ graph_node_registry.

Made-with: Cursor

* Fix unregister_handle and rename invalidate_graph_node_handle

unregister_handle: remove the expired() guard that prevented erasure
when the shared_ptr was still alive. This caused stale registry
entries after destroy(), leading to CUDA_ERROR_INVALID_VALUE when
the driver reused CUgraphNode pointer values.

Rename invalidate_graph_node_handle -> invalidate_graph_node for
consistency with the rest of the graph node API.

Made-with: Cursor

* Add cheap containment test and early type check for AdjacencySetProxy

Add _AdjacencySetCore.contains() that checks membership by comparing
raw CUgraphNode handles at the C level, avoiding Python object
construction. Uses a 16-element stack buffer for a single driver call
in the common case.

Move the type check in update() inline next to the extend loop so
invalid input is rejected immediately.

Made-with: Cursor

* Add GraphDef.empty(), stack-buffer query optimization, and registry test

- Add GraphDef.empty() for creating entry-point empty nodes; replace
  all no-arg join() calls on GraphDef with empty() in tests.
- Optimize _AdjacencySetCore.query() to use a 16-element stack buffer,
  matching the contains() optimization.
- Add test_registry_cleanup exercising destroy(), graph deletion, and
  weak-reference cleanup of the node registry.

Made-with: Cursor

* 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

* Fix import formatting in test_registry_cleanup

Made-with: Cursor

* Optimize GraphDef.nodes() and edges() to try a single driver call

Pre-allocate vectors to 128 entries and pass them on the first call.
Only fall back to a second call if the graph exceeds 128 nodes/edges.

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/_adjacency_set_proxy.pyx

@@ -39,7 +39,7 @@ class AdjacencySetProxy(MutableSet):
     def __contains__(self, x):
         if not isinstance(x, GraphNode):
             return False
-        return x in (<_AdjacencySetCore>self._core).query()
+        return (<_AdjacencySetCore>self._core).contains(<GraphNode>x)
 
     def __iter__(self):
         return iter((<_AdjacencySetCore>self._core).query())
@@ -87,13 +87,13 @@ class AdjacencySetProxy(MutableSet):
             if isinstance(other, GraphNode):
                 nodes.append(other)
             else:
-                nodes.extend(other)
+                for n in other:
+                    if not isinstance(n, GraphNode):
+                        raise TypeError(
+                            f"expected GraphNode, got {type(n).__name__}")
+                    nodes.append(n)
         if not nodes:
             return
-        for n in nodes:
-            if not isinstance(n, GraphNode):
-                raise TypeError(
-                    f"expected GraphNode, got {type(n).__name__}")
         new = [n for n in nodes if n not in self]
         if new:
             (<_AdjacencySetCore>self._core).add_edges(new)
@@ -143,11 +143,14 @@ cdef class _AdjacencySetCore:
         cdef cydriver.CUgraphNode c_node = as_cu(self._h_node)
         if c_node == NULL:
             return []
-        cdef size_t count = 0
+        cdef cydriver.CUgraphNode buf[16]
+        cdef size_t count = 16
+        cdef size_t i
         with nogil:
-            HANDLE_RETURN(self._query_fn(c_node, NULL, &count))
-        if count == 0:
-            return []
+            HANDLE_RETURN(self._query_fn(c_node, buf, &count))
+        if count <= 16:
+            return [GraphNode._create(self._h_graph, buf[i])
+                    for i in range(count)]
         cdef vector[cydriver.CUgraphNode] nodes_vec
         nodes_vec.resize(count)
         with nogil:
@@ -156,6 +159,35 @@ cdef class _AdjacencySetCore:
         return [GraphNode._create(self._h_graph, nodes_vec[i])
                 for i in range(count)]
 
+    cdef bint contains(self, GraphNode other):
+        cdef cydriver.CUgraphNode c_node = as_cu(self._h_node)
+        cdef cydriver.CUgraphNode target = as_cu(other._h_node)
+        if c_node == NULL or target == NULL:
+            return False
+        cdef cydriver.CUgraphNode buf[16]
+        cdef size_t count = 16
+        cdef size_t i
+        with nogil:
+            HANDLE_RETURN(self._query_fn(c_node, buf, &count))
+
+        # Fast path for small sets.
+        if count <= 16:
+            for i in range(count):
+                if buf[i] == target:
+                    return True
+            return False
+
+        # Fallback for large sets.
+        cdef vector[cydriver.CUgraphNode] nodes_vec
+        nodes_vec.resize(count)
+        with nogil:
+            HANDLE_RETURN(self._query_fn(c_node, nodes_vec.data(), &count))
+        assert count == nodes_vec.size()
+        for i in range(count):
+            if nodes_vec[i] == target:
+                return True
+        return False
+
     cdef Py_ssize_t count(self):
         cdef cydriver.CUgraphNode c_node = as_cu(self._h_node)
         if c_node == NULL:

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

@@ -159,6 +159,16 @@ cdef class GraphDef:
         """
         return self._entry.launch(config, kernel, *args)
 
+    def empty(self) -> "EmptyNode":
+        """Add an entry-point empty node (no dependencies).
+
+        Returns
+        -------
+        EmptyNode
+            A new EmptyNode with no dependencies.
+        """
+        return self._entry.join()
+
     def join(self, *nodes) -> "EmptyNode":
         """Create an empty node that depends on all given nodes.
 
@@ -322,18 +332,20 @@ cdef class GraphDef:
         set of GraphNode
             All nodes in the graph.
         """
-        cdef size_t num_nodes = 0
+        cdef vector[cydriver.CUgraphNode] nodes_vec
+        nodes_vec.resize(128)
+        cdef size_t num_nodes = 128
 
         with nogil:
-            HANDLE_RETURN(cydriver.cuGraphGetNodes(as_cu(self._h_graph), NULL, &num_nodes))
+            HANDLE_RETURN(cydriver.cuGraphGetNodes(as_cu(self._h_graph), nodes_vec.data(), &num_nodes))
 
         if num_nodes == 0:
             return set()
 
-        cdef vector[cydriver.CUgraphNode] nodes_vec
-        nodes_vec.resize(num_nodes)
-        with nogil:
-            HANDLE_RETURN(cydriver.cuGraphGetNodes(as_cu(self._h_graph), nodes_vec.data(), &num_nodes))
+        if num_nodes > 128:
+            nodes_vec.resize(num_nodes)
+            with nogil:
+                HANDLE_RETURN(cydriver.cuGraphGetNodes(as_cu(self._h_graph), nodes_vec.data(), &num_nodes))
 
         return set(GraphNode._create(self._h_graph, nodes_vec[i]) for i in range(num_nodes))
 
@@ -346,21 +358,12 @@ cdef class GraphDef:
             Each element is a (from_node, to_node) pair representing
             a dependency edge in the graph.
         """
-        cdef size_t num_edges = 0
-
-        with nogil:
-            IF CUDA_CORE_BUILD_MAJOR >= 13:
-                HANDLE_RETURN(cydriver.cuGraphGetEdges(as_cu(self._h_graph), NULL, NULL, NULL, &num_edges))
-            ELSE:
-                HANDLE_RETURN(cydriver.cuGraphGetEdges(as_cu(self._h_graph), NULL, NULL, &num_edges))
-
-        if num_edges == 0:
-            return set()
-
         cdef vector[cydriver.CUgraphNode] from_nodes
         cdef vector[cydriver.CUgraphNode] to_nodes
-        from_nodes.resize(num_edges)
-        to_nodes.resize(num_edges)
+        from_nodes.resize(128)
+        to_nodes.resize(128)
+        cdef size_t num_edges = 128
+
         with nogil:
             IF CUDA_CORE_BUILD_MAJOR >= 13:
                 HANDLE_RETURN(cydriver.cuGraphGetEdges(
@@ -369,6 +372,20 @@ cdef class GraphDef:
                 HANDLE_RETURN(cydriver.cuGraphGetEdges(
                     as_cu(self._h_graph), from_nodes.data(), to_nodes.data(), &num_edges))
 
+        if num_edges == 0:
+            return set()
+
+        if num_edges > 128:
+            from_nodes.resize(num_edges)
+            to_nodes.resize(num_edges)
+            with nogil:
+                IF CUDA_CORE_BUILD_MAJOR >= 13:
+                    HANDLE_RETURN(cydriver.cuGraphGetEdges(
+                        as_cu(self._h_graph), from_nodes.data(), to_nodes.data(), NULL, &num_edges))
+                ELSE:
+                    HANDLE_RETURN(cydriver.cuGraphGetEdges(
+                        as_cu(self._h_graph), from_nodes.data(), to_nodes.data(), &num_edges))
+
         return set(
             (GraphNode._create(self._h_graph, from_nodes[i]),
              GraphNode._create(self._h_graph, to_nodes[i]))

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()