Add `PINNED_UNTIL_CONTINUE_AS_NEW` behavior and `CONTINUE_AS_NEW_SUGGESTED_REASON` #657

carlydf · 2025-10-31T00:27:22Z

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

Add PINNED_UNTIL_CONTINUE_AS_NEW behavior and CONTINUE_AS_NEW_SUGGESTED_REASON

So that long running workflows can take advantage of workflow pinning, for the small price of doing Continue-As-New

No, all additive

This does not break the server, since it only adds enums, so it can be merged whenever.

…nput

…nue-as-new-signal

temporal/api/enums/v1/workflow.proto

cretz · 2025-10-31T17:08:13Z

temporal/api/enums/v1/workflow.proto

+  // Workflow History size is getting too large.
+  CONTINUE_AS_NEW_SUGGESTED_REASON_HISTORY_SIZE_TOO_LARGE = 1;


If I understand correctly, there is "length too large" and "size too large". Is that correct? If so, we can either collapse this into one by removing the SIZE_ part of this enum, or we can separate the enums.

Yeah, I vote for separating them. Users using external object storage will hit the length limit but not the size, and they may wonder, "I thought using external storage was supposed to fix my workflow history problems!"

yes, the existing history related continue as new suggestion options are based on: limit.historySize.suggestContinueAsNew, limit.historyCount.suggestContinueAsNew, and history.maxTotalUpdates.suggestContinueAsNewThreshold, where the maxTotalUpdates one is about count, not size

So can we have CONTINUE_AS_NEW_SUGGESTED_REASON_HISTORY_SIZE_TOO_LARGE and CONTINUE_AS_NEW_SUGGESTED_REASON_HISTORY_COUNT_TOO_LARGE as independent enum values here? Or if both reasons must be represented as a single enum value, can it be called CONTINUE_AS_NEW_SUGGESTED_REASON_HISTORY_TOO_LARGE instead?

we can separate it. The place in history where we decide to suggest CaN can tell which one it is

cretz · 2025-10-31T17:56:21Z

temporal/api/enums/v1/workflow.proto

+  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;


Does this already exist today? I can't find the docs on it, but just want to understand it a bit

We document the update limit here: https://docs.temporal.io/workflow-execution/event#event-history-limits

drewhoskins-temporal · 2025-10-31T18:18:14Z

openapi/openapiv3.yaml

+          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


Let's not introduce the term "registry" since it's an implementation detail.
Would "too many updates" be sufficiently accurate?

yes, "too many updates" is accurate and concise!

drewhoskins-temporal · 2025-10-31T18:19:47Z

openapi/openapiv3.yaml

+            - 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


TARGET_WORKER... since we've now documented that?

drewhoskins-temporal · 2025-10-31T18:21:21Z

temporal/api/enums/v1/workflow.proto

+  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;


We document the update limit here: https://docs.temporal.io/workflow-execution/event#event-history-limits

drewhoskins-temporal · 2025-10-31T18:24:23Z

temporal/api/enums/v1/workflow.proto

+  // Workflow History size is getting too large.
+  CONTINUE_AS_NEW_SUGGESTED_REASON_HISTORY_SIZE_TOO_LARGE = 1;


Yeah, I vote for separating them. Users using external object storage will hit the length limit but not the size, and they may wonder, "I thought using external storage was supposed to fix my workflow history problems!"

Sushisource · 2025-10-31T00:31:22Z

temporal/api/history/v1/message.proto

-    // 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


What is an update registry?

dnr · 2025-11-21T01:18:12Z

temporal/api/history/v1/message.proto

+    // 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;


put this right underneath suggest_continue_as_new, since they're semantically related

dnr · 2025-11-21T01:21:47Z

temporal/api/enums/v1/workflow.proto

+// 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,


there's no configuration, right? it's just whether it's a new enough server version to set this field. and if suggest_continue_as_new is false then no one should look at this. I think we don't really need a comment on the unspecified value.

dnr · 2025-11-21T01:24:34Z

temporal/api/history/v1/message.proto

    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;


the word order switch throws me off every time. can we name this suggest_continue_as_new_reason / SuggestContinueAsNewReason to line up with the existing field?

dnr · 2025-11-21T01:27:40Z

temporal/api/history/v1/message.proto

    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;


this could be too sneaky, but it would be wire-compatible to actually just change the existing bool field to this enum: previous clients would read any non-zero value as true

