worker: accept compatible-MINOR worker_protocol versions instead of strict-equal

Previously the SDK rejected any worker_protocol.version that did not
exactly match the SDK's own constant (1.1). When the server bumped to
worker_protocol 1.2 (additive — new optional fields, new non-terminal
command types per workflow:v2's WorkerProtocolVersion contract), every
sdk-python worker started failing registration with "Server compatibility
error: unsupported worker_protocol.version '1.2'; sdk-python requires '1.1'".

Replace the strict equality with a major-equal + server-minor>=sdk-minor
check. The SDK can talk to a newer server happily — it just won't exercise
the new optional shapes. Major bumps still hard-reject as before.

Add a positive test that a higher compatible MINOR is accepted, and rename
the existing major-mismatch test for clarity.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: durable-workflow-ops

src/durable_workflow/worker.py

@@ -164,6 +164,38 @@ def _manifest_version(manifest: Any) -> str:
     return "missing"
 
 
+def _parse_protocol_version(value: str) -> tuple[int, int] | None:
+    """Parse "MAJOR.MINOR" into a tuple. Returns None for malformed inputs."""
+    if not isinstance(value, str):
+        return None
+    parts = value.split(".")
+    if len(parts) != 2:
+        return None
+    try:
+        return int(parts[0]), int(parts[1])
+    except ValueError:
+        return None
+
+
+def _server_protocol_compatible(server_version: str, sdk_version: str) -> bool:
+    """A server's worker_protocol.version is compatible with this SDK when
+    they share a major and the server's minor is at least the SDK's minor.
+
+    Per workflow:v2's WorkerProtocolVersion contract, MINOR bumps are
+    additive (new optional fields, new non-terminal command types) and
+    therefore safe for older SDKs to talk to newer servers — they just
+    will not exercise the new optional shapes. MAJOR bumps are breaking
+    and must always be rejected.
+    """
+    server = _parse_protocol_version(server_version)
+    sdk = _parse_protocol_version(sdk_version)
+    if server is None or sdk is None:
+        return server_version == sdk_version
+    if server[0] != sdk[0]:
+        return False
+    return server[1] >= sdk[1]
+
+
 def _validate_server_compatibility(info: dict[str, Any]) -> None:
     control_plane = info.get("control_plane")
     if not isinstance(control_plane, dict):
@@ -206,10 +238,11 @@ def _validate_server_compatibility(info: dict[str, Any]) -> None:
         )
 
     worker_protocol_version = _manifest_version(worker_protocol)
-    if worker_protocol_version != PROTOCOL_VERSION:
+    if not _server_protocol_compatible(worker_protocol_version, PROTOCOL_VERSION):
         raise RuntimeError(
-            "Server compatibility error: unsupported worker_protocol.version "
-            f"{worker_protocol_version!r}; sdk-python requires {PROTOCOL_VERSION!r}."
+            "Server compatibility error: incompatible worker_protocol.version "
+            f"{worker_protocol_version!r}; sdk-python requires major-equal and "
+            f"minor>={PROTOCOL_VERSION!r}."
         )
 
     auth_composition = info.get("auth_composition_contract")

tests/test_worker.py

@@ -332,15 +332,30 @@ async def test_register_rejects_missing_request_contract(self, mock_client: Asyn
         mock_client.register_worker.assert_not_called()
 
     @pytest.mark.asyncio
-    async def test_register_rejects_unsupported_worker_protocol_version(self, mock_client: AsyncMock) -> None:
+    async def test_register_rejects_worker_protocol_major_mismatch(self, mock_client: AsyncMock) -> None:
         mock_client.get_cluster_info = AsyncMock(
             return_value=compatible_cluster_info(worker_protocol={"version": "2.0"})
         )
         worker = Worker(mock_client, task_queue="q1", workflows=[TestWorkflow], activities=[])
-        with pytest.raises(RuntimeError, match="unsupported worker_protocol.version"):
+        with pytest.raises(RuntimeError, match="incompatible worker_protocol.version"):
             await worker._register()
         mock_client.register_worker.assert_not_called()
 
+    @pytest.mark.asyncio
+    async def test_register_accepts_higher_compatible_minor_protocol(self, mock_client: AsyncMock) -> None:
+        # Server is one minor ahead of the SDK. MINOR bumps in workflow:v2's
+        # WorkerProtocolVersion are documented as additive (new optional
+        # fields, new non-terminal command types) so the SDK must talk to a
+        # newer server happily — the test pins that contract.
+        major, minor = (int(p) for p in PROTOCOL_VERSION.split("."))
+        future_version = f"{major}.{minor + 1}"
+        mock_client.get_cluster_info = AsyncMock(
+            return_value=compatible_cluster_info(worker_protocol={"version": future_version})
+        )
+        worker = Worker(mock_client, task_queue="q1", workflows=[TestWorkflow], activities=[])
+        await worker._register()
+        mock_client.register_worker.assert_called_once()
+
     @pytest.mark.asyncio
     async def test_register_rejects_worker_protocol_below_payload_codec_floor(
         self, mock_client: AsyncMock
@@ -349,7 +364,7 @@ async def test_register_rejects_worker_protocol_below_payload_codec_floor(
             return_value=compatible_cluster_info(worker_protocol={"version": "1.0"})
         )
         worker = Worker(mock_client, task_queue="q1", workflows=[TestWorkflow], activities=[])
-        with pytest.raises(RuntimeError, match="requires '1.1'"):
+        with pytest.raises(RuntimeError, match=r"minor>='1\.1'"):
             await worker._register()
         mock_client.register_worker.assert_not_called()