fix(compat): order prereleases below stable in version guard

SemVer §11: a prerelease precedes its stable release (0.1.0-rc.1 < 0.1.0).
The old _parse dropped the suffix, so a release-candidate backend compared
equal to a stable floor and slipped past the guard even though it may lack
the final contract. Parse the prerelease and compare via a SemVer precedence
key; a prerelease of a higher version (0.2.0-rc.1) still clears a 0.1.0 floor.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: NiteshDhanpal

src/agentex/lib/core/compat/version_guard.py

@@ -34,16 +34,43 @@
 
 SKIP_ENV = "AGENTEX_SKIP_VERSION_CHECK"
 
-_VERSION_RE = re.compile(r"^\s*v?(\d+)\.(\d+)\.(\d+)")
+# major.minor.patch, optional `-prerelease`; build metadata (after `+`) is ignored.
+_VERSION_RE = re.compile(r"^\s*v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?")
 
 
 class IncompatibleBackendError(RuntimeError):
     """Raised when the agentex backend is older than this SDK's minimum supported contract."""
 
 
-def _parse(version: str | None) -> tuple[int, int, int] | None:
+def _parse(version: str | None) -> tuple[int, int, int, str | None] | None:
+    """Parse ``major.minor.patch[-prerelease]`` → ``(major, minor, patch, prerelease)``.
+
+    ``prerelease`` is the raw dot-separated identifier string (e.g. ``"rc.1"``), or None for
+    a stable release. Build metadata (after ``+``) is ignored. Returns None if unparseable.
+    """
     m = _VERSION_RE.match(version or "")
-    return (int(m.group(1)), int(m.group(2)), int(m.group(3))) if m else None
+    if not m:
+        return None
+    return (int(m.group(1)), int(m.group(2)), int(m.group(3)), m.group(4) or None)
+
+
+def _precedence_key(parsed: tuple[int, int, int, str | None]):
+    """SemVer §11 precedence key (directly comparable with ``<``).
+
+    A stable release outranks any prerelease of the same triplet (``0.1.0-rc.1 < 0.1.0``);
+    among prereleases, numeric identifiers rank below alphanumeric and compare field-by-field,
+    with a longer identifier list outranking a shorter prefix-equal one.
+    """
+    major, minor, patch, prerelease = parsed
+    if prerelease is None:
+        return (major, minor, patch, (1,))  # stable sorts above every prerelease
+    identifiers = []
+    for ident in prerelease.split("."):
+        if ident.isdigit():
+            identifiers.append((0, int(ident), ""))  # numeric: lowest class, numeric order
+        else:
+            identifiers.append((1, 0, ident))  # alphanumeric: higher class, lexical order
+    return (major, minor, patch, (0, identifiers))
 
 
 def _truthy(name: str) -> bool:
@@ -108,7 +135,7 @@ async def assert_backend_compatible(
         )
         return
 
-    if backend < minimum:
+    if _precedence_key(backend) < _precedence_key(minimum):
         raise IncompatibleBackendError(
             f"agentex-sdk {sdk_version} requires agentex backend >= {min_version}, "
             f"but {base_url} reports {backend_version}. "

tests/test_version_guard.py

@@ -14,13 +14,22 @@ def _run(coro):
 
 
 def test_parse_versions():
-    assert vg._parse("0.2.1") == (0, 2, 1)
-    assert vg._parse("v1.4.0") == (1, 4, 0)
-    assert vg._parse("0.2.1-rc.1+build5") == (0, 2, 1)
+    assert vg._parse("0.2.1") == (0, 2, 1, None)
+    assert vg._parse("v1.4.0") == (1, 4, 0, None)
+    assert vg._parse("0.2.1-rc.1+build5") == (0, 2, 1, "rc.1")  # build metadata ignored
     assert vg._parse("garbage") is None
     assert vg._parse(None) is None
 
 
+def test_prerelease_precedence():
+    k = lambda v: vg._precedence_key(vg._parse(v))  # noqa: E731
+    assert k("0.1.0-rc.1") < k("0.1.0")       # prerelease precedes its stable release (SemVer §11)
+    assert k("0.1.0-rc.1") < k("0.1.0-rc.2")  # numeric prerelease identifiers compare numerically
+    assert k("0.1.0-alpha") < k("0.1.0-rc")   # numeric/alpha ordering by identifier
+    assert k("0.1.0") < k("0.1.1-rc.1")       # patch bump outranks prior stable
+    assert k("0.2.0-rc.1") > k("0.1.0")       # prerelease of a higher version still clears the floor
+
+
 def test_compatible_backend_passes(monkeypatch):
     async def fake(url, **kw):
         return "0.2.0"
@@ -41,6 +50,15 @@ async def fake(url, **kw):
     assert "0.13.0" in msg and "0.1.0" in msg and "0.0.9" in msg  # actionable message
 
 
+def test_prerelease_backend_below_stable_floor_raises(monkeypatch):
+    async def fake(url, **kw):
+        return "0.1.0-rc.1"  # release candidate: precedes the stable 0.1.0 contract
+
+    monkeypatch.setattr(vg, "fetch_backend_version", fake)
+    with pytest.raises(vg.IncompatibleBackendError):
+        _run(vg.assert_backend_compatible("http://backend", min_version="0.1.0", sdk_version="0.13.0"))
+
+
 def test_skip_env_bypasses(monkeypatch):
     async def fake(url, **kw):
         raise AssertionError("must not fetch when skip env is set")