cuda.bindings: support multiple CTK release lines on main

[rwgk]

REMINDER

Before merging, remove the temporary .lycheeignore before triggering final CI. It excludes only three canonical main/cuda_bindings_12 URLs that cannot resolve until this PR is merged. The authored-source lychee pre-commit hook is explicitly skipped by the CI pre-commit jobs; CI separately checks links in rendered documentation. Removing this file therefore will not introduce a required-check failure before merge.

After merging, run pre-commit run lychee --all-files on fresh main to validate those links.

Summary

Closes #1199.

This is the writable continuation of Keith Kraus's original PR #2675, "cuda.bindings: build 12.9 and 13.x selectively from main". Keith authored most of the CUDA 12 source import and the initial build, test, and release integration. GitHub closed #2675 automatically when its temporary base branch was deleted after #2467 merged; this replacement preserves that work and incorporates the redesigns requested so far.

This PR moves active development of both released CUDA bindings lines onto main:

Source root	Release status	Toolkit pin
cuda_bindings_12/	maintenance	12.9.1
cuda_bindings/	current	13.3.0

The two roots are alternative source trees for the same cuda-bindings distribution and cuda.bindings import namespace. Either can be built and installed independently, but they are not separately named or intended to coexist in one environment. CI, documentation, and release workflows select the appropriate source root and toolkit pin. After merge, the historical 12.9.x branch remains only as a read-only release record, not an active backport or artifact-source branch.

Narrated Review Branch

For human review, this six-commit branch is tree-identical to review snapshot 7cb81e1:

review/multi-ctk-bindings-on-main-20260903-1844-7cb81e1

The PR branch remains authoritative. Read the review branch oldest to newest; each commit message explains its boundary, suggested review focus, and final-tree validation:

1. Import the maintained CUDA 12.9 source root
2. Define bindings package roots and release statuses
3. Plan selective work by bindings package root
4. Route builds and tests by bindings package root
5. Select releases from the tagged package root
6. Retire the CUDA 12.9 backport workflow

The highest-value review path is layers 2-5. Layer 1 is predominantly Keith's imported CUDA 12.9 tree; layer 6 isolates the branch-ownership policy. The intermediate commits are a narrative decomposition, not independently deployable states.

Design

• The source root identifies the release line. ci/versions.yml maps each unique root directly to its exact toolkit pin and scalar current or maintenance status. There are no synthetic line IDs or separate role-to-line mappings.
• Package metadata owns tag syntax. Each root's [tool.setuptools_scm].tag_regex defines its accepted release family. Registry validation reads that metadata and checks that it agrees with the configured toolkit pin; it derives the CTK target and CUDA ABI fields.
• The supported registry shape is explicit. Validation currently requires exactly one current root and one maintenance root with different CUDA ABI majors. Other shapes fail rather than implying workflow support that does not exist.
• Selective CI remains dependency-aware. The planner introduced by ci: activate dependency-aware package builds and tests #2467 now keys bindings and metapackage work by source root and CUDA Core work by ABI variant. Package-local changes select the affected work and reuse exact-merge-base artifacts where safe; shared or uncertain changes expand conservatively. A one-root bindings source change still rebuilds both Core ABI variants because they are merged into one Core wheel, while bindings and metapackage testing remains root-specific.
• Workflows consume normalized records. The repository-local, importable ci.tools package centralizes registry, version, planner, and release logic. Build, test, sdist, source-smoke, coverage, nightly, documentation, and release workflows consume explicit normalized inputs instead of reconstructing bindings identity from directory names or hard-coded CUDA majors.
• Release selection follows the tagged source tree. Modern bindings tags resolve against the registry and SCM metadata in their tagged checkout, not whichever registry later exists on main. A contained compatibility path handles historical tags whose trees predate the registry; malformed modern registries and unknown tags fail closed. Artifact selection excludes test-only wheels, and release validation rejects missing, mismatched, development/local, or unexpected distributions.
• Cross-root maintenance is a review responsibility. cuda_bindings_12/MAINTENANCE.md records the imported tree's source and partial cybind-generation provenance. The roots are not required to be byte-identical: generated and target-specific differences may be legitimate, while handwritten changes require an explicit applicability review across both roots.

Review Feedback Incorporated

• Removed duplicate tag-family metadata, synthetic line IDs, the separate role map, unsupported planner shapes, and unused workflow fallbacks.
• Packaged shared CI helpers under ci/pyproject.toml; downstream consumers trust normalized records, and build setup reads the registry once.
• Added pre-commit validation between the registry and each root's SCM metadata, and documented semantic cross-root review instead of requiring byte identity.

Reviewer Decisions

Please explicitly accept or reject these policies:

1. main is the sole active source of truth. The historical 12.9.x branch receives no further routine or emergency backports. CUDA 12 fixes are made in cuda_bindings_12/ on main, alongside a corresponding current-root change when applicable.
2. Released bindings lines use explicit source roots. The directory identifies the CI/build/release source line; release_status records its place in the release lifecycle without introducing a second line identity.
3. Full-root duplication is reviewed semantically. Contributors assess handwritten changes for both roots and explain intentional one-root-only changes; the repository does not require byte identity across roots that legitimately differ.

Validation

The following validation completed successfully for review snapshot 7cb81e1:

• Full local CI-tool suite: 136 passed
• pre-commit run --all-files: passed, including Ruff, actionlint, YAML/TOML/RST checks, generated-file seals, SCM/registry checks, and authored-source lychee with the three temporary exact exclusions described in the REMINDER
• Full gated GitHub status: 110 passed, 3 conditional skips, 0 pending, failed, or cancelled
• Bindings wheels for CUDA 12.9.1 and CUDA 13.3.0 were built and tested on Linux x86_64, Linux AArch64, and Windows; sdists for both roots were exercised on Linux x86_64 and Windows
• Documentation and selected-source build smoke checks passed

