[rwgk]

— codex GPT-6 on behalf of Ralf —

Layer 3 of 7 of the staged "CUDA 12 bindings on main" stack. Previous: #3315. Next: #3318. Stack map at the bottom.

What this PR does

main starts building the CUDA 12 bindings wheel itself and running its GPU test suite, next to the existing CUDA 13 pipeline. Nothing else moves yet: cuda.core and the metapackage keep consuming the 12.9.x-branch artifacts (that cord is cut in #3318).

• build-wheel.yml: after the CUDA 13 work, switch to the maintenance mini-CTK (already fetched for Core's cu12 half), build the cuda_bindings_12 wheel with the same cibuildwheel environment (shared through a YAML anchor), twine check it, upload it, and build and upload its Cython test extensions.
• ci.yml: three new jobs, Maintenance bindings (linux-64 / linux-aarch64 / win-64), call the existing test workflows with bindings-only: true. Only matrix rows with CUDA_VER == 12.9.1 run, and only the bindings suite.
• test-wheel-linux.yml, test-wheel-windows.yml: new inputs bindings-config and bindings-only; rows gain BINDINGS_ROOT.
• ci/tools/env-vars, ci/tools/run-tests: CUDA_BINDINGS_ROOT replaces the hard-coded cuda_bindings_13.
• cuda_bindings_12/pyproject.toml: wheel payload policy copied from CUDA 13 (include-package-data = false: wheels ship .pxd/.pxi and headers, not .pyx sources or .in templates; sdists keep everything) and cibuildwheel settings. Recorded in the upcoming release notes.

Temporary scaffolding: the artifact name maintenance-bindings-python<py>-cuda12.9.1-<platform>-<sha> and the three jobs exist only in this layer. #3318 folds the tests into the regular jobs and #3319 renames the artifacts to the final cuda-bindings-python<py>-cuda<toolkit>-... scheme.

After this merges

• Every CI run additionally builds one CUDA 12 bindings wheel per Python version and platform (no Windows ARM64; CUDA 12 has no toolkit there) and runs the bindings suite on the matrix rows whose toolkit is 12.9.1 (a few extra GPU jobs per platform).
• cuda.core, the metapackage, releases, and nightly are unchanged.

Where to look

• .github/workflows/build-wheel.yml: the "maintenance cuda.bindings" steps near the bottom and the &bindings-wheel-env anchor.
• .github/workflows/test-wheel-linux.yml: the bindings-only matrix filter (the Windows file mirrors it).
• cuda_bindings_12/pyproject.toml: the payload policy, a deliberate product decision.

All changes (8 files, +254 / -19)

• .github/workflows/build-wheel.yml: maintenance wheel build/check/upload, Cython test build/upload, pip install -e ./ci, SCM preview bootstrap step, mini-CTK gating.
• .github/workflows/ci.yml: ci-vars exports the registry JSON; three test-maintenance-bindings-* jobs; the checks aggregator expects them.
• .github/workflows/test-wheel-linux.yml, test-wheel-windows.yml: bindings-config / bindings-only inputs, matrix filter, artifact prefix.
• ci/tools/env-vars: MAINTENANCE_* build variables, CUDA_BINDINGS_ROOT, artifact prefix.
• ci/tools/run-tests: bindings suite runs from CUDA_BINDINGS_ROOT.
• cuda_bindings_12/pyproject.toml, docs/source/release/12.X.Y-notes.rst: payload policy and its note.

Validation

• Full CI passed at the pre-rebase head afe9fc9e (run 41185002774), including the three new maintenance-bindings jobs.
• Current head 24d485d405ec1b9fb82d061abd57666e03825e81 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 afe9fc9

[github-actions]

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

[mdboom]

This PR is a bit of a special case to call it out. It adds things that we wouldn't want permanently that subsequence steps remove, really to just "bootstrap" the wheels into the right place. It would be better if there were a way to bootstrap in a single step because this will put us on a path to merge each of these individually.

I think a better arrangement would be to have a lower-level wheel-building workflow for specific wheels that could be triggered manually. Then for bootstrapping, we kick it off directly, and otherwise it would just be used in various configurations from the existing build-wheel.yml script. But that's probably not worth it.

🔴 JUST AN IMPORTANT NOTE TO MAKE SURE THE STACK ABOVE THIS IS APPROVED BEFORE MERGING THIS SO WE DON'T GET STUCK IN THIS BAD INTERMEDIATE STATE.

[mdboom]

See my previous comments in #3315 and #3316 about bindings_scm_version.

[mdboom]

Again, 3.12 is an odd choice. 3.11 would be better.

[mdboom]

bindings-only is a confusing name for this variable (if the comment is correct). Maybe maintenance-bindings?