python: abi3 wheels, CI gate on publish, musllinux, action pins

P1: enable pyo3/abi3-py39 in the python feature. One wheel per
platform/arch now covers CPython 3.9-3.13+ instead of being tied to the
host Python ABI; published wheel name becomes pyvicinity-X.Y.Z-cp39-abi3-{plat}.
Caveat: abi3 is incompatible with free-threaded CPython (3.13t+);
revisit if/when free-threaded support is requested. Verified locally:
maturin develop and maturin build both produce cp39-abi3 wheels; the
existing 168 Rust unit tests + 23 Python tests + stubtest all pass.

P2: gate publish-pypi on CI green for the same SHA. Previously the only
gate was a text-input "confirm=publish" check; the workflow could ship
wheels for a SHA whose CI was red or pending. Add a guard step that
queries the GitHub API for the most recent ci.yml run on $GITHUB_SHA
and aborts unless conclusion == success.

P3: add musllinux x86_64 + aarch64 to the wheel matrix. Alpine and other
musl-based distros previously had no wheel and would fall back to
building from sdist.

P4: pin all GitHub Actions to specific minor versions instead of moving
major tags. Tags like @v1 / @release/v1 are mutable refs and have been
abused for supply-chain attacks; specific versions are reproducible and
auditable. checkout v6.0.2, setup-python v6.2.0 (was v5),
upload-artifact v7.0.1 (was v4), download-artifact v8.0.1 (was v4),
maturin-action v1.51.0, gh-action-pypi-publish v1.14.0 (was release/v1).

P5: expand [project.urls] in pyproject.toml with Documentation, Issues,
and Changelog so PyPI's project page and `pip show` link to all three.

All five items recommended by /scrutinize 2026-04-28; user greenlit
"proceed on all fronts".

Author: arclabs561

.github/workflows/publish-pypi.yml

@@ -16,67 +16,98 @@ jobs:
   guard:
     runs-on: ubuntu-latest
     steps:
-      - name: Guard
+      - name: Confirm input
         run: |
           if [ "${{ inputs.confirm }}" != "publish" ]; then
             echo "Refusing to publish: set workflow input confirm=publish"
             exit 1
           fi
+      - name: Verify CI passed for this SHA
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          conclusion=$(gh run list \
+            --repo "$GITHUB_REPOSITORY" \
+            --workflow=ci.yml \
+            --commit="$GITHUB_SHA" \
+            --json conclusion \
+            --jq '.[0].conclusion // "missing"')
+          echo "CI conclusion for $GITHUB_SHA: $conclusion"
+          if [ "$conclusion" != "success" ]; then
+            echo "::error::CI for $GITHUB_SHA is '$conclusion', not 'success'. Aborting publish."
+            exit 1
+          fi
 
+  # Wheels are abi3 (cp39-abi3) -- one wheel per platform/arch covers all
+  # CPython 3.9+ versions. Free-threaded Python is not supported by abi3.
   build-wheels:
     needs: guard
     strategy:
       matrix:
         include:
           - os: ubuntu-latest
             target: x86_64-unknown-linux-gnu
-            platform: manylinux
+            manylinux: "2_28"
+            artifact-suffix: manylinux-x86_64
+          - os: ubuntu-latest
+            target: aarch64-unknown-linux-gnu
+            manylinux: "2_28"
+            artifact-suffix: manylinux-aarch64
+          - os: ubuntu-latest
+            target: x86_64-unknown-linux-gnu
+            manylinux: "musllinux_1_2"
+            artifact-suffix: musllinux-x86_64
           - os: ubuntu-latest
             target: aarch64-unknown-linux-gnu
-            platform: manylinux
+            manylinux: "musllinux_1_2"
+            artifact-suffix: musllinux-aarch64
           - os: macos-14
             target: aarch64-apple-darwin
-            platform: macosx
+            manylinux: "auto"
+            artifact-suffix: macos-arm64
           - os: macos-13
             target: x86_64-apple-darwin
-            platform: macosx
+            manylinux: "auto"
+            artifact-suffix: macos-x86_64
           - os: windows-latest
             target: x86_64-pc-windows-msvc
-            platform: windows
+            manylinux: "auto"
+            artifact-suffix: windows-x86_64
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v6.0.2
+      - uses: actions/setup-python@v6.2.0
         with:
           python-version: "3.11"
       - name: Build wheels
-        uses: PyO3/maturin-action@v1
+        uses: PyO3/maturin-action@v1.51.0
         with:
           target: ${{ matrix.target }}
           args: --release --out dist --features "hnsw,python,parallel"
-          manylinux: ${{ matrix.platform == 'manylinux' && '2_28' || 'auto' }}
+          manylinux: ${{ matrix.manylinux }}
       - name: Upload wheels
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7.0.1
         with:
-          name: wheels-${{ matrix.platform }}-${{ matrix.target }}
+          name: wheels-${{ matrix.artifact-suffix }}
           path: dist/*.whl
           if-no-files-found: error
 
   build-sdist:
     needs: guard
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v6.0.2
+      - uses: actions/setup-python@v6.2.0
         with:
           python-version: "3.11"
       - name: Build sdist
-        uses: PyO3/maturin-action@v1
+        uses: PyO3/maturin-action@v1.51.0
         with:
           command: sdist
           args: --out dist
       - name: Upload sdist
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7.0.1
         with:
           name: sdist
           path: dist/*.tar.gz
@@ -88,11 +119,11 @@ jobs:
     environment: pypi
     steps:
       - name: Gather dist artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8.0.1
         with:
           path: dist
           merge-multiple: true
       - name: Publish to PyPI (trusted publishing)
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@v1.14.0
         with:
           packages-dir: dist

Cargo.toml

@@ -30,7 +30,12 @@ thiserror = "2.0"
 # Note: do NOT enable `pyo3/extension-module` here. It breaks `cargo test --all-features`
 # by disabling libpython linking for test binaries on macOS.
 # Maturin sets `PYO3_BUILD_EXTENSION_MODULE=1` when building wheels.
-pyo3 = { version = "0.27.2", optional = true }
+#
+# `abi3-py39` builds a stable-ABI wheel that works on CPython 3.9+, so one
+# wheel per platform/arch covers every supported Python version. Caveat:
+# abi3 wheels are not compatible with free-threaded CPython (3.13t+); revisit
+# if/when free-threaded support is requested.
+pyo3 = { version = "0.27.2", optional = true, features = ["abi3-py39"] }
 numpy = { version = "0.27.0", optional = true }
 
 # SIMD primitives (ecosystem crate)

pyproject.toml

@@ -21,6 +21,9 @@ classifiers = [
 [project.urls]
 Homepage = "https://github.com/arclabs561/vicinity"
 Source = "https://github.com/arclabs561/vicinity"
+Documentation = "https://docs.rs/vicinity"
+Issues = "https://github.com/arclabs561/vicinity/issues"
+Changelog = "https://github.com/arclabs561/vicinity/blob/main/CHANGELOG.md"
 
 [project.optional-dependencies]
 ann-benchmarks = ["h5py"]