innteresting.. I'm curious on @Sushisource thoughts on this

I'm fine with that. Fewer redundant fields the better.

The PR was updated to make this now a repeated and therefore may not be wire compatible (unsure, didn't dig into internals)

ShahabT · 2025-11-24T21:08:57Z

temporal/api/enums/v1/workflow.proto

    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.


Probably better to rephrase this to say the new run will start with AU behavior, and then takes the behavior specified on the Target Version (likely PUCAN again). Because that's what happens really.

…nue-as-new-signal

…vior

cretz

LGTM from a "suggest continue as new reason", but will defer to others on the versioning aspect

cretz · 2025-12-01T16:12:31Z

temporal/api/history/v1/message.proto

+    //   - Workflow's Target Version is different from its Pinned Version, and the Versioning Behavior is PinnedUntilContinueAsNew
    bool suggest_continue_as_new = 4;
+    // The reason(s) that suggest_continue_as_new is true, if it is.
+    // Nil if suggest_continue_as_new is false.


Pedantic, but this can't be "nil" in the traditional sense, more like "unset"/"empty"

carlydf and others added 9 commits October 10, 2025 20:06

add ContinueAsNewSuggestedReason enum and SuggestContinueAsNewSignalI…

4890840

…nput

simplify can-reason

b8e8ddf

Merge branch 'master' of github.com:temporalio/api into suggest-conti…

3042685

…nue-as-new-signal

make proto

f1423de

Merge branch 'master' of github.com:temporalio/api into suggest-conti…

487527e

…nue-as-new-signal

add behavior and remove special signaL

20f6ece

revert whitespace change

4272db6

improve language

e924a55

even more language changes

d96b797

carlydf requested review from a team as code owners October 31, 2025 00:27

carlydf added 5 commits October 30, 2025 17:33

talk about suggested in the behavior

154c0ae

Merge branch 'master' of github.com:temporalio/api into suggest-conti…

393652b

…nue-as-new-signal

make proto

e445f2e

fix it's -> its

e463cf5

more small change

9549ed0

cretz reviewed Oct 31, 2025

View reviewed changes

drewhoskins-temporal reviewed Oct 31, 2025

View reviewed changes

Sushisource reviewed Oct 31, 2025

View reviewed changes

dnr reviewed Nov 21, 2025

View reviewed changes

ShahabT reviewed Nov 24, 2025

View reviewed changes

carlydf added 9 commits November 26, 2025 14:05

respond to comments and populate override options

0af2b5a

Merge branch 'master' of github.com:temporalio/api into suggest-conti…

8d52d2e

…nue-as-new-signal

make proto

035e09a

make PinnedOverride version optional

7a7c4b3

.

920567c

Merge branch 'master' of github.com:temporalio/api into suggest-conti…

2ff986c

…nue-as-new-signal

proto

aabc4f8

add separate NonPinningPolicy to avoid overloading PinnedOverrideBeha…

bfe31c8

…vior

put back deprecated fields

d312085

carlydf added 3 commits November 30, 2025 19:53

language

d45fa3b

indents

c4e30e4

reasons list

ffda305

cretz approved these changes Dec 1, 2025

View reviewed changes

		// Workflow History size is getting too large.
		CONTINUE_AS_NEW_SUGGESTED_REASON_HISTORY_SIZE_TOO_LARGE = 1;

Add PINNED_UNTIL_CONTINUE_AS_NEW behavior and CONTINUE_AS_NEW_SUGGESTED_REASON #657

Are you sure you want to change the base?

Add PINNED_UNTIL_CONTINUE_AS_NEW behavior and CONTINUE_AS_NEW_SUGGESTED_REASON #657

Uh oh!

Conversation

carlydf commented Oct 31, 2025

Uh oh!

Uh oh!

cretz Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

carlydf Nov 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cretz Nov 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cretz Dec 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cretz left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

Add `PINNED_UNTIL_CONTINUE_AS_NEW` behavior and `CONTINUE_AS_NEW_SUGGESTED_REASON` #657

Add `PINNED_UNTIL_CONTINUE_AS_NEW` behavior and `CONTINUE_AS_NEW_SUGGESTED_REASON` #657

cretz Oct 31, 2025 •

edited

Loading

carlydf Nov 21, 2025 •

edited

Loading

cretz Nov 21, 2025 •

edited

Loading

cretz Dec 1, 2025 •

edited

Loading