Conformance finding: worker-versioning PHP/Python build-id pinning remains unproved (#192)

Author: durable-workflow-ops

src/durable_workflow/client.py

@@ -2138,6 +2138,8 @@ async def start_workflow(
         priority: int | None = None,
         fairness_key: str | None = None,
         fairness_weight: int | None = None,
+        build_id: str | None = None,
+        compatibility: str | None = None,
     ) -> WorkflowHandle:
         """Start a new workflow instance and return a handle bound to it.
 
@@ -2166,6 +2168,11 @@ async def start_workflow(
         (``1..1000``, default ``1``) lets a class take a proportionally
         larger share of dispatch slots versus other classes on the same
         queue.
+
+        ``build_id`` pins the new run to a specific worker build when
+        multiple worker versions share a task queue. ``compatibility`` is an
+        alias accepted by the server for SDK-neutral callers; when both are
+        provided, the server gives ``build_id`` precedence.
         """
         body: dict[str, Any] = {
             "workflow_id": workflow_id,
@@ -2198,6 +2205,10 @@ async def start_workflow(
             body["fairness_key"] = fairness_key
         if fairness_weight is not None:
             body["fairness_weight"] = fairness_weight
+        if build_id is not None:
+            body["build_id"] = build_id
+        if compatibility is not None:
+            body["compatibility"] = compatibility
         data = await self._request("POST", "/workflows", json=body, context=workflow_id)
         return WorkflowHandle(
             self,

src/durable_workflow/sync.py

@@ -273,6 +273,8 @@ def start_workflow(
         priority: int | None = None,
         fairness_key: str | None = None,
         fairness_weight: int | None = None,
+        build_id: str | None = None,
+        compatibility: str | None = None,
     ) -> SyncWorkflowHandle:
         handle = _run(
             self._async.start_workflow(
@@ -288,6 +290,8 @@ def start_workflow(
                 priority=priority,
                 fairness_key=fairness_key,
                 fairness_weight=fairness_weight,
+                build_id=build_id,
+                compatibility=compatibility,
             )
         )
         return SyncWorkflowHandle(handle)

tests/test_client.py

@@ -263,6 +263,26 @@ async def test_priority_and_fairness_are_forwarded_on_start(self, client: Client
         assert body["fairness_key"] == "tenant-a"
         assert body["fairness_weight"] == 3
 
+    @pytest.mark.asyncio
+    async def test_build_id_and_compatibility_are_forwarded_on_start(self, client: Client) -> None:
+        resp = _mock_response(201, {
+            "workflow_id": "wf-build",
+            "run_id": "run-build",
+            "workflow_type": "greeter",
+        })
+        with patch.object(client._http, "request", new_callable=AsyncMock, return_value=resp) as mock:
+            await client.start_workflow(
+                workflow_type="greeter",
+                task_queue="shared",
+                workflow_id="wf-build",
+                build_id="php-v1",
+                compatibility="ignored-when-build-id-present",
+            )
+
+        body = mock.call_args.kwargs.get("json") or mock.call_args[1].get("json")
+        assert body["build_id"] == "php-v1"
+        assert body["compatibility"] == "ignored-when-build-id-present"
+
     @pytest.mark.asyncio
     async def test_priority_and_fairness_are_omitted_when_unset(self, client: Client) -> None:
         resp = _mock_response(201, {

tests/test_sync.py

@@ -98,6 +98,29 @@ def test_priority_and_fairness_are_forwarded_on_start(self) -> None:
         assert body["fairness_key"] == "tenant-a"
         assert body["fairness_weight"] == 3
 
+    def test_build_id_is_forwarded_on_start(self) -> None:
+        client = Client("http://localhost:8080")
+        resp = _mock_response(
+            201,
+            {
+                "workflow_id": "wf-build",
+                "run_id": "run-build",
+                "workflow_type": "greeter",
+            },
+        )
+        with patch.object(
+            client._async._http, "request", new_callable=AsyncMock, return_value=resp
+        ) as mock:
+            client.start_workflow(
+                workflow_type="greeter",
+                task_queue="shared",
+                workflow_id="wf-build",
+                build_id="python-v1",
+            )
+
+        body = mock.call_args.kwargs.get("json") or mock.call_args[1].get("json")
+        assert body["build_id"] == "python-v1"
+
     def test_priority_and_fairness_are_omitted_when_unset(self) -> None:
         client = Client("http://localhost:8080")
         resp = _mock_response(