From 48908405ee2e5f5f354f45800f04a74b3de65172 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Fri, 10 Oct 2025 20:06:54 -0700 Subject: [PATCH 01/21] add ContinueAsNewSuggestedReason enum and SuggestContinueAsNewSignalInput --- openapi/openapiv2.json | 18 +++++++++++++++++- openapi/openapiv3.yaml | 19 +++++++++++++++++-- temporal/api/enums/v1/workflow.proto | 22 ++++++++++++++++++++++ temporal/api/history/v1/message.proto | 10 ++++++++-- temporal/api/workflow/v1/message.proto | 5 +++++ 5 files changed, 69 insertions(+), 5 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index cfed16ffd..68fb344d7 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -10626,6 +10626,18 @@ "default": "CONTINUE_AS_NEW_INITIATOR_UNSPECIFIED", "title": "- CONTINUE_AS_NEW_INITIATOR_WORKFLOW: The workflow itself requested to continue as new\n - CONTINUE_AS_NEW_INITIATOR_RETRY: The workflow continued as new because it is retrying\n - CONTINUE_AS_NEW_INITIATOR_CRON_SCHEDULE: The workflow continued as new because cron has triggered a new execution" }, + "v1ContinueAsNewSuggestedReason": { + "type": "string", + "enum": [ + "CONTINUE_AS_NEW_SUGGESTED_REASON_UNSPECIFIED", + "CONTINUE_AS_NEW_SUGGESTED_REASON_HISTORY_SIZE_TOO_LARGE", + "CONTINUE_AS_NEW_SUGGESTED_REASON_UPDATE_REGISTRY_TOO_LARGE", + "CONTINUE_AS_NEW_SUGGESTED_REASON_NEW_RAMPING_VERSION", + "CONTINUE_AS_NEW_SUGGESTED_REASON_NEW_CURRENT_VERSION" + ], + "default": "CONTINUE_AS_NEW_SUGGESTED_REASON_UNSPECIFIED", + "description": "ContinueAsNewSuggestedReason specifies why SuggestContinueAsNew is true.\n\n - CONTINUE_AS_NEW_SUGGESTED_REASON_UNSPECIFIED: Reason will be Unspecified if the server is not configured to suggest continue as new,\nif the server is not configured to provide a reason for continue as new suggested,\nif continue as new is not suggested, or if the reason is unknown.\n - CONTINUE_AS_NEW_SUGGESTED_REASON_HISTORY_SIZE_TOO_LARGE: Workflow History size is getting too large.\n - CONTINUE_AS_NEW_SUGGESTED_REASON_UPDATE_REGISTRY_TOO_LARGE: Workflow Update registry is getting too large.\n - CONTINUE_AS_NEW_SUGGESTED_REASON_NEW_RAMPING_VERSION: Workflow's Worker Deployment has a new Ramping Version, and the workflow's\nVersioning Behavior is PinnedUntilContinueAsNew.\n - CONTINUE_AS_NEW_SUGGESTED_REASON_NEW_CURRENT_VERSION: Workflow's Worker Deployment has a new Current Version, and the workflow's\nVersioning Behavior is PinnedUntilContinueAsNew." + }, "v1ContinueAsNewWorkflowExecutionCommandAttributes": { "type": "object", "properties": { @@ -17487,7 +17499,7 @@ }, "suggestContinueAsNew": { "type": "boolean", - "description": "True if this workflow should continue-as-new soon because its history size (in\neither event count or bytes) is getting large." + "title": "True if this workflow should continue-as-new soon. Reasons for this could be:\n - History size (in either event count or bytes) is getting large\n - Update registry size is getting large\n - Workflow's Worker Deployment has a new Ramping Version, and the workflow's Versioning Behavior is PinnedUntilContinueAsNew\n - Workflow's Worker Deployment has a new Current Version, and the workflow's Versioning Behavior is PinnedUntilContinueAsNew" }, "historySizeBytes": { "type": "string", @@ -17502,6 +17514,10 @@ "type": "string", "format": "int64", "title": "Used by server internally to properly reapply build ID redirects to an execution\nwhen rebuilding it from events.\nDeprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv]" + }, + "continueAsNewSuggestedReason": { + "$ref": "#/definitions/v1ContinueAsNewSuggestedReason", + "description": "The reason that suggest_continue_as_new is true, if it is.\nUnspecified if suggest_continue_as_new is false or if the reason is unknown." } } }, diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 88f8737d0..76bce14f6 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -15042,8 +15042,11 @@ components: suggestContinueAsNew: type: boolean description: |- - True if this workflow should continue-as-new soon because its history size (in - either event count or bytes) is getting large. + True if this workflow should continue-as-new soon. Reasons for this could be: + - History size (in either event count or bytes) is getting large + - Update registry size is getting large + - Workflow's Worker Deployment has a new Ramping Version, and the workflow's Versioning Behavior is PinnedUntilContinueAsNew + - Workflow's Worker Deployment has a new Current Version, and the workflow's Versioning Behavior is PinnedUntilContinueAsNew historySizeBytes: type: string description: |- @@ -15062,6 +15065,18 @@ components: Used by server internally to properly reapply build ID redirects to an execution when rebuilding it from events. Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv] + continueAsNewSuggestedReason: + enum: + - CONTINUE_AS_NEW_SUGGESTED_REASON_UNSPECIFIED + - CONTINUE_AS_NEW_SUGGESTED_REASON_HISTORY_SIZE_TOO_LARGE + - CONTINUE_AS_NEW_SUGGESTED_REASON_UPDATE_REGISTRY_TOO_LARGE + - CONTINUE_AS_NEW_SUGGESTED_REASON_NEW_RAMPING_VERSION + - CONTINUE_AS_NEW_SUGGESTED_REASON_NEW_CURRENT_VERSION + type: string + description: |- + The reason that suggest_continue_as_new is true, if it is. + Unspecified if suggest_continue_as_new is false or if the reason is unknown. + format: enum WorkflowTaskTimedOutEventAttributes: type: object properties: diff --git a/temporal/api/enums/v1/workflow.proto b/temporal/api/enums/v1/workflow.proto index 7d0e1ba29..128b7aa64 100644 --- a/temporal/api/enums/v1/workflow.proto +++ b/temporal/api/enums/v1/workflow.proto @@ -161,3 +161,25 @@ enum VersioningBehavior { // complete on the old Version. VERSIONING_BEHAVIOR_AUTO_UPGRADE = 2; } + +// ContinueAsNewSuggestedReason specifies why SuggestContinueAsNew is true. +enum ContinueAsNewSuggestedReason { + // Reason will be Unspecified if the server is not configured to suggest continue as new, + // if the server is not configured to provide a reason for continue as new suggested, + // if continue as new is not suggested, or if the reason is unknown. + CONTINUE_AS_NEW_SUGGESTED_REASON_UNSPECIFIED = 0; + + // Workflow History size is getting too large. + CONTINUE_AS_NEW_SUGGESTED_REASON_HISTORY_SIZE_TOO_LARGE = 1; + + // Workflow Update registry is getting too large. + CONTINUE_AS_NEW_SUGGESTED_REASON_UPDATE_REGISTRY_TOO_LARGE = 2; + + // Workflow's Worker Deployment has a new Ramping Version, and the workflow's + // Versioning Behavior is PinnedUntilContinueAsNew. + CONTINUE_AS_NEW_SUGGESTED_REASON_NEW_RAMPING_VERSION = 3; + + // Workflow's Worker Deployment has a new Current Version, and the workflow's + // Versioning Behavior is PinnedUntilContinueAsNew. + CONTINUE_AS_NEW_SUGGESTED_REASON_NEW_CURRENT_VERSION = 4; +} diff --git a/temporal/api/history/v1/message.proto b/temporal/api/history/v1/message.proto index dfbc7b7ad..a47a086f7 100644 --- a/temporal/api/history/v1/message.proto +++ b/temporal/api/history/v1/message.proto @@ -235,8 +235,11 @@ message WorkflowTaskStartedEventAttributes { string identity = 2; // TODO: ? Appears unused? string request_id = 3; - // True if this workflow should continue-as-new soon because its history size (in - // either event count or bytes) is getting large. + // True if this workflow should continue-as-new soon. Reasons for this could be: + // - History size (in either event count or bytes) is getting large + // - Update registry size is getting large + // - Workflow's Worker Deployment has a new Ramping Version, and the workflow's Versioning Behavior is PinnedUntilContinueAsNew + // - Workflow's Worker Deployment has a new Current Version, and the workflow's Versioning Behavior is PinnedUntilContinueAsNew bool suggest_continue_as_new = 4; // Total history size in bytes, which the workflow might use to decide when to // continue-as-new regardless of the suggestion. Note that history event count is @@ -249,6 +252,9 @@ message WorkflowTaskStartedEventAttributes { // when rebuilding it from events. // Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv] int64 build_id_redirect_counter = 7 [deprecated = true]; + // The reason that suggest_continue_as_new is true, if it is. + // Unspecified if suggest_continue_as_new is false or if the reason is unknown. + temporal.api.enums.v1.ContinueAsNewSuggestedReason continue_as_new_suggested_reason = 8; } message WorkflowTaskCompletedEventAttributes { diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index 1d5737c79..9c21ed1ed 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -636,3 +636,8 @@ message PostResetOperation { } } +// SuggestContinueAsNewSignalInput is the input for the system-defined SuggestContinueAsNew signal. +message SuggestContinueAsNewSignalInput { + temporal.api.enums.v1.ContinueAsNewSuggestedReason continue_as_new_suggested_reason = 1; +} + From b8e8ddfc1f2ba4234121099f59f318786b78323d Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Fri, 17 Oct 2025 09:36:26 -0700 Subject: [PATCH 02/21] simplify can-reason --- temporal/api/enums/v1/workflow.proto | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/temporal/api/enums/v1/workflow.proto b/temporal/api/enums/v1/workflow.proto index 128b7aa64..eb29d1375 100644 --- a/temporal/api/enums/v1/workflow.proto +++ b/temporal/api/enums/v1/workflow.proto @@ -175,11 +175,7 @@ enum ContinueAsNewSuggestedReason { // Workflow Update registry is getting too large. CONTINUE_AS_NEW_SUGGESTED_REASON_UPDATE_REGISTRY_TOO_LARGE = 2; - // Workflow's Worker Deployment has a new Ramping Version, and the workflow's + // Workflow's Worker Deployment has a new Ramping Version, and the workflow's // Versioning Behavior is PinnedUntilContinueAsNew. - CONTINUE_AS_NEW_SUGGESTED_REASON_NEW_RAMPING_VERSION = 3; - - // Workflow's Worker Deployment has a new Current Version, and the workflow's - // Versioning Behavior is PinnedUntilContinueAsNew. - CONTINUE_AS_NEW_SUGGESTED_REASON_NEW_CURRENT_VERSION = 4; + CONTINUE_AS_NEW_SUGGESTED_REASON_WORKER_DEPLOYMENT_VERSION_CHANGED = 3; } From f1423deedc96fe7e0e9f380cc8d7689ed08bcab6 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Fri, 17 Oct 2025 09:37:09 -0700 Subject: [PATCH 03/21] make proto --- openapi/openapiv2.json | 5 ++--- openapi/openapiv3.yaml | 3 +-- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index c9af449e5..53f890625 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -10651,11 +10651,10 @@ "CONTINUE_AS_NEW_SUGGESTED_REASON_UNSPECIFIED", "CONTINUE_AS_NEW_SUGGESTED_REASON_HISTORY_SIZE_TOO_LARGE", "CONTINUE_AS_NEW_SUGGESTED_REASON_UPDATE_REGISTRY_TOO_LARGE", - "CONTINUE_AS_NEW_SUGGESTED_REASON_NEW_RAMPING_VERSION", - "CONTINUE_AS_NEW_SUGGESTED_REASON_NEW_CURRENT_VERSION" + "CONTINUE_AS_NEW_SUGGESTED_REASON_WORKER_DEPLOYMENT_VERSION_CHANGED" ], "default": "CONTINUE_AS_NEW_SUGGESTED_REASON_UNSPECIFIED", - "description": "ContinueAsNewSuggestedReason specifies why SuggestContinueAsNew is true.\n\n - CONTINUE_AS_NEW_SUGGESTED_REASON_UNSPECIFIED: Reason will be Unspecified if the server is not configured to suggest continue as new,\nif the server is not configured to provide a reason for continue as new suggested,\nif continue as new is not suggested, or if the reason is unknown.\n - CONTINUE_AS_NEW_SUGGESTED_REASON_HISTORY_SIZE_TOO_LARGE: Workflow History size is getting too large.\n - CONTINUE_AS_NEW_SUGGESTED_REASON_UPDATE_REGISTRY_TOO_LARGE: Workflow Update registry is getting too large.\n - CONTINUE_AS_NEW_SUGGESTED_REASON_NEW_RAMPING_VERSION: Workflow's Worker Deployment has a new Ramping Version, and the workflow's\nVersioning Behavior is PinnedUntilContinueAsNew.\n - CONTINUE_AS_NEW_SUGGESTED_REASON_NEW_CURRENT_VERSION: Workflow's Worker Deployment has a new Current Version, and the workflow's\nVersioning Behavior is PinnedUntilContinueAsNew." + "description": "ContinueAsNewSuggestedReason specifies why SuggestContinueAsNew is true.\n\n - CONTINUE_AS_NEW_SUGGESTED_REASON_UNSPECIFIED: Reason will be Unspecified if the server is not configured to suggest continue as new,\nif the server is not configured to provide a reason for continue as new suggested,\nif continue as new is not suggested, or if the reason is unknown.\n - CONTINUE_AS_NEW_SUGGESTED_REASON_HISTORY_SIZE_TOO_LARGE: Workflow History size is getting too large.\n - CONTINUE_AS_NEW_SUGGESTED_REASON_UPDATE_REGISTRY_TOO_LARGE: Workflow Update registry is getting too large.\n - CONTINUE_AS_NEW_SUGGESTED_REASON_WORKER_DEPLOYMENT_VERSION_CHANGED: Workflow's Worker Deployment has a new Ramping Version, and the workflow's\nVersioning Behavior is PinnedUntilContinueAsNew." }, "v1ContinueAsNewWorkflowExecutionCommandAttributes": { "type": "object", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 1cb0c4530..e2d5e808a 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -15090,8 +15090,7 @@ components: - CONTINUE_AS_NEW_SUGGESTED_REASON_UNSPECIFIED - CONTINUE_AS_NEW_SUGGESTED_REASON_HISTORY_SIZE_TOO_LARGE - CONTINUE_AS_NEW_SUGGESTED_REASON_UPDATE_REGISTRY_TOO_LARGE - - CONTINUE_AS_NEW_SUGGESTED_REASON_NEW_RAMPING_VERSION - - CONTINUE_AS_NEW_SUGGESTED_REASON_NEW_CURRENT_VERSION + - CONTINUE_AS_NEW_SUGGESTED_REASON_WORKER_DEPLOYMENT_VERSION_CHANGED type: string description: |- The reason that suggest_continue_as_new is true, if it is. From 20f6ece9cfa25e629f502da339de496c6a6b8178 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Thu, 30 Oct 2025 17:18:55 -0700 Subject: [PATCH 04/21] add behavior and remove special signaL --- openapi/openapiv2.json | 7 ++++--- openapi/openapiv3.yaml | 3 +++ temporal/api/enums/v1/workflow.proto | 13 ++++++++++--- temporal/api/workflow/v1/message.proto | 6 ------ 4 files changed, 17 insertions(+), 12 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 53f890625..8032d2fd8 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -10654,7 +10654,7 @@ "CONTINUE_AS_NEW_SUGGESTED_REASON_WORKER_DEPLOYMENT_VERSION_CHANGED" ], "default": "CONTINUE_AS_NEW_SUGGESTED_REASON_UNSPECIFIED", - "description": "ContinueAsNewSuggestedReason specifies why SuggestContinueAsNew is true.\n\n - CONTINUE_AS_NEW_SUGGESTED_REASON_UNSPECIFIED: Reason will be Unspecified if the server is not configured to suggest continue as new,\nif the server is not configured to provide a reason for continue as new suggested,\nif continue as new is not suggested, or if the reason is unknown.\n - CONTINUE_AS_NEW_SUGGESTED_REASON_HISTORY_SIZE_TOO_LARGE: Workflow History size is getting too large.\n - CONTINUE_AS_NEW_SUGGESTED_REASON_UPDATE_REGISTRY_TOO_LARGE: Workflow Update registry is getting too large.\n - CONTINUE_AS_NEW_SUGGESTED_REASON_WORKER_DEPLOYMENT_VERSION_CHANGED: Workflow's Worker Deployment has a new Ramping Version, and the workflow's\nVersioning Behavior is PinnedUntilContinueAsNew." + "description": "ContinueAsNewSuggestedReason specifies why SuggestContinueAsNew is true.\n\n - CONTINUE_AS_NEW_SUGGESTED_REASON_UNSPECIFIED: Reason will be Unspecified if the server is not configured to suggest continue as new,\nif the server is not configured to provide a reason for continue as new suggested,\nif continue as new is not suggested, or if the reason is unknown.\n - CONTINUE_AS_NEW_SUGGESTED_REASON_HISTORY_SIZE_TOO_LARGE: Workflow History size is getting too large.\n - CONTINUE_AS_NEW_SUGGESTED_REASON_UPDATE_REGISTRY_TOO_LARGE: Workflow Update registry is getting too large.\n - CONTINUE_AS_NEW_SUGGESTED_REASON_WORKER_DEPLOYMENT_VERSION_CHANGED: Workflow's Worker Deployment has a new Ramping Version, and the workflow's\nVersioning Behavior is PinnedUntilContinueAsNew." }, "v1ContinueAsNewWorkflowExecutionCommandAttributes": { "type": "object", @@ -16014,10 +16014,11 @@ "enum": [ "VERSIONING_BEHAVIOR_UNSPECIFIED", "VERSIONING_BEHAVIOR_PINNED", - "VERSIONING_BEHAVIOR_AUTO_UPGRADE" + "VERSIONING_BEHAVIOR_AUTO_UPGRADE", + "VERSIONING_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW" ], "default": "VERSIONING_BEHAVIOR_UNSPECIFIED", - "description": "Versioning Behavior specifies if and how a workflow execution moves between Worker Deployment\nVersions. The Versioning Behavior of a workflow execution is typically specified by the worker\nwho completes the first task of the execution, but is also overridable manually for new and\nexisting workflows (see VersioningOverride).\nExperimental. Worker Deployments are experimental and might significantly change in the future.\n\n - VERSIONING_BEHAVIOR_UNSPECIFIED: Workflow execution does not have a Versioning Behavior and is called Unversioned. This is the\nlegacy behavior. An Unversioned workflow's task can go to any Unversioned worker (see\n`WorkerVersioningMode`.)\nUser needs to use Patching to keep the new code compatible with prior versions when dealing\nwith Unversioned workflows.\n - VERSIONING_BEHAVIOR_PINNED: Workflow will start on the Current Deployment Version of its Task Queue, and then\nwill be pinned to that same Deployment Version until completion (the Version that\nthis Workflow is pinned to is specified in `versioning_info.version`).\nThis behavior eliminates most of compatibility concerns users face when changing their code.\nPatching is not needed when pinned workflows code change.\nCan be overridden explicitly via `UpdateWorkflowExecutionOptions` API to move the\nexecution to another Deployment Version.\nActivities of `PINNED` workflows are sent to the same Deployment Version. Exception to this\nwould be when the activity Task Queue workers are not present in the workflow's Deployment\nVersion, in which case the activity will be sent to the Current Deployment Version of its own\ntask queue.\n - VERSIONING_BEHAVIOR_AUTO_UPGRADE: Workflow will automatically move to the Current Deployment Version of its Task Queue when the\nnext workflow task is dispatched.\nAutoUpgrade behavior is suitable for long-running workflows as it allows them to move to the\nlatest Deployment Version, but the user still needs to use Patching to keep the new code\ncompatible with prior versions for changed workflow types.\nActivities of `AUTO_UPGRADE` workflows are sent to the Deployment Version of the workflow\nexecution (as specified in versioning_info.version based on the last completed\nworkflow task). Exception to this would be when the activity Task Queue workers are not\npresent in the workflow's Deployment Version, in which case, the activity will be sent to a\ndifferent Deployment Version according to the Current Deployment Version of its own task\nqueue.\nWorkflows stuck on a backlogged activity will still auto-upgrade if the Current Deployment\nVersion of their Task Queue changes, without having to wait for the backlogged activity to\ncomplete on the old Version." + "description": "Versioning Behavior specifies if and how a workflow execution moves between Worker Deployment\nVersions. The Versioning Behavior of a workflow execution is typically specified by the worker\nwho completes the first task of the execution, but is also overridable manually for new and\nexisting workflows (see VersioningOverride).\nExperimental. Worker Deployments are experimental and might significantly change in the future.\n\n - VERSIONING_BEHAVIOR_UNSPECIFIED: Workflow execution does not have a Versioning Behavior and is called Unversioned. This is the\nlegacy behavior. An Unversioned workflow's task can go to any Unversioned worker (see\n`WorkerVersioningMode`.)\nUser needs to use Patching to keep the new code compatible with prior versions when dealing\nwith Unversioned workflows.\n - VERSIONING_BEHAVIOR_PINNED: Workflow will start on the Current Deployment Version of its Task Queue, and then\nwill be pinned to that same Deployment Version until completion (the Version that\nthis Workflow is pinned to is specified in `versioning_info.version`).\nThis behavior eliminates most of compatibility concerns users face when changing their code.\nPatching is not needed when pinned workflows code change.\nCan be overridden explicitly via `UpdateWorkflowExecutionOptions` API to move the\nexecution to another Deployment Version.\nActivities of `PINNED` workflows are sent to the same Deployment Version. Exception to this\nwould be when the activity Task Queue workers are not present in the workflow's Deployment\nVersion, in which case the activity will be sent to the Current Deployment Version of its own\ntask queue.\n - VERSIONING_BEHAVIOR_AUTO_UPGRADE: Workflow will automatically move to its Target Version when the next workflow task is dispatched.\nThe workflow's Target Version is the Current Version of its Task Queue, or, if the\nTask Queue has a Ramping Version with non-zero Ramp Percentage `P`, the workflow's Target\nVersion has a P% chance of being the Ramping Version. Whether a workflow falls into the\nP% group depends on it's Workflow ID.\nAutoUpgrade behavior is suitable for long-running workflows as it allows them to move to the\nlatest Deployment Version, but the user still needs to use Patching to keep the new code\ncompatible with prior versions for changed workflow types.\nActivities of `AUTO_UPGRADE` workflows are sent to the Deployment Version of the workflow\nexecution (as specified in versioning_info.version based on the last completed\nworkflow task). Exception to this would be when the activity Task Queue workers are not\npresent in the workflow's Deployment Version, in which case, the activity will be sent to a\ndifferent Deployment Version according to the Current Deployment Version of its own task\nqueue.\nWorkflows stuck on a backlogged activity will still auto-upgrade if the Current Deployment\nVersion of their Task Queue changes, without having to wait for the backlogged activity to\ncomplete on the old Version.\n - VERSIONING_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW: The same semantics as PINNED, with the exception of Continue-As-New.\nWhen a PINNED_UNTIL_CONTINUE_AS_NEW workflow continues-as-new, the new execution\nwill start on the workflow's Target Version, just like an AUTO_UPGRADE workflow." }, "v1VersioningOverride": { "type": "object", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index e2d5e808a..a6dbba6db 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -13219,6 +13219,7 @@ components: - VERSIONING_BEHAVIOR_UNSPECIFIED - VERSIONING_BEHAVIOR_PINNED - VERSIONING_BEHAVIOR_AUTO_UPGRADE + - VERSIONING_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW type: string description: |- Required. @@ -14585,6 +14586,7 @@ components: - VERSIONING_BEHAVIOR_UNSPECIFIED - VERSIONING_BEHAVIOR_PINNED - VERSIONING_BEHAVIOR_AUTO_UPGRADE + - VERSIONING_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW type: string description: |- Versioning behavior determines how the server should treat this execution when workers are @@ -14868,6 +14870,7 @@ components: - VERSIONING_BEHAVIOR_UNSPECIFIED - VERSIONING_BEHAVIOR_PINNED - VERSIONING_BEHAVIOR_AUTO_UPGRADE + - VERSIONING_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW type: string description: |- Versioning behavior sent by the worker that completed this task for this particular workflow diff --git a/temporal/api/enums/v1/workflow.proto b/temporal/api/enums/v1/workflow.proto index eb29d1375..a422b86c1 100644 --- a/temporal/api/enums/v1/workflow.proto +++ b/temporal/api/enums/v1/workflow.proto @@ -145,8 +145,11 @@ enum VersioningBehavior { // Version, in which case the activity will be sent to the Current Deployment Version of its own // task queue. VERSIONING_BEHAVIOR_PINNED = 1; - // Workflow will automatically move to the Current Deployment Version of its Task Queue when the - // next workflow task is dispatched. + // Workflow will automatically move to its Target Version when the next workflow task is dispatched. + // The workflow's Target Version is the Current Version of its Task Queue, or, if the + // Task Queue has a Ramping Version with non-zero Ramp Percentage `P`, the workflow's Target + // Version has a P% chance of being the Ramping Version. Whether a workflow falls into the + // P% group depends on it's Workflow ID. // AutoUpgrade behavior is suitable for long-running workflows as it allows them to move to the // latest Deployment Version, but the user still needs to use Patching to keep the new code // compatible with prior versions for changed workflow types. @@ -160,6 +163,10 @@ enum VersioningBehavior { // Version of their Task Queue changes, without having to wait for the backlogged activity to // complete on the old Version. VERSIONING_BEHAVIOR_AUTO_UPGRADE = 2; + // The same semantics as PINNED, with the exception of Continue-As-New. + // When a PINNED_UNTIL_CONTINUE_AS_NEW workflow continues-as-new, the new execution + // will start on the workflow's Target Version, just like an AUTO_UPGRADE workflow. + VERSIONING_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW = 3; } // ContinueAsNewSuggestedReason specifies why SuggestContinueAsNew is true. @@ -175,7 +182,7 @@ enum ContinueAsNewSuggestedReason { // Workflow Update registry is getting too large. CONTINUE_AS_NEW_SUGGESTED_REASON_UPDATE_REGISTRY_TOO_LARGE = 2; - // Workflow's Worker Deployment has a new Ramping Version, and the workflow's + // Workflow's Worker Deployment has a new Ramping Version, and the workflow's // Versioning Behavior is PinnedUntilContinueAsNew. CONTINUE_AS_NEW_SUGGESTED_REASON_WORKER_DEPLOYMENT_VERSION_CHANGED = 3; } diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index 9c21ed1ed..2b1e6793e 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -635,9 +635,3 @@ message PostResetOperation { UpdateWorkflowOptions update_workflow_options = 2; } } - -// SuggestContinueAsNewSignalInput is the input for the system-defined SuggestContinueAsNew signal. -message SuggestContinueAsNewSignalInput { - temporal.api.enums.v1.ContinueAsNewSuggestedReason continue_as_new_suggested_reason = 1; -} - From 4272db62e14dd6676b1048650cf401498a8e843a Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Thu, 30 Oct 2025 17:20:06 -0700 Subject: [PATCH 05/21] revert whitespace change --- temporal/api/workflow/v1/message.proto | 1 + 1 file changed, 1 insertion(+) diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index 2b1e6793e..1d5737c79 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -635,3 +635,4 @@ message PostResetOperation { UpdateWorkflowOptions update_workflow_options = 2; } } + From e924a55374eff7043690af792d8437215c4809a7 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Thu, 30 Oct 2025 17:21:59 -0700 Subject: [PATCH 06/21] improve language --- openapi/openapiv2.json | 2 +- temporal/api/enums/v1/workflow.proto | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 8032d2fd8..5451eba64 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -16018,7 +16018,7 @@ "VERSIONING_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW" ], "default": "VERSIONING_BEHAVIOR_UNSPECIFIED", - "description": "Versioning Behavior specifies if and how a workflow execution moves between Worker Deployment\nVersions. The Versioning Behavior of a workflow execution is typically specified by the worker\nwho completes the first task of the execution, but is also overridable manually for new and\nexisting workflows (see VersioningOverride).\nExperimental. Worker Deployments are experimental and might significantly change in the future.\n\n - VERSIONING_BEHAVIOR_UNSPECIFIED: Workflow execution does not have a Versioning Behavior and is called Unversioned. This is the\nlegacy behavior. An Unversioned workflow's task can go to any Unversioned worker (see\n`WorkerVersioningMode`.)\nUser needs to use Patching to keep the new code compatible with prior versions when dealing\nwith Unversioned workflows.\n - VERSIONING_BEHAVIOR_PINNED: Workflow will start on the Current Deployment Version of its Task Queue, and then\nwill be pinned to that same Deployment Version until completion (the Version that\nthis Workflow is pinned to is specified in `versioning_info.version`).\nThis behavior eliminates most of compatibility concerns users face when changing their code.\nPatching is not needed when pinned workflows code change.\nCan be overridden explicitly via `UpdateWorkflowExecutionOptions` API to move the\nexecution to another Deployment Version.\nActivities of `PINNED` workflows are sent to the same Deployment Version. Exception to this\nwould be when the activity Task Queue workers are not present in the workflow's Deployment\nVersion, in which case the activity will be sent to the Current Deployment Version of its own\ntask queue.\n - VERSIONING_BEHAVIOR_AUTO_UPGRADE: Workflow will automatically move to its Target Version when the next workflow task is dispatched.\nThe workflow's Target Version is the Current Version of its Task Queue, or, if the\nTask Queue has a Ramping Version with non-zero Ramp Percentage `P`, the workflow's Target\nVersion has a P% chance of being the Ramping Version. Whether a workflow falls into the\nP% group depends on it's Workflow ID.\nAutoUpgrade behavior is suitable for long-running workflows as it allows them to move to the\nlatest Deployment Version, but the user still needs to use Patching to keep the new code\ncompatible with prior versions for changed workflow types.\nActivities of `AUTO_UPGRADE` workflows are sent to the Deployment Version of the workflow\nexecution (as specified in versioning_info.version based on the last completed\nworkflow task). Exception to this would be when the activity Task Queue workers are not\npresent in the workflow's Deployment Version, in which case, the activity will be sent to a\ndifferent Deployment Version according to the Current Deployment Version of its own task\nqueue.\nWorkflows stuck on a backlogged activity will still auto-upgrade if the Current Deployment\nVersion of their Task Queue changes, without having to wait for the backlogged activity to\ncomplete on the old Version.\n - VERSIONING_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW: The same semantics as PINNED, with the exception of Continue-As-New.\nWhen a PINNED_UNTIL_CONTINUE_AS_NEW workflow continues-as-new, the new execution\nwill start on the workflow's Target Version, just like an AUTO_UPGRADE workflow." + "description": "Versioning Behavior specifies if and how a workflow execution moves between Worker Deployment\nVersions. The Versioning Behavior of a workflow execution is typically specified by the worker\nwho completes the first task of the execution, but is also overridable manually for new and\nexisting workflows (see VersioningOverride).\nExperimental. Worker Deployments are experimental and might significantly change in the future.\n\n - VERSIONING_BEHAVIOR_UNSPECIFIED: Workflow execution does not have a Versioning Behavior and is called Unversioned. This is the\nlegacy behavior. An Unversioned workflow's task can go to any Unversioned worker (see\n`WorkerVersioningMode`.)\nUser needs to use Patching to keep the new code compatible with prior versions when dealing\nwith Unversioned workflows.\n - VERSIONING_BEHAVIOR_PINNED: Workflow will start on the Current Deployment Version of its Task Queue, and then\nwill be pinned to that same Deployment Version until completion (the Version that\nthis Workflow is pinned to is specified in `versioning_info.version`).\nThis behavior eliminates most of compatibility concerns users face when changing their code.\nPatching is not needed when pinned workflows code change.\nCan be overridden explicitly via `UpdateWorkflowExecutionOptions` API to move the\nexecution to another Deployment Version.\nActivities of `PINNED` workflows are sent to the same Deployment Version. Exception to this\nwould be when the activity Task Queue workers are not present in the workflow's Deployment\nVersion, in which case the activity will be sent to the Current Deployment Version of its own\ntask queue.\n - VERSIONING_BEHAVIOR_AUTO_UPGRADE: Workflow will automatically move to its Target Version when the next workflow task is dispatched.\nThe workflow's Target Version is the Current Version of its Task Queue, or, if the\nTask Queue has a Ramping Version with non-zero Ramp Percentage `P`, the workflow's Target\nVersion has a P% chance of being the Ramping Version. Whether a workflow falls into the\nRamping group depends on it's Workflow ID and and the Ramp Percentage.\nAutoUpgrade behavior is suitable for long-running workflows as it allows them to move to the\nlatest Deployment Version, but the user still needs to use Patching to keep the new code\ncompatible with prior versions for changed workflow types.\nActivities of `AUTO_UPGRADE` workflows are sent to the Deployment Version of the workflow\nexecution (as specified in versioning_info.version based on the last completed\nworkflow task). Exception to this would be when the activity Task Queue workers are not\npresent in the workflow's Deployment Version, in which case, the activity will be sent to a\ndifferent Deployment Version according to the Current Deployment Version of its own task\nqueue.\nWorkflows stuck on a backlogged activity will still auto-upgrade if the Current Deployment\nVersion of their Task Queue changes, without having to wait for the backlogged activity to\ncomplete on the old Version.\n - VERSIONING_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW: The same semantics as PINNED, with the exception of Continue-As-New.\nWhen a PINNED_UNTIL_CONTINUE_AS_NEW workflow continues-as-new, the new execution\nwill start on the workflow's Target Version, just like an AUTO_UPGRADE workflow." }, "v1VersioningOverride": { "type": "object", diff --git a/temporal/api/enums/v1/workflow.proto b/temporal/api/enums/v1/workflow.proto index a422b86c1..d1462f24d 100644 --- a/temporal/api/enums/v1/workflow.proto +++ b/temporal/api/enums/v1/workflow.proto @@ -149,7 +149,7 @@ enum VersioningBehavior { // The workflow's Target Version is the Current Version of its Task Queue, or, if the // Task Queue has a Ramping Version with non-zero Ramp Percentage `P`, the workflow's Target // Version has a P% chance of being the Ramping Version. Whether a workflow falls into the - // P% group depends on it's Workflow ID. + // Ramping group depends on it's Workflow ID and and the Ramp Percentage. // AutoUpgrade behavior is suitable for long-running workflows as it allows them to move to the // latest Deployment Version, but the user still needs to use Patching to keep the new code // compatible with prior versions for changed workflow types. From d96b797acd0210b6c89035fa697c4d4fa5af2d4b Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Thu, 30 Oct 2025 17:25:59 -0700 Subject: [PATCH 07/21] even more language changes --- openapi/openapiv2.json | 2 +- temporal/api/enums/v1/workflow.proto | 23 +++++++++++++++-------- 2 files changed, 16 insertions(+), 9 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 5451eba64..506b4b7f2 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -16018,7 +16018,7 @@ "VERSIONING_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW" ], "default": "VERSIONING_BEHAVIOR_UNSPECIFIED", - "description": "Versioning Behavior specifies if and how a workflow execution moves between Worker Deployment\nVersions. The Versioning Behavior of a workflow execution is typically specified by the worker\nwho completes the first task of the execution, but is also overridable manually for new and\nexisting workflows (see VersioningOverride).\nExperimental. Worker Deployments are experimental and might significantly change in the future.\n\n - VERSIONING_BEHAVIOR_UNSPECIFIED: Workflow execution does not have a Versioning Behavior and is called Unversioned. This is the\nlegacy behavior. An Unversioned workflow's task can go to any Unversioned worker (see\n`WorkerVersioningMode`.)\nUser needs to use Patching to keep the new code compatible with prior versions when dealing\nwith Unversioned workflows.\n - VERSIONING_BEHAVIOR_PINNED: Workflow will start on the Current Deployment Version of its Task Queue, and then\nwill be pinned to that same Deployment Version until completion (the Version that\nthis Workflow is pinned to is specified in `versioning_info.version`).\nThis behavior eliminates most of compatibility concerns users face when changing their code.\nPatching is not needed when pinned workflows code change.\nCan be overridden explicitly via `UpdateWorkflowExecutionOptions` API to move the\nexecution to another Deployment Version.\nActivities of `PINNED` workflows are sent to the same Deployment Version. Exception to this\nwould be when the activity Task Queue workers are not present in the workflow's Deployment\nVersion, in which case the activity will be sent to the Current Deployment Version of its own\ntask queue.\n - VERSIONING_BEHAVIOR_AUTO_UPGRADE: Workflow will automatically move to its Target Version when the next workflow task is dispatched.\nThe workflow's Target Version is the Current Version of its Task Queue, or, if the\nTask Queue has a Ramping Version with non-zero Ramp Percentage `P`, the workflow's Target\nVersion has a P% chance of being the Ramping Version. Whether a workflow falls into the\nRamping group depends on it's Workflow ID and and the Ramp Percentage.\nAutoUpgrade behavior is suitable for long-running workflows as it allows them to move to the\nlatest Deployment Version, but the user still needs to use Patching to keep the new code\ncompatible with prior versions for changed workflow types.\nActivities of `AUTO_UPGRADE` workflows are sent to the Deployment Version of the workflow\nexecution (as specified in versioning_info.version based on the last completed\nworkflow task). Exception to this would be when the activity Task Queue workers are not\npresent in the workflow's Deployment Version, in which case, the activity will be sent to a\ndifferent Deployment Version according to the Current Deployment Version of its own task\nqueue.\nWorkflows stuck on a backlogged activity will still auto-upgrade if the Current Deployment\nVersion of their Task Queue changes, without having to wait for the backlogged activity to\ncomplete on the old Version.\n - VERSIONING_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW: The same semantics as PINNED, with the exception of Continue-As-New.\nWhen a PINNED_UNTIL_CONTINUE_AS_NEW workflow continues-as-new, the new execution\nwill start on the workflow's Target Version, just like an AUTO_UPGRADE workflow." + "description": "Versioning Behavior specifies if and how a workflow execution moves between Worker Deployment\nVersions. The Versioning Behavior of a workflow execution is typically specified by the worker\nwho completes the first task of the execution, but is also overridable manually for new and\nexisting workflows (see VersioningOverride).\nExperimental. Worker Deployments are experimental and might significantly change in the future.\n\n - VERSIONING_BEHAVIOR_UNSPECIFIED: Workflow execution does not have a Versioning Behavior and is called Unversioned. This is the\nlegacy behavior. An Unversioned workflow's task can go to any Unversioned worker (see\n`WorkerVersioningMode`.)\nUser needs to use Patching to keep the new code compatible with prior versions when dealing\nwith Unversioned workflows.\n - VERSIONING_BEHAVIOR_PINNED: Workflow will start on its Target Version and then will be pinned to that same Deployment\nVersion until completion (the Version that this Workflow is pinned to is specified in\n`versioning_info.version` and is the Pinned Version of the Workflow).\n\nThe workflow's Target Version is the Current Version of its Task Queue, or, if the\nTask Queue has a Ramping Version with non-zero Ramp Percentage `P`, the workflow's Target\nVersion has a P% chance of being the Ramping Version. Whether a workflow falls into the\nRamping group depends on it's Workflow ID and and the Ramp Percentage.\n\nThis behavior eliminates most of compatibility concerns users face when changing their code.\nPatching is not needed when pinned workflows code change.\nCan be overridden explicitly via `UpdateWorkflowExecutionOptions` API to move the\nexecution to another Deployment Version.\nActivities of `PINNED` workflows are sent to the same Deployment Version. Exception to this\nwould be when the activity Task Queue workers are not present in the workflow's Deployment\nVersion, in which case the activity will be sent to the Current Deployment Version of its own\ntask queue.\n - VERSIONING_BEHAVIOR_AUTO_UPGRADE: Workflow will automatically move to its Target Version when the next workflow task is dispatched.\n\nThe workflow's Target Version is the Current Version of its Task Queue, or, if the\nTask Queue has a Ramping Version with non-zero Ramp Percentage `P`, the workflow's Target\nVersion has a P% chance of being the Ramping Version. Whether a workflow falls into the\nRamping group depends on it's Workflow ID and and the Ramp Percentage.\n\nAutoUpgrade behavior is suitable for long-running workflows as it allows them to move to the\nlatest Deployment Version, but the user still needs to use Patching to keep the new code\ncompatible with prior versions for changed workflow types.\nActivities of `AUTO_UPGRADE` workflows are sent to the Deployment Version of the workflow\nexecution (as specified in versioning_info.version based on the last completed\nworkflow task). Exception to this would be when the activity Task Queue workers are not\npresent in the workflow's Deployment Version, in which case, the activity will be sent to a\ndifferent Deployment Version according to the Current or Ramping Deployment Version of its own\nTask Queue.\nWorkflows stuck on a backlogged activity will still auto-upgrade if their Target Version\nchanges, without having to wait for the backlogged activity to complete on the old Version.\n - VERSIONING_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW: The same semantics as PINNED, with the exception of Continue-As-New.\nWhen a PINNED_UNTIL_CONTINUE_AS_NEW workflow continues-as-new, the new execution\nwill start on the workflow's Target Version, just like an AUTO_UPGRADE workflow." }, "v1VersioningOverride": { "type": "object", diff --git a/temporal/api/enums/v1/workflow.proto b/temporal/api/enums/v1/workflow.proto index d1462f24d..dc8c85990 100644 --- a/temporal/api/enums/v1/workflow.proto +++ b/temporal/api/enums/v1/workflow.proto @@ -133,9 +133,15 @@ enum VersioningBehavior { // User needs to use Patching to keep the new code compatible with prior versions when dealing // with Unversioned workflows. VERSIONING_BEHAVIOR_UNSPECIFIED = 0; - // Workflow will start on the Current Deployment Version of its Task Queue, and then - // will be pinned to that same Deployment Version until completion (the Version that - // this Workflow is pinned to is specified in `versioning_info.version`). + // Workflow will start on its Target Version and then will be pinned to that same Deployment + // Version until completion (the Version that this Workflow is pinned to is specified in + // `versioning_info.version` and is the Pinned Version of the Workflow). + // + // The workflow's Target Version is the Current Version of its Task Queue, or, if the + // Task Queue has a Ramping Version with non-zero Ramp Percentage `P`, the workflow's Target + // Version has a P% chance of being the Ramping Version. Whether a workflow falls into the + // Ramping group depends on it's Workflow ID and and the Ramp Percentage. + // // This behavior eliminates most of compatibility concerns users face when changing their code. // Patching is not needed when pinned workflows code change. // Can be overridden explicitly via `UpdateWorkflowExecutionOptions` API to move the @@ -146,10 +152,12 @@ enum VersioningBehavior { // task queue. VERSIONING_BEHAVIOR_PINNED = 1; // Workflow will automatically move to its Target Version when the next workflow task is dispatched. + // // The workflow's Target Version is the Current Version of its Task Queue, or, if the // Task Queue has a Ramping Version with non-zero Ramp Percentage `P`, the workflow's Target // Version has a P% chance of being the Ramping Version. Whether a workflow falls into the // Ramping group depends on it's Workflow ID and and the Ramp Percentage. + // // AutoUpgrade behavior is suitable for long-running workflows as it allows them to move to the // latest Deployment Version, but the user still needs to use Patching to keep the new code // compatible with prior versions for changed workflow types. @@ -157,11 +165,10 @@ enum VersioningBehavior { // execution (as specified in versioning_info.version based on the last completed // workflow task). Exception to this would be when the activity Task Queue workers are not // present in the workflow's Deployment Version, in which case, the activity will be sent to a - // different Deployment Version according to the Current Deployment Version of its own task - // queue. - // Workflows stuck on a backlogged activity will still auto-upgrade if the Current Deployment - // Version of their Task Queue changes, without having to wait for the backlogged activity to - // complete on the old Version. + // different Deployment Version according to the Current or Ramping Deployment Version of its own + // Task Queue. + // Workflows stuck on a backlogged activity will still auto-upgrade if their Target Version + // changes, without having to wait for the backlogged activity to complete on the old Version. VERSIONING_BEHAVIOR_AUTO_UPGRADE = 2; // The same semantics as PINNED, with the exception of Continue-As-New. // When a PINNED_UNTIL_CONTINUE_AS_NEW workflow continues-as-new, the new execution From 154c0aed4f76b932c0ca1ab188176cb4e9ad38a9 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Thu, 30 Oct 2025 17:33:47 -0700 Subject: [PATCH 08/21] talk about suggested in the behavior --- temporal/api/enums/v1/workflow.proto | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/temporal/api/enums/v1/workflow.proto b/temporal/api/enums/v1/workflow.proto index dc8c85990..4b0719e1b 100644 --- a/temporal/api/enums/v1/workflow.proto +++ b/temporal/api/enums/v1/workflow.proto @@ -173,6 +173,10 @@ enum VersioningBehavior { // The same semantics as PINNED, with the exception of Continue-As-New. // When a PINNED_UNTIL_CONTINUE_AS_NEW workflow continues-as-new, the new execution // will start on the workflow's Target Version, just like an AUTO_UPGRADE workflow. + // + // When the Target Version of a PINNED_UNTIL_CONTINUE_AS_NEW workflow is different + // from its Pinned Version, the workflow's continue_as_new_suggested flag will be true, + // so that these workflows can tell when continuing-as-new would cause a version change. VERSIONING_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW = 3; } From e445f2e8e9ecce32b4dd8b1b281eb44c1c739032 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Thu, 30 Oct 2025 17:34:21 -0700 Subject: [PATCH 09/21] make proto --- openapi/openapiv2.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 64a937563..eff4745f9 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -16022,7 +16022,7 @@ "VERSIONING_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW" ], "default": "VERSIONING_BEHAVIOR_UNSPECIFIED", - "description": "Versioning Behavior specifies if and how a workflow execution moves between Worker Deployment\nVersions. The Versioning Behavior of a workflow execution is typically specified by the worker\nwho completes the first task of the execution, but is also overridable manually for new and\nexisting workflows (see VersioningOverride).\nExperimental. Worker Deployments are experimental and might significantly change in the future.\n\n - VERSIONING_BEHAVIOR_UNSPECIFIED: Workflow execution does not have a Versioning Behavior and is called Unversioned. This is the\nlegacy behavior. An Unversioned workflow's task can go to any Unversioned worker (see\n`WorkerVersioningMode`.)\nUser needs to use Patching to keep the new code compatible with prior versions when dealing\nwith Unversioned workflows.\n - VERSIONING_BEHAVIOR_PINNED: Workflow will start on its Target Version and then will be pinned to that same Deployment\nVersion until completion (the Version that this Workflow is pinned to is specified in\n`versioning_info.version` and is the Pinned Version of the Workflow).\n\nThe workflow's Target Version is the Current Version of its Task Queue, or, if the\nTask Queue has a Ramping Version with non-zero Ramp Percentage `P`, the workflow's Target\nVersion has a P% chance of being the Ramping Version. Whether a workflow falls into the\nRamping group depends on it's Workflow ID and and the Ramp Percentage.\n\nThis behavior eliminates most of compatibility concerns users face when changing their code.\nPatching is not needed when pinned workflows code change.\nCan be overridden explicitly via `UpdateWorkflowExecutionOptions` API to move the\nexecution to another Deployment Version.\nActivities of `PINNED` workflows are sent to the same Deployment Version. Exception to this\nwould be when the activity Task Queue workers are not present in the workflow's Deployment\nVersion, in which case the activity will be sent to the Current Deployment Version of its own\ntask queue.\n - VERSIONING_BEHAVIOR_AUTO_UPGRADE: Workflow will automatically move to its Target Version when the next workflow task is dispatched.\n\nThe workflow's Target Version is the Current Version of its Task Queue, or, if the\nTask Queue has a Ramping Version with non-zero Ramp Percentage `P`, the workflow's Target\nVersion has a P% chance of being the Ramping Version. Whether a workflow falls into the\nRamping group depends on it's Workflow ID and and the Ramp Percentage.\n\nAutoUpgrade behavior is suitable for long-running workflows as it allows them to move to the\nlatest Deployment Version, but the user still needs to use Patching to keep the new code\ncompatible with prior versions for changed workflow types.\nActivities of `AUTO_UPGRADE` workflows are sent to the Deployment Version of the workflow\nexecution (as specified in versioning_info.version based on the last completed\nworkflow task). Exception to this would be when the activity Task Queue workers are not\npresent in the workflow's Deployment Version, in which case, the activity will be sent to a\ndifferent Deployment Version according to the Current or Ramping Deployment Version of its own\nTask Queue.\nWorkflows stuck on a backlogged activity will still auto-upgrade if their Target Version\nchanges, without having to wait for the backlogged activity to complete on the old Version.\n - VERSIONING_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW: The same semantics as PINNED, with the exception of Continue-As-New.\nWhen a PINNED_UNTIL_CONTINUE_AS_NEW workflow continues-as-new, the new execution\nwill start on the workflow's Target Version, just like an AUTO_UPGRADE workflow." + "description": "Versioning Behavior specifies if and how a workflow execution moves between Worker Deployment\nVersions. The Versioning Behavior of a workflow execution is typically specified by the worker\nwho completes the first task of the execution, but is also overridable manually for new and\nexisting workflows (see VersioningOverride).\nExperimental. Worker Deployments are experimental and might significantly change in the future.\n\n - VERSIONING_BEHAVIOR_UNSPECIFIED: Workflow execution does not have a Versioning Behavior and is called Unversioned. This is the\nlegacy behavior. An Unversioned workflow's task can go to any Unversioned worker (see\n`WorkerVersioningMode`.)\nUser needs to use Patching to keep the new code compatible with prior versions when dealing\nwith Unversioned workflows.\n - VERSIONING_BEHAVIOR_PINNED: Workflow will start on its Target Version and then will be pinned to that same Deployment\nVersion until completion (the Version that this Workflow is pinned to is specified in\n`versioning_info.version` and is the Pinned Version of the Workflow).\n\nThe workflow's Target Version is the Current Version of its Task Queue, or, if the\nTask Queue has a Ramping Version with non-zero Ramp Percentage `P`, the workflow's Target\nVersion has a P% chance of being the Ramping Version. Whether a workflow falls into the\nRamping group depends on it's Workflow ID and and the Ramp Percentage.\n\nThis behavior eliminates most of compatibility concerns users face when changing their code.\nPatching is not needed when pinned workflows code change.\nCan be overridden explicitly via `UpdateWorkflowExecutionOptions` API to move the\nexecution to another Deployment Version.\nActivities of `PINNED` workflows are sent to the same Deployment Version. Exception to this\nwould be when the activity Task Queue workers are not present in the workflow's Deployment\nVersion, in which case the activity will be sent to the Current Deployment Version of its own\ntask queue.\n - VERSIONING_BEHAVIOR_AUTO_UPGRADE: Workflow will automatically move to its Target Version when the next workflow task is dispatched.\n\nThe workflow's Target Version is the Current Version of its Task Queue, or, if the\nTask Queue has a Ramping Version with non-zero Ramp Percentage `P`, the workflow's Target\nVersion has a P% chance of being the Ramping Version. Whether a workflow falls into the\nRamping group depends on it's Workflow ID and and the Ramp Percentage.\n\nAutoUpgrade behavior is suitable for long-running workflows as it allows them to move to the\nlatest Deployment Version, but the user still needs to use Patching to keep the new code\ncompatible with prior versions for changed workflow types.\nActivities of `AUTO_UPGRADE` workflows are sent to the Deployment Version of the workflow\nexecution (as specified in versioning_info.version based on the last completed\nworkflow task). Exception to this would be when the activity Task Queue workers are not\npresent in the workflow's Deployment Version, in which case, the activity will be sent to a\ndifferent Deployment Version according to the Current or Ramping Deployment Version of its own\nTask Queue.\nWorkflows stuck on a backlogged activity will still auto-upgrade if their Target Version\nchanges, without having to wait for the backlogged activity to complete on the old Version.\n - VERSIONING_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW: The same semantics as PINNED, with the exception of Continue-As-New.\nWhen a PINNED_UNTIL_CONTINUE_AS_NEW workflow continues-as-new, the new execution\nwill start on the workflow's Target Version, just like an AUTO_UPGRADE workflow.\n\nWhen the Target Version of a PINNED_UNTIL_CONTINUE_AS_NEW workflow is different\nfrom its Pinned Version, the workflow's continue_as_new_suggested flag will be true,\nso that these workflows can tell when continuing-as-new would cause a version change." }, "v1VersioningOverride": { "type": "object", From e463cf597084ff70608ebba397c70ac3e0168fd5 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Thu, 30 Oct 2025 17:36:14 -0700 Subject: [PATCH 10/21] fix it's -> its --- openapi/openapiv2.json | 2 +- temporal/api/enums/v1/workflow.proto | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index eff4745f9..23f5e5ab0 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -16022,7 +16022,7 @@ "VERSIONING_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW" ], "default": "VERSIONING_BEHAVIOR_UNSPECIFIED", - "description": "Versioning Behavior specifies if and how a workflow execution moves between Worker Deployment\nVersions. The Versioning Behavior of a workflow execution is typically specified by the worker\nwho completes the first task of the execution, but is also overridable manually for new and\nexisting workflows (see VersioningOverride).\nExperimental. Worker Deployments are experimental and might significantly change in the future.\n\n - VERSIONING_BEHAVIOR_UNSPECIFIED: Workflow execution does not have a Versioning Behavior and is called Unversioned. This is the\nlegacy behavior. An Unversioned workflow's task can go to any Unversioned worker (see\n`WorkerVersioningMode`.)\nUser needs to use Patching to keep the new code compatible with prior versions when dealing\nwith Unversioned workflows.\n - VERSIONING_BEHAVIOR_PINNED: Workflow will start on its Target Version and then will be pinned to that same Deployment\nVersion until completion (the Version that this Workflow is pinned to is specified in\n`versioning_info.version` and is the Pinned Version of the Workflow).\n\nThe workflow's Target Version is the Current Version of its Task Queue, or, if the\nTask Queue has a Ramping Version with non-zero Ramp Percentage `P`, the workflow's Target\nVersion has a P% chance of being the Ramping Version. Whether a workflow falls into the\nRamping group depends on it's Workflow ID and and the Ramp Percentage.\n\nThis behavior eliminates most of compatibility concerns users face when changing their code.\nPatching is not needed when pinned workflows code change.\nCan be overridden explicitly via `UpdateWorkflowExecutionOptions` API to move the\nexecution to another Deployment Version.\nActivities of `PINNED` workflows are sent to the same Deployment Version. Exception to this\nwould be when the activity Task Queue workers are not present in the workflow's Deployment\nVersion, in which case the activity will be sent to the Current Deployment Version of its own\ntask queue.\n - VERSIONING_BEHAVIOR_AUTO_UPGRADE: Workflow will automatically move to its Target Version when the next workflow task is dispatched.\n\nThe workflow's Target Version is the Current Version of its Task Queue, or, if the\nTask Queue has a Ramping Version with non-zero Ramp Percentage `P`, the workflow's Target\nVersion has a P% chance of being the Ramping Version. Whether a workflow falls into the\nRamping group depends on it's Workflow ID and and the Ramp Percentage.\n\nAutoUpgrade behavior is suitable for long-running workflows as it allows them to move to the\nlatest Deployment Version, but the user still needs to use Patching to keep the new code\ncompatible with prior versions for changed workflow types.\nActivities of `AUTO_UPGRADE` workflows are sent to the Deployment Version of the workflow\nexecution (as specified in versioning_info.version based on the last completed\nworkflow task). Exception to this would be when the activity Task Queue workers are not\npresent in the workflow's Deployment Version, in which case, the activity will be sent to a\ndifferent Deployment Version according to the Current or Ramping Deployment Version of its own\nTask Queue.\nWorkflows stuck on a backlogged activity will still auto-upgrade if their Target Version\nchanges, without having to wait for the backlogged activity to complete on the old Version.\n - VERSIONING_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW: The same semantics as PINNED, with the exception of Continue-As-New.\nWhen a PINNED_UNTIL_CONTINUE_AS_NEW workflow continues-as-new, the new execution\nwill start on the workflow's Target Version, just like an AUTO_UPGRADE workflow.\n\nWhen the Target Version of a PINNED_UNTIL_CONTINUE_AS_NEW workflow is different\nfrom its Pinned Version, the workflow's continue_as_new_suggested flag will be true,\nso that these workflows can tell when continuing-as-new would cause a version change." + "description": "Versioning Behavior specifies if and how a workflow execution moves between Worker Deployment\nVersions. The Versioning Behavior of a workflow execution is typically specified by the worker\nwho completes the first task of the execution, but is also overridable manually for new and\nexisting workflows (see VersioningOverride).\nExperimental. Worker Deployments are experimental and might significantly change in the future.\n\n - VERSIONING_BEHAVIOR_UNSPECIFIED: Workflow execution does not have a Versioning Behavior and is called Unversioned. This is the\nlegacy behavior. An Unversioned workflow's task can go to any Unversioned worker (see\n`WorkerVersioningMode`.)\nUser needs to use Patching to keep the new code compatible with prior versions when dealing\nwith Unversioned workflows.\n - VERSIONING_BEHAVIOR_PINNED: Workflow will start on its Target Version and then will be pinned to that same Deployment\nVersion until completion (the Version that this Workflow is pinned to is specified in\n`versioning_info.version` and is the Pinned Version of the Workflow).\n\nThe workflow's Target Version is the Current Version of its Task Queue, or, if the\nTask Queue has a Ramping Version with non-zero Ramp Percentage `P`, the workflow's Target\nVersion has a P% chance of being the Ramping Version. Whether a workflow falls into the\nRamping group depends on its Workflow ID and and the Ramp Percentage.\n\nThis behavior eliminates most of compatibility concerns users face when changing their code.\nPatching is not needed when pinned workflows code change.\nCan be overridden explicitly via `UpdateWorkflowExecutionOptions` API to move the\nexecution to another Deployment Version.\nActivities of `PINNED` workflows are sent to the same Deployment Version. Exception to this\nwould be when the activity Task Queue workers are not present in the workflow's Deployment\nVersion, in which case the activity will be sent to the Current Deployment Version of its own\ntask queue.\n - VERSIONING_BEHAVIOR_AUTO_UPGRADE: Workflow will automatically move to its Target Version when the next workflow task is dispatched.\n\nThe workflow's Target Version is the Current Version of its Task Queue, or, if the\nTask Queue has a Ramping Version with non-zero Ramp Percentage `P`, the workflow's Target\nVersion has a P% chance of being the Ramping Version. Whether a workflow falls into the\nRamping group depends on its Workflow ID and and the Ramp Percentage.\n\nAutoUpgrade behavior is suitable for long-running workflows as it allows them to move to the\nlatest Deployment Version, but the user still needs to use Patching to keep the new code\ncompatible with prior versions for changed workflow types.\nActivities of `AUTO_UPGRADE` workflows are sent to the Deployment Version of the workflow\nexecution (as specified in versioning_info.version based on the last completed\nworkflow task). Exception to this would be when the activity Task Queue workers are not\npresent in the workflow's Deployment Version, in which case, the activity will be sent to a\ndifferent Deployment Version according to the Current or Ramping Deployment Version of its own\nTask Queue.\nWorkflows stuck on a backlogged activity will still auto-upgrade if their Target Version\nchanges, without having to wait for the backlogged activity to complete on the old Version.\n - VERSIONING_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW: The same semantics as PINNED, with the exception of Continue-As-New.\nWhen a PINNED_UNTIL_CONTINUE_AS_NEW workflow continues-as-new, the new execution\nwill start on the workflow's Target Version, just like an AUTO_UPGRADE workflow.\n\nWhen the Target Version of a PINNED_UNTIL_CONTINUE_AS_NEW workflow is different\nfrom its Pinned Version, the workflow's continue_as_new_suggested flag will be true,\nso that these workflows can tell when continuing-as-new would cause a version change." }, "v1VersioningOverride": { "type": "object", diff --git a/temporal/api/enums/v1/workflow.proto b/temporal/api/enums/v1/workflow.proto index 4b0719e1b..a54c89980 100644 --- a/temporal/api/enums/v1/workflow.proto +++ b/temporal/api/enums/v1/workflow.proto @@ -140,7 +140,7 @@ enum VersioningBehavior { // The workflow's Target Version is the Current Version of its Task Queue, or, if the // Task Queue has a Ramping Version with non-zero Ramp Percentage `P`, the workflow's Target // Version has a P% chance of being the Ramping Version. Whether a workflow falls into the - // Ramping group depends on it's Workflow ID and and the Ramp Percentage. + // Ramping group depends on its Workflow ID and and the Ramp Percentage. // // This behavior eliminates most of compatibility concerns users face when changing their code. // Patching is not needed when pinned workflows code change. @@ -156,7 +156,7 @@ enum VersioningBehavior { // The workflow's Target Version is the Current Version of its Task Queue, or, if the // Task Queue has a Ramping Version with non-zero Ramp Percentage `P`, the workflow's Target // Version has a P% chance of being the Ramping Version. Whether a workflow falls into the - // Ramping group depends on it's Workflow ID and and the Ramp Percentage. + // Ramping group depends on its Workflow ID and and the Ramp Percentage. // // AutoUpgrade behavior is suitable for long-running workflows as it allows them to move to the // latest Deployment Version, but the user still needs to use Patching to keep the new code From 9549ed095ef663bd1f2de02d7144cfae7f22909d Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Thu, 30 Oct 2025 17:39:17 -0700 Subject: [PATCH 11/21] more small change --- openapi/openapiv2.json | 4 ++-- openapi/openapiv3.yaml | 3 +-- temporal/api/enums/v1/workflow.proto | 4 ++-- temporal/api/history/v1/message.proto | 3 +-- 4 files changed, 6 insertions(+), 8 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 23f5e5ab0..37f2eea62 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -10658,7 +10658,7 @@ "CONTINUE_AS_NEW_SUGGESTED_REASON_WORKER_DEPLOYMENT_VERSION_CHANGED" ], "default": "CONTINUE_AS_NEW_SUGGESTED_REASON_UNSPECIFIED", - "description": "ContinueAsNewSuggestedReason specifies why SuggestContinueAsNew is true.\n\n - CONTINUE_AS_NEW_SUGGESTED_REASON_UNSPECIFIED: Reason will be Unspecified if the server is not configured to suggest continue as new,\nif the server is not configured to provide a reason for continue as new suggested,\nif continue as new is not suggested, or if the reason is unknown.\n - CONTINUE_AS_NEW_SUGGESTED_REASON_HISTORY_SIZE_TOO_LARGE: Workflow History size is getting too large.\n - CONTINUE_AS_NEW_SUGGESTED_REASON_UPDATE_REGISTRY_TOO_LARGE: Workflow Update registry is getting too large.\n - CONTINUE_AS_NEW_SUGGESTED_REASON_WORKER_DEPLOYMENT_VERSION_CHANGED: Workflow's Worker Deployment has a new Ramping Version, and the workflow's\nVersioning Behavior is PinnedUntilContinueAsNew." + "description": "ContinueAsNewSuggestedReason specifies why SuggestContinueAsNew is true.\n\n - CONTINUE_AS_NEW_SUGGESTED_REASON_UNSPECIFIED: Reason will be Unspecified if the server is not configured to suggest continue as new,\nif the server is not configured to provide a reason for continue as new suggested,\nif continue as new is not suggested, or if the reason is unknown.\n - CONTINUE_AS_NEW_SUGGESTED_REASON_HISTORY_SIZE_TOO_LARGE: Workflow History size is getting too large.\n - CONTINUE_AS_NEW_SUGGESTED_REASON_UPDATE_REGISTRY_TOO_LARGE: Workflow Update registry is getting too large.\n - CONTINUE_AS_NEW_SUGGESTED_REASON_WORKER_DEPLOYMENT_VERSION_CHANGED: Workflow's Target Worker Deployment Version is different from its\nPinned Version and the workflow's Versioning Behavior is PinnedUntilContinueAsNew." }, "v1ContinueAsNewWorkflowExecutionCommandAttributes": { "type": "object", @@ -17534,7 +17534,7 @@ }, "suggestContinueAsNew": { "type": "boolean", - "title": "True if this workflow should continue-as-new soon. Reasons for this could be:\n - History size (in either event count or bytes) is getting large\n - Update registry size is getting large\n - Workflow's Worker Deployment has a new Ramping Version, and the workflow's Versioning Behavior is PinnedUntilContinueAsNew\n - Workflow's Worker Deployment has a new Current Version, and the workflow's Versioning Behavior is PinnedUntilContinueAsNew" + "title": "True if this workflow should continue-as-new soon. Reasons for this could be:\n - History size (in either event count or bytes) is getting large\n - Update registry size is getting large\n - Workflow's Target Version is different from its Pinned Version, and the Versioning Behavior is PinnedUntilContinueAsNew" }, "historySizeBytes": { "type": "string", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index bf2804659..2504349f6 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -15074,8 +15074,7 @@ components: True if this workflow should continue-as-new soon. Reasons for this could be: - History size (in either event count or bytes) is getting large - Update registry size is getting large - - Workflow's Worker Deployment has a new Ramping Version, and the workflow's Versioning Behavior is PinnedUntilContinueAsNew - - Workflow's Worker Deployment has a new Current Version, and the workflow's Versioning Behavior is PinnedUntilContinueAsNew + - Workflow's Target Version is different from its Pinned Version, and the Versioning Behavior is PinnedUntilContinueAsNew historySizeBytes: type: string description: |- diff --git a/temporal/api/enums/v1/workflow.proto b/temporal/api/enums/v1/workflow.proto index a54c89980..135a7f98c 100644 --- a/temporal/api/enums/v1/workflow.proto +++ b/temporal/api/enums/v1/workflow.proto @@ -193,7 +193,7 @@ enum ContinueAsNewSuggestedReason { // Workflow Update registry is getting too large. CONTINUE_AS_NEW_SUGGESTED_REASON_UPDATE_REGISTRY_TOO_LARGE = 2; - // Workflow's Worker Deployment has a new Ramping Version, and the workflow's - // Versioning Behavior is PinnedUntilContinueAsNew. + // Workflow's Target Worker Deployment Version is different from its + // Pinned Version and the workflow's Versioning Behavior is PinnedUntilContinueAsNew. CONTINUE_AS_NEW_SUGGESTED_REASON_WORKER_DEPLOYMENT_VERSION_CHANGED = 3; } diff --git a/temporal/api/history/v1/message.proto b/temporal/api/history/v1/message.proto index 0f7fa54e4..6412cc86f 100644 --- a/temporal/api/history/v1/message.proto +++ b/temporal/api/history/v1/message.proto @@ -238,8 +238,7 @@ message WorkflowTaskStartedEventAttributes { // True if this workflow should continue-as-new soon. Reasons for this could be: // - History size (in either event count or bytes) is getting large // - Update registry size is getting large - // - Workflow's Worker Deployment has a new Ramping Version, and the workflow's Versioning Behavior is PinnedUntilContinueAsNew - // - Workflow's Worker Deployment has a new Current Version, and the workflow's Versioning Behavior is PinnedUntilContinueAsNew + // - Workflow's Target Version is different from its Pinned Version, and the Versioning Behavior is PinnedUntilContinueAsNew bool suggest_continue_as_new = 4; // Total history size in bytes, which the workflow might use to decide when to // continue-as-new regardless of the suggestion. Note that history event count is From 0af2b5a30087fbe5b84ff99989fcc8f0dad5f1c6 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Wed, 26 Nov 2025 14:05:23 -0800 Subject: [PATCH 12/21] respond to comments and populate override options --- temporal/api/enums/v1/workflow.proto | 32 +++++++++++++++----------- temporal/api/history/v1/message.proto | 8 +++---- temporal/api/workflow/v1/message.proto | 11 ++++++++- 3 files changed, 32 insertions(+), 19 deletions(-) diff --git a/temporal/api/enums/v1/workflow.proto b/temporal/api/enums/v1/workflow.proto index 135a7f98c..cdd0463d1 100644 --- a/temporal/api/enums/v1/workflow.proto +++ b/temporal/api/enums/v1/workflow.proto @@ -172,7 +172,11 @@ enum VersioningBehavior { VERSIONING_BEHAVIOR_AUTO_UPGRADE = 2; // The same semantics as PINNED, with the exception of Continue-As-New. // When a PINNED_UNTIL_CONTINUE_AS_NEW workflow continues-as-new, the new execution - // will start on the workflow's Target Version, just like an AUTO_UPGRADE workflow. + // will start on the workflow's Target Version, with AUTO_UPGRADE behavior. + // On the first workflow task completion of the new run, the workflow will assume + // the behavior specified for that workflow type on the Target Version. If that + // behavior is also PINNED_UNTIL_CONTINUE_AS_NEW, the new run will now be pinned to + // that version until the next time it continues-as-new. // // When the Target Version of a PINNED_UNTIL_CONTINUE_AS_NEW workflow is different // from its Pinned Version, the workflow's continue_as_new_suggested flag will be true, @@ -180,20 +184,20 @@ enum VersioningBehavior { VERSIONING_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW = 3; } -// ContinueAsNewSuggestedReason specifies why SuggestContinueAsNew is true. -enum ContinueAsNewSuggestedReason { - // Reason will be Unspecified if the server is not configured to suggest continue as new, - // if the server is not configured to provide a reason for continue as new suggested, - // if continue as new is not suggested, or if the reason is unknown. - CONTINUE_AS_NEW_SUGGESTED_REASON_UNSPECIFIED = 0; +// SuggestContinueAsNewReason specifies why SuggestContinueAsNew is true. +enum SuggestContinueAsNewReason { + SUGGEST_CONTINUE_AS_NEW_REASON_UNSPECIFIED = 0; - // Workflow History size is getting too large. - CONTINUE_AS_NEW_SUGGESTED_REASON_HISTORY_SIZE_TOO_LARGE = 1; + // Workflow History size is getting too large. + SUGGEST_CONTINUE_AS_NEW_REASON_HISTORY_SIZE_TOO_LARGE = 1; - // Workflow Update registry is getting too large. - CONTINUE_AS_NEW_SUGGESTED_REASON_UPDATE_REGISTRY_TOO_LARGE = 2; + // Workflow History event count is getting too large. + SUGGEST_CONTINUE_AS_NEW_REASON_TOO_MANY_HISTORY_EVENTS = 2; - // Workflow's Target Worker Deployment Version is different from its - // Pinned Version and the workflow's Versioning Behavior is PinnedUntilContinueAsNew. - CONTINUE_AS_NEW_SUGGESTED_REASON_WORKER_DEPLOYMENT_VERSION_CHANGED = 3; + // Workflow's count of completed plus in-flight updates is too large. + SUGGEST_CONTINUE_AS_NEW_REASON_TOO_MANY_UPDATES = 3; + + // Workflow's Target Worker Deployment Version is different from its + // Pinned Version and the workflow's Versioning Behavior is PinnedUntilContinueAsNew. + SUGGEST_CONTINUE_AS_NEW_REASON_TARGET_WORKER_DEPLOYMENT_VERSION_CHANGED = 4; } diff --git a/temporal/api/history/v1/message.proto b/temporal/api/history/v1/message.proto index 6412cc86f..43f0490f6 100644 --- a/temporal/api/history/v1/message.proto +++ b/temporal/api/history/v1/message.proto @@ -237,9 +237,12 @@ message WorkflowTaskStartedEventAttributes { string request_id = 3; // True if this workflow should continue-as-new soon. Reasons for this could be: // - History size (in either event count or bytes) is getting large - // - Update registry size is getting large + // - Total number of completed and in-flight updates on the workflow is too large // - Workflow's Target Version is different from its Pinned Version, and the Versioning Behavior is PinnedUntilContinueAsNew bool suggest_continue_as_new = 4; + // The reason that suggest_continue_as_new is true, if it is. + // Unspecified if suggest_continue_as_new is false or if the reason is unknown. + temporal.api.enums.v1.SuggestContinueAsNewReason suggest_continue_as_new_reason = 8; // Total history size in bytes, which the workflow might use to decide when to // continue-as-new regardless of the suggestion. Note that history event count is // just the event id of this event, so we don't include it explicitly here. @@ -251,9 +254,6 @@ message WorkflowTaskStartedEventAttributes { // when rebuilding it from events. // Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv] int64 build_id_redirect_counter = 7 [deprecated = true]; - // The reason that suggest_continue_as_new is true, if it is. - // Unspecified if suggest_continue_as_new is false or if the reason is unknown. - temporal.api.enums.v1.ContinueAsNewSuggestedReason continue_as_new_suggested_reason = 8; } message WorkflowTaskCompletedEventAttributes { diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index 1d5737c79..1a4607778 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -538,8 +538,9 @@ message WorkflowExecutionOptions { // to indicate that it should be mutated. // Pinned overrides are automatically inherited by child workflows, continue-as-new workflows, // workflow retries, and cron workflows. +// TODO(carlydf): How should other types of pinned overrides be inherited? when a PUCAN-override wf continues-as-new, if it inherits an override that is both version and behavior, then it doesn't actually upgrade, which doesn't make sense message VersioningOverride { - // Indicates whether to override the workflow to be AutoUpgrade or Pinned. + // Indicates whether to override the workflow to be AutoUpgrade, Pinned, or PinnedUntilContinueAsNew. oneof override { // Send the next workflow task to the Version specified in the override. PinnedOverride pinned = 3; @@ -576,6 +577,14 @@ message VersioningOverride { PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED = 0; // Override workflow behavior to be Pinned. PINNED_OVERRIDE_BEHAVIOR_PINNED = 1; + // Override workflow behavior to be PinnedUntilContinueAsNew. + PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW = 2; + // If workflow is AutoUpgrade or Unversioned, override workflow behavior to Pinned. + // If workflow is already Pinned or PinnedUntilContinueAsNew, keep existing behavior. + PINNED_OVERRIDE_BEHAVIOR_PINNED_OR_KEEP_EXISTING = 3; + // If workflow is AutoUpgrade or Unversioned, override workflow behavior to PinnedUntilContinueAsNew. + // If workflow is already Pinned or PinnedUntilContinueAsNew, keep existing behavior. + PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW_OR_KEEP_EXISTING = 4; } } From 035e09a6233b94f4d259a4a4e42ecc1cf9d4d843 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Wed, 26 Nov 2025 14:06:49 -0800 Subject: [PATCH 13/21] make proto --- openapi/openapiv2.json | 44 +++++++++++++++++++++++------------------- openapi/openapiv3.yaml | 29 ++++++++++++++++------------ 2 files changed, 41 insertions(+), 32 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 6b3efcb0d..6f943da51 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -7870,10 +7870,13 @@ "type": "string", "enum": [ "PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED", - "PINNED_OVERRIDE_BEHAVIOR_PINNED" + "PINNED_OVERRIDE_BEHAVIOR_PINNED", + "PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW", + "PINNED_OVERRIDE_BEHAVIOR_PINNED_OR_KEEP_EXISTING", + "PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW_OR_KEEP_EXISTING" ], "default": "PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED", - "description": "Used to specify different sub-types of Pinned override that we plan to add in the future.\n\n - PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED: Unspecified.\n - PINNED_OVERRIDE_BEHAVIOR_PINNED: Override workflow behavior to be Pinned." + "description": "Used to specify different sub-types of Pinned override that we plan to add in the future.\n\n - PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED: Unspecified.\n - PINNED_OVERRIDE_BEHAVIOR_PINNED: Override workflow behavior to be Pinned.\n - PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW: Override workflow behavior to be PinnedUntilContinueAsNew.\n - PINNED_OVERRIDE_BEHAVIOR_PINNED_OR_KEEP_EXISTING: If workflow is AutoUpgrade or Unversioned, override workflow behavior to Pinned.\nIf workflow is already Pinned or PinnedUntilContinueAsNew, keep existing behavior.\n - PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW_OR_KEEP_EXISTING: If workflow is AutoUpgrade or Unversioned, override workflow behavior to PinnedUntilContinueAsNew.\nIf workflow is already Pinned or PinnedUntilContinueAsNew, keep existing behavior." }, "WorkerConfigAutoscalingPollerBehavior": { "type": "object", @@ -10786,17 +10789,6 @@ "default": "CONTINUE_AS_NEW_INITIATOR_UNSPECIFIED", "title": "- CONTINUE_AS_NEW_INITIATOR_WORKFLOW: The workflow itself requested to continue as new\n - CONTINUE_AS_NEW_INITIATOR_RETRY: The workflow continued as new because it is retrying\n - CONTINUE_AS_NEW_INITIATOR_CRON_SCHEDULE: The workflow continued as new because cron has triggered a new execution" }, - "v1ContinueAsNewSuggestedReason": { - "type": "string", - "enum": [ - "CONTINUE_AS_NEW_SUGGESTED_REASON_UNSPECIFIED", - "CONTINUE_AS_NEW_SUGGESTED_REASON_HISTORY_SIZE_TOO_LARGE", - "CONTINUE_AS_NEW_SUGGESTED_REASON_UPDATE_REGISTRY_TOO_LARGE", - "CONTINUE_AS_NEW_SUGGESTED_REASON_WORKER_DEPLOYMENT_VERSION_CHANGED" - ], - "default": "CONTINUE_AS_NEW_SUGGESTED_REASON_UNSPECIFIED", - "description": "ContinueAsNewSuggestedReason specifies why SuggestContinueAsNew is true.\n\n - CONTINUE_AS_NEW_SUGGESTED_REASON_UNSPECIFIED: Reason will be Unspecified if the server is not configured to suggest continue as new,\nif the server is not configured to provide a reason for continue as new suggested,\nif continue as new is not suggested, or if the reason is unknown.\n - CONTINUE_AS_NEW_SUGGESTED_REASON_HISTORY_SIZE_TOO_LARGE: Workflow History size is getting too large.\n - CONTINUE_AS_NEW_SUGGESTED_REASON_UPDATE_REGISTRY_TOO_LARGE: Workflow Update registry is getting too large.\n - CONTINUE_AS_NEW_SUGGESTED_REASON_WORKER_DEPLOYMENT_VERSION_CHANGED: Workflow's Target Worker Deployment Version is different from its\nPinned Version and the workflow's Versioning Behavior is PinnedUntilContinueAsNew." - }, "v1ContinueAsNewWorkflowExecutionCommandAttributes": { "type": "object", "properties": { @@ -15450,6 +15442,18 @@ }, "description": "StructuredCalendarSpec describes an event specification relative to the\ncalendar, in a form that's easy to work with programmatically. Each field can\nbe one or more ranges.\nA timestamp matches if at least one range of each field matches the\ncorresponding fields of the timestamp, except for year: if year is missing,\nthat means all years match. For all fields besides year, at least one Range\nmust be present to match anything.\nRelative expressions such as \"last day of the month\" or \"third Monday\" are not currently\nrepresentable; callers must enumerate the concrete days they require." }, + "v1SuggestContinueAsNewReason": { + "type": "string", + "enum": [ + "SUGGEST_CONTINUE_AS_NEW_REASON_UNSPECIFIED", + "SUGGEST_CONTINUE_AS_NEW_REASON_HISTORY_SIZE_TOO_LARGE", + "SUGGEST_CONTINUE_AS_NEW_REASON_TOO_MANY_HISTORY_EVENTS", + "SUGGEST_CONTINUE_AS_NEW_REASON_TOO_MANY_UPDATES", + "SUGGEST_CONTINUE_AS_NEW_REASON_TARGET_WORKER_DEPLOYMENT_VERSION_CHANGED" + ], + "default": "SUGGEST_CONTINUE_AS_NEW_REASON_UNSPECIFIED", + "description": "SuggestContinueAsNewReason specifies why SuggestContinueAsNew is true.\n\n - SUGGEST_CONTINUE_AS_NEW_REASON_HISTORY_SIZE_TOO_LARGE: Workflow History size is getting too large.\n - SUGGEST_CONTINUE_AS_NEW_REASON_TOO_MANY_HISTORY_EVENTS: Workflow History event count is getting too large.\n - SUGGEST_CONTINUE_AS_NEW_REASON_TOO_MANY_UPDATES: Workflow's count of completed plus in-flight updates is too large.\n - SUGGEST_CONTINUE_AS_NEW_REASON_TARGET_WORKER_DEPLOYMENT_VERSION_CHANGED: Workflow's Target Worker Deployment Version is different from its\nPinned Version and the workflow's Versioning Behavior is PinnedUntilContinueAsNew." + }, "v1TaskIdBlock": { "type": "object", "properties": { @@ -16189,7 +16193,7 @@ "VERSIONING_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW" ], "default": "VERSIONING_BEHAVIOR_UNSPECIFIED", - "description": "Versioning Behavior specifies if and how a workflow execution moves between Worker Deployment\nVersions. The Versioning Behavior of a workflow execution is typically specified by the worker\nwho completes the first task of the execution, but is also overridable manually for new and\nexisting workflows (see VersioningOverride).\nExperimental. Worker Deployments are experimental and might significantly change in the future.\n\n - VERSIONING_BEHAVIOR_UNSPECIFIED: Workflow execution does not have a Versioning Behavior and is called Unversioned. This is the\nlegacy behavior. An Unversioned workflow's task can go to any Unversioned worker (see\n`WorkerVersioningMode`.)\nUser needs to use Patching to keep the new code compatible with prior versions when dealing\nwith Unversioned workflows.\n - VERSIONING_BEHAVIOR_PINNED: Workflow will start on its Target Version and then will be pinned to that same Deployment\nVersion until completion (the Version that this Workflow is pinned to is specified in\n`versioning_info.version` and is the Pinned Version of the Workflow).\n\nThe workflow's Target Version is the Current Version of its Task Queue, or, if the\nTask Queue has a Ramping Version with non-zero Ramp Percentage `P`, the workflow's Target\nVersion has a P% chance of being the Ramping Version. Whether a workflow falls into the\nRamping group depends on its Workflow ID and and the Ramp Percentage.\n\nThis behavior eliminates most of compatibility concerns users face when changing their code.\nPatching is not needed when pinned workflows code change.\nCan be overridden explicitly via `UpdateWorkflowExecutionOptions` API to move the\nexecution to another Deployment Version.\nActivities of `PINNED` workflows are sent to the same Deployment Version. Exception to this\nwould be when the activity Task Queue workers are not present in the workflow's Deployment\nVersion, in which case the activity will be sent to the Current Deployment Version of its own\ntask queue.\n - VERSIONING_BEHAVIOR_AUTO_UPGRADE: Workflow will automatically move to its Target Version when the next workflow task is dispatched.\n\nThe workflow's Target Version is the Current Version of its Task Queue, or, if the\nTask Queue has a Ramping Version with non-zero Ramp Percentage `P`, the workflow's Target\nVersion has a P% chance of being the Ramping Version. Whether a workflow falls into the\nRamping group depends on its Workflow ID and and the Ramp Percentage.\n\nAutoUpgrade behavior is suitable for long-running workflows as it allows them to move to the\nlatest Deployment Version, but the user still needs to use Patching to keep the new code\ncompatible with prior versions for changed workflow types.\nActivities of `AUTO_UPGRADE` workflows are sent to the Deployment Version of the workflow\nexecution (as specified in versioning_info.version based on the last completed\nworkflow task). Exception to this would be when the activity Task Queue workers are not\npresent in the workflow's Deployment Version, in which case, the activity will be sent to a\ndifferent Deployment Version according to the Current or Ramping Deployment Version of its own\nTask Queue.\nWorkflows stuck on a backlogged activity will still auto-upgrade if their Target Version\nchanges, without having to wait for the backlogged activity to complete on the old Version.\n - VERSIONING_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW: The same semantics as PINNED, with the exception of Continue-As-New.\nWhen a PINNED_UNTIL_CONTINUE_AS_NEW workflow continues-as-new, the new execution\nwill start on the workflow's Target Version, just like an AUTO_UPGRADE workflow.\n\nWhen the Target Version of a PINNED_UNTIL_CONTINUE_AS_NEW workflow is different\nfrom its Pinned Version, the workflow's continue_as_new_suggested flag will be true,\nso that these workflows can tell when continuing-as-new would cause a version change." + "description": "Versioning Behavior specifies if and how a workflow execution moves between Worker Deployment\nVersions. The Versioning Behavior of a workflow execution is typically specified by the worker\nwho completes the first task of the execution, but is also overridable manually for new and\nexisting workflows (see VersioningOverride).\nExperimental. Worker Deployments are experimental and might significantly change in the future.\n\n - VERSIONING_BEHAVIOR_UNSPECIFIED: Workflow execution does not have a Versioning Behavior and is called Unversioned. This is the\nlegacy behavior. An Unversioned workflow's task can go to any Unversioned worker (see\n`WorkerVersioningMode`.)\nUser needs to use Patching to keep the new code compatible with prior versions when dealing\nwith Unversioned workflows.\n - VERSIONING_BEHAVIOR_PINNED: Workflow will start on its Target Version and then will be pinned to that same Deployment\nVersion until completion (the Version that this Workflow is pinned to is specified in\n`versioning_info.version` and is the Pinned Version of the Workflow).\n\nThe workflow's Target Version is the Current Version of its Task Queue, or, if the\nTask Queue has a Ramping Version with non-zero Ramp Percentage `P`, the workflow's Target\nVersion has a P% chance of being the Ramping Version. Whether a workflow falls into the\nRamping group depends on its Workflow ID and and the Ramp Percentage.\n\nThis behavior eliminates most of compatibility concerns users face when changing their code.\nPatching is not needed when pinned workflows code change.\nCan be overridden explicitly via `UpdateWorkflowExecutionOptions` API to move the\nexecution to another Deployment Version.\nActivities of `PINNED` workflows are sent to the same Deployment Version. Exception to this\nwould be when the activity Task Queue workers are not present in the workflow's Deployment\nVersion, in which case the activity will be sent to the Current Deployment Version of its own\ntask queue.\n - VERSIONING_BEHAVIOR_AUTO_UPGRADE: Workflow will automatically move to its Target Version when the next workflow task is dispatched.\n\nThe workflow's Target Version is the Current Version of its Task Queue, or, if the\nTask Queue has a Ramping Version with non-zero Ramp Percentage `P`, the workflow's Target\nVersion has a P% chance of being the Ramping Version. Whether a workflow falls into the\nRamping group depends on its Workflow ID and and the Ramp Percentage.\n\nAutoUpgrade behavior is suitable for long-running workflows as it allows them to move to the\nlatest Deployment Version, but the user still needs to use Patching to keep the new code\ncompatible with prior versions for changed workflow types.\nActivities of `AUTO_UPGRADE` workflows are sent to the Deployment Version of the workflow\nexecution (as specified in versioning_info.version based on the last completed\nworkflow task). Exception to this would be when the activity Task Queue workers are not\npresent in the workflow's Deployment Version, in which case, the activity will be sent to a\ndifferent Deployment Version according to the Current or Ramping Deployment Version of its own\nTask Queue.\nWorkflows stuck on a backlogged activity will still auto-upgrade if their Target Version\nchanges, without having to wait for the backlogged activity to complete on the old Version.\n - VERSIONING_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW: The same semantics as PINNED, with the exception of Continue-As-New.\nWhen a PINNED_UNTIL_CONTINUE_AS_NEW workflow continues-as-new, the new execution\nwill start on the workflow's Target Version, with AUTO_UPGRADE behavior.\nOn the first workflow task completion of the new run, the workflow will assume\nthe behavior specified for that workflow type on the Target Version. If that\nbehavior is also PINNED_UNTIL_CONTINUE_AS_NEW, the new run will now be pinned to\nthat version until the next time it continues-as-new.\n\nWhen the Target Version of a PINNED_UNTIL_CONTINUE_AS_NEW workflow is different\nfrom its Pinned Version, the workflow's continue_as_new_suggested flag will be true,\nso that these workflows can tell when continuing-as-new would cause a version change." }, "v1VersioningOverride": { "type": "object", @@ -16215,7 +16219,7 @@ "description": "Required if behavior is `PINNED`. Must be absent if behavior is not `PINNED`.\nIdentifies the worker deployment version to pin the workflow to, in the format\n\".\".\nDeprecated. Use `override.pinned.version`." } }, - "description": "Used to override the versioning behavior (and pinned deployment version, if applicable) of a\nspecific workflow execution. If set, takes precedence over the worker-sent values. See\n`WorkflowExecutionInfo.VersioningInfo` for more information. To remove the override, call\n`UpdateWorkflowExecutionOptions` with a null `VersioningOverride`, and use the `update_mask`\nto indicate that it should be mutated.\nPinned overrides are automatically inherited by child workflows, continue-as-new workflows,\nworkflow retries, and cron workflows." + "title": "Used to override the versioning behavior (and pinned deployment version, if applicable) of a\nspecific workflow execution. If set, takes precedence over the worker-sent values. See\n`WorkflowExecutionInfo.VersioningInfo` for more information. To remove the override, call\n`UpdateWorkflowExecutionOptions` with a null `VersioningOverride`, and use the `update_mask`\nto indicate that it should be mutated.\nPinned overrides are automatically inherited by child workflows, continue-as-new workflows,\nworkflow retries, and cron workflows.\nTODO(carlydf): How should other types of pinned overrides be inherited? when a PUCAN-override wf continues-as-new, if it inherits an override that is both version and behavior, then it doesn't actually upgrade, which doesn't make sense" }, "v1WaitPolicy": { "type": "object", @@ -17770,7 +17774,11 @@ }, "suggestContinueAsNew": { "type": "boolean", - "title": "True if this workflow should continue-as-new soon. Reasons for this could be:\n - History size (in either event count or bytes) is getting large\n - Update registry size is getting large\n - Workflow's Target Version is different from its Pinned Version, and the Versioning Behavior is PinnedUntilContinueAsNew" + "title": "True if this workflow should continue-as-new soon. Reasons for this could be:\n - History size (in either event count or bytes) is getting large\n - Total number of completed and in-flight updates on the workflow is too large\n - Workflow's Target Version is different from its Pinned Version, and the Versioning Behavior is PinnedUntilContinueAsNew" + }, + "suggestContinueAsNewReason": { + "$ref": "#/definitions/v1SuggestContinueAsNewReason", + "description": "The reason that suggest_continue_as_new is true, if it is.\nUnspecified if suggest_continue_as_new is false or if the reason is unknown." }, "historySizeBytes": { "type": "string", @@ -17785,10 +17793,6 @@ "type": "string", "format": "int64", "title": "Used by server internally to properly reapply build ID redirects to an execution\nwhen rebuilding it from events.\nDeprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv]" - }, - "continueAsNewSuggestedReason": { - "$ref": "#/definitions/v1ContinueAsNewSuggestedReason", - "description": "The reason that suggest_continue_as_new is true, if it is.\nUnspecified if suggest_continue_as_new is false or if the reason is unknown." } } }, diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 7556554fc..b1ae1f546 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -13436,6 +13436,7 @@ components: to indicate that it should be mutated. Pinned overrides are automatically inherited by child workflows, continue-as-new workflows, workflow retries, and cron workflows. + TODO(carlydf): How should other types of pinned overrides be inherited? when a PUCAN-override wf continues-as-new, if it inherits an override that is both version and behavior, then it doesn't actually upgrade, which doesn't make sense VersioningOverride_PinnedOverride: type: object properties: @@ -13443,6 +13444,9 @@ components: enum: - PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED - PINNED_OVERRIDE_BEHAVIOR_PINNED + - PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW + - PINNED_OVERRIDE_BEHAVIOR_PINNED_OR_KEEP_EXISTING + - PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW_OR_KEEP_EXISTING type: string description: |- Defaults to PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED. @@ -15342,8 +15346,20 @@ components: description: |- True if this workflow should continue-as-new soon. Reasons for this could be: - History size (in either event count or bytes) is getting large - - Update registry size is getting large + - Total number of completed and in-flight updates on the workflow is too large - Workflow's Target Version is different from its Pinned Version, and the Versioning Behavior is PinnedUntilContinueAsNew + suggestContinueAsNewReason: + enum: + - SUGGEST_CONTINUE_AS_NEW_REASON_UNSPECIFIED + - SUGGEST_CONTINUE_AS_NEW_REASON_HISTORY_SIZE_TOO_LARGE + - SUGGEST_CONTINUE_AS_NEW_REASON_TOO_MANY_HISTORY_EVENTS + - SUGGEST_CONTINUE_AS_NEW_REASON_TOO_MANY_UPDATES + - SUGGEST_CONTINUE_AS_NEW_REASON_TARGET_WORKER_DEPLOYMENT_VERSION_CHANGED + type: string + description: |- + The reason that suggest_continue_as_new is true, if it is. + Unspecified if suggest_continue_as_new is false or if the reason is unknown. + format: enum historySizeBytes: type: string description: |- @@ -15362,17 +15378,6 @@ components: Used by server internally to properly reapply build ID redirects to an execution when rebuilding it from events. Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv] - continueAsNewSuggestedReason: - enum: - - CONTINUE_AS_NEW_SUGGESTED_REASON_UNSPECIFIED - - CONTINUE_AS_NEW_SUGGESTED_REASON_HISTORY_SIZE_TOO_LARGE - - CONTINUE_AS_NEW_SUGGESTED_REASON_UPDATE_REGISTRY_TOO_LARGE - - CONTINUE_AS_NEW_SUGGESTED_REASON_WORKER_DEPLOYMENT_VERSION_CHANGED - type: string - description: |- - The reason that suggest_continue_as_new is true, if it is. - Unspecified if suggest_continue_as_new is false or if the reason is unknown. - format: enum WorkflowTaskTimedOutEventAttributes: type: object properties: From 7a7c4b32b6cbe673a28dd6013e8d17a1762a23ba Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Wed, 26 Nov 2025 15:03:27 -0800 Subject: [PATCH 14/21] make PinnedOverride version optional --- openapi/openapiv2.json | 4 ++-- openapi/openapiv3.yaml | 12 +++++++++--- temporal/api/workflow/v1/message.proto | 19 ++++++++++++------- 3 files changed, 23 insertions(+), 12 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 6f943da51..c67003d9f 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -7862,7 +7862,7 @@ }, "version": { "$ref": "#/definitions/v1WorkerDeploymentVersion", - "description": "Required." + "description": "Required if the target workflow is not already pinned to a version.\nIf the target workflow is already pinned to a version and this is omitted,\nthe effective Pinned Version of the workflow will be the non-override pinned\nversion." } } }, @@ -16219,7 +16219,7 @@ "description": "Required if behavior is `PINNED`. Must be absent if behavior is not `PINNED`.\nIdentifies the worker deployment version to pin the workflow to, in the format\n\".\".\nDeprecated. Use `override.pinned.version`." } }, - "title": "Used to override the versioning behavior (and pinned deployment version, if applicable) of a\nspecific workflow execution. If set, takes precedence over the worker-sent values. See\n`WorkflowExecutionInfo.VersioningInfo` for more information. To remove the override, call\n`UpdateWorkflowExecutionOptions` with a null `VersioningOverride`, and use the `update_mask`\nto indicate that it should be mutated.\nPinned overrides are automatically inherited by child workflows, continue-as-new workflows,\nworkflow retries, and cron workflows.\nTODO(carlydf): How should other types of pinned overrides be inherited? when a PUCAN-override wf continues-as-new, if it inherits an override that is both version and behavior, then it doesn't actually upgrade, which doesn't make sense" + "description": "Used to override the versioning behavior (and pinned deployment version, if applicable) of a\nspecific workflow execution. If set, takes precedence over the worker-sent values. See\n`WorkflowExecutionInfo.VersioningInfo` for more information. To remove the override, call\n`UpdateWorkflowExecutionOptions` with a null `VersioningOverride`, and use the `update_mask`\nto indicate that it should be mutated.\nAll types of Pinned overrides are automatically inherited by child workflows, continue-as-new workflows,\nworkflow retries, and cron workflows.\nWhen a workflow with some type of Pinned override and effect versioning behavior PinnedUntilContinueAsNew\ncontinues-as-new, the override version will not be inherited. If you want your workflow to run on the same\nversion across continue-as-new runs, use Pinned behavior, not PinnedUntilContinueAsNew." }, "v1WaitPolicy": { "type": "object", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index b1ae1f546..cd02464a2 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -13434,9 +13434,11 @@ components: `WorkflowExecutionInfo.VersioningInfo` for more information. To remove the override, call `UpdateWorkflowExecutionOptions` with a null `VersioningOverride`, and use the `update_mask` to indicate that it should be mutated. - Pinned overrides are automatically inherited by child workflows, continue-as-new workflows, + All types of Pinned overrides are automatically inherited by child workflows, continue-as-new workflows, workflow retries, and cron workflows. - TODO(carlydf): How should other types of pinned overrides be inherited? when a PUCAN-override wf continues-as-new, if it inherits an override that is both version and behavior, then it doesn't actually upgrade, which doesn't make sense + When a workflow with some type of Pinned override and effect versioning behavior PinnedUntilContinueAsNew + continues-as-new, the override version will not be inherited. If you want your workflow to run on the same + version across continue-as-new runs, use Pinned behavior, not PinnedUntilContinueAsNew. VersioningOverride_PinnedOverride: type: object properties: @@ -13455,7 +13457,11 @@ components: version: allOf: - $ref: '#/components/schemas/WorkerDeploymentVersion' - description: Required. + description: |- + Required if the target workflow is not already pinned to a version. + If the target workflow is already pinned to a version and this is omitted, + the effective Pinned Version of the workflow will be the non-override pinned + version. WaitPolicy: type: object properties: diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index bce5f5102..f9e6fe1cc 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -547,9 +547,11 @@ message WorkflowExecutionOptions { // `WorkflowExecutionInfo.VersioningInfo` for more information. To remove the override, call // `UpdateWorkflowExecutionOptions` with a null `VersioningOverride`, and use the `update_mask` // to indicate that it should be mutated. -// Pinned overrides are automatically inherited by child workflows, continue-as-new workflows, +// All types of Pinned overrides are automatically inherited by child workflows, continue-as-new workflows, // workflow retries, and cron workflows. -// TODO(carlydf): How should other types of pinned overrides be inherited? when a PUCAN-override wf continues-as-new, if it inherits an override that is both version and behavior, then it doesn't actually upgrade, which doesn't make sense +// When a workflow with some type of Pinned override and effect versioning behavior PinnedUntilContinueAsNew +// continues-as-new, the override version will not be inherited. If you want your workflow to run on the same +// version across continue-as-new runs, use Pinned behavior, not PinnedUntilContinueAsNew. message VersioningOverride { // Indicates whether to override the workflow to be AutoUpgrade, Pinned, or PinnedUntilContinueAsNew. oneof override { @@ -578,7 +580,10 @@ message VersioningOverride { // Defaults to PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED. // See `PinnedOverrideBehavior` for details. PinnedOverrideBehavior behavior = 1; - // Required. + // Required if the target workflow is not already pinned to a version. + // If the target workflow is already pinned to a version and this is omitted, + // the effective Pinned Version of the workflow will be the non-override pinned + // version. temporal.api.deployment.v1.WorkerDeploymentVersion version = 2; } @@ -590,11 +595,11 @@ message VersioningOverride { PINNED_OVERRIDE_BEHAVIOR_PINNED = 1; // Override workflow behavior to be PinnedUntilContinueAsNew. PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW = 2; - // If workflow is AutoUpgrade or Unversioned, override workflow behavior to Pinned. - // If workflow is already Pinned or PinnedUntilContinueAsNew, keep existing behavior. + // If workflow is AutoUpgrade or Unversioned, override workflow behavior to Pinned. + // If workflow is already Pinned or PinnedUntilContinueAsNew, keep existing behavior. PINNED_OVERRIDE_BEHAVIOR_PINNED_OR_KEEP_EXISTING = 3; - // If workflow is AutoUpgrade or Unversioned, override workflow behavior to PinnedUntilContinueAsNew. - // If workflow is already Pinned or PinnedUntilContinueAsNew, keep existing behavior. + // If workflow is AutoUpgrade or Unversioned, override workflow behavior to PinnedUntilContinueAsNew. + // If workflow is already Pinned or PinnedUntilContinueAsNew, keep existing behavior. PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW_OR_KEEP_EXISTING = 4; } } From 920567c17e31a7971032bc99297c5f9cdcfff15c Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Sat, 29 Nov 2025 01:27:43 -0800 Subject: [PATCH 15/21] . --- temporal/api/workflow/v1/message.proto | 127 ++++++++++++++----------- 1 file changed, 69 insertions(+), 58 deletions(-) diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index f9e6fe1cc..232e72ac8 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -543,65 +543,76 @@ message WorkflowExecutionOptions { } // Used to override the versioning behavior (and pinned deployment version, if applicable) of a -// specific workflow execution. If set, takes precedence over the worker-sent values. See -// `WorkflowExecutionInfo.VersioningInfo` for more information. To remove the override, call -// `UpdateWorkflowExecutionOptions` with a null `VersioningOverride`, and use the `update_mask` -// to indicate that it should be mutated. -// All types of Pinned overrides are automatically inherited by child workflows, continue-as-new workflows, -// workflow retries, and cron workflows. -// When a workflow with some type of Pinned override and effect versioning behavior PinnedUntilContinueAsNew -// continues-as-new, the override version will not be inherited. If you want your workflow to run on the same -// version across continue-as-new runs, use Pinned behavior, not PinnedUntilContinueAsNew. +// specific workflow execution. If set, this override takes precedence over worker-sent values. +// See `WorkflowExecutionInfo.VersioningInfo` for more information. +// +// To remove the override, call `UpdateWorkflowExecutionOptions` with a null +// `VersioningOverride`, and use the `update_mask` to indicate that it should be mutated. +// +// Pinning behaviors (PINNED and PINNED_UNTIL_CONTINUE_AS_NEW) are automatically inherited +// by child workflows, workflow retries, and cron workflows. +// +// For continue-as-new: +// - PINNED overrides are inherited by the new run. +// - PINNED_UNTIL_CONTINUE_AS_NEW overrides are *not* inherited; after continue-as-new, +// versioning behavior falls back to worker-sent values. message VersioningOverride { - // Indicates whether to override the workflow to be AutoUpgrade, Pinned, or PinnedUntilContinueAsNew. - oneof override { - // Send the next workflow task to the Version specified in the override. - PinnedOverride pinned = 3; - // Send the next workflow task to the Current Deployment Version - // of its Task Queue when the next workflow task is dispatched. - bool auto_upgrade = 4; - } - // Required. - // Deprecated. Use `override`. - temporal.api.enums.v1.VersioningBehavior behavior = 1 [deprecated = true]; - - // Required if behavior is `PINNED`. Must be null if behavior is `AUTO_UPGRADE`. - // Identifies the worker deployment to pin the workflow to. - // Deprecated. Use `override.pinned.version`. - temporal.api.deployment.v1.Deployment deployment = 2 [deprecated = true]; - - // Required if behavior is `PINNED`. Must be absent if behavior is not `PINNED`. - // Identifies the worker deployment version to pin the workflow to, in the format - // ".". - // Deprecated. Use `override.pinned.version`. - string pinned_version = 9 [deprecated = true]; - - message PinnedOverride { - // Defaults to PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED. - // See `PinnedOverrideBehavior` for details. - PinnedOverrideBehavior behavior = 1; - // Required if the target workflow is not already pinned to a version. - // If the target workflow is already pinned to a version and this is omitted, - // the effective Pinned Version of the workflow will be the non-override pinned - // version. - temporal.api.deployment.v1.WorkerDeploymentVersion version = 2; - } - - // Used to specify different sub-types of Pinned override that we plan to add in the future. - enum PinnedOverrideBehavior { - // Unspecified. - PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED = 0; - // Override workflow behavior to be Pinned. - PINNED_OVERRIDE_BEHAVIOR_PINNED = 1; - // Override workflow behavior to be PinnedUntilContinueAsNew. - PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW = 2; - // If workflow is AutoUpgrade or Unversioned, override workflow behavior to Pinned. - // If workflow is already Pinned or PinnedUntilContinueAsNew, keep existing behavior. - PINNED_OVERRIDE_BEHAVIOR_PINNED_OR_KEEP_EXISTING = 3; - // If workflow is AutoUpgrade or Unversioned, override workflow behavior to PinnedUntilContinueAsNew. - // If workflow is already Pinned or PinnedUntilContinueAsNew, keep existing behavior. - PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW_OR_KEEP_EXISTING = 4; - } + // Indicates whether to override the workflow to be AutoUpgrade or use a pinning behavior. + oneof override { + // Override the workflow to use a pinning behavior, optionally specifying a pinned + // deployment version. + PinnedOverride pinned = 3; + + // Override the workflow to use AutoUpgrade. The next workflow task will be sent + // to the current deployment version of the workflow's task queue. + bool auto_upgrade = 4; + } + + // Describes which pinning behavior to apply and, when needed, which WorkerDeploymentVersion to pin to. + message PinnedOverride { + // Defaults to PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED. + // See `PinnedOverrideBehavior` for details. + PinnedOverrideBehavior behavior = 1; + + // Required if the target workflow is not already pinned to a version. + // + // If the target workflow is already using a pinning behavior and this field is omitted, + // the effective pinned version will be the existing pinned version. + temporal.api.deployment.v1.WorkerDeploymentVersion version = 2; + } + + // "Pinning behaviors" refers to behaviors in which a workflow is explicitly assigned + // to a particular version. Currently, the pinning behaviors are: + // - PINNED + // - PINNED_UNTIL_CONTINUE_AS_NEW + // + // `PinnedOverrideBehavior` controls how the override interacts with existing pinning + // behaviors and with workflows that are not currently pinned. + enum PinnedOverrideBehavior { + // Unspecified behavior. + PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED = 0; + + // Force the workflow to use the PINNED pinning behavior, regardless of its current + // versioning behavior. + PINNED_OVERRIDE_BEHAVIOR_PINNED = 1; + + // Force the workflow to use the PINNED_UNTIL_CONTINUE_AS_NEW pinning behavior, + // regardless of its current versioning behavior. + PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW = 2; + + // If the workflow is already using a pinning behavior (PINNED or + // PINNED_UNTIL_CONTINUE_AS_NEW), keep its existing behavior. + // Otherwise, reject the override. + PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING_ELSE_REJECT = 3; + + // If the workflow is already using a pinning behavior, keep its existing behavior. + // Otherwise, apply the PINNED behavior. + PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING_ELSE_PINNED = 4; + + // If the workflow is already using a pinning behavior, keep its existing behavior. + // Otherwise, apply the PINNED_UNTIL_CONTINUE_AS_NEW behavior. + PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING_ELSE_PINNED_UNTIL_CONTINUE_AS_NEW = 5; + } } // When StartWorkflowExecution uses the conflict policy WORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING and From aabc4f82c155b533aa0d1271a6cb4ffb20ac9461 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Sat, 29 Nov 2025 01:28:24 -0800 Subject: [PATCH 16/21] proto --- openapi/openapiv2.json | 31 +++++++------------ openapi/openapiv3.yaml | 67 ++++++++++++++++-------------------------- 2 files changed, 36 insertions(+), 62 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index dc0ecba64..85445d8d6 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -7877,9 +7877,10 @@ }, "version": { "$ref": "#/definitions/v1WorkerDeploymentVersion", - "description": "Required if the target workflow is not already pinned to a version.\nIf the target workflow is already pinned to a version and this is omitted,\nthe effective Pinned Version of the workflow will be the non-override pinned\nversion." + "description": "Required if the target workflow is not already pinned to a version.\n\nIf the target workflow is already using a pinning behavior and this field is omitted,\nthe effective pinned version will be the existing pinned version." } - } + }, + "description": "Describes which pinning behavior to apply and, when needed, which WorkerDeploymentVersion to pin to." }, "VersioningOverridePinnedOverrideBehavior": { "type": "string", @@ -7887,11 +7888,13 @@ "PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED", "PINNED_OVERRIDE_BEHAVIOR_PINNED", "PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW", - "PINNED_OVERRIDE_BEHAVIOR_PINNED_OR_KEEP_EXISTING", - "PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW_OR_KEEP_EXISTING" + "PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING_ELSE_REJECT", + "PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING_ELSE_PINNED", + "PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING_ELSE_PINNED_UNTIL_CONTINUE_AS_NEW" ], "default": "PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED", - "description": "Used to specify different sub-types of Pinned override that we plan to add in the future.\n\n - PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED: Unspecified.\n - PINNED_OVERRIDE_BEHAVIOR_PINNED: Override workflow behavior to be Pinned.\n - PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW: Override workflow behavior to be PinnedUntilContinueAsNew.\n - PINNED_OVERRIDE_BEHAVIOR_PINNED_OR_KEEP_EXISTING: If workflow is AutoUpgrade or Unversioned, override workflow behavior to Pinned.\nIf workflow is already Pinned or PinnedUntilContinueAsNew, keep existing behavior.\n - PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW_OR_KEEP_EXISTING: If workflow is AutoUpgrade or Unversioned, override workflow behavior to PinnedUntilContinueAsNew.\nIf workflow is already Pinned or PinnedUntilContinueAsNew, keep existing behavior." + "description": "`PinnedOverrideBehavior` controls how the override interacts with existing pinning\nbehaviors and with workflows that are not currently pinned.\n\n - PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED: Unspecified behavior.\n - PINNED_OVERRIDE_BEHAVIOR_PINNED: Force the workflow to use the PINNED pinning behavior, regardless of its current\nversioning behavior.\n - PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW: Force the workflow to use the PINNED_UNTIL_CONTINUE_AS_NEW pinning behavior,\nregardless of its current versioning behavior.\n - PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING_ELSE_REJECT: If the workflow is already using a pinning behavior (PINNED or\nPINNED_UNTIL_CONTINUE_AS_NEW), keep its existing behavior.\nOtherwise, reject the override.\n - PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING_ELSE_PINNED: If the workflow is already using a pinning behavior, keep its existing behavior.\nOtherwise, apply the PINNED behavior.\n - PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING_ELSE_PINNED_UNTIL_CONTINUE_AS_NEW: If the workflow is already using a pinning behavior, keep its existing behavior.\nOtherwise, apply the PINNED_UNTIL_CONTINUE_AS_NEW behavior.", + "title": "\"Pinning behaviors\" refers to behaviors in which a workflow is explicitly assigned\nto a particular version. Currently, the pinning behaviors are:\n - PINNED\n - PINNED_UNTIL_CONTINUE_AS_NEW" }, "WorkerConfigAutoscalingPollerBehavior": { "type": "object", @@ -16238,26 +16241,14 @@ "properties": { "pinned": { "$ref": "#/definitions/VersioningOverridePinnedOverride", - "description": "Send the next workflow task to the Version specified in the override." + "description": "Override the workflow to use a pinning behavior, optionally specifying a pinned\ndeployment version." }, "autoUpgrade": { "type": "boolean", - "description": "Send the next workflow task to the Current Deployment Version\nof its Task Queue when the next workflow task is dispatched." - }, - "behavior": { - "$ref": "#/definitions/v1VersioningBehavior", - "description": "Required.\nDeprecated. Use `override`." - }, - "deployment": { - "$ref": "#/definitions/v1Deployment", - "description": "Required if behavior is `PINNED`. Must be null if behavior is `AUTO_UPGRADE`.\nIdentifies the worker deployment to pin the workflow to.\nDeprecated. Use `override.pinned.version`." - }, - "pinnedVersion": { - "type": "string", - "description": "Required if behavior is `PINNED`. Must be absent if behavior is not `PINNED`.\nIdentifies the worker deployment version to pin the workflow to, in the format\n\".\".\nDeprecated. Use `override.pinned.version`." + "description": "Override the workflow to use AutoUpgrade. The next workflow task will be sent\nto the current deployment version of the workflow's task queue." } }, - "description": "Used to override the versioning behavior (and pinned deployment version, if applicable) of a\nspecific workflow execution. If set, takes precedence over the worker-sent values. See\n`WorkflowExecutionInfo.VersioningInfo` for more information. To remove the override, call\n`UpdateWorkflowExecutionOptions` with a null `VersioningOverride`, and use the `update_mask`\nto indicate that it should be mutated.\nAll types of Pinned overrides are automatically inherited by child workflows, continue-as-new workflows,\nworkflow retries, and cron workflows.\nWhen a workflow with some type of Pinned override and effect versioning behavior PinnedUntilContinueAsNew\ncontinues-as-new, the override version will not be inherited. If you want your workflow to run on the same\nversion across continue-as-new runs, use Pinned behavior, not PinnedUntilContinueAsNew." + "description": "Used to override the versioning behavior (and pinned deployment version, if applicable) of a\nspecific workflow execution. If set, this override takes precedence over worker-sent values.\nSee `WorkflowExecutionInfo.VersioningInfo` for more information.\n\nTo remove the override, call `UpdateWorkflowExecutionOptions` with a null\n`VersioningOverride`, and use the `update_mask` to indicate that it should be mutated.\n\nPinning behaviors (PINNED and PINNED_UNTIL_CONTINUE_AS_NEW) are automatically inherited\nby child workflows, workflow retries, and cron workflows.\n\nFor continue-as-new:\n - PINNED overrides are inherited by the new run.\n - PINNED_UNTIL_CONTINUE_AS_NEW overrides are *not* inherited; after continue-as-new,\n versioning behavior falls back to worker-sent values." }, "v1WaitPolicy": { "type": "object", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 7972f5760..7ba330c77 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -13432,48 +13432,29 @@ components: pinned: allOf: - $ref: '#/components/schemas/VersioningOverride_PinnedOverride' - description: Send the next workflow task to the Version specified in the override. + description: |- + Override the workflow to use a pinning behavior, optionally specifying a pinned + deployment version. autoUpgrade: type: boolean description: |- - Send the next workflow task to the Current Deployment Version - of its Task Queue when the next workflow task is dispatched. - behavior: - enum: - - VERSIONING_BEHAVIOR_UNSPECIFIED - - VERSIONING_BEHAVIOR_PINNED - - VERSIONING_BEHAVIOR_AUTO_UPGRADE - - VERSIONING_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW - type: string - description: |- - Required. - Deprecated. Use `override`. - format: enum - deployment: - allOf: - - $ref: '#/components/schemas/Deployment' - description: |- - Required if behavior is `PINNED`. Must be null if behavior is `AUTO_UPGRADE`. - Identifies the worker deployment to pin the workflow to. - Deprecated. Use `override.pinned.version`. - pinnedVersion: - type: string - description: |- - Required if behavior is `PINNED`. Must be absent if behavior is not `PINNED`. - Identifies the worker deployment version to pin the workflow to, in the format - ".". - Deprecated. Use `override.pinned.version`. + Override the workflow to use AutoUpgrade. The next workflow task will be sent + to the current deployment version of the workflow's task queue. description: |- Used to override the versioning behavior (and pinned deployment version, if applicable) of a - specific workflow execution. If set, takes precedence over the worker-sent values. See - `WorkflowExecutionInfo.VersioningInfo` for more information. To remove the override, call - `UpdateWorkflowExecutionOptions` with a null `VersioningOverride`, and use the `update_mask` - to indicate that it should be mutated. - All types of Pinned overrides are automatically inherited by child workflows, continue-as-new workflows, - workflow retries, and cron workflows. - When a workflow with some type of Pinned override and effect versioning behavior PinnedUntilContinueAsNew - continues-as-new, the override version will not be inherited. If you want your workflow to run on the same - version across continue-as-new runs, use Pinned behavior, not PinnedUntilContinueAsNew. + specific workflow execution. If set, this override takes precedence over worker-sent values. + See `WorkflowExecutionInfo.VersioningInfo` for more information. + + To remove the override, call `UpdateWorkflowExecutionOptions` with a null + `VersioningOverride`, and use the `update_mask` to indicate that it should be mutated. + + Pinning behaviors (PINNED and PINNED_UNTIL_CONTINUE_AS_NEW) are automatically inherited + by child workflows, workflow retries, and cron workflows. + + For continue-as-new: + - PINNED overrides are inherited by the new run. + - PINNED_UNTIL_CONTINUE_AS_NEW overrides are *not* inherited; after continue-as-new, + versioning behavior falls back to worker-sent values. VersioningOverride_PinnedOverride: type: object properties: @@ -13482,8 +13463,9 @@ components: - PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED - PINNED_OVERRIDE_BEHAVIOR_PINNED - PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW - - PINNED_OVERRIDE_BEHAVIOR_PINNED_OR_KEEP_EXISTING - - PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW_OR_KEEP_EXISTING + - PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING_ELSE_REJECT + - PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING_ELSE_PINNED + - PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING_ELSE_PINNED_UNTIL_CONTINUE_AS_NEW type: string description: |- Defaults to PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED. @@ -13494,9 +13476,10 @@ components: - $ref: '#/components/schemas/WorkerDeploymentVersion' description: |- Required if the target workflow is not already pinned to a version. - If the target workflow is already pinned to a version and this is omitted, - the effective Pinned Version of the workflow will be the non-override pinned - version. + + If the target workflow is already using a pinning behavior and this field is omitted, + the effective pinned version will be the existing pinned version. + description: Describes which pinning behavior to apply and, when needed, which WorkerDeploymentVersion to pin to. WaitPolicy: type: object properties: From bfe31c8beaee532253385c5b792c2362de8b4f1d Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Sun, 30 Nov 2025 19:35:25 -0800 Subject: [PATCH 17/21] add separate NonPinningPolicy to avoid overloading PinnedOverrideBehavior --- openapi/openapiv2.json | 24 ++++++++++++--- openapi/openapiv3.yaml | 22 ++++++++++++-- temporal/api/workflow/v1/message.proto | 42 +++++++++++++++++++++----- 3 files changed, 72 insertions(+), 16 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 85445d8d6..78c176a90 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -7868,6 +7868,18 @@ }, "description": "Replaces the routing rule with the given source Build ID." }, + "VersioningOverrideNonPinningPolicy": { + "type": "string", + "enum": [ + "NON_PINNING_POLICY_UNSPECIFIED", + "NON_PINNING_POLICY_REJECT", + "NON_PINNING_POLICY_IGNORE", + "NON_PINNING_POLICY_PINNED", + "NON_PINNING_POLICY_PINNED_UNTIL_CONTINUE_AS_NEW" + ], + "default": "NON_PINNING_POLICY_UNSPECIFIED", + "description": "Describes how a Pinning behavior override that keeps original pinning behavior\nshould be applied to workflows that do not have a pinning behavior.\nThis applies to all workflows that have not yet completed their first workflow\ntask, because only after first-workflow-task-completion does the server know the\nbehavior of a workflow execution.\n\n - NON_PINNING_POLICY_UNSPECIFIED: Unspecified.\n - NON_PINNING_POLICY_REJECT: Reject the override at apply time.\n - NON_PINNING_POLICY_IGNORE: Accept the override at apply time, but ignore it for workflows that do not\nhave a pinning behavior. Once a workflow's behavior is known, the override\nwill only affect it if that behavior is a pinning behavior.\n - NON_PINNING_POLICY_PINNED: Use Pinned.\n - NON_PINNING_POLICY_PINNED_UNTIL_CONTINUE_AS_NEW: Use PinnedUntilContinueAsNew." + }, "VersioningOverridePinnedOverride": { "type": "object", "properties": { @@ -7877,7 +7889,11 @@ }, "version": { "$ref": "#/definitions/v1WorkerDeploymentVersion", - "description": "Required if the target workflow is not already pinned to a version.\n\nIf the target workflow is already using a pinning behavior and this field is omitted,\nthe effective pinned version will be the existing pinned version." + "description": "Required if the target workflow is not already pinned to a version.\n\nIf the target workflow is already using a pinning behavior and this field is omitted,\nthe effective pinned version will be the existing pinned version.\n\nIf the target workflow is not using a pinning behavior and this field is omitted,\nthe override request will be rejected." + }, + "ifNotPinning": { + "$ref": "#/definitions/VersioningOverrideNonPinningPolicy", + "description": "Required if behavior is PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING.\nIgnored if behavior is not PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING.\nWe will reject overrides that have PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING PinnedOverrideBehavior\nand UNSPECIFIED NonPinningPolicy before the batch even starts, but if it somehow sneaks in,\nUNSPECIFIED will be treated the same as REJECT." } }, "description": "Describes which pinning behavior to apply and, when needed, which WorkerDeploymentVersion to pin to." @@ -7888,12 +7904,10 @@ "PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED", "PINNED_OVERRIDE_BEHAVIOR_PINNED", "PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW", - "PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING_ELSE_REJECT", - "PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING_ELSE_PINNED", - "PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING_ELSE_PINNED_UNTIL_CONTINUE_AS_NEW" + "PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING" ], "default": "PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED", - "description": "`PinnedOverrideBehavior` controls how the override interacts with existing pinning\nbehaviors and with workflows that are not currently pinned.\n\n - PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED: Unspecified behavior.\n - PINNED_OVERRIDE_BEHAVIOR_PINNED: Force the workflow to use the PINNED pinning behavior, regardless of its current\nversioning behavior.\n - PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW: Force the workflow to use the PINNED_UNTIL_CONTINUE_AS_NEW pinning behavior,\nregardless of its current versioning behavior.\n - PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING_ELSE_REJECT: If the workflow is already using a pinning behavior (PINNED or\nPINNED_UNTIL_CONTINUE_AS_NEW), keep its existing behavior.\nOtherwise, reject the override.\n - PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING_ELSE_PINNED: If the workflow is already using a pinning behavior, keep its existing behavior.\nOtherwise, apply the PINNED behavior.\n - PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING_ELSE_PINNED_UNTIL_CONTINUE_AS_NEW: If the workflow is already using a pinning behavior, keep its existing behavior.\nOtherwise, apply the PINNED_UNTIL_CONTINUE_AS_NEW behavior.", + "description": "`PinnedOverrideBehavior` controls how the override interacts with existing pinning\nbehaviors and with workflows that are not currently pinned.\n\n - PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED: Unspecified behavior.\n - PINNED_OVERRIDE_BEHAVIOR_PINNED: Force the workflow to use the PINNED pinning behavior, regardless of its current\nversioning behavior.\n - PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW: Force the workflow to use the PINNED_UNTIL_CONTINUE_AS_NEW pinning behavior,\nregardless of its current versioning behavior.\n - PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING: If the workflow is already using a pinning behavior (PINNED or\nPINNED_UNTIL_CONTINUE_AS_NEW), keep its existing behavior.\nUse if_not_pinning to specify how to treat other workflows.", "title": "\"Pinning behaviors\" refers to behaviors in which a workflow is explicitly assigned\nto a particular version. Currently, the pinning behaviors are:\n - PINNED\n - PINNED_UNTIL_CONTINUE_AS_NEW" }, "WorkerConfigAutoscalingPollerBehavior": { diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 7ba330c77..63f717d65 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -13463,9 +13463,7 @@ components: - PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED - PINNED_OVERRIDE_BEHAVIOR_PINNED - PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW - - PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING_ELSE_REJECT - - PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING_ELSE_PINNED - - PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING_ELSE_PINNED_UNTIL_CONTINUE_AS_NEW + - PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING type: string description: |- Defaults to PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED. @@ -13479,6 +13477,24 @@ components: If the target workflow is already using a pinning behavior and this field is omitted, the effective pinned version will be the existing pinned version. + + If the target workflow is not using a pinning behavior and this field is omitted, + the override request will be rejected. + ifNotPinning: + enum: + - NON_PINNING_POLICY_UNSPECIFIED + - NON_PINNING_POLICY_REJECT + - NON_PINNING_POLICY_IGNORE + - NON_PINNING_POLICY_PINNED + - NON_PINNING_POLICY_PINNED_UNTIL_CONTINUE_AS_NEW + type: string + description: |- + Required if behavior is PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING. + Ignored if behavior is not PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING. + We will reject overrides that have PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING PinnedOverrideBehavior + and UNSPECIFIED NonPinningPolicy before the batch even starts, but if it somehow sneaks in, + UNSPECIFIED will be treated the same as REJECT. + format: enum description: Describes which pinning behavior to apply and, when needed, which WorkerDeploymentVersion to pin to. WaitPolicy: type: object diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index b3e3ce788..b8c13e264 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -588,7 +588,17 @@ message VersioningOverride { // // If the target workflow is already using a pinning behavior and this field is omitted, // the effective pinned version will be the existing pinned version. + // + // If the target workflow is not using a pinning behavior and this field is omitted, + // the override request will be rejected. temporal.api.deployment.v1.WorkerDeploymentVersion version = 2; + + // Required if behavior is PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING. + // Ignored if behavior is not PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING. + // We will reject overrides that have PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING PinnedOverrideBehavior + // and UNSPECIFIED NonPinningPolicy before the batch even starts, but if it somehow sneaks in, + // UNSPECIFIED will be treated the same as REJECT. + NonPinningPolicy if_not_pinning = 3; } // "Pinning behaviors" refers to behaviors in which a workflow is explicitly assigned @@ -612,16 +622,32 @@ message VersioningOverride { // If the workflow is already using a pinning behavior (PINNED or // PINNED_UNTIL_CONTINUE_AS_NEW), keep its existing behavior. - // Otherwise, reject the override. - PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING_ELSE_REJECT = 3; + // Use if_not_pinning to specify how to treat other workflows. + PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING = 3; + } + + // Describes how a Pinning behavior override that keeps original pinning behavior + // should be applied to workflows that do not have a pinning behavior. + // This applies to all workflows that have not yet completed their first workflow + // task, because only after first-workflow-task-completion does the server know the + // behavior of a workflow execution. + enum NonPinningPolicy { + // Unspecified. + NON_PINNING_POLICY_UNSPECIFIED = 0; + + // Reject the override at apply time. + NON_PINNING_POLICY_REJECT = 1; + + // Accept the override at apply time, but ignore it for workflows that do not + // have a pinning behavior. Once a workflow's behavior is known, the override + // will only affect it if that behavior is a pinning behavior. + NON_PINNING_POLICY_IGNORE = 2; - // If the workflow is already using a pinning behavior, keep its existing behavior. - // Otherwise, apply the PINNED behavior. - PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING_ELSE_PINNED = 4; + // Use Pinned. + NON_PINNING_POLICY_PINNED = 3; - // If the workflow is already using a pinning behavior, keep its existing behavior. - // Otherwise, apply the PINNED_UNTIL_CONTINUE_AS_NEW behavior. - PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING_ELSE_PINNED_UNTIL_CONTINUE_AS_NEW = 5; + // Use PinnedUntilContinueAsNew. + NON_PINNING_POLICY_PINNED_UNTIL_CONTINUE_AS_NEW = 4; } } From d3120856cd3c6e38e900b6e6873b686c7df80f84 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Sun, 30 Nov 2025 19:50:56 -0800 Subject: [PATCH 18/21] put back deprecated fields --- openapi/openapiv2.json | 12 ++++++++++++ openapi/openapiv3.yaml | 25 +++++++++++++++++++++++++ temporal/api/workflow/v1/message.proto | 15 +++++++++++++++ 3 files changed, 52 insertions(+) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 78c176a90..07f7510d5 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -16260,6 +16260,18 @@ "autoUpgrade": { "type": "boolean", "description": "Override the workflow to use AutoUpgrade. The next workflow task will be sent\nto the current deployment version of the workflow's task queue." + }, + "behavior": { + "$ref": "#/definitions/v1VersioningBehavior", + "description": "Required.\nDeprecated. Use `override`." + }, + "deployment": { + "$ref": "#/definitions/v1Deployment", + "description": "Required if behavior is `PINNED`. Must be null if behavior is `AUTO_UPGRADE`.\nIdentifies the worker deployment to pin the workflow to.\nDeprecated. Use `override.pinned.version`." + }, + "pinnedVersion": { + "type": "string", + "description": "Required if behavior is `PINNED`. Must be absent if behavior is not `PINNED`.\nIdentifies the worker deployment version to pin the workflow to, in the format\n\".\".\nDeprecated. Use `override.pinned.version`." } }, "description": "Used to override the versioning behavior (and pinned deployment version, if applicable) of a\nspecific workflow execution. If set, this override takes precedence over worker-sent values.\nSee `WorkflowExecutionInfo.VersioningInfo` for more information.\n\nTo remove the override, call `UpdateWorkflowExecutionOptions` with a null\n`VersioningOverride`, and use the `update_mask` to indicate that it should be mutated.\n\nPinning behaviors (PINNED and PINNED_UNTIL_CONTINUE_AS_NEW) are automatically inherited\nby child workflows, workflow retries, and cron workflows.\n\nFor continue-as-new:\n - PINNED overrides are inherited by the new run.\n - PINNED_UNTIL_CONTINUE_AS_NEW overrides are *not* inherited; after continue-as-new,\n versioning behavior falls back to worker-sent values." diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 63f717d65..9571cfe9c 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -13440,6 +13440,31 @@ components: description: |- Override the workflow to use AutoUpgrade. The next workflow task will be sent to the current deployment version of the workflow's task queue. + behavior: + enum: + - VERSIONING_BEHAVIOR_UNSPECIFIED + - VERSIONING_BEHAVIOR_PINNED + - VERSIONING_BEHAVIOR_AUTO_UPGRADE + - VERSIONING_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW + type: string + description: |- + Required. + Deprecated. Use `override`. + format: enum + deployment: + allOf: + - $ref: '#/components/schemas/Deployment' + description: |- + Required if behavior is `PINNED`. Must be null if behavior is `AUTO_UPGRADE`. + Identifies the worker deployment to pin the workflow to. + Deprecated. Use `override.pinned.version`. + pinnedVersion: + type: string + description: |- + Required if behavior is `PINNED`. Must be absent if behavior is not `PINNED`. + Identifies the worker deployment version to pin the workflow to, in the format + ".". + Deprecated. Use `override.pinned.version`. description: |- Used to override the versioning behavior (and pinned deployment version, if applicable) of a specific workflow execution. If set, this override takes precedence over worker-sent values. diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index b8c13e264..00b27c02c 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -578,6 +578,21 @@ message VersioningOverride { bool auto_upgrade = 4; } + // Required. + // Deprecated. Use `override`. + temporal.api.enums.v1.VersioningBehavior behavior = 1 [deprecated = true]; + + // Required if behavior is `PINNED`. Must be null if behavior is `AUTO_UPGRADE`. + // Identifies the worker deployment to pin the workflow to. + // Deprecated. Use `override.pinned.version`. + temporal.api.deployment.v1.Deployment deployment = 2 [deprecated = true]; + + // Required if behavior is `PINNED`. Must be absent if behavior is not `PINNED`. + // Identifies the worker deployment version to pin the workflow to, in the format + // ".". + // Deprecated. Use `override.pinned.version`. + string pinned_version = 9 [deprecated = true]; + // Describes which pinning behavior to apply and, when needed, which WorkerDeploymentVersion to pin to. message PinnedOverride { // Defaults to PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED. From d45fa3ba83241c7331c6b35d2894d2603247841b Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Sun, 30 Nov 2025 19:53:25 -0800 Subject: [PATCH 19/21] language --- openapi/openapiv2.json | 2 +- openapi/openapiv3.yaml | 2 +- temporal/api/workflow/v1/message.proto | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 07f7510d5..74a16f006 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -16274,7 +16274,7 @@ "description": "Required if behavior is `PINNED`. Must be absent if behavior is not `PINNED`.\nIdentifies the worker deployment version to pin the workflow to, in the format\n\".\".\nDeprecated. Use `override.pinned.version`." } }, - "description": "Used to override the versioning behavior (and pinned deployment version, if applicable) of a\nspecific workflow execution. If set, this override takes precedence over worker-sent values.\nSee `WorkflowExecutionInfo.VersioningInfo` for more information.\n\nTo remove the override, call `UpdateWorkflowExecutionOptions` with a null\n`VersioningOverride`, and use the `update_mask` to indicate that it should be mutated.\n\nPinning behaviors (PINNED and PINNED_UNTIL_CONTINUE_AS_NEW) are automatically inherited\nby child workflows, workflow retries, and cron workflows.\n\nFor continue-as-new:\n - PINNED overrides are inherited by the new run.\n - PINNED_UNTIL_CONTINUE_AS_NEW overrides are *not* inherited; after continue-as-new,\n versioning behavior falls back to worker-sent values." + "description": "Used to override the versioning behavior (and pinned deployment version, if applicable) of a\nspecific workflow execution. If set, this override takes precedence over worker-sent values.\nSee `WorkflowExecutionInfo.VersioningInfo` for more information.\n\nTo remove the override, call `UpdateWorkflowExecutionOptions` with a null\n`VersioningOverride`, and use the `update_mask` to indicate that it should be mutated.\n\nPinning behavior overrides (PINNED and PINNED_UNTIL_CONTINUE_AS_NEW) are automatically inherited\nby child workflows, workflow retries, and cron workflows.\n\nFor continue-as-new:\n - PINNED overrides are inherited by the new run.\n - PINNED_UNTIL_CONTINUE_AS_NEW overrides are *not* inherited; after continue-as-new,\n versioning behavior falls back to worker-sent values." }, "v1WaitPolicy": { "type": "object", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 9571cfe9c..8c46625ee 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -13473,7 +13473,7 @@ components: To remove the override, call `UpdateWorkflowExecutionOptions` with a null `VersioningOverride`, and use the `update_mask` to indicate that it should be mutated. - Pinning behaviors (PINNED and PINNED_UNTIL_CONTINUE_AS_NEW) are automatically inherited + Pinning behavior overrides (PINNED and PINNED_UNTIL_CONTINUE_AS_NEW) are automatically inherited by child workflows, workflow retries, and cron workflows. For continue-as-new: diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index 00b27c02c..ca7111c10 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -559,7 +559,7 @@ message WorkflowExecutionOptions { // To remove the override, call `UpdateWorkflowExecutionOptions` with a null // `VersioningOverride`, and use the `update_mask` to indicate that it should be mutated. // -// Pinning behaviors (PINNED and PINNED_UNTIL_CONTINUE_AS_NEW) are automatically inherited +// Pinning behavior overrides (PINNED and PINNED_UNTIL_CONTINUE_AS_NEW) are automatically inherited // by child workflows, workflow retries, and cron workflows. // // For continue-as-new: From c4e30e4ea48245a38830a92079bdb2bf9efda798 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Sun, 30 Nov 2025 19:56:39 -0800 Subject: [PATCH 20/21] indents --- temporal/api/workflow/v1/message.proto | 192 ++++++++++++------------- 1 file changed, 96 insertions(+), 96 deletions(-) diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index ca7111c10..0f0616001 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -567,103 +567,103 @@ message WorkflowExecutionOptions { // - PINNED_UNTIL_CONTINUE_AS_NEW overrides are *not* inherited; after continue-as-new, // versioning behavior falls back to worker-sent values. message VersioningOverride { - // Indicates whether to override the workflow to be AutoUpgrade or use a pinning behavior. - oneof override { - // Override the workflow to use a pinning behavior, optionally specifying a pinned - // deployment version. - PinnedOverride pinned = 3; - - // Override the workflow to use AutoUpgrade. The next workflow task will be sent - // to the current deployment version of the workflow's task queue. - bool auto_upgrade = 4; - } - - // Required. - // Deprecated. Use `override`. - temporal.api.enums.v1.VersioningBehavior behavior = 1 [deprecated = true]; - - // Required if behavior is `PINNED`. Must be null if behavior is `AUTO_UPGRADE`. - // Identifies the worker deployment to pin the workflow to. - // Deprecated. Use `override.pinned.version`. - temporal.api.deployment.v1.Deployment deployment = 2 [deprecated = true]; - - // Required if behavior is `PINNED`. Must be absent if behavior is not `PINNED`. - // Identifies the worker deployment version to pin the workflow to, in the format - // ".". - // Deprecated. Use `override.pinned.version`. - string pinned_version = 9 [deprecated = true]; - - // Describes which pinning behavior to apply and, when needed, which WorkerDeploymentVersion to pin to. - message PinnedOverride { - // Defaults to PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED. - // See `PinnedOverrideBehavior` for details. - PinnedOverrideBehavior behavior = 1; - - // Required if the target workflow is not already pinned to a version. - // - // If the target workflow is already using a pinning behavior and this field is omitted, - // the effective pinned version will be the existing pinned version. + // Indicates whether to override the workflow to be AutoUpgrade or use a pinning behavior. + oneof override { + // Override the workflow to use a pinning behavior, optionally specifying a pinned + // deployment version. + PinnedOverride pinned = 3; + + // Override the workflow to use AutoUpgrade. The next workflow task will be sent + // to the current deployment version of the workflow's task queue. + bool auto_upgrade = 4; + } + + // Required. + // Deprecated. Use `override`. + temporal.api.enums.v1.VersioningBehavior behavior = 1 [deprecated = true]; + + // Required if behavior is `PINNED`. Must be null if behavior is `AUTO_UPGRADE`. + // Identifies the worker deployment to pin the workflow to. + // Deprecated. Use `override.pinned.version`. + temporal.api.deployment.v1.Deployment deployment = 2 [deprecated = true]; + + // Required if behavior is `PINNED`. Must be absent if behavior is not `PINNED`. + // Identifies the worker deployment version to pin the workflow to, in the format + // ".". + // Deprecated. Use `override.pinned.version`. + string pinned_version = 9 [deprecated = true]; + + // Describes which pinning behavior to apply and, when needed, which WorkerDeploymentVersion to pin to. + message PinnedOverride { + // Defaults to PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED. + // See `PinnedOverrideBehavior` for details. + PinnedOverrideBehavior behavior = 1; + + // Required if the target workflow is not already pinned to a version. + // + // If the target workflow is already using a pinning behavior and this field is omitted, + // the effective pinned version will be the existing pinned version. + // + // If the target workflow is not using a pinning behavior and this field is omitted, + // the override request will be rejected. + temporal.api.deployment.v1.WorkerDeploymentVersion version = 2; + + // Required if behavior is PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING. + // Ignored if behavior is not PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING. + // We will reject overrides that have PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING PinnedOverrideBehavior + // and UNSPECIFIED NonPinningPolicy before the batch even starts, but if it somehow sneaks in, + // UNSPECIFIED will be treated the same as REJECT. + NonPinningPolicy if_not_pinning = 3; + } + + // "Pinning behaviors" refers to behaviors in which a workflow is explicitly assigned + // to a particular version. Currently, the pinning behaviors are: + // - PINNED + // - PINNED_UNTIL_CONTINUE_AS_NEW // - // If the target workflow is not using a pinning behavior and this field is omitted, - // the override request will be rejected. - temporal.api.deployment.v1.WorkerDeploymentVersion version = 2; - - // Required if behavior is PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING. - // Ignored if behavior is not PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING. - // We will reject overrides that have PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING PinnedOverrideBehavior - // and UNSPECIFIED NonPinningPolicy before the batch even starts, but if it somehow sneaks in, - // UNSPECIFIED will be treated the same as REJECT. - NonPinningPolicy if_not_pinning = 3; - } - - // "Pinning behaviors" refers to behaviors in which a workflow is explicitly assigned - // to a particular version. Currently, the pinning behaviors are: - // - PINNED - // - PINNED_UNTIL_CONTINUE_AS_NEW - // - // `PinnedOverrideBehavior` controls how the override interacts with existing pinning - // behaviors and with workflows that are not currently pinned. - enum PinnedOverrideBehavior { - // Unspecified behavior. - PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED = 0; - - // Force the workflow to use the PINNED pinning behavior, regardless of its current - // versioning behavior. - PINNED_OVERRIDE_BEHAVIOR_PINNED = 1; - - // Force the workflow to use the PINNED_UNTIL_CONTINUE_AS_NEW pinning behavior, - // regardless of its current versioning behavior. - PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW = 2; - - // If the workflow is already using a pinning behavior (PINNED or - // PINNED_UNTIL_CONTINUE_AS_NEW), keep its existing behavior. - // Use if_not_pinning to specify how to treat other workflows. - PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING = 3; - } - - // Describes how a Pinning behavior override that keeps original pinning behavior - // should be applied to workflows that do not have a pinning behavior. - // This applies to all workflows that have not yet completed their first workflow - // task, because only after first-workflow-task-completion does the server know the - // behavior of a workflow execution. - enum NonPinningPolicy { - // Unspecified. - NON_PINNING_POLICY_UNSPECIFIED = 0; - - // Reject the override at apply time. - NON_PINNING_POLICY_REJECT = 1; - - // Accept the override at apply time, but ignore it for workflows that do not - // have a pinning behavior. Once a workflow's behavior is known, the override - // will only affect it if that behavior is a pinning behavior. - NON_PINNING_POLICY_IGNORE = 2; - - // Use Pinned. - NON_PINNING_POLICY_PINNED = 3; - - // Use PinnedUntilContinueAsNew. - NON_PINNING_POLICY_PINNED_UNTIL_CONTINUE_AS_NEW = 4; - } + // `PinnedOverrideBehavior` controls how the override interacts with existing pinning + // behaviors and with workflows that are not currently pinned. + enum PinnedOverrideBehavior { + // Unspecified behavior. + PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED = 0; + + // Force the workflow to use the PINNED pinning behavior, regardless of its current + // versioning behavior. + PINNED_OVERRIDE_BEHAVIOR_PINNED = 1; + + // Force the workflow to use the PINNED_UNTIL_CONTINUE_AS_NEW pinning behavior, + // regardless of its current versioning behavior. + PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW = 2; + + // If the workflow is already using a pinning behavior (PINNED or + // PINNED_UNTIL_CONTINUE_AS_NEW), keep its existing behavior. + // Use if_not_pinning to specify how to treat other workflows. + PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING = 3; + } + + // Describes how a Pinning behavior override that keeps original pinning behavior + // should be applied to workflows that do not have a pinning behavior. + // This applies to all workflows that have not yet completed their first workflow + // task, because only after first-workflow-task-completion does the server know the + // behavior of a workflow execution. + enum NonPinningPolicy { + // Unspecified. + NON_PINNING_POLICY_UNSPECIFIED = 0; + + // Reject the override at apply time. + NON_PINNING_POLICY_REJECT = 1; + + // Accept the override at apply time, but ignore it for workflows that do not + // have a pinning behavior. Once a workflow's behavior is known, the override + // will only affect it if that behavior is a pinning behavior. + NON_PINNING_POLICY_IGNORE = 2; + + // Use Pinned. + NON_PINNING_POLICY_PINNED = 3; + + // Use PinnedUntilContinueAsNew. + NON_PINNING_POLICY_PINNED_UNTIL_CONTINUE_AS_NEW = 4; + } } // When StartWorkflowExecution uses the conflict policy WORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING and From ffda305628dfba1be1dee6dade70630bd7b2ecef Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Mon, 1 Dec 2025 02:38:20 -0800 Subject: [PATCH 21/21] reasons list --- openapi/openapiv2.json | 9 ++++++--- openapi/openapiv3.yaml | 24 +++++++++++++----------- temporal/api/history/v1/message.proto | 6 +++--- 3 files changed, 22 insertions(+), 17 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 74a16f006..d8312bd36 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -17843,9 +17843,12 @@ "type": "boolean", "title": "True if this workflow should continue-as-new soon. Reasons for this could be:\n - History size (in either event count or bytes) is getting large\n - Total number of completed and in-flight updates on the workflow is too large\n - Workflow's Target Version is different from its Pinned Version, and the Versioning Behavior is PinnedUntilContinueAsNew" }, - "suggestContinueAsNewReason": { - "$ref": "#/definitions/v1SuggestContinueAsNewReason", - "description": "The reason that suggest_continue_as_new is true, if it is.\nUnspecified if suggest_continue_as_new is false or if the reason is unknown." + "suggestContinueAsNewReasons": { + "type": "array", + "items": { + "$ref": "#/definitions/v1SuggestContinueAsNewReason" + }, + "description": "The reason(s) that suggest_continue_as_new is true, if it is.\nNil if suggest_continue_as_new is false." }, "historySizeBytes": { "type": "string", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 8c46625ee..7c7b6ccf0 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -15431,18 +15431,20 @@ components: - History size (in either event count or bytes) is getting large - Total number of completed and in-flight updates on the workflow is too large - Workflow's Target Version is different from its Pinned Version, and the Versioning Behavior is PinnedUntilContinueAsNew - suggestContinueAsNewReason: - enum: - - SUGGEST_CONTINUE_AS_NEW_REASON_UNSPECIFIED - - SUGGEST_CONTINUE_AS_NEW_REASON_HISTORY_SIZE_TOO_LARGE - - SUGGEST_CONTINUE_AS_NEW_REASON_TOO_MANY_HISTORY_EVENTS - - SUGGEST_CONTINUE_AS_NEW_REASON_TOO_MANY_UPDATES - - SUGGEST_CONTINUE_AS_NEW_REASON_TARGET_WORKER_DEPLOYMENT_VERSION_CHANGED - type: string + suggestContinueAsNewReasons: + type: array + items: + enum: + - SUGGEST_CONTINUE_AS_NEW_REASON_UNSPECIFIED + - SUGGEST_CONTINUE_AS_NEW_REASON_HISTORY_SIZE_TOO_LARGE + - SUGGEST_CONTINUE_AS_NEW_REASON_TOO_MANY_HISTORY_EVENTS + - SUGGEST_CONTINUE_AS_NEW_REASON_TOO_MANY_UPDATES + - SUGGEST_CONTINUE_AS_NEW_REASON_TARGET_WORKER_DEPLOYMENT_VERSION_CHANGED + type: string + format: enum description: |- - The reason that suggest_continue_as_new is true, if it is. - Unspecified if suggest_continue_as_new is false or if the reason is unknown. - format: enum + The reason(s) that suggest_continue_as_new is true, if it is. + Nil if suggest_continue_as_new is false. historySizeBytes: type: string description: |- diff --git a/temporal/api/history/v1/message.proto b/temporal/api/history/v1/message.proto index c2d2e9a6f..0fb268183 100644 --- a/temporal/api/history/v1/message.proto +++ b/temporal/api/history/v1/message.proto @@ -275,9 +275,9 @@ message WorkflowTaskStartedEventAttributes { // - Total number of completed and in-flight updates on the workflow is too large // - Workflow's Target Version is different from its Pinned Version, and the Versioning Behavior is PinnedUntilContinueAsNew bool suggest_continue_as_new = 4; - // The reason that suggest_continue_as_new is true, if it is. - // Unspecified if suggest_continue_as_new is false or if the reason is unknown. - temporal.api.enums.v1.SuggestContinueAsNewReason suggest_continue_as_new_reason = 8; + // The reason(s) that suggest_continue_as_new is true, if it is. + // Nil if suggest_continue_as_new is false. + repeated temporal.api.enums.v1.SuggestContinueAsNewReason suggest_continue_as_new_reasons = 8; // Total history size in bytes, which the workflow might use to decide when to // continue-as-new regardless of the suggestion. Note that history event count is // just the event id of this event, so we don't include it explicitly here.