version: packed integer comparison key — 2.1–5.2x faster warm resolutions

[jonyoder]

Adds a packed integer comparison key to version.Version: a fixed-size 4× uint64 encoding of the PEP 440 comparison key, computed once at Parse time. When both versions carry one — 97.26% of the 7,666,849 version occurrences in the production PyPI index — Compare is a handful of integer comparisons with zero allocations instead of the allocating, interface-dispatched walk through part.Parts. Unpackable versions (nonzero epoch, local label, >6 release segments after trailing-zero strip, a segment ≥ 2^32, or oversized pre/post/dev numbers) fall back to the general path unchanged.

Three commits, deliberately separate:

1. The packed key (version/packed.go), wired into Parse and Compare, plus a fallback-path fix that makes Compare read-only on both receivers: padding now copies (padParts) instead of appending into the spare capacity Parts.Normalize leaves behind, which was a data race when two goroutines compared by-value copies of one Version. A parsed Version is now safe to share across goroutines; TestCompareSharedVersionCopiesRace fails under -race with the old padding and passes with the new (verified both ways).
2. Removal of the String() == String() equality fast path in Compare. With the packed key in place it could only serve pairs with an unpackable side, and the key comparison answers those without rendering two strings. Separate commit so its standalone value (1.18–1.51x warm, measured alone) stays attributable.
3. Frozen conformance fixtures: Compare is pinned in CI against orderings produced by pypa/packaging 26.2 — a 204,288-version generated grid crossing every packed-field limit (set-equality-checked against the in-repo generator) and 10,064 unique versions sampled from the production PyPI index. Adjacent pairs across the whole order plus ~2.7M sampled pairs must agree exactly. This test is the only thing in CI holding either ordering encoding to the reference implementation — do not delete or weaken it. Negative control: swapping the packed pre-release classes for a and b fails the test with pinpointed pairs.

Why packing, and not just the cheap fixes

Profiling go-pyresolver showed version.Compare at 81–85% of warm resolve time. Three remedies were measured independently against BenchmarkResolveWarm (production snapshot, base go-pyresolver@baa7af1, M4 Max, 10x, avg of 2 runs):

entry	base ms	packed	A1: drop reflect.DeepEqual in go-version	A2: drop String() fast path	A3: A1+A2
single-no-deps	1.750	0.368 (4.8x)	1.57x	1.51x	3.11x
small-tree	4.492	2.134 (2.1x)	1.39x	1.21x	1.88x
extras	10.19	3.55 (2.9x)	1.56x	1.25x	2.23x
app-set	69.73	14.54 (4.8x)	1.92x	1.29x	3.03x
wide-versions	81.75	15.85 (5.2x)	2.05x	1.29x	3.45x
backtracking	6.55	1.74 (3.8x)	1.62x	1.24x	2.44x
unsatisfiable	0.762	0.370 (2.1x)	1.40x	1.18x	1.70x

