Update Workflow and Activity Priority (#610)

_**READ BEFORE MERGING:** All PRs require approval by both Server AND
SDK teams before merging! This is why the number of required approvals
is "2" and not "1"--two reviewers from the same team is NOT sufficient.
If your PR is not approved by someone in BOTH teams, it may be summarily
reverted._

<!-- Describe what has changed in this PR -->
**What changed?**

Added `Priority` field to the workflow and activity update API options.

Batch API support is going to be added in a follow-up PR.

<!-- Tell your future self why have you made these changes -->
**Why?**

Allow users to update priority after the workflow/activity was
submitted.

<!-- Are there any breaking changes on binary or code level? -->
**Breaking changes**

See field deprecation.

<!-- If this breaks the Server, please provide the Server PR to merge
right after this PR was merged. -->

**Server PR**

TBD

Author: stephanos

openapi/openapiv2.json

@@ -9593,6 +9593,10 @@
         },
         "retryPolicy": {
           "$ref": "#/definitions/v1RetryPolicy"
+        },
+        "priority": {
+          "$ref": "#/definitions/v1Priority",
+          "description": "Priority metadata. If this message is not present, or any fields are not\npresent, they inherit the values from the workflow."
         }
       }
     },
@@ -13158,7 +13162,7 @@
         },
         "priority": {
           "$ref": "#/definitions/v1Priority",
-          "title": "Priority metadata"
+          "description": "Priority metadata. If this message is not present, or any fields are not\npresent, they inherit the values from the workflow."
         },
         "pauseInfo": {
           "$ref": "#/definitions/PendingActivityInfoPauseInfo"
@@ -16988,6 +16992,10 @@
         "versioningOverride": {
           "$ref": "#/definitions/v1VersioningOverride",
           "description": "If set, takes precedence over the Versioning Behavior sent by the SDK on Workflow Task completion."
+        },
+        "priority": {
+          "$ref": "#/definitions/v1Priority",
+          "description": "If set, overrides the workflow's priority sent by the SDK."
         }
       }
     },
@@ -17004,7 +17012,7 @@
         },
         "attachedRequestId": {
           "type": "string",
-          "description": "Request ID attachedto the running workflow execution so that subsequent requests with same\nrequest ID will be deduped."
+          "description": "Request ID attached to the running workflow execution so that subsequent requests with same\nrequest ID will be deduped."
         },
         "attachedCompletionCallbacks": {
           "type": "array",
@@ -17017,6 +17025,10 @@
         "identity": {
           "type": "string",
           "description": "Optional. The identity of the client who initiated the request that created this event."
+        },
+        "priority": {
+          "$ref": "#/definitions/v1Priority",
+          "description": "Priority override upserted in this event. Represents the full priority; not just partial fields.\nIgnored if nil."
         }
       }
     },
@@ -17228,11 +17240,11 @@
         },
         "inheritedPinnedVersion": {
           "$ref": "#/definitions/v1WorkerDeploymentVersion",
-          "description": "If present, the new workflow should start on this version with pinned base behavior.\nChild of pinned parent will inherit the parent's version if the Child's Task Queue belongs to that version.\n\nA new run initiated by workflow ContinueAsNew of pinned run, will inherit the previous run's version if the\nnew run's Task Queue belongs to that version.\n\nA new run initiated by workflow Cron will never inherit.\n\nA new run initiated by workflow Retry will only inherit if the retried run is effectively pinned at the time\nof retry, and the retried run inherited a pinned version when it started (ie. it is a child of a pinned\nparent, or a CaN of a pinned run, and is running on a Task Queue in the inherited version).\n\nPinned override is inherited if Task Queue of new run is compatible with the override version.\nOverride is inherited separately and takes precedence over inherited base version.\n\nNote: This field is mutually exclusive with inherited_auto_upgrade_info. \nAdditionaly, versioning_override, if present, overrides this field during routing decisions."
+          "description": "If present, the new workflow should start on this version with pinned base behavior.\nChild of pinned parent will inherit the parent's version if the Child's Task Queue belongs to that version.\n\nA new run initiated by workflow ContinueAsNew of pinned run, will inherit the previous run's version if the\nnew run's Task Queue belongs to that version.\n\nA new run initiated by workflow Cron will never inherit.\n\nA new run initiated by workflow Retry will only inherit if the retried run is effectively pinned at the time\nof retry, and the retried run inherited a pinned version when it started (ie. it is a child of a pinned\nparent, or a CaN of a pinned run, and is running on a Task Queue in the inherited version).\n\nPinned override is inherited if Task Queue of new run is compatible with the override version.\nOverride is inherited separately and takes precedence over inherited base version.\n\nNote: This field is mutually exclusive with inherited_auto_upgrade_info.\nAdditionaly, versioning_override, if present, overrides this field during routing decisions."
         },
         "inheritedAutoUpgradeInfo": {
           "$ref": "#/definitions/v1InheritedAutoUpgradeInfo",
-          "description": "If present, the new workflow begins with AutoUpgrade behavior. Before dispatching the\nfirst workflow task, this field is set to the deployment version on which the parent/\nprevious run was operating. This inheritance only happens when the task queues belong to\nthe same deployment version. The first workflow task will then be dispatched to either\nthis inherited deployment version, or the current deployment version of the task queue's\nDeployment. After the first workflow task, the effective behavior depends on worker-sent\nvalues in subsequent workflow tasks.\n\nInheritance rules:\n  - ContinueAsNew and child workflows: inherit AutoUpgrade behavior and deployment version\n  - Cron: never inherits\n  - Retry: inherits only if the retried run is effectively AutoUpgrade at the time of\n    retry, and inherited AutoUpgrade behavior when it started (i.e. it is a child of an\n    AutoUpgrade parent or ContinueAsNew of an AutoUpgrade run, running on the same\n    deployment as the parent/previous run)\n\nAdditional notes: \n- This field is mutually exclusive with `inherited_pinned_version`. \n- `versioning_override`, if present, overrides this field during routing decisions.\n- SDK implementations do not interact with this field and is only used internally by \n  the server to ensure task routing correctness."
+          "description": "If present, the new workflow begins with AutoUpgrade behavior. Before dispatching the\nfirst workflow task, this field is set to the deployment version on which the parent/\nprevious run was operating. This inheritance only happens when the task queues belong to\nthe same deployment version. The first workflow task will then be dispatched to either\nthis inherited deployment version, or the current deployment version of the task queue's\nDeployment. After the first workflow task, the effective behavior depends on worker-sent\nvalues in subsequent workflow tasks.\n\nInheritance rules:\n  - ContinueAsNew and child workflows: inherit AutoUpgrade behavior and deployment version\n  - Cron: never inherits\n  - Retry: inherits only if the retried run is effectively AutoUpgrade at the time of\n    retry, and inherited AutoUpgrade behavior when it started (i.e. it is a child of an\n    AutoUpgrade parent or ContinueAsNew of an AutoUpgrade run, running on the same\n    deployment as the parent/previous run)\n\nAdditional notes:\n- This field is mutually exclusive with `inherited_pinned_version`.\n- `versioning_override`, if present, overrides this field during routing decisions.\n- SDK implementations do not interact with this field and is only used internally by\n  the server to ensure task routing correctness."
         },
         "eagerExecutionAccepted": {
           "type": "boolean",

openapi/openapiv3.yaml

@@ -6681,6 +6681,12 @@ components:
           description: Maximum permitted time between successful worker heartbeats.
         retryPolicy:
           $ref: '#/components/schemas/RetryPolicy'
+        priority:
+          allOf:
+            - $ref: '#/components/schemas/Priority'
+          description: |-
+            Priority metadata. If this message is not present, or any fields are not
+             present, they inherit the values from the workflow.
     ActivityPropertiesModifiedExternallyEventAttributes:
       type: object
       properties:
@@ -9921,7 +9927,9 @@ components:
         priority:
           allOf:
             - $ref: '#/components/schemas/Priority'
-          description: Priority metadata
+          description: |-
+            Priority metadata. If this message is not present, or any fields are not
+             present, they inherit the values from the workflow.
         pauseInfo:
           $ref: '#/components/schemas/PendingActivityInfo_PauseInfo'
         activityOptions:
@@ -14466,6 +14474,10 @@ components:
           allOf:
             - $ref: '#/components/schemas/VersioningOverride'
           description: If set, takes precedence over the Versioning Behavior sent by the SDK on Workflow Task completion.
+        priority:
+          allOf:
+            - $ref: '#/components/schemas/Priority'
+          description: If set, overrides the workflow's priority sent by the SDK.
     WorkflowExecutionOptionsUpdatedEventAttributes:
       type: object
       properties:
@@ -14481,7 +14493,7 @@ components:
         attachedRequestId:
           type: string
           description: |-
-            Request ID attachedto the running workflow execution so that subsequent requests with same
+            Request ID attached to the running workflow execution so that subsequent requests with same
              request ID will be deduped.
         attachedCompletionCallbacks:
           type: array
@@ -14491,6 +14503,12 @@ components:
         identity:
           type: string
           description: Optional. The identity of the client who initiated the request that created this event.
+        priority:
+          allOf:
+            - $ref: '#/components/schemas/Priority'
+          description: |-
+            Priority override upserted in this event. Represents the full priority; not just partial fields.
+             Ignored if nil.
     WorkflowExecutionPauseInfo:
       type: object
       properties:
@@ -14721,11 +14739,49 @@ components:
         inheritedPinnedVersion:
           allOf:
             - $ref: '#/components/schemas/WorkerDeploymentVersion'
-          description: "If present, the new workflow should start on this version with pinned base behavior.\n Child of pinned parent will inherit the parent's version if the Child's Task Queue belongs to that version.\n\n A new run initiated by workflow ContinueAsNew of pinned run, will inherit the previous run's version if the\n new run's Task Queue belongs to that version.\n\n A new run initiated by workflow Cron will never inherit.\n\n A new run initiated by workflow Retry will only inherit if the retried run is effectively pinned at the time\n of retry, and the retried run inherited a pinned version when it started (ie. it is a child of a pinned\n parent, or a CaN of a pinned run, and is running on a Task Queue in the inherited version).\n\n Pinned override is inherited if Task Queue of new run is compatible with the override version.\n Override is inherited separately and takes precedence over inherited base version.\n\n Note: This field is mutually exclusive with inherited_auto_upgrade_info. \n Additionaly, versioning_override, if present, overrides this field during routing decisions."
+          description: |-
+            If present, the new workflow should start on this version with pinned base behavior.
+             Child of pinned parent will inherit the parent's version if the Child's Task Queue belongs to that version.
+
+             A new run initiated by workflow ContinueAsNew of pinned run, will inherit the previous run's version if the
+             new run's Task Queue belongs to that version.
+
+             A new run initiated by workflow Cron will never inherit.
+
+             A new run initiated by workflow Retry will only inherit if the retried run is effectively pinned at the time
+             of retry, and the retried run inherited a pinned version when it started (ie. it is a child of a pinned
+             parent, or a CaN of a pinned run, and is running on a Task Queue in the inherited version).
+
+             Pinned override is inherited if Task Queue of new run is compatible with the override version.
+             Override is inherited separately and takes precedence over inherited base version.
+
+             Note: This field is mutually exclusive with inherited_auto_upgrade_info.
+             Additionaly, versioning_override, if present, overrides this field during routing decisions.
         inheritedAutoUpgradeInfo:
           allOf:
             - $ref: '#/components/schemas/InheritedAutoUpgradeInfo'
-          description: "If present, the new workflow begins with AutoUpgrade behavior. Before dispatching the\n first workflow task, this field is set to the deployment version on which the parent/\n previous run was operating. This inheritance only happens when the task queues belong to\n the same deployment version. The first workflow task will then be dispatched to either\n this inherited deployment version, or the current deployment version of the task queue's\n Deployment. After the first workflow task, the effective behavior depends on worker-sent\n values in subsequent workflow tasks.\n\n Inheritance rules:\n   - ContinueAsNew and child workflows: inherit AutoUpgrade behavior and deployment version\n   - Cron: never inherits\n   - Retry: inherits only if the retried run is effectively AutoUpgrade at the time of\n     retry, and inherited AutoUpgrade behavior when it started (i.e. it is a child of an\n     AutoUpgrade parent or ContinueAsNew of an AutoUpgrade run, running on the same\n     deployment as the parent/previous run)\n \n Additional notes: \n - This field is mutually exclusive with `inherited_pinned_version`. \n - `versioning_override`, if present, overrides this field during routing decisions.\n - SDK implementations do not interact with this field and is only used internally by \n   the server to ensure task routing correctness."
+          description: |-
+            If present, the new workflow begins with AutoUpgrade behavior. Before dispatching the
+             first workflow task, this field is set to the deployment version on which the parent/
+             previous run was operating. This inheritance only happens when the task queues belong to
+             the same deployment version. The first workflow task will then be dispatched to either
+             this inherited deployment version, or the current deployment version of the task queue's
+             Deployment. After the first workflow task, the effective behavior depends on worker-sent
+             values in subsequent workflow tasks.
+
+             Inheritance rules:
+               - ContinueAsNew and child workflows: inherit AutoUpgrade behavior and deployment version
+               - Cron: never inherits
+               - Retry: inherits only if the retried run is effectively AutoUpgrade at the time of
+                 retry, and inherited AutoUpgrade behavior when it started (i.e. it is a child of an
+                 AutoUpgrade parent or ContinueAsNew of an AutoUpgrade run, running on the same
+                 deployment as the parent/previous run)
+
+             Additional notes:
+             - This field is mutually exclusive with `inherited_pinned_version`.
+             - `versioning_override`, if present, overrides this field during routing decisions.
+             - SDK implementations do not interact with this field and is only used internally by
+               the server to ensure task routing correctness.
         eagerExecutionAccepted:
           type: boolean
           description: |-

temporal/api/activity/v1/message.proto

@@ -42,4 +42,8 @@ message ActivityOptions {
     google.protobuf.Duration heartbeat_timeout = 5;
 
     temporal.api.common.v1.RetryPolicy retry_policy = 6;
+
+    // Priority metadata. If this message is not present, or any fields are not
+    // present, they inherit the values from the workflow.
+    temporal.api.common.v1.Priority priority = 7;
 }

temporal/api/history/v1/message.proto

@@ -152,8 +152,8 @@ message WorkflowExecutionStartedEventAttributes {
     // Pinned override is inherited if Task Queue of new run is compatible with the override version.
     // Override is inherited separately and takes precedence over inherited base version.
     //
-    // Note: This field is mutually exclusive with inherited_auto_upgrade_info. 
-    // Additionaly, versioning_override, if present, overrides this field during routing decisions.  
+    // Note: This field is mutually exclusive with inherited_auto_upgrade_info.
+    // Additionaly, versioning_override, if present, overrides this field during routing decisions.
     temporal.api.deployment.v1.WorkerDeploymentVersion inherited_pinned_version = 37;
 
     // If present, the new workflow begins with AutoUpgrade behavior. Before dispatching the
@@ -171,11 +171,11 @@ message WorkflowExecutionStartedEventAttributes {
     //     retry, and inherited AutoUpgrade behavior when it started (i.e. it is a child of an
     //     AutoUpgrade parent or ContinueAsNew of an AutoUpgrade run, running on the same
     //     deployment as the parent/previous run)
-    // 
-    // Additional notes: 
-    // - This field is mutually exclusive with `inherited_pinned_version`. 
+    //
+    // Additional notes:
+    // - This field is mutually exclusive with `inherited_pinned_version`.
     // - `versioning_override`, if present, overrides this field during routing decisions.
-    // - SDK implementations do not interact with this field and is only used internally by 
+    // - SDK implementations do not interact with this field and is only used internally by
     //   the server to ensure task routing correctness.
     temporal.api.deployment.v1.InheritedAutoUpgradeInfo inherited_auto_upgrade_info = 39;
 
@@ -834,13 +834,16 @@ message WorkflowExecutionOptionsUpdatedEventAttributes {
     temporal.api.workflow.v1.VersioningOverride versioning_override = 1;
     // Versioning override removed in this event.
     bool unset_versioning_override = 2;
-    // Request ID attachedto the running workflow execution so that subsequent requests with same
+    // Request ID attached to the running workflow execution so that subsequent requests with same
     // request ID will be deduped.
     string attached_request_id = 3;
     // Completion callbacks attached to the running workflow execution.
     repeated temporal.api.common.v1.Callback attached_completion_callbacks = 4;
     // Optional. The identity of the client who initiated the request that created this event.
     string identity = 5;
+    // Priority override upserted in this event. Represents the full priority; not just partial fields.
+    // Ignored if nil.
+    temporal.api.common.v1.Priority priority = 6;
 }
 
 // Not used anywhere. Use case is replaced by WorkflowExecutionOptionsUpdatedEventAttributes

temporal/api/workflow/v1/message.proto

@@ -318,8 +318,8 @@ message PendingActivityInfo {
     // If nil, the activity has not yet been dispatched or was last dispatched to an unversioned worker.
     temporal.api.deployment.v1.WorkerDeploymentVersion last_deployment_version = 25;
 
-
-    // Priority metadata
+    // Priority metadata. If this message is not present, or any fields are not
+    // present, they inherit the values from the workflow.
     temporal.api.common.v1.Priority priority = 22;
 
     message PauseInfo {
@@ -547,6 +547,9 @@ message NexusOperationCancellationInfo {
 message WorkflowExecutionOptions {
     // If set, takes precedence over the Versioning Behavior sent by the SDK on Workflow Task completion.
     VersioningOverride versioning_override = 1;
+
+    // If set, overrides the workflow's priority sent by the SDK.
+    temporal.api.common.v1.Priority priority = 2;
 }
 
 // Used to override the versioning behavior (and pinned deployment version, if applicable) of a