[rwgk]

— codex GPT-6 on behalf of Ralf —

Layer 2 of 7 of the staged "CUDA 12 bindings on main" stack. Previous: #3314. Next: #3317. Stack map at the bottom.

What this PR does

Makes cuda_bindings_12/ a place a developer can actually work in on main: install it, run its tests, build its docs. It also carries the three runtime fixes that CUDA 13 already has, and the NVML test adaptations the current CI runners need.

Size: 37 files, +14,041 / -155, of which 13,185 lines are the new cuda_bindings_12/pixi.lock. The hand-written part is about 850 lines, roughly half of it documentation.

• Packaging (cuda_bindings_12/pyproject.toml): Python >= 3.11 (3.10 dropped, as agreed with Mike on cuda.bindings: configure independent CUDA 12 and CUDA 13 packages #3174), 3.14/3.15 classifiers, [dependency-groups] mirroring CUDA 13, standard setuptools-scm tag parsing with selector v12.9.* (the custom tag_regex is gone), and a scm-bootstrap-release = "12.9.11" preview target.
• Pixi: new cuda_bindings_12/pixi.toml + lock (cu12, docs, cython-tests features). The root test-bindings task picks the root from the environment name. The pin check covers both roots and Core.
• Version preview bootstrap (ci/tools/bindings_scm_version.py, 124 lines). Copying the sources did not bring the 12.9.x tags along, so a plain checkout derives 12.9.1.devN. In a disposable CI checkout the helper creates one local tag v12.9.11a0.dev0 at HEAD^, so builds get 12.9.11a0.devN. It never pushes, never moves an existing tag, and stands down once a real v12.9.* tag at or above 12.9.10 is reachable. The lifecycle rules are written into AGENTS.md.
• CI tooling as a package: ci/pyproject.toml, installed with pip install -e ./ci.
• CPU source-build smoke (ci-pixi-source-test.yml): the PR job runs a cu12 and a cu13 leg; the nightly GPU full-test too. A container checkout needs git config --global --add safe.directory before the SCM bootstrap runs; that was found and fixed here.
• Runtime fixes ported from CUDA 13: bytes compiler options (Fix get_nested_resource_ptr to accept both str and bytes inputs #1665, Fix get_nested_resource_ptr to accept both str and bytes inputs #1698), coredump buffer ownership (Harden program-cache permissions, binary-path resolution, and coredump helper lifetime #2399), handle-getter error propagation (Do not report a registered type as "Unknown type" in get_cuda_native_handle #2551), each with its test.
• Test maintenance ported from the CUDA 13 NVML tests: Orin/Thor naming, NotSupportedError for PCI info, driver >= 13.4 refcount skip, removal of the flaky energy test, thread_unsafe markers.
• Docs: root and package AGENTS.md (the rule that a change in one root must be checked against the other), README, install/support pages (Python 3.11), rewritten 12.X.Y-notes.rst.

After this merges

• Developers: pixi run --manifest-path cuda_bindings_12 -e cu12 test, or python -m pip install -e . --group test inside cuda_bindings_12/, work.
• CI: wheel builds, GPU tests, and releases are unchanged. cuda.core still gets its CUDA 12 bindings from the 12.9.x branch. New: the PR-time CPU smoke job also source-builds the CUDA 12 root.
• CUDA 13 package versions are unchanged.

Where to look

• ci/tools/bindings_scm_version.py and the lifecycle section of AGENTS.md: the one piece of "magic" in the stack. Check that it can only ever add a local tag.
• cuda_bindings_12/pyproject.toml: the Python 3.11 floor and the v12.9.* selector.
• The three runtime diffs under cuda_bindings_12/cuda/bindings/ (31 lines total), side by side with their CUDA 13 counterparts.
• cuda_core/pixi.toml: Core's pixi run test now collects tests/ instead of the package root. This retains Core's owned Python and Cython tests while excluding vendored CCCL tests.

All changes (37 files; 36 without the lockfile, +856 / -155)

Tooling: ci/pyproject.toml (new), ci/tools/bindings_config.py (JSON CLI, python.supported), ci/tools/bindings_scm_version.py (new), ci/tools/check_pixi_cuda_version.py (both roots), ci/tools/compute_ci_plan.py (map cuda_bindings_12/ to the bindings module), tests for the new helper and the registry CLI, removal of a workflow-text test.

Workflows: ci-pixi-source-test.yml (cu12/cu13 matrix for build-smoke and full-test, SCM bootstrap, safe.directory), ci.yml and ci-nightly.yml (install ./ci[test] for the tool tests), .pre-commit-config.yaml (pixi hook paths, large-file exception for the lockfiles).

Package: cuda_bindings_12/pyproject.toml, pixi.toml (new), pixi.lock (new), tests/pytest.ini (thread_unsafe marker), runtime fixes in _internal/utils.pyx, _lib/utils.pxd, _lib/utils.pxi, utils/__init__.py, tests in test_nvjitlink.py, test_nvvm.py, test_utils.py, test_cuda.py, NVML tests.

Pixi: root pixi.toml (test-bindings root selection), cuda_core/pixi.toml (test task scope).

Docs: AGENTS.md, README.md, cuda_bindings_12/AGENTS.md (new), cuda_bindings_12/README.md, docs/source/install.md, support.rst, release/12.X.Y-notes.rst.

Validation

• Full CI passed at the pre-rebase head 4e22130d (run 41183676173, 104 jobs).
• The pixi source-build workflow was dispatched manually for cu12 at that head (run 41183098858): build smoke (cu12), pixi run test (cu12, GPU), and the cu13/cu12/cu13 round trip all passed. Three earlier dispatches at intermediate commits failed or were cancelled; the fixes they produced (safe.directory, root task forwarding, Core test scope) are included in this layer.
• Current head 968ad32089f4a0f1ee8f0f223982527cc2c67b24 includes the follow-up fixes. Local validation: 303 CI-tool tests, actionlint passed. Full CI and native Pixi source/GPU checks have not been rerun for it.

Stack map: what main can do after each layer merges

Layer	PR	After it merges, main ...
1	#3314	behaves exactly as before; CI has one reader for the two bindings roots; CUDA 13 versions can no longer match a v12.* tag
2	#3315	lets a developer build, test, and document cuda_bindings_12/; the PR-time CPU source-build smoke covers both roots; three CUDA 12 runtime fixes are in
3	#3317	builds the CUDA 12 bindings wheel itself and runs its GPU tests; cuda.core and the metapackage still consume 12.9.x artifacts
4	#3318	uses same-run CUDA 12 wheels everywhere; PR CI no longer reads the 12.9.x branch
5	#3319	can release CUDA 12 from a v12.9.N tag on main; CUDA 13 releases are unchanged
6	#3321	builds and tests only what a change needs, per bindings root, reusing baseline artifacts
7	#3322	carries the schema-2 registry, a manual-only backport workflow, a metadata consistency hook, and the maintenance docs; 12.9.x is frozen

Every layer was designed to be mergeable on its own and had a green full CI run at its pre-rebase head on 2026-10-31. The stack is the "individually mergeable pieces" alternative to #3174-#3182; both stacks reach the same end state except that this one keeps compatibility routes for older artifact sources and retained CUDA 13 tags.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[rwgk]

/ok to test b7c7625

[rwgk]

/ok to test eaf85d9

[github-actions]

Doc Preview CI
🚀 View preview at https://nvidia.github.io/cuda-python/pr-preview/pr-3315/
https://nvidia.github.io/cuda-python/pr-preview/pr-3315/cuda-core/
https://nvidia.github.io/cuda-python/pr-preview/pr-3315/cuda-bindings/
https://nvidia.github.io/cuda-python/pr-preview/pr-3315/cuda-pathfinder/
Preview will be ready when the GitHub Pages deployment is complete.

[rwgk]

/ok to test 792b7d1

[rwgk]

/ok to test 4e22130