Add versioned PollerGroupsInfo, deprecate poller_group_infos (#819)

**What changed?**
Introduce a `PollerGroupsInfo` message carrying a monotonically
increasing `version` alongside the poller groups, so the SDK can ignore
stale snapshots that arrive out of order (e.g. after polls are cancelled
during cell migration).

Deprecate the repeated `poller_group_infos` fields in favor of the new
`poller_groups_info` field on `DescribeNamespaceResponse` and the Poll
Workflow/Activity/Nexus TaskQueue responses.

**Why?**
The server sends poller-group assignment info to the SDK via poll
responses. During cell migration, the server cancels in-flight polls and
returns updated poller-group info, but responses can arrive out of order
— a stale snapshot can land after a fresh one and overwrite it.
Attaching a monotonically increasing `version` lets the SDK ignore any
snapshot that isn't newer than the one it has already applied,
preventing stale overwrites.

**Breaking changes**
None. New fields use fresh field numbers (no reuse), and the old
`poller_group_infos` fields are only marked `[deprecated = true]` —
still fully wire-compatible. `buf breaking` against `main` passes clean.
Consumers referencing the deprecated fields will see deprecation
warnings but will not break.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: cbsandeep10

openapi/openapiv2.json

@@ -15242,7 +15242,11 @@
             "type": "object",
             "$ref": "#/definitions/v1PollerGroupInfo"
           },
-          "description": "The initial info that client should use for poller group assignment. This information is\nupdated through poll response. Client is supposed to use the info received in the latest\npoll response."
+          "description": "Deprecated. Use `poller_groups_info` instead, which carries a version so the client can\nignore stale updates.\nThe initial info that client should use for poller group assignment. This information is\nupdated through poll response. Client is supposed to use the info received in the latest\npoll response."
+        },
+        "pollerGroupsInfo": {
+          "$ref": "#/definitions/v1PollerGroupsInfo",
+          "description": "The initial, versioned info that client should use for poller group assignment. This\ninformation is updated through poll responses. Client is supposed to use the info with the\nhighest version it has received."
         }
       }
     },
@@ -17943,7 +17947,11 @@
             "type": "object",
             "$ref": "#/definitions/v1PollerGroupInfo"
           },
-          "description": "The weighted list of poller groups IDs that client should use for future polls to this task\nqueue. Client is expected to:\n  1. Maintain minimum number of pollers no less than the number of groups.\n  2. Try to assign the next poll to a group without any pending polls,\n  3. If every group has some pending polls, assign the next poll to a group randomly\n    according to the weights."
+          "description": "Deprecated. Use `poller_groups_info` instead, which carries a version so the client can\nignore stale updates.\nThe weighted list of poller groups IDs that client should use for future polls to this task\nqueue. Client is expected to:\n  1. Maintain minimum number of pollers no less than the number of groups.\n  2. Try to assign the next poll to a group without any pending polls,\n  3. If every group has some pending polls, assign the next poll to a group randomly\n    according to the weights."
+        },
+        "pollerGroupsInfo": {
+          "$ref": "#/definitions/v1PollerGroupsInfo",
+          "description": "The weighted, versioned list of poller groups IDs that client should use for future polls to\nthis task queue. Client should ignore this if it has already applied a snapshot with a\nversion greater than or equal to `poller_groups_info.version`. Client is expected to:\n  1. Maintain minimum number of pollers no less than the number of groups.\n  2. Try to assign the next poll to a group without any pending polls,\n  3. If every group has some pending polls, assign the next poll to a group randomly\n    according to the weights."
         }
       }
     },
@@ -17959,6 +17967,25 @@
         }
       }
     },
