release: cut 0.3.0 — the ranking face exists in no published release

[hseshadr]

Why this is urgent, not a chore

assay.ranking merged in #13 after the v0.2.0 tag, so it ships in no published release. PyPI avow 0.2.0 has neither the module nor ir-measures in its metadata.

The consequence is a live supply-chain hole. The first consumer had to pin avow to the git merge commit 1c382ce by full SHA to reach the module. A URL requirement cannot be resolved to a version, so that consumer's dependency audit now skips avow entirely — "URL requirements cannot be pinned to a specific package version." A CVE against avow or its transitive dependencies would go unseen for as long as that pin stands.

Cutting the release closes it: the consumer moves back to a PyPI range, avow[assay]>=0.3.0, and its audit sees the package again.

A trap worth naming: the git checkout of 1c382ce reports version 0.2.0 — the same string as the published artifact that does not contain this code. Version strings were never the identity here.

Why 0.3.0, not 0.2.1

Two independent reasons, either sufficient on its own:

1. A new public face + a new runtime dependency. assay.ranking and assay.ranking_score are new API; ir-measures is a new runtime dep. That is a feature, not a patch.
2. A BREAKING rename is in the same unreleased set. ReplayMismatch → PayloadHashMismatch, and the code string avow.replay_mismatch → avow.payload_hash_mismatch. This repo bumps the minor for breaking changes in 0.x — that is exactly what 0.2.0 was ("a breaking release that makes three trust claims literally true").

The repo had also already committed to the number in prose: README.md:690 says the rename "ships in 0.3.0", and ts/README.md:57 says "renamed in 0.3.0". 0.2.1 would have contradicted both.

Every place the version lives — all three bumped

File	Role
src/avow/_version.py	hatchling's single source, read at build time so installed metadata and avow.__version__ cannot drift
ts/package.json	@edgeproc/avow, pair-versioned. A v* tag publishes PyPI and npm; npm rejects a re-publish at an unchanged version
CHANGELOG.md	[Unreleased] → [0.3.0] - 2026-08-03

The npm half is not optional, and it is not a judgement call — tests/test_packaging.py::test_python_and_typescript_packages_carry_the_same_version asserts ts/package.json version == avow.__version__. Bumping _version.py alone turns the gate red. publish.yml states the same thing in its header: "A tag push that re-runs this workflow at an unchanged version will be REJECTED by both registries. Bump the version before tagging."

Changelog correction: the entry named the wrong engine

The [Unreleased] entry claimed the ranking arithmetic was scikit-learn's. It is not, and has not been since the engine swap — it is trec_eval's, reached through ir_measures, the reference implementation the IR field validates its own numbers against.

The entry now records why, because the reasoning is the reusable part:

ndcg_score and label_ranking_average_precision_score are multilabel-classification metrics. Neither has any notion of a relevant document that was never retrieved, so both had to be talked into retrieval semantics at the boundary: nDCG by padding the positions the ranker left empty, average precision by rescaling LRAP by |relevant retrieved| / |relevant| to undo its habit of dividing by the labels it was handed — without which, retrieving 1 of 4 relevant documents scored 1.0. Two hand-written semantic corrections wrapped around a mismatched engine, and a subtle error in either would have silently corrupted every number downstream. Both are deleted.

The adapter code was the tell, not the fix. Maturity was never the question — scikit-learn is impeccably mature and was still the wrong engine for this field. It stays in the assay extra, because metrics.py still uses it for the classification metrics it is actually right for.

How ir-measures is declared

Under the assay extra, not the base install:

[project.optional-dependencies]
assay = [
    "scikit-learn>=1.9",
    "scipy>=1.18",
    "numpy>=2.5",
    "ir-measures>=0.4.3",
]

That is correct and unchanged by this PR — it landed with #13. The base install stays the envelope only (pydantic, pydantic-settings, pynacl, rfc8785) so pip install avow and micropip in Pyodide never pull the scientific stack. ir-measures carries exactly one transitive dependency, pytrec-eval-terrier (the C++ binding to trec_eval itself), whose own deps are numpy + scipy — already pinned in the same extra.

Claim this PR touches

None directly — no code, no public API, no guard. It makes the version strings and the changelog tell the truth about what is on main. The guard that protects this change is the packaging parity test, and it is pre-existing and green.

Evidence

Claim	Proof
Python gate passes	uv run poe gate → exit 0; ruff → ruff-format → mypy --strict → xenon A → pytest
Test count + coverage	184 passed; 100% statement and branch coverage (803 statements, 68 branches, none missed) against a 90% floor
TypeScript gate passes	cd ts && pnpm gate → exit 0; 40 tests in 2 files (biome → tsc --noEmit → vitest → build)
The artifact actually carries the fix	avow-0.3.0-py3-none-any.whl → Version: 0.3.0, Requires-Dist: ir-measures>=0.4.3; extra == 'assay', and assay/ranking.py present in the wheel
Base install not widened	wheel Requires-Dist outside the extras is still pydantic / pydantic-settings / pynacl / rfc8785 only

The wheel metadata is the load-bearing one — it is precisely what PyPI avow 0.2.0 lacks and what makes the consumer's audit work again.

Not in this PR — human gates

No tag and no GitHub release. git tag v0.3.0 && git push origin v0.3.0 is what fires publish.yml.

After merge, and remembering that a green publish job is not evidence:

1. confirm the registries actually serve it (pip index versions avow, npm view @edgeproc/avow@0.3.0), not the workflow conclusion;
2. inspect npm view @edgeproc/avow@0.3.0 dist.attestations --json for an actual value — it prints empty and exits 0 when provenance is missing, so an exit-code check proves nothing;
3. then move the consumer off the git-SHA pin to avow[assay]>=0.3.0 and confirm its audit stops skipping the package.

🤖 Generated with Claude Code

https://claude.ai/code/session_015o7tjWLFZvzRv4KyNfDukx

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.