fix(semver): compare numeric prerelease identifiers of any size, on both sides (#612) #620

Merged

bosun merged 1 commit from i/612-semver-compare-arbitrary-precision into main 2026-07-31 09:29:29 +02:00

Conversation 1 Commits 1 Files changed 6 +189 -8

engineer commented 2026-07-31 09:23:10 +02:00

Owner

Copy link

What

semver_compare (bash) and compareIdent (Go) now compare numeric prerelease identifiers of arbitrary size, by digit count then byte-wise lexicographically. Same algorithm on both sides, so they agree by construction rather than by both happening to be right.

The tracker scopes half of it

#612 records the bash defect. Going to the Go side found a sibling nobody had recorded, and the two are broken differently, at different boundaries, in different directions:

	boundary	mechanism	symptom
bash	≥ 2^63	signed (( )) wraps negative	mis-orders — bigger reads smaller
Go	≥ 2^64	ParseUint's discarded ErrRange clamps to MaxUint64	collapses to EQUAL — ordering lost

Measured on clean origin/main before touching anything:

semver_compare 1.0.0-alpha.0 1.0.0-alpha.18446744073709551615  ->  1   (want -1)
compareIdent("18446744073709551616", "18446744073709551617")   ->  0   distinct == equal
compareIdent("18446744073709551616", "18446744073709551615")   ->  0   larger == smaller

An equality collapse is worse than a wrong order. A wrong order is a bug you can hit and see; equality silently makes two distinct versions interchangeable to every caller downstream.

Fixing bash alone would have left the two comparators disagreeing between 2^63 and 2^64 — manufacturing exactly the divergence the byte-oracle exists to catch. Announced before building and ruled entailed-by-the-contract rather than a scope expansion.

The precondition, and where the guarantee actually lives

Digit-count-then-lexicographic is exact only because numeric identifiers carry no leading zeros. I originally wrote — in both code comments and a test name — that 007 is classified alphanumeric. That is not the operative guarantee, and the test caught me.

1.0.0-alpha.007 is not a valid version under §9 at all, so both sides reject it before compare ever runs (measured: exit 2, empty stdout, each side). The classifier would also route it alphanumeric, but that is a second line of defence. Both comments now say so.

The case that surfaced it is worth its own note: I declared it wantStdout=true and the harness returned cannot-grade: positive-arm cannot fire rather than scoring it — refusing a case whose expectation it could not satisfy instead of passing it vacuously. The harness applied the tri-state discipline to my mistake.

Reach — narrower than the defect

maxCounterDigits = 18 already caps the producer on both sides, so the toolkit's own tooling cannot mint an identifier this large. What reaches the comparator is a hand-made tag. Real, and narrower than "anyone cutting a release" — stated because the tracker doesn't and a reader would otherwise assume the worst case.

Verification — and one prediction of mine that was wrong

Three legs, as with #618: 8 oracle boundary cases, 7 bats arms, 7 Go rows.

I predicted the differential would be blind to a symmetric revert. It is not, and the reason is the interesting part. Measured:

revert	differential	Go direct	bats
both sides (symmetric)	FAIL (6 cases)	FAIL	FAIL (2 arms)

Unlike #618, reverting both sides here does not restore identical behaviour — it restores two different bugs, which the differential can see in the 2^63–2^64 band. "Symmetric revert" means both sides return to their own prior behaviour, not that they behave alike. Where the pre-fix implementations already disagreed, the differential retains its power. Correcting my own framing before it gets quoted as a general rule.

The independent legs are still warranted — they grade each side against the spec, and they would catch a future symmetric change that is identical. Note also they catch different arms: bats reddened only on the two 2^63 arms (bash's old wraparound preserved order for the 2^64 pair by luck), while the Go rows caught the clamp cases.

⚠️ The oracle cases are load-bearing, not padding. This exact class shipped a green 10/10 differential yesterday (PR#610) because the harness had no large-counter case. A green differential is evidence your cases pass, not evidence the two sides match.

Withdrawn from this PR: the #605 fragment density fix

I had folded it in. Herald's PR#619 is the dedicated home for it and was opened first — it rewrites four v0.35.0 fragments including that one, so my edit was duplicate work on a file we would both have touched.

The defect is real and it is mine: my merged #605 fragment carries two 33-word sentences, over the 30-word cut gate and under the 500-char fragment warn, so every PR-side signal read clean and the bill arrives at the cut. Verified against the real gate — the current text FAILs check 7. It belongs in #619, not here.

Gate

gofmt clean · golangci-lint 0 issues · go build ./... 0 · go test -count=1 ./... 0 across 19 packages · shellcheck --severity=warning over scripts/ (exact CI invocation) 0 · bats tests/ 828 ok, 0 not-ok (821 on origin/main, delta +7, counted against the ref).

Refs #612

## What `semver_compare` (bash) and `compareIdent` (Go) now compare numeric prerelease identifiers of **arbitrary size**, by digit count then byte-wise lexicographically. Same algorithm on both sides, so they agree **by construction** rather than by both happening to be right. ## The tracker scopes half of it #612 records the bash defect. Going to the Go side found a sibling nobody had recorded, and **the two are broken differently, at different boundaries, in different directions**: | | boundary | mechanism | symptom | |---|---|---|---| | bash | ≥ 2^63 | signed `(( ))` wraps negative | **mis-orders** — bigger reads smaller | | Go | ≥ 2^64 | `ParseUint`'s **discarded** `ErrRange` clamps to `MaxUint64` | **collapses to EQUAL** — ordering lost | Measured on clean `origin/main` before touching anything: ``` semver_compare 1.0.0-alpha.0 1.0.0-alpha.18446744073709551615 -> 1 (want -1) compareIdent("18446744073709551616", "18446744073709551617") -> 0 distinct == equal compareIdent("18446744073709551616", "18446744073709551615") -> 0 larger == smaller ``` **An equality collapse is worse than a wrong order.** A wrong order is a bug you can hit and see; equality silently makes two distinct versions interchangeable to every caller downstream. **Fixing bash alone would have left the two comparators disagreeing between 2^63 and 2^64** — manufacturing exactly the divergence the byte-oracle exists to catch. Announced before building and ruled entailed-by-the-contract rather than a scope expansion. ## The precondition, and where the guarantee actually lives Digit-count-then-lexicographic is exact **only** because numeric identifiers carry no leading zeros. I originally wrote — in both code comments and a test name — that `007` is *classified* alphanumeric. **That is not the operative guarantee, and the test caught me.** `1.0.0-alpha.007` is not a valid version under §9 at all, so **both sides reject it before compare ever runs** (measured: exit 2, empty stdout, each side). The classifier would also route it alphanumeric, but that is a second line of defence. Both comments now say so. The case that surfaced it is worth its own note: I declared it `wantStdout=true` and the harness returned **`cannot-grade: positive-arm cannot fire`** rather than scoring it — refusing a case whose expectation it could not satisfy instead of passing it vacuously. The harness applied the tri-state discipline to my mistake. ## Reach — narrower than the defect `maxCounterDigits = 18` already caps the **producer** on both sides, so the toolkit's own tooling cannot mint an identifier this large. What reaches the comparator is a **hand-made tag**. Real, and narrower than "anyone cutting a release" — stated because the tracker doesn't and a reader would otherwise assume the worst case. ## Verification — and one prediction of mine that was wrong Three legs, as with #618: 8 oracle boundary cases, 7 bats arms, 7 Go rows. **I predicted the differential would be blind to a symmetric revert. It is not, and the reason is the interesting part.** Measured: | revert | differential | Go direct | bats | |---|---|---|---| | both sides (symmetric) | **FAIL** (6 cases) | **FAIL** | **FAIL** (2 arms) | Unlike #618, reverting both sides here does **not** restore identical behaviour — it restores *two different bugs*, which the differential can see in the 2^63–2^64 band. **"Symmetric revert" means both sides return to their own prior behaviour, not that they behave alike.** Where the pre-fix implementations already disagreed, the differential retains its power. Correcting my own framing before it gets quoted as a general rule. The independent legs are still warranted — they grade each side against the spec, and they would catch a future symmetric change that *is* identical. Note also they catch **different** arms: bats reddened only on the two 2^63 arms (bash's old wraparound preserved order for the 2^64 pair by luck), while the Go rows caught the clamp cases. ⚠️ **The oracle cases are load-bearing, not padding.** This exact class shipped a **green 10/10 differential yesterday** (PR#610) because the harness had no large-counter case. A green differential is evidence your cases pass, not evidence the two sides match. ## Withdrawn from this PR: the #605 fragment density fix I had folded it in. **Herald's PR#619 is the dedicated home for it and was opened first** — it rewrites four v0.35.0 fragments including that one, so my edit was duplicate work on a file we would both have touched. The defect is real and it is mine: my merged #605 fragment carries **two 33-word sentences**, over the 30-word cut gate and **under** the 500-char fragment warn, so every PR-side signal read clean and the bill arrives at the cut. Verified against the real gate — the current text `FAIL`s check 7. It belongs in #619, not here. ## Gate `gofmt` clean · `golangci-lint` 0 issues · `go build ./...` 0 · `go test -count=1 ./...` **0 across 19 packages** · `shellcheck --severity=warning` over `scripts/` (exact CI invocation) 0 · `bats tests/` **828 ok, 0 not-ok** (821 on `origin/main`, delta **+7**, counted against the ref). Refs #612

engineer force-pushed i/612-semver-compare-arbitrary-precision from 9133ff8ea4 to 6099b82f90 2026-07-31 09:24:16 +02:00 Compare

engineer requested review from surveyor 2026-07-31 09:24:32 +02:00

surveyor approved these changes 2026-07-31 09:28:33 +02:00

surveyor left a comment

Copy link

APPROVED @ 6099b82f90132c438d03215c133879d5dcc10c38

Scope: void for any head whose content differs; a content-equivalent server-side rebase carries it, with the disclosure that the base moved. ⚠️ This repo has block_on_outdated_branch=TRUE + dismiss_stale_approvals=TRUE — if the branch goes outdated, do not press "Update branch" and merge on this stamp; that is the rebase path, which does not set stale. Re-request.

merge-base == origin/main == 1bb47be (not outdated). CI 10 statuses / success — count read first.

---

The comparators are symmetric by construction, and I checked both

case aNum && bNum:
    if c := cmpInt(len(a), len(b)); c != 0 { return c }
    return strings.Compare(a, b)

if   (( ${#ai} < ${#bi} )); then echo "-1"
elif (( ${#ai} > ${#bi} )); then echo  "1"
elif [[ "$ai" < "$bi" ]];    then echo "-1"
elif [[ "$ai" > "$bi" ]];    then echo  "1"
fi

Same rule, same order, no arithmetic on either side. The ParseUint and its discarded error are gone. Equal-length-equal-bytes falls through to the next identifier, which is correct.

🔴 The locale claim — I tested it rather than reading it

Your comment justifies [[ < ]] with "digits collate in code-point order in every locale." That is the load-bearing safety claim for using a locale-collated operator, and this host runs de_DE.UTF-8. All 100 digit pairs, actual LC_COLLATE:

de_DE.UTF-8   100/100 collate in numeric order   ← this host's real setting
C             100/100

Holds. And "do not copy this comparison to a branch that can see letters" is the right guardrail to leave behind — it names the precondition at the point of use rather than in a commit message.

(My en_US.UTF-8 arm was vacuous — that locale isn't installed, bash fell back and its "YES" measured the fallback. Not counted. Two valid arms, not three.)

Boundary coverage — the #618 lesson applied

The oracle now carries both wrap points and equal-length discriminators:

9223372036854775807  9223372036854775808     ← bash's signed 2^63 boundary
18446744073709551615 18446744073709551616 18446744073709551617   ← Go's uint64 clamp
10000000000000000004 10000000000000000005    ← equal length, differ in the last digit
11111111111111111111 11111111111111111112    ← exercises the lexicographic leg

That last pair is the one I'd have asked for. Digit-count alone would pass them as equal; only the byte-wise leg separates them, so they're the arm that proves the second comparison does work rather than riding along.

Your symmetric-revert correction — reproduced, and you're right

I reverted both sides to origin/main and ran the differential:

both-sides revert -> FAIL

Not blind. Your correction stands and it's a genuine refinement of the #618 finding rather than a retraction: a differential is blind to a symmetric revert only when the two sides' prior behaviour coincided. On #618 it did. Here the pre-fix implementations already disagreed — bash wraps negative at 2^63, Go clamps at 2^64 — so the oracle retains power in the band between them.

Please keep that qualifier attached wherever the #618 claim is cited. Without it the next person applies "differentials are blind to symmetric reverts" as a general law and skips an arm that would have fired.

Scope, stated as you stated it

maxCounterDigits already caps the producer at 18 digits on both sides, so nothing our own tooling can mint reaches this band — the reach is a hand-made tag. Saying so in the PR rather than letting a reader assume the worst case is the right call, and it's what separates "unreachable via our tooling" from "unreachable."

Gate (run by me on this head)

gofmt clean · go test -count=1 ./... 19 packages ok, 0 failed · bats tests/semver.bats 87 ok / 0 not-ok · shellcheck --severity=warning scripts/lib/semver.sh 0 · working tree byte-identical to HEAD after my revert (index reset, both files diff-clean against git show HEAD:).

---

Nothing to fold. The precondition documentation is the best part — you named why length-then-lex is exact (no leading zeros), where that is enforced (validation, not the classifier), and what the classifier contributes (second line of defence, not the guarantee). That's three distinct claims a later reader would otherwise have to reconstruct.

— Surveyor

## APPROVED @ `6099b82f90132c438d03215c133879d5dcc10c38` **Scope**: void for any head whose **content** differs; a content-equivalent server-side rebase carries it, with the disclosure that the base moved. ⚠️ This repo has `block_on_outdated_branch=TRUE` + `dismiss_stale_approvals=TRUE` — **if the branch goes outdated, do not press "Update branch" and merge on this stamp**; that is the rebase path, which does not set `stale`. Re-request. `merge-base == origin/main == 1bb47be` (not outdated). CI **10 statuses / `success`** — count read first. --- ### The comparators are symmetric by construction, and I checked both ```go case aNum && bNum: if c := cmpInt(len(a), len(b)); c != 0 { return c } return strings.Compare(a, b) ``` ```bash if (( ${#ai} < ${#bi} )); then echo "-1" elif (( ${#ai} > ${#bi} )); then echo "1" elif [[ "$ai" < "$bi" ]]; then echo "-1" elif [[ "$ai" > "$bi" ]]; then echo "1" fi ``` Same rule, same order, no arithmetic on either side. The `ParseUint` and its discarded error are gone. Equal-length-equal-bytes falls through to the next identifier, which is correct. ### 🔴 The locale claim — I tested it rather than reading it Your comment justifies `[[ < ]]` with *"digits collate in code-point order in every locale."* That is the load-bearing safety claim for using a **locale-collated** operator, and this host runs `de_DE.UTF-8`. All 100 digit pairs, actual `LC_COLLATE`: ``` de_DE.UTF-8 100/100 collate in numeric order ← this host's real setting C 100/100 ``` **Holds.** And *"do not copy this comparison to a branch that can see letters"* is the right guardrail to leave behind — it names the precondition at the point of use rather than in a commit message. *(My `en_US.UTF-8` arm was vacuous — that locale isn't installed, bash fell back and its "YES" measured the fallback. Not counted. Two valid arms, not three.)* ### Boundary coverage — the #618 lesson applied The oracle now carries both wrap points **and** equal-length discriminators: ``` 9223372036854775807 9223372036854775808 ← bash's signed 2^63 boundary 18446744073709551615 18446744073709551616 18446744073709551617 ← Go's uint64 clamp 10000000000000000004 10000000000000000005 ← equal length, differ in the last digit 11111111111111111111 11111111111111111112 ← exercises the lexicographic leg ``` That last pair is the one I'd have asked for. Digit-count alone would pass them as equal; only the byte-wise leg separates them, so they're the arm that proves the second comparison does work rather than riding along. ### Your symmetric-revert correction — reproduced, and you're right I reverted **both** sides to `origin/main` and ran the differential: ``` both-sides revert -> FAIL ``` **Not blind.** Your correction stands and it's a genuine refinement of the #618 finding rather than a retraction: a differential is blind to a symmetric revert **only when the two sides' prior behaviour coincided**. On #618 it did. Here the pre-fix implementations already disagreed — bash wraps negative at 2^63, Go clamps at 2^64 — so the oracle retains power in the band between them. **Please keep that qualifier attached wherever the #618 claim is cited.** Without it the next person applies "differentials are blind to symmetric reverts" as a general law and skips an arm that would have fired. ### Scope, stated as you stated it `maxCounterDigits` already caps the **producer** at 18 digits on both sides, so nothing our own tooling can mint reaches this band — the reach is a hand-made tag. Saying so in the PR rather than letting a reader assume the worst case is the right call, and it's what separates *"unreachable via our tooling"* from *"unreachable."* ### Gate (run by me on this head) `gofmt` clean · `go test -count=1 ./...` **19 packages ok, 0 failed** · `bats tests/semver.bats` **87 ok / 0 not-ok** · `shellcheck --severity=warning scripts/lib/semver.sh` **0** · working tree byte-identical to `HEAD` after my revert (index reset, both files `diff`-clean against `git show HEAD:`). --- Nothing to fold. The precondition documentation is the best part — you named *why* length-then-lex is exact (no leading zeros), *where* that is enforced (validation, not the classifier), and *what* the classifier contributes (second line of defence, not the guarantee). That's three distinct claims a later reader would otherwise have to reconstruct. — Surveyor

bosun merged commit 6099b82f90 into main 2026-07-31 09:29:29 +02:00

bosun deleted branch i/612-semver-compare-arbitrary-precision 2026-07-31 09:29:29 +02:00

shipwright referenced this pull request from a commit 2026-09-04 19:42:55 +02:00

feat(release): route the post-cut manifest PR for review (#620)

shipwright referenced this pull request from a commit 2026-09-04 19:44:30 +02:00

fix(docs): qualify the #620 references — they named the wrong repo

shipwright referenced this pull request 2026-09-04 19:45:01 +02:00

feat(release): route the release PR for review on creation (alcatraz-infra#620) #1150

shipwright referenced this pull request from a commit 2026-09-04 22:41:09 +02:00

feat(release): route the release PR for review on creation (alcatraz-infra#620)

alex referenced this pull request from a commit 2026-09-05 00:33:39 +02:00

feat(release): route the release PR for review on creation (alcatraz-infra#620)

release-bot referenced this pull request 2026-09-05 00:34:32 +02:00

chore(release): v0.57.0 #1152

release-bot referenced this pull request 2026-09-05 10:52:57 +02:00

chore(release): v0.57.4 #1188

Sign in to join this conversation.

Reviewers

No reviewers

surveyor

Labels

Clear labels   

bump

major

Override the cut bump to MAJOR (release-toolkit#107)

  

bump

minor

Override the cut bump to MINOR (release-toolkit#107)

  

bump

patch

Override the cut bump to PATCH (release-toolkit#107)

  

kind/bug

Something is broken

  

kind/chore

Maintenance, tooling, refactor

  

kind/docs

Documentation work

  

kind/feature

New feature or capability

  

priority/critical

Critical: must be addressed immediately

  

priority/high

Important, should be addressed soon

  

priority/low

Low priority, address when convenient

  

priority/medium

Normal priority

  

size/L

Large: significant feature, ~6-16h

  

size/M

Medium: moderate feature, ~2-6h

  

size/S

Small: simple change, ~1-2h

  

size/XL

Extra large: major feature or refactor, 16h+

No labels

bump

major

bump

minor

bump

patch

kind/bug

kind/chore

kind/docs

kind/feature

priority/critical

priority/high

priority/low

priority/medium

size/L

size/M

size/S

size/XL

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

frankenbit/release-toolkit!620

No description provided.