View all PR checks, the completed main CI run, and the selected-source smoke run.

Out of Scope

• Restructuring or deduplicating the contents of the two source roots

Checklist

• New and updated tests cover registry validation, selective planning, build/test routing, and release behavior.
• Documentation describes the package-root registry and cross-root maintenance model.
• Update ci/.ci-pipeline-regen.md and regenerate ci/ci-pipeline.svg to reflect the current pipeline, including removal of the retired backport artifact flows.
• Remove .lycheeignore before final CI and merging, as described in the REMINDER.

[rwgk]

/ok to test 22108c1

[rwgk]

/ok to test 889062e

[rwgk]

/ok to test 7e2b151

[rwgk]

To log this here:

To make manual review more tractable, I created this 6-layer review-only branch:

https://github.com/rwgk/cuda-python/commits/review/multi-ctk-bindings-on-main-20260902-2224-7e2b151

There are six narrated layers:

1. b98e17b — import maintained CUDA 12.9 source root
2. 3b8ba55 — define package roots and release statuses
3. 2c3c2b0 — plan selective work by package root
4. 8404ccd — route builds and tests by package root
5. 3a5ce0a — select releases from the tagged package root
6. 202584f — retire the CUDA 12.9 backport workflow

Verified:

• Final tree is exactly identical to PR head 7e2b151.
• Exactly six linear commits, with no merges.
• 134 tests and 47 subtests passed.
• Full pre-commit suite passed.

[rwgk]

/ok to test 09f27fb

[rwgk]

/ok to test 7cb81e1

[rwgk]

Hi @mdboom, I rebuilt the six-layer narrated review branch a third time from the current PR head (7cb81e1):

https://github.com/rwgk/cuda-python/commits/review/multi-ctk-bindings-on-main-20260903-1844-7cb81e1

That branch is only a review aid; this PR remains authoritative. The six commits are meant to be read oldest to newest. Each commit message explains its boundary, suggested review focus, and validation:

1. 6abe8bb — import the maintained CUDA 12.9 source root
2. dbbdf68 — define the package-root/release-status registry
3. 8be614a — plan selective work by package root
4. 61e67bb — route builds and tests
5. c1bad81 — resolve and validate releases
6. 04bfed6 — retire the 12.9 backport workflow

For the shortest useful path, I'd start with layer 2 and then review layers 3-5. Layer 4 is necessarily the broad workflow-integration layer.

I incorporated your latest feedback: ci.tools is now a small package under ci/pyproject.toml; downstream consumers trust normalized package records; pre-commit checks the registry against both bindings packages' metadata; and the generic --package-json behavior was replaced by the purpose-specific write-github-env command.

I then made another simplification pass, removing unsupported planner shapes, unused workflow fallbacks, repeated registry reads, and redundant release metadata/checks while preserving historical-tag compatibility. That pass changed 280 lines in and 412 lines out - a net reduction of 132 lines, including the added focused tests.

The current PR head is fully green. When you have a chance, could you please review this fresh layered view and let me know whether you see anything else blocking this PR? The main decisions I hope to settle are the package-root/release-status model, release routing, and moving CUDA 12.9 maintenance onto main.

[rwgk]

This implies that (a) you are running from the root of the repo, and (b) you already did a pip install -r ci/tools/requirements.txt.

requirements.txt has been deprecated for a long time. We should either: add a pyproject.toml for ci/tools and require that the package is installed into a venv (which removes the $PWD problem), or use PEP 723 comments in each script and not have a proper package altogether.

Personally, I think PEP 723 is the simpler solution (it doesn't require juggling virtual environments), but it does require having uv or pixi around to run the script.

The argument in favor of a package would be if these scripts start to share a lot of logic and helpers between them such that things in ci/tools need to import other things in ci/tools. It doesn't look like they do right now, but in the original mega-PR they started to do that a bit.

Agreed. I chose the package option after the later refactor made the helpers genuinely share logic: bindings_scm_version, check_pixi_cuda_version, check_release_notes, and compute_ci_plan now import the registry/version machinery rather than duplicating it. The PR now adds ci/pyproject.toml, removes both requirements files, and installs ./ci in editable mode at workflow call sites. The documented module invocation therefore works through an installed package and no longer relies on $PWD putting the repository on Python's import path; PEP 723 would repeat the same dependency metadata across several scripts.

[rwgk]

What's the purpose of this flag? It looks like it just spits the JSON provided right back out, doing nothing to it?

Agreed--it had no useful standalone meaning. --package-json and --github-env are gone. The only JSON-consuming operation is now the purpose-specific write-github-env GITHUB_ENV subcommand, which reads a selected package record from stdin, validates it, and appends only the supported environment variables. This removes the round-trip behavior and prevents that operation from being accidentally combined with registry-selection modes.

[rwgk]

This duplication from versions.yml is worrisome, but I don't see any way around it. I think a precommit hook to make sure it's in sync with versions.yml would be a good idea.

Agreed. I added this check-bindings-config hook, triggered by ci/versions.yml or any bindings pyproject.toml. Registry validation reads each package root's tag_regex, constructs v<toolkit_version> from the registry, and requires the SCM regex to accept that exact version. Focused SCM tests additionally verify that the current 13.3 pattern rejects 13.4 and that metapackage SCM metadata matches both bindings roots. A normal release-family update on either side now fails locally and in CI if the duplicated metadata drifts.