+    "v1PollerGroupsInfo": {
+      "type": "object",
+      "properties": {
+        "version": {
+          "type": "string",
+          "format": "int64",
+          "description": "Monotonically increasing version of this snapshot. A client should ignore any snapshot whose\nversion is not greater than the one it last applied."
+        },
+        "pollerGroups": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "$ref": "#/definitions/v1PollerGroupInfo"
+          },
+          "description": "The weighted list of poller groups the client should use for future polls to this task queue."
+        }
+      },
+      "description": "A versioned snapshot of the poller groups the client should use for future polls to a task\nqueue. The version is monotonically increasing so that a client can ignore a snapshot that is\nolder than the one it has already applied."
+    },
     "v1PollerInfo": {
       "type": "object",
       "properties": {

openapi/openapiv3.yaml

@@ -11683,9 +11683,18 @@ components:
           items:
             $ref: '#/components/schemas/PollerGroupInfo'
           description: |-
-            The initial info that client should use for poller group assignment. This information is
+            Deprecated. Use `poller_groups_info` instead, which carries a version so the client can
+             ignore stale updates.
+             The initial info that client should use for poller group assignment. This information is
              updated through poll response. Client is supposed to use the info received in the latest
              poll response.
+        pollerGroupsInfo:
+          allOf:
+            - $ref: '#/components/schemas/PollerGroupsInfo'
+          description: |-
+            The initial, versioned info that client should use for poller group assignment. This
+             information is updated through poll responses. Client is supposed to use the info with the
+             highest version it has received.
     DescribeNexusOperationExecutionResponse:
       type: object
       properties:
@@ -14377,12 +14386,25 @@ components:
           items:
             $ref: '#/components/schemas/PollerGroupInfo'
           description: |-
-            The weighted list of poller groups IDs that client should use for future polls to this task
+            Deprecated. Use `poller_groups_info` instead, which carries a version so the client can
+             ignore stale updates.
+             The weighted list of poller groups IDs that client should use for future polls to this task
              queue. Client is expected to:
                1. Maintain minimum number of pollers no less than the number of groups.
                2. Try to assign the next poll to a group without any pending polls,
                3. If every group has some pending polls, assign the next poll to a group randomly
                  according to the weights.
+        pollerGroupsInfo:
+          allOf:
+            - $ref: '#/components/schemas/PollerGroupsInfo'
+          description: |-
+            The weighted, versioned list of poller groups IDs that client should use for future polls to
+             this task queue. Client should ignore this if it has already applied a snapshot with a
+             version greater than or equal to `poller_groups_info.version`. Client is expected to:
+               1. Maintain minimum number of pollers no less than the number of groups.
+               2. Try to assign the next poll to a group without any pending polls,
+               3. If every group has some pending polls, assign the next poll to a group randomly
+                 according to the weights.
     PollerGroupInfo:
       type: object
       properties:
@@ -14391,6 +14413,23 @@ components:
         weight:
           type: number
           format: float
+    PollerGroupsInfo:
+      type: object
+      properties:
+        version:
+          type: string
+          description: |-
+            Monotonically increasing version of this snapshot. A client should ignore any snapshot whose
+             version is not greater than the one it last applied.
+        pollerGroups:
+          type: array
+          items:
+            $ref: '#/components/schemas/PollerGroupInfo'
+          description: The weighted list of poller groups the client should use for future polls to this task queue.
+      description: |-
+        A versioned snapshot of the poller groups the client should use for future polls to a task
+         queue. The version is monotonically increasing so that a client can ignore a snapshot that is
+         older than the one it has already applied.
     PollerInfo:
       type: object
       properties:

temporal/api/taskqueue/v1/message.proto

@@ -308,6 +308,17 @@ message PollerGroupInfo {
   float weight = 2;
 }
 
+// A versioned snapshot of the poller groups the client should use for future polls to a task
+// queue. The version is monotonically increasing so that a client can ignore a snapshot that is
+// older than the one it has already applied.
+message PollerGroupsInfo {
+  // Monotonically increasing version of this snapshot. A client should ignore any snapshot whose
+  // version is not greater than the one it last applied.
+  int64 version = 1;
+  // The weighted list of poller groups the client should use for future polls to this task queue.
+  repeated PollerGroupInfo poller_groups = 2;
+}
+
 // Attached to task responses to give hints to the SDK about how it may adjust its number of
 // pollers.
 message PollerScalingDecision {

temporal/api/workflowservice/v1/request_response.proto

@@ -102,10 +102,16 @@ message DescribeNamespaceResponse {
     // Contains the historical state of failover_versions for the cluster, truncated to contain only the last N
     // states to ensure that the list does not grow unbounded.
     repeated temporal.api.replication.v1.FailoverStatus failover_history = 6;
+    // Deprecated. Use `poller_groups_info` instead, which carries a version so the client can
+    // ignore stale updates.
     // The initial info that client should use for poller group assignment. This information is
     // updated through poll response. Client is supposed to use the info received in the latest
     // poll response.
-    repeated temporal.api.taskqueue.v1.PollerGroupInfo poller_group_infos = 7;
+    repeated temporal.api.taskqueue.v1.PollerGroupInfo poller_group_infos = 7 [deprecated = true];
+    // The initial, versioned info that client should use for poller group assignment. This
+    // information is updated through poll responses. Client is supposed to use the info with the
+    // highest version it has received.
+    temporal.api.taskqueue.v1.PollerGroupsInfo poller_groups_info = 8;
 }
 
 message UpdateNamespaceRequest {
@@ -357,13 +363,23 @@ message PollWorkflowTaskQueueResponse {
     // This poller group ID identifies the owner of the workflow task awaiting for query response.
     // Corresponding RespondQueryTaskCompleted should pass this value for proper routing.
     string poller_group_id = 17;
+    // Deprecated. Use `poller_groups_info` instead, which carries a version so the client can
+    // ignore stale updates.
     // The weighted list of poller groups IDs that client should use for future polls to this task
     // queue. Client is expected to:
     //   1. Maintain minimum number of pollers no less than the number of groups.
     //   2. Try to assign the next poll to a group without any pending polls,
     //   3. If every group has some pending polls, assign the next poll to a group randomly
     //     according to the weights.
-    repeated temporal.api.taskqueue.v1.PollerGroupInfo poller_group_infos = 18;
+    repeated temporal.api.taskqueue.v1.PollerGroupInfo poller_group_infos = 18 [deprecated = true];
+    // The weighted, versioned list of poller groups IDs that client should use for future polls to
+    // this task queue. Client should ignore this if it has already applied a snapshot with a
+    // version greater than or equal to `poller_groups_info.version`. Client is expected to:
+    //   1. Maintain minimum number of pollers no less than the number of groups.
+    //   2. Try to assign the next poll to a group without any pending polls,
+    //   3. If every group has some pending polls, assign the next poll to a group randomly
+    //     according to the weights.
+    temporal.api.taskqueue.v1.PollerGroupsInfo poller_groups_info = 19;
 }
 
 message RespondWorkflowTaskCompletedRequest {
@@ -583,7 +599,15 @@ message PollActivityTaskQueueResponse {
     //   2. Try to assign the next poll to a group without any pending polls,
     //   3. If every group has some pending polls, assign the next poll to a group randomly
     //     according to the weights.
-    repeated temporal.api.taskqueue.v1.PollerGroupInfo poller_group_infos = 21;
+    repeated temporal.api.taskqueue.v1.PollerGroupInfo poller_group_infos = 21 [deprecated = true];
+    // The weighted, versioned list of poller groups IDs that client should use for future polls to
+    // this task queue. Client should ignore this if it has already applied a snapshot with a
+    // version greater than or equal to `poller_groups_info.version`. Client is expected to:
+    //   1. Maintain minimum number of pollers no less than the number of groups.
+    //   2. Try to assign the next poll to a group without any pending polls,
+    //   3. If every group has some pending polls, assign the next poll to a group randomly
+    //     according to the weights.
+    temporal.api.taskqueue.v1.PollerGroupsInfo poller_groups_info = 22;
 }
 
 message RecordActivityTaskHeartbeatRequest {
@@ -2006,7 +2030,15 @@ message PollNexusTaskQueueResponse {
     //   2. Try to assign the next poll to a group without any pending polls,
     //   3. If every group has some pending polls, assign the next poll to a group randomly
     //     according to the weights.
-    repeated temporal.api.taskqueue.v1.PollerGroupInfo poller_group_infos = 5;
+    repeated temporal.api.taskqueue.v1.PollerGroupInfo poller_group_infos = 5 [deprecated = true];
+    // The weighted, versioned list of poller groups IDs that client should use for future polls to
+    // this task queue. Client should ignore this if it has already applied a snapshot with a
+    // version greater than or equal to `poller_groups_info.version`. Client is expected to:
+    //   1. Maintain minimum number of pollers no less than the number of groups.
+    //   2. Try to assign the next poll to a group without any pending polls,
+    //   3. If every group has some pending polls, assign the next poll to a group randomly
+    //     according to the weights.
+    temporal.api.taskqueue.v1.PollerGroupsInfo poller_groups_info = 6;
 }
 
 message RespondNexusTaskCompletedRequest {