ci: constrain internal builds to exact local wheels

[rwgk]

Description

Fixes #2468.

xref: #2464, #2470

Same-checkout CI builds must not silently substitute a compatible package from PyPI for the local CUDA Python wheel that the workflow intends to test. This PR makes that invariant explicit: once CI selects a local internal wheel, pip must consume that exact artifact or fail. Public package indexes remain available for third-party dependencies. See #2468 for the failure history and detailed analysis.

This PR is stacked on #2509. The base PR reports the version and location of the dependencies imported by the build hooks; this PR enforces which artifacts pip selects.

The selection policy remains entirely in CI. Normal package build requirements are unchanged, and builds that do not supply these constraints retain their existing behavior.

Exact local-wheel constraints

This PR adds ci/tools/write_wheel_constraints.py, a small cross-platform helper that turns selected wheel artifacts into PEP 508 direct-reference constraints such as:

cuda-bindings @ file:///.../cuda_bindings-13.3.2.dev...whl

The helper:

• reads each wheel's .dist-info/METADATA instead of trusting its filename;
• canonicalizes and validates the requested distribution name;
• optionally selects an expected CUDA release major;
• requires exactly one matching artifact and fails clearly for missing, ambiguous, mismatched, or malformed wheels;
• produces correctly escaped file URIs, including paths containing spaces;
• maps host paths to cibuildwheel's /host mount when needed;
• removes stale output before resolution and writes completed constraint files atomically; and
• logs the selected package, version, source path, and consumer-visible URI.

Each protected build supplies both PIP_BUILD_CONSTRAINT and PIP_CONSTRAINT. The former constrains dependencies installed into PEP 517 isolated build environments; the latter applies the same selection to other pip dependency resolution in the step. The affected environments install pip 25.3 or newer, where dedicated build constraints are supported.

This replaces artifact selection based on PIP_FIND_LINKS and PIP_PRE in these workflows. Those settings can make a local wheel discoverable or make a prerelease eligible, but they do not identify the exact artifact that must be tested.

Protected dependency edges

Consumer build	Exact local constraints
cuda.bindings	selected cuda-pathfinder wheel
current-major cuda.core	selected cuda-pathfinder and current-major cuda-bindings wheels
previous-major cuda.core	selected cuda-pathfinder and previous-major cuda-bindings wheels

The constraints are applied across:

• production wheel builds on Linux and Windows, including the previous-CUDA-major cuda.core build;
• Linux and Windows wheel-from-sdist tests; and
• Linux and Windows coverage builds.

The downloaded previous-major bindings wheel is kept in a separate directory from the current build artifacts. This makes major selection explicit and avoids an ambiguous wheel directory before generating the previous-major core constraint.

Tests

The new helper has unit coverage for successful direct-reference generation, project-name canonicalization, expected-major selection, paths containing spaces, cibuildwheel container-path mapping, and diagnostic output. Failure coverage includes missing or empty directories, wrong distributions or majors, multiple matching wheels, invalid project names, corrupt archives, malformed metadata, duplicate requests, invalid container mounts, and stale-output removal.

The standalone CI-tool tests are now run by the existing pre-commit CI job without importing the repository-level test configuration.

[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