ci: separate source and built artifact validation

[SSobol77]

Summary

Separate source and structural release validation from final built-artifact verification.

This fixes Gate 2 behavior where ignored historical files under releases/
could incorrectly trigger final PyPI artifact validation.

Root cause

validate-gate2 previously treated the presence of either an artifact or its
checksum sidecar as a trigger for final artifact validation.

The ignored historical releases/0.2.3/ tree contains PyPI artifacts but keeps
older checksum evidence under .checksums/. This caused Gate 2 to invoke the
fail-closed final PyPI validator and require adjacent checksum sidecars.

The defect was in Gate 2 dispatch logic, not in:

• scripts/verify_artifact.py
• scripts/verify_release_assets.py
• the exact 21 GitHub Release asset contract

What changed

Added:

make validate-pypi-source-contract

This runs:

python scripts/publish_pypi.py --dry-run

The default:

make validate-gate2

now performs source and structural validation only:

• version consistency
• runtime import guard
• Linux official evidence drift gate
• PyPI source contract validation

Final built-artifact verification is now explicit:

make validate-built-artifacts

Fail-closed artifact behavior

For each optional artifact:

• artifact absent and sidecar absent: skip;
• artifact present and sidecar present: run final validator;
• artifact present and sidecar missing: fail;
• sidecar present and artifact missing: fail.

For the PyPI artifact set:

• none of the four required files present: skip;
• all four present: run validate-pypi-contract;
• any partial set: fail and report every missing file.

Required PyPI files:

• wheel
• wheel .sha256
• sdist
• sdist .sha256

Preserved contracts

This PR does not change:

• the exact 21 GitHub Release asset contract;
• scripts/verify_release_assets.py;
• .github/workflows/release.yml;
• release upload behavior;
• checksum digest verification;
• adjacent sidecar requirements for final artifact verification;
• artifact names;
• versions;
• packaging mappings;
• release artifacts.

No .checksums/ fallback was added.

Tests

Added focused coverage for:

• Gate 2 source-only behavior;
• explicit built-artifact validation;
• complete artifact pairs;
• missing sidecars;
• orphan sidecars;
• absent artifact pairs;
• complete PyPI four-file sets;
• all partial PyPI file combinations;
• preservation of the exact 21 release asset contract.

Validation

Passed:

uv run ruff check src tests scripts
uv run ruff format --check src tests scripts
uv run python scripts/check_runtime_imports.py
uv run pytest -q tests/packaging/test_release_asset_count_gate.py
uv run pytest -q tests/packaging
uv run pytest -q tests/docs
uv run python scripts/f4_linter_linux_provisioning.py --check-official-evidence-drift
make validate-gate2
git diff --check

Observed:

tests/packaging/test_release_asset_count_gate.py: 85 passed
tests/packaging: 523 passed
tests/docs: 18 passed
PASS: Linux official distro evidence drift audit clean
--> OK: Gate 2 source and structural contract validation completed

Scope

Changed only:

• Makefile
• docs/release/release-process.md
• tests/packaging/test_release_asset_count_gate.py

No release artifacts were created or modified.

Summary by CodeRabbit

• New Features

  • Added separate validation commands for source contracts and built release artifacts.
  • Added PyPI source-contract validation through a dry-run publishing check.
  • Built-artifact validation now covers supported packages, platform artifacts, release assets, and checksum sidecars.

• Bug Fixes

  • Artifact validation now fails safely when files or checksum sidecars are missing or incomplete.

• Documentation

  • Clarified the scope and recommended use of source and built-artifact validation commands.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 7adb1191-b80e-428d-8e10-1b68ccb69672

📥 Commits

Reviewing files that changed from the base of the PR and between a72044e and 5bb5bda.

📒 Files selected for processing (3)

• Makefile
• docs/release/release-process.md
• tests/packaging/test_release_asset_count_gate.py

---

📝 Walkthrough

Walkthrough

Changes

Release validation split

Layer / File(s)	Summary
Artifact contract helpers Makefile	Adds separate helpers for single artifacts, complete PyPI sets, and optional release assets, enforcing artifact and .sha256 sidecar pairing.
Validation target orchestration Makefile, docs/release/release-process.md	Adds the PyPI source-contract target, limits validate-gate2 to source/structural checks, and moves optional artifact verification to validate-built-artifacts; documentation describes the split.
Makefile probe coverage tests/packaging/test_release_asset_count_gate.py	Adds subprocess tests for target separation, skip behavior, validator invocation, complete sidecar pairs, and fail-closed partial PyPI sets.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Developer
  participant Makefile
  participant publish_pypi.py
  participant ArtifactValidators

  Developer->>Makefile: make validate-gate2
  Makefile->>publish_pypi.py: run --dry-run
  publish_pypi.py-->>Makefile: source contract result
  Developer->>Makefile: make validate-built-artifacts
  Makefile->>ArtifactValidators: validate complete present artifacts
  ArtifactValidators-->>Makefile: validation result

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: separating source validation from built artifact validation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/release-checksum-sidecar-contract

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud