fix(mcp): order prerelease identifiers by semver precedence

[luciferlive112116]

Summary

compareMcpSemver in src/services/mcp-compatibility.ts compared two prerelease tags by running a single
numeric-collation localeCompare over the whole prerelease string. Semver (§11.4) compares prerelease
tags identifier by identifier (dot-separated), which this got wrong in two ways:

1. Numeric vs alphanumeric precedence. A purely numeric identifier always has lower precedence
   than an alphanumeric one. Whole-string numeric collation instead compares leading digit runs
   numerically, so it mis-ranks pairs where the alphanumeric identifier starts with a smaller digit:

   compareMcpSemver("0.3.0-2", "0.3.0-1a")   // was 1, should be -1 ("2" is numeric, "1a" is not)

2. Large numeric identifiers. A Number()-based numeric compare loses precision past
   Number.MAX_SAFE_INTEGER, so distinct large identifiers collapse to equal:

   compareMcpSemver("0.3.0-9007199254740992", "0.3.0-9007199254740993")   // must be -1, not 0

Fix: a per-identifier comparePrerelease that applies semver precedence — numeric identifiers ranked
below alphanumeric; two numeric identifiers compared as decimal strings (with no leading zeros, a
longer digit string is the larger number and equal-length strings compare lexicographically), avoiding any
Number() precision loss; alphanumeric identifiers compared lexically; and a shorter identifier list
ranked lower when all preceding fields are equal. The pre-existing case-insensitive behavior
(RC.1 == rc.1) is preserved intentionally.

No linked issue: small, self-evident correctness fix to one deterministic semver helper, with no public
API, auth, schema, or deploy surface change — fits the repo's preferred (not required) linked-issue
policy.

Scope

• The PR title follows type(scope): short summary Conventional Commit format, for example fix(api): restore profile access checks.
• This PR is focused and does not mix unrelated backend, UI, MCP, docs, dependency, and deploy changes.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• I linked an issue, or this is small enough that the summary explains why an issue is not needed.

Validation

• git diff --check
• npm run actionlint
• npm run typecheck
• npm run test:coverage locally; codecov/patch requires ≥99% coverage of the lines AND branches you changed (aim for 100% on your diff so CI variance does not fail near the threshold). Global coverage is a non-blocking trend with a loose 90% backstop, not the gate.
• npm run test:workers
• npm run build:mcp
• npm run test:mcp-pack
• npm run ui:openapi:check
• npm run ui:lint
• npm run ui:typecheck
• npm run ui:build
• npm audit --audit-level=moderate
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries

If any required check was skipped, explain why:

• Ran locally: git diff --check (clean), npm run typecheck (clean), and a focused test:coverage
  over test/unit/mcp-compatibility.test.ts — 8 tests pass and the changed lines are at 100% branch
  coverage (the numeric decimal-string, numeric-vs-alpha both directions, alpha, and field-length
  branches are all exercised; the only uncovered line in the file, 38, is a pre-existing snapshot builder
  outside this diff), so codecov/patch is 100% on this diff.
• Not run locally: the UI, MCP-pack, workers, OpenAPI, actionlint, and audit jobs. This is a src/-only
  change to one deterministic helper touching no UI/API/OpenAPI/DB/workflow surface, so those jobs are
  no-ops for this diff; they run on CI (Linux).

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed.
• Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics.
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests.
• API/OpenAPI/MCP behavior is updated and tested where needed.
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks.
• Visible UI changes include a UI Evidence section below with JPG/JPEG or PNG screenshots arranged as organized, captioned, clickable thumbnails. SVG screenshots are not used as review evidence. Review-only screenshots or recordings are not committed to the repository.
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs.

Notes

• No UI, auth, CORS, API, or schema surface is touched — a pure deterministic semver-compare fix, so the
  auth/UI/OpenAPI boxes are N/A.
• Regression tests added in test/unit/mcp-compatibility.test.ts: compareMcpSemver("0.3.0-2","0.3.0-1a")
  is now -1, and two large numeric identifiers past MAX_SAFE_INTEGER order as -1/1 instead of
  collapsing to 0. All 16 existing prerelease-precedence assertions still hold under the per-identifier
  comparator.

[loopover-orb]

Warning

🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-04 10:16:01 UTC}

2 files · 1 AI reviewer · no blockers · readiness 80/100 · CI green · clean

⏸️ Suggested Action - Manual Review

Review summary
The change replaces whole-prerelease numeric collation with identifier-by-identifier prerelease comparison, which fixes the reachable semver precedence bugs described by the PR and keeps the existing case-insensitive behavior covered by tests. The numeric-vs-alphanumeric and large numeric identifier cases are exercised through the public compareMcpSemver path, so this is not a fabricated-test fix. I do not see a blocking correctness issue in the visible diff.

Nits — 4 non-blocking

• nit: src/services/mcp-compatibility.ts:83 says numeric identifiers are compared "with no leading zeros," but parseSemver still accepts prerelease identifiers like 0.3.0-01, so either tighten parsing or soften that comment to avoid implying validation that is not present.
• nit: src/services/mcp-compatibility.ts:86 describes the helper as semver §11.4, while the alphanumeric branch intentionally keeps the old case-insensitive ordering; call that out as a compatibility exception so future readers do not mistake it for strict semver.
• src/services/mcp-compatibility.ts:96: consider hoisting the numeric identifier regex to a module-level constant if this helper grows more comparison cases, mainly to keep the loop visually focused on precedence rules.
• test/unit/mcp-compatibility.test.ts:121: add one focused case where the numeric-vs-alphanumeric decision happens after an equal prefix, such as rc.2 vs rc.1a, to prove the new per-identifier path rather than only first-identifier behavior.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ No-issue rationale	PR body explains why no issue is linked.
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (no linked issue context).
Validation posture	❌ 5/25	Preflight is holding this PR: the review lane is unavailable, so it is not ready for automated review.
Contributor workload	✅ 10/10	Author activity: 79 registered-repo PR(s), 30 merged, 21 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	luciferlive112116; Gittensor profile; 79 PR(s), 21 issue(s).
Gate result	✅ Passing	No configured blocker found.

Review context

• Author: luciferlive112116
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository registration is not available in the local Gittensory cache.
• Public profile languages: not available
• Official Gittensor activity: 79 PR(s), 21 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Await review-lane availability.
• Refresh registry data or choose a registered active repo.
• Link the issue being solved, or explicitly explain why this is a no-issue PR.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.10%. Comparing base (3bf6de7) to head (cb10b21).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3049   +/-   ##
=======================================
  Coverage   96.10%   96.10%           
=======================================
  Files         261      261           
  Lines       28872    28889   +17     
  Branches    10510    10517    +7     
=======================================
+ Hits        27746    27763   +17     
  Misses        492      492           
  Partials      634      634           

Files with missing lines	Coverage Δ
src/services/mcp-compatibility.ts	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

Gittensory approves — the gate is satisfied and CI is green.