cuda.core: add GraphBuilder.graph_definition property

[Andy-Jost]

Summary

Completes step 3 of #1330 by exposing the captured graph as an explicit GraphDefinition view that shares ownership of the same graph the builder is producing. The handle-layer plumbing landed in #2008; this PR wires up the user-facing surface and the state-guard rules.

The new property unlocks two hybrid flows:

• Inspect or augment a captured graph through the explicit API after end_building(), then re-complete() to pick up the changes.
• Populate a conditional body (returned by if_then / if_else / while_loop / switch) entirely through the explicit API without ever calling begin_building() on it.

API addition

GraphBuilder.graph_definition: GraphDefinition (read-only property)

Availability rules:

Builder kind	Before begin_building	While building	After end_building
Primary	RuntimeError	RuntimeError	OK
Conditional body	OK	RuntimeError	OK
Forked	RuntimeError	RuntimeError	RuntimeError

The returned GraphDefinition is a view, not an owning wrapper: nodes added through it appear in subsequent complete() and debug_dot_print() calls on the builder.

Test plan

Nine new tests in test_graph_builder.py:

• Happy path: graph_definition returns a GraphDefinition after end_building() and reflects the captured nodes.
• Three error paths: forked builder, primary pre-begin_building, any builder mid-capture.
• Shared validity: the returned GraphDefinition keeps working after the builder is closed.
• Round-trip: mutate via the explicit API after capture, complete(), and run end-to-end on a stream.
• Conditional-body hybrid flow: populate the body entirely through the explicit API and run.
• Conditional-body augmentation flow: capture into the body, then add extra nodes through the explicit view, and run.
• Conditional-body during-capture rejection.

Local pre-commit clean. Local test run on a 2-GPU machine: all cuda_core/tests/graph pass.

Related

• Builds on cuda.core: Cythonize GraphBuilder and Graph with handle-layer cleanup #2008 (graph-builder-refactor); branched off that PR's head, plus origin/main (so reviewers see only this commit).
• Issue CUDA graph phase N - graph updates #1330 step 3.

Made with Cursor

[Andy-Jost]

The builds on #2008. Commits unique to this PR begin at de85b92adfc0ea6c975a2259cfc2c6ef185ca430

[rwgk]

gpt-5.5 (prompt was, roughly: fully review of technical details, with moderate consideration of high-level aspects)

Findings

• P2: GraphBuilder.graph_definition can be accessed after gb.close(), but close() has reset _h_graph, so the property returns a GraphDefinition wrapper around an empty graph handle. Calls on that wrapper then reach CUDA with a null CUgraph instead of failing at the builder boundary with the same clear closed-state behavior as complete() and debug_dot_print(). A GraphDefinition obtained before close() should keep working; accessing the property after close() should be rejected. See cuda_core/cuda/core/graph/_graph_builder.pyx:267 and cuda_core/cuda/core/graph/_graph_builder.pyx:326.
• P3: The new public GraphBuilder.graph_definition API is missing the repo-required API lifecycle documentation. cuda_core/AGENTS.md says new public APIs must carry @versionadded or an explicit .. versionadded:: directive, and the 1.1.0 release notes have no entry for this user-facing graph API. Add the version annotation to the property docstring/stub and a release-note bullet so users can discover the feature. See cuda_core/cuda/core/graph/_graph_builder.pyx:286, cuda_core/cuda/core/graph/_graph_builder.pyi:133, and cuda_core/docs/source/release/1.1.0-notes.rst:10.
• P3: The newly added tests do not include the repository’s explicit authorship markers. The root AGENTS.md requires one of agent_authored, human_reviewed, or human_authored immediately above each newly added unit test. The nine new test_graph_definition_* tests are currently unmarked, starting at cuda_core/tests/graph/test_graph_builder.py:395; the conditional tests at cuda_core/tests/graph/test_graph_builder.py:488, cuda_core/tests/graph/test_graph_builder.py:527, and cuda_core/tests/graph/test_graph_builder.py:563 also need a marker in addition to their existing requires_module decorator.

[Andy-Jost]

All comments should be addressed in the latest commit.

[rwgk]

I manually reviewed the production code changes.

I trust that the tests are fine: generated by claude-opus-4.8, reviewed by codex gpt-5.5.

[github-actions]

Doc Preview CI
Preview removed because the pull request was closed or merged.