release: close remaining tag and artifact coherence gaps

[dgenio]

Summary

Hardens the remaining release-coherence boundaries tracked by #519 without changing package/runtime behavior.

What changed

• publication checkout now fetches tags and proves that the release tag resolves to the exact checked-out commit before any test/build/publish work continues;
• release validation exposes the verified commit as workflow output for auditability;
• adds stdlib-only scripts/verify_dist.py to inspect the exact wheel and sdist built for publication before they are uploaded;
• verifies artifact cardinality and filenames;
• verifies wheel METADATA and sdist PKG-INFO Name/Version against the intended release;
• verifies the wheel contains chainweaver/py.typed;
• adds unit tests for happy path, metadata drift, missing py.typed, and unexpected dist artifacts;
• strengthens structural workflow tests so tag-commit and built-metadata checks cannot silently disappear.

Why

The repository already has strong source-level coherence checks in scripts/release.py and post-publish verification, and v0.14.1 successfully published to PyPI. The remaining high-value gaps in #519 were proving the built artifacts themselves match the intended version and making the publish job explicitly prove it is operating on the commit named by the release tag.

This does not claim #519 is closed until CI passes and the issue's full acceptance criteria are re-audited.

Validation

Expected on this PR:

• workflow YAML structural tests;
• new distribution-verifier unit tests;
• normal CI matrix/static checks.

Closes #519 only after the acceptance-criteria audit confirms no remaining gap.

[dgenio]

Found a release-breaking bug in this branch and fixed it on the branch — d48da5a.

The bug

scripts/verify_dist.py rejected every real sdist. _verify_sdist selected metadata with member.name.endswith("/PKG-INFO"), and setuptools ships the .egg-info directory inside the sdist, so a genuine archive has two:

chainweaver-0.14.1/PKG-INFO
chainweaver-0.14.1/chainweaver.egg-info/PKG-INFO

Reproduced rather than reasoned about — exported this branch, ran python -m build, ran the script:

$ python3 scripts/verify_dist.py 0.14.1
distribution verification error: chainweaver-0.14.1.tar.gz: expected one PKG-INFO, found 2
$ echo $?
1

Why it mattered. In publish.yml the step sits after python -m build and before Upload dist artifacts. On the next v* tag the build job would have died and publish never run — a release outage introduced by the change whose purpose is protecting releases.

The fix, and the reason the tests missed it

Selection now matches only the archive's top-level PKG-INFO, via PurePosixPath(...).parts.

The more interesting half: the five existing tests passed because _build_fixture wrote a single PKG-INFO — a shape python -m build never produces. The suite was asserting against an artifact that does not exist. The fixture now adds the nested egg-info member, so all five existing cases exercise the real shape, plus one new case pinning that the nested file is ignored rather than counted.

Verified by mutation: with the realistic fixture and the old selector, 3 tests fail — including two that previously passed against the unrealistic shape. With the fix, 6 pass. End to end against a genuine wheel + sdist:

$ python3 scripts/verify_dist.py 0.14.1
verified ChainWeaver 0.14.1 wheel + sdist metadata
$ echo $?
0

ruff check, ruff format --check, mypy clean. Also moved Sequence to collections.abc — pre-existing on this branch and would have failed lint.

One structural gap I did not close

No CI job builds a distribution, so verify_dist.py still meets a real artifact for the first time during an actual release. That is exactly why this bug survived review and a green suite. distribution-check.yml is not the home for it — it triggers on workflow_run after Publish, so it validates what already shipped.

The fix would be a small job in ci.yml that runs python -m build and then verify_dist.py against the result on every PR. I have deliberately not added it: it is a scope decision on your draft, and I have already changed the branch once. Say the word and I will.

Two minors from the review, also unaddressed: test "${tag_commit}" = "${head_commit}" fails with no diagnostic showing which SHAs disagreed, and the github-release job still binds by tag_name: v${version} rather than the verified SHA — a residual gap against this PR's own goal.

The PR is still a draft and its previous CI run (2026-08-22) predates three commits of main, so it needs a fresh run before merge.

---

Generated by Claude Code