[rwgk]

— codex GPT-6 on behalf of Ralf —

Work in progress: awaiting CI and an interactive walkthrough.

Consolidates the six-PR stack ending at #3182 onto current main: shared builds, tests, documentation, and releases for CUDA 12/13 bindings. Trims redundant CI plumbing and implementation-shaped tests while retaining release and artifact checks.

Local validation: 347 CI-tool tests and full pre-commit.

• Contribution guidelines read.
• Tests cover the changes.
• Documentation updated.

[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 aaf85bf

[rwgk]

Diff stats comparison, PR 3182 stack vs this PR

Both diffs use the same main baseline (71e837a), after merging it into the #3182 stack. This PR is 257 net lines smaller overall.

Scope	#3182 stack: added / deleted	This PR: added / deleted
Whole PR, including lockfiles	+10,841 / −10,333	+10,586 / −10,335
.github/ + ci/, all text	+4,793 / −1,902	+4,537 / −1,904
Those directories: code/config only	+3,120 / −1,401	+3,004 / −1,403
Those directories: tests only	+1,226 / −465	+1,086 / −465

Code/config excludes tests and Markdown, reStructuredText, and Mermaid documentation. Its added lines decreased 3.7%; the existing-file footprint remains 26 of 101 files in both versions.

— codex GPT-6 on behalf of Ralf —

[github-actions]

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

[rwgk]

Narration sketch for PR 3309

This outline captures the narration approach considered alongside splitting the
change into independently mergeable PRs. The walkthrough follows concrete
development and release stories, with focused code visits and question
checkpoints. The aim is to make the behavior predictable enough to judge the
design and choose merge boundaries.

This sketch refers to PR 3309 at aaf85bf,
compared with main at 71e837a.

How each stop would work

Start with the intended behavior, trace one example, inspect one or two relevant
code sections, then challenge the design with a changed input or a failure.
Record any decision that changes scope, compatibility, or a proposed merge
boundary. Keep a short list of questions requiring a deeper second pass.

1 Establish the starting point

Main already contains both bindings source roots. Its existing pipeline builds
CUDA 13 bindings locally and obtains CUDA 12 bindings from 12.9.x for Core's
prior-major build. PR 3309 makes the main-tree CUDA 12 root participate in the
shared build, test, and release machinery.

Draw that before-and-after picture. Both roots produce the same cuda-bindings
distribution and cuda.bindings namespace, in separate environments. Distinguish
the source root, toolkit pin, Python package version, and source commit. For
example, toolkit 12.9.1 does not determine a package's release patch number.

Checkpoint: trace which source tree and which wheel supply bindings to a CUDA 12
Core test before and after this change.

Open: the existing prior-branch download
and the proposed registry.

2 Explain package and version selection

Follow three builds: the default CUDA 13 metapackage, an explicitly selected
CUDA 12 metapackage, and a CUDA 12 sdist rebuilt outside Git without the selection
environment variable. Explain how the resolved version keeps that last build's
dependencies on the CUDA 12 line.

Then explain the maintenance-version bootstrap. At the baseline, v12.9.0 is
the only reachable CUDA 12.9 tag. A narrower selector alone would derive a
12.9.1.devN version. The proposed helper supplies a local preview milestone
only when suitable history is missing. A retained milestone is a separate
release-owner decision. Standard parsing, isolated selectors, and deliberate
tag-triggered CI behavior must be ready before using it to remove this machinery.

Identify three product choices separately: the CUDA 12 Python 3.11 minimum,
omission of implementation/template files from wheels, and the CUDA 12
metapackage's dependency policy. Decide whether each belongs in this migration.

Checkpoint: predict the version and dependency family of each example before
looking at the packaging tests.

Open: metapackage selection
and SCM bootstrap.

3 Follow one CUDA 12 source change through the planner

Use a handwritten CUDA 12 bindings edit as the example. Show the resulting build
and test decisions: matching bindings and metapackage, Core tests against those
bindings, and reuse of eligible unchanged wheels. Then remove the exact-baseline
run or one required artifact and show why the plan becomes a full rebuild.

Compare this with a Core-only edit and a shared-helper edit. Explain why builds
and tests have different dependency graphs, including symlinked shared helpers.
Show a small workplan excerpt rather than walking through every field.

Checkpoint: which decisions are required for correctness, and which save CI
work? This is a promising boundary for a later optimization PR.

Open: the planner.

4 Follow wheels into actual tests

Draw the producer-consumer graph: Pathfinder, each bindings line, both Core ABI
builds and their merged wheel, metapackages, Cython test extensions, GPU tests,
sdist tests, and docs. Use one artifact's name and destination to explain the
Python, toolkit, platform, and source identity that consumers rely on.

Compare a local-bindings GPU row with a published-floor row. Explain the purpose
of each, which suites actually run, and why Cython outputs must be kept distinct
between majors. Include a source build so the discussion covers more than
prebuilt wheels.

A required local build or artifact failure must stay a failure. Any temporary
use of the legacy branch should be an explicit migration state.

Checkpoint: if local CUDA 12 wheels appeared in a new job tomorrow, which
existing consumers could keep their current inputs, and which must move together?

Open: wheel orchestration
and matrix selection.

5 Trace a release from its tag

Use a hypothetical v12.9.P release, then repeat the essential differences for
CUDA 13. Separate the workflow's control revision from the tagged source being
released. Follow root selection, the exact-tag CI run, artifact selection,
release notes, wheel validation, documentation, and publication inputs.

Make artifact compatibility explicit. Changing the metapackage artifact name or
introducing a second bindings major also changes what old release and docs
consumers can safely select. A proposed intermediate PR must keep the current
release procedure usable. Decide how historical tags retain compatible tooling.

Checkpoint: after each proposed merge, could we still release CUDA 13 while
leaving the unfinished CUDA 12 migration alone?

Open: tagged-source resolution
and release wheel validation.

6 Review the small behavior and policy changes

Compare each of the three runtime backports with its CUDA 13 counterpart: byte
compiler options, coredump buffer ownership, and propagation of registered
handle-getter errors. Keep functional coverage distinct from instrumented proof
of memory ownership.

Discuss the maintenance policy and manual-backport workflow separately. Decide
when the old branch can be frozen and its automation retired. Keep documentation
beside the behavior it describes in any future PR sequence.

Checkpoint: which of these changes can be understood, tested, and merged before
the shared CI transition?

7 Challenge proportionality and choose a landing strategy

For the checks and tests we encountered, ask what wrong outcome could otherwise
pass unnoticed, what would already fail loudly, and whether the protection earns
its maintenance cost. Apply this to artifact identity, version selection, matrix
coverage, Core ABI merging, and ordinary metadata parsing.

Use the recorded manual validation run
and its suite-step outcomes to support specific claims. Ordinary build/test
success does not establish hosted release publication. Keep earlier reuse and
release rehearsals tied to their original scope.

Finish by agreeing on the next functional landing state and its acceptance test.
For each proposed PR, identify what works immediately after merging, how the
current release path stays usable, and when temporary compatibility is removed.
Use these checkpoints to refine the staged migration.

— codex GPT-6 on behalf of Ralf —

[rwgk]

Alternative route: seven independently mergeable PRs

An alternative direction is a staged migration through seven individually reviewable and mergeable PRs, using #3309 as the complete reference implementation.

Each merged PR should leave a working state that can stand on its own while later stages are unfinished. Main already combines local CUDA 13 builds with CUDA 12 bindings from 12.9.x; that established path can remain while tested portions of the replacement are introduced.

Stage	Proposed boundary	Useful state after merging
1	Version/configuration foundations	A small shared reader consumes the existing configuration; current CUDA 13 behavior remains intact. Change the YAML representation later.
2	CUDA 12 developer workflow	Packaging, Pixi, and an explicit source-build smoke test make local CUDA 12 development usable.
3	Local CUDA 12 builds and bindings tests	Main builds and tests its CUDA 12 bindings; existing Core consumers temporarily retain their established inputs.
4	Core and metapackage adoption	Consumers move to same-run CUDA 12 artifacts, with the appropriate runtime and Cython tests.
5	CUDA 12 releases from main	Tagged-source routing, artifact selection, and documentation support the new release path while preserving CUDA 13 releases.
6	Finer per-root planning and reuse	Add the optimization after conservative rebuilding has established correctness.
7	Legacy retirement	Remove obsolete configuration, branch dependencies, and automation after their replacements work.

Release continuity matters alongside green test CI. The existing downloader uses broad component patterns. Introducing another major's artifacts can affect existing releases immediately. Every stage must preserve those contracts through explicit selection or separate artifact names.

The runtime backports, Python minimum, wheel payload, and metapackage dependency policy need explicit placement when refining these boundaries. A retained version milestone also needs deliberate SCM and tag-CI preparation.

This approach costs temporary compatibility, some duplicate CI work, and validation of each intermediate state. Total migration churn may increase, and central build/test increments are likely to remain several hundred lines. These are proposed boundaries; the intermediate states still need implementation and validation.

The first substantial test of the decomposition is a working local CUDA 12 build/test path that leaves existing CUDA 13 CI and releases usable. Use that increment, together with the narration, to refine the series before undertaking the full migration.

— codex GPT-6 on behalf of Ralf —