Packed beats A3 everywhere, and packed+A1 measured identical to packed alone — packable pairs never reach Parts.Compare, so the reflect.DeepEqual removal buys nothing once packing is in. A1 therefore stays out of this PR: it lives in rstudio/go-version (a different repo, with an unmerged related PR #5 already open there) and is noted here as measured-and-deferred at 1.39–2.05x standalone. Cold resolutions improve 3.1–11.8x (wide-versions 240 → 20.4 ms). Warm app-set allocations drop 1.50M → 276k. Resolution outputs are byte-identical across all variants. Microbenchmark: ~15 ns / 0 allocs vs 2.3–2.9 µs / 25–28 allocs per Compare.

Correctness evidence

• Differential against pypa/packaging 26.2 (the behavioural reference): the 204,288-version grid and all 634,150 unique production-index versions, adjacent-pair plus ~4M sampled-pair checks each — zero mismatches, zero parse divergences, and both implementations reject the identical 37 malformed corpus strings.
• TestPackedAgreesWithSlowPath holds the packed and general paths together across the grid; TestPackedLimits pins every packability boundary on both sides.
• Full conformance suite (PEP 440/508 tables) green, go test ./... and go test -race ./...; golangci-lint v2.11.2 clean.
• Canonicalization holds: 1.0, 1.0.0, 1.0.0.0, 1.00 compare equal — trailing-zero stripping plus zero-padding to fixed width is order-isomorphic to cmpkey's stripped-tuple comparison, and the equal-rank fixture groups cover it.

Provenance note (uv-pep440)

I read astral-sh/uv's uv-pep440 version.rs only after this layout was designed, implemented, and validated against pypa/packaging — under an explicit one-repo permission granted for this work, uv being Apache-2.0/MIT dual-licensed and already credited in this repository's NOTICE for other packages. The layout here differs materially from uv's VersionSmall: uv packs into a single u64 (release ≤4 segments with seg0 ≤ u16 and segs 1–3 ≤ u8, at most one of pre/post/dev, pre number < 64, post/dev < 256); this PR uses 4× uint64 with six 32-bit segments and three concurrent suffix fields, sized from a measured corpus distribution (the wide 25-bit dev field exists because devYYYYMMDD nightlies are the most common large suffix). uv's exact bounds would fit 86.5% of our production index; this layout fits 97.26%. Nothing — no layout, bit allocation, threshold, or code — was adopted from uv, so no NOTICE entry was added. If review later tightens the layout toward theirs, add the entry then.

Size

Version grows 352 → 392 bytes. A prior experiment shrinking a consumer-side key struct 416 → 72 bytes moved end-to-end numbers by nothing, so the growth is expected to be equally invisible; the end-to-end numbers above are measured with the growth included.

🤖 Generated with Claude Code

[jonyoder]

🟡 Medium

This regression test only fails under -race (the CHANGELOG's new "safe to share across goroutines" guarantee rests on it), but CI runs plain go test ./... (.github/workflows/ci.yml line 24) — so a later revert of padParts back to Parts.Padding would sail through CI green.
Consider adding a go test -race ./... step (or a scoped -race -run TestCompareSharedVersionCopiesRace if the full run is too slow; the three packed tests took ~49s under -race locally).

[jonyoder]

⚪ Low

Stale counts from the 6-locals grid: gridStrings() now generates 204,288 strings (verified against the fixture line count), so all pairs would be ~4.2e10, not 2.3e10.

Suggested change

	// The full grid is 153,216 versions; all pairs would be 2.3e10 comparisons.
	// The full grid is 204,288 versions; all pairs would be 4.2e10 comparisons.

[jonyoder]

⚪ Low

CLAUDE.md's changelog convention enumerates the sections as Breaking, Added, Fixed, Notes — ### Changed is new to this file. Intentional? If a Changed section is the right home for behavior-preserving performance notes (it does read naturally here), consider adding it to the CLAUDE.md list so the next entry doesn't have to guess; otherwise Notes is the documented fit.

[jonyoder]

All three review findings addressed in 537c012: CI now runs 'go test -race ./...' as its own step (the shareability guarantee is otherwise unguarded — good catch, that was the only thing standing behind the CHANGELOG claim), the stale 153,216-version grid comment now reads 204,288/~4.2e10, and the CHANGELOG entries moved from 'Changed' to the repo's enumerated 'Notes' section.

[jonyoder]

Second review pass (code-review, high effort) findings addressed in 8c7c544:

• Agreement test was 99% tautological (only 154 of 1548 sampled versions were packable, and only packable x packable pairs discriminate the encodings) — now samples 1200 packable + 400 unpackable from a seeded shuffle.
• The deterministic stride collapsed the locals grid dimension (gcd(132,8)=4 sampled 2 of 8 local labels) — both tests now shuffle-sample.
• w3 shifts are now derived from field widths with compile-time guards pinning the layout to exactly 64 bits, packedMaxSegments to the unrolled 6, and preClassInf inside its field — widening a field now stops the build instead of silently collapsing pre-release classes.
• packVersion refuses an empty release (was: packed it as version 0's key, latent only because Parse is the sole constructor).
• Dead 'e != 0' epoch clause replaced with a direct sign check.
• Grid + fixture extended with '0!' and 7-8-segment trailing-zero releases; regenerated at 338,688 versions ranked by packaging 26.2, 0 rejected.
• SortedVersions.Less now compares through an internal pointer-core instead of copying four ~392-byte structs per comparison; public API unchanged.
• CHANGELOG claim scoped: unpackable ordering unchanged, but equal local-labeled pairs are somewhat slower without the String fast path.
• NOTICE records the ranked fixtures' pypa/packaging provenance, matching the tags/testdata precedent.

Deferred with rationale: lazy cmpkey (dead work at Parse for packable versions — real, but it interacts with the zero-value guard ordering and deserves its own change and measurements); trimmedRelease's stale caches (pre-existing, String-only use); cmp.Compare dedup and fixture memory retention (test-only, below the bar).

End-to-end numbers re-verified after the refactor: app-set 14.1 ms, wide-versions 15.2/15.3 ms warm — unchanged from before the hardening pass.