Add one-time move to the versioning override API!

openapi/openapiv2.json

@@ -11112,6 +11112,16 @@
         }
       }
     },
+    "VersioningOverrideOneTimeOverride": {
+      "type": "object",
+      "properties": {
+        "targetDeploymentVersion": {
+          "$ref": "#/definitions/v1WorkerDeploymentVersion",
+          "description": "Required. Worker Deployment Version to receive the one-time Workflow Task."
+        }
+      },
+      "description": "Routes Workflow Tasks for this execution to `target_deployment_version`\nuntil a Workflow Task completes on that version, then clears the override.\n\nThis does not force the workflow's normal Versioning Behavior to become\nPinned. After the Workflow Task completes on `target_deployment_version`,\nthe workflow execution's normal Versioning Behavior and Deployment Version\nare taken from the worker's completion response.\n\nExample: if an execution is one-time moved from version X to version Y, and\nversion Z later becomes current:\n- if worker Y reports Pinned, the execution stays on Y;\n- if worker Y reports AutoUpgrade, the execution routes to Z on a future\n  Workflow Task;\n- if worker Y reports Pinned and the workflow uses upgrade-on-continue-as-new,\n  the current run stays on Y and the execution can route to Z after\n  continue-as-new.\n\nIf no Workflow Task completes on `target_deployment_version`, this override\nremains pending."
+    },
     "VersioningOverridePinnedOverride": {
       "type": "object",
       "properties": {
@@ -20170,12 +20180,16 @@
       "properties": {
         "pinned": {
           "$ref": "#/definitions/VersioningOverridePinnedOverride",
-          "description": "Override the workflow to have Pinned behavior."
+          "description": "Override the workflow to have Pinned behavior. This is a sticky override:\nWorkflow Tasks continue to route according to this override until it is\nexplicitly removed."
         },
         "autoUpgrade": {
           "type": "boolean",
           "description": "Override the workflow to have AutoUpgrade behavior."
         },
+        "oneTime": {
+          "$ref": "#/definitions/VersioningOverrideOneTimeOverride",
+          "description": "Override Workflow Task routing to a specific Worker Deployment Version until\none Workflow Task completes there. After completion, the workflow execution's\nVersioning Behavior and Deployment Version come from the worker's completion\nresponse."
+        },
         "behavior": {
           "$ref": "#/definitions/v1VersioningBehavior",
           "description": "Required.\nDeprecated. Use `override`."

openapi/openapiv3.yaml

@@ -18362,10 +18362,23 @@ components:
         pinned:
           allOf:
             - $ref: '#/components/schemas/VersioningOverride_PinnedOverride'
-          description: Override the workflow to have Pinned behavior.
+          description: |-
+            Override the workflow to have Pinned behavior. This is a sticky override:
+             Workflow Tasks continue to route according to this override until it is
+             explicitly removed.
         autoUpgrade:
           type: boolean
           description: Override the workflow to have AutoUpgrade behavior.
+        oneTime:
+          allOf:
+            - $ref: '#/components/schemas/VersioningOverride_OneTimeOverride'
+          description: |-
+            Override Workflow Task routing to a specific Worker Deployment Version until
+             one Workflow Task completes there. After completion, the workflow execution's
+             Versioning Behavior and Deployment Version come from the worker's completion
+             response.
+             (-- api-linter: core::0142::time-field-type=disabled
+                 aip.dev/not-precedent: one_time describes one-time routing semantics, not a timestamp or duration. --)
         behavior:
           enum:
             - VERSIONING_BEHAVIOR_UNSPECIFIED
@@ -18400,6 +18413,33 @@ components:
 
          Pinned behavior overrides are automatically inherited by child workflows, workflow retries, continue-as-new
          workflows, and cron workflows.
+    VersioningOverride_OneTimeOverride:
+      type: object
+      properties:
+        targetDeploymentVersion:
+          allOf:
+            - $ref: '#/components/schemas/WorkerDeploymentVersion'
+          description: Required. Worker Deployment Version to receive the one-time Workflow Task.
+      description: |-
+        Routes Workflow Tasks for this execution to `target_deployment_version`
+         until a Workflow Task completes on that version, then clears the override.
+
+         This does not force the workflow's normal Versioning Behavior to become
+         Pinned. After the Workflow Task completes on `target_deployment_version`,
+         the workflow execution's normal Versioning Behavior and Deployment Version
+         are taken from the worker's completion response.
+
+         Example: if an execution is one-time moved from version X to version Y, and
+         version Z later becomes current:
+         - if worker Y reports Pinned, the execution stays on Y;
+         - if worker Y reports AutoUpgrade, the execution routes to Z on a future
+           Workflow Task;
+         - if worker Y reports Pinned and the workflow uses upgrade-on-continue-as-new,
+           the current run stays on Y and the execution can route to Z after
+           continue-as-new.
+
+         If no Workflow Task completes on `target_deployment_version`, this override
+         remains pending.
     VersioningOverride_PinnedOverride:
       type: object
       properties:

temporal/api/workflow/v1/message.proto

@@ -609,11 +609,21 @@ message WorkflowExecutionOptions {
 message VersioningOverride {
     // Indicates whether to override the workflow to be AutoUpgrade or Pinned.
     oneof override {
-        // Override the workflow to have Pinned behavior.
+        // Override the workflow to have Pinned behavior. This is a sticky override:
+        // Workflow Tasks continue to route according to this override until it is
+        // explicitly removed.
         PinnedOverride pinned = 3;
 
         // Override the workflow to have AutoUpgrade behavior.
         bool auto_upgrade = 4;
+
+        // Override Workflow Task routing to a specific Worker Deployment Version until
+        // one Workflow Task completes there. After completion, the workflow execution's
+        // Versioning Behavior and Deployment Version come from the worker's completion
+        // response.
+        // (-- api-linter: core::0142::time-field-type=disabled
+        //     aip.dev/not-precedent: one_time describes one-time routing semantics, not a timestamp or duration. --)
+        OneTimeOverride one_time = 5;
     }
 
     // Required.
@@ -647,6 +657,30 @@ message VersioningOverride {
         temporal.api.deployment.v1.WorkerDeploymentVersion version = 2;
     }
 
+    // Routes Workflow Tasks for this execution to `target_deployment_version`
+    // until a Workflow Task completes on that version, then clears the override.
+    //
+    // This does not force the workflow's normal Versioning Behavior to become
+    // Pinned. After the Workflow Task completes on `target_deployment_version`,
+    // the workflow execution's normal Versioning Behavior and Deployment Version
+    // are taken from the worker's completion response.
+    //
+    // Example: if an execution is one-time moved from version X to version Y, and
+    // version Z later becomes current:
+    // - if worker Y reports Pinned, the execution stays on Y;
+    // - if worker Y reports AutoUpgrade, the execution routes to Z on a future
+    //   Workflow Task;
+    // - if worker Y reports Pinned and the workflow uses upgrade-on-continue-as-new,
+    //   the current run stays on Y and the execution can route to Z after
+    //   continue-as-new.
+    //
+    // If no Workflow Task completes on `target_deployment_version`, this override
+    // remains pending.
+    message OneTimeOverride {
+        // Required. Worker Deployment Version to receive the one-time Workflow Task.
+        temporal.api.deployment.v1.WorkerDeploymentVersion target_deployment_version = 1;
+    }
+
     enum PinnedOverrideBehavior {
         // Unspecified.
         PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED = 0;