Preserve the workspace lockfile in Python source distributions

.github/workflows/python-publish.yml

@@ -7,6 +7,9 @@ on:
   pull_request:
     paths:
       - .github/workflows/python-publish.yml
+      - Cargo.lock
+      - python/Cargo.lock
+      - python/pyproject.toml
   workflow_dispatch:
     inputs:
       mode:
@@ -97,6 +100,29 @@ jobs:
           target: ${{ matrix.target }}
           rust-toolchain: stable
 
+      - name: Verify sdist workspace lockfile
+        if: matrix.name == 'linux-x86_64'
+        run: |
+          python3 - <<'PY'
+          import tarfile
+          from pathlib import Path
+
+          archives = list(Path("python/dist").glob("*.tar.gz"))
+          if len(archives) != 1:
+              raise SystemExit(f"Expected one source distribution, found {len(archives)}")
+          archive = archives[0]
+          with tarfile.open(archive) as source:
+              root = archive.name.removesuffix(".tar.gz")
+              if f"{root}/Cargo.lock" not in source.getnames():
+                  raise SystemExit("Source distribution is missing the workspace Cargo.lock")
+              lock = source.extractfile(f"{root}/Cargo.lock")
+              if lock is None or lock.read() != Path("Cargo.lock").read_bytes():
+                  raise SystemExit("Source distribution must contain the workspace Cargo.lock")
+              if f"{root}/python/Cargo.lock" in source.getnames():
+                  raise SystemExit("Source distribution contains an obsolete nested Cargo.lock")
+          print("Source distribution preserves the workspace Cargo.lock")
+          PY
+
       - name: Verify wheel tag
         run: |
           ls python/dist/${{ matrix.wheel-pattern }}

DEVELOPMENT.md

@@ -8,3 +8,20 @@ uv venv
 uv pip install -e ".[tests]"
 uv run pytest
 ```
+
+## Python release dependency locking
+
+The Python crate is a member of the root Cargo workspace. Keep only the root
+`Cargo.lock`: an obsolete `python/Cargo.lock` makes Maturin package that nested
+lock instead, leaving source-distribution builds without a workspace lock.
+
+From the repository root, build release artifacts with
+`maturin build --manifest-path python/Cargo.toml --release --sdist`.
+The publish workflow verifies that the sdist contains the exact root lockfile
+and no nested lock. Cargo can then retain the pinned dependency versions when
+building the source archive.
+
+Do not add `--locked` to the combined `--sdist` build: Maturin removes workspace
+members unused by the Python package, so Cargo must prune their lockfile
+entries in the extracted tree. This is different from resolving versions
+without a lockfile. Dependency upgrades belong in the checked-in root lock.