add detailed explanation of in-flight work which will impact time-skipping, and change event name

Author: feiyang3cat

openapi/openapiv2.json

@@ -10157,7 +10157,7 @@ components:
             - EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_FAILED
             - EVENT_TYPE_WORKFLOW_EXECUTION_PAUSED
             - EVENT_TYPE_WORKFLOW_EXECUTION_UNPAUSED
-            - EVENT_TYPE_WORKFLOW_EXECUTION_TIME_SKIPPED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_TIME_SKIPPING_STATE_CHANGED
           type: string
           format: enum
         version:
@@ -10316,8 +10316,8 @@ components:
           $ref: '#/components/schemas/WorkflowExecutionPausedEventAttributes'
         workflowExecutionUnpausedEventAttributes:
           $ref: '#/components/schemas/WorkflowExecutionUnpausedEventAttributes'
-        workflowExecutionTimeSkippedEventAttributes:
-          $ref: '#/components/schemas/WorkflowExecutionTimeSkippedEventAttributes'
+        workflowExecutionTimeSkippingStateChangedEventAttributes:
+          $ref: '#/components/schemas/WorkflowExecutionTimeSkippingStateChangedEventAttributes'
       description: |-
         History events are the method by which Temporal SDKs advance (or recreate) workflow state.
          See the `EventType` enum for more info about what each event is for.
@@ -12263,7 +12263,7 @@ components:
             - EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_FAILED
             - EVENT_TYPE_WORKFLOW_EXECUTION_PAUSED
             - EVENT_TYPE_WORKFLOW_EXECUTION_UNPAUSED
-            - EVENT_TYPE_WORKFLOW_EXECUTION_TIME_SKIPPED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_TIME_SKIPPING_STATE_CHANGED
           type: string
           description: The event type of the history event generated by the request.
           format: enum
@@ -13580,7 +13580,7 @@ components:
         timeSkippingConfig:
           allOf:
             - $ref: '#/components/schemas/TimeSkippingConfig'
-          description: Time skipping configuration. If not set, automatic time-skipping is disabled.
+          description: Time-skipping configuration. If not set, time skipping is disabled.
     SignalWithStartWorkflowExecutionResponse:
       type: object
       properties:
@@ -14046,7 +14046,7 @@ components:
         timeSkippingConfig:
           allOf:
             - $ref: '#/components/schemas/TimeSkippingConfig'
-          description: Automatic time-skipping configuration. If not set, automatic time-skipping is disabled.
+          description: Time-skipping configuration. If not set, time skipping is disabled.
     StartWorkflowExecutionResponse:
       type: object
       properties:
@@ -14455,7 +14455,7 @@ components:
       properties:
         enabled:
           type: boolean
-          description: "Enables or disables automatic time skipping for this workflow execution.\n By default, this field is propagated to transitively related workflows (child workflows/start-as-new/reset) \n at the time they are started.\n Changes made after a transitively related workflow has started are not propagated."
+          description: "Enables or disables time skipping for this workflow execution.\n By default, this field is propagated to transitively related workflows (child workflows/start-as-new/reset) \n at the time they are started.\n Changes made after a transitively related workflow has started are not propagated."
         disablePropagation:
           type: boolean
           description: If set, the enabled field is not propagated to transitively related workflows.
@@ -14476,9 +14476,11 @@ components:
              Time skipping will not advance beyond this point.
           format: date-time
       description: |-
-        Configuration for automatic time skipping during a workflow execution.
-         When enabled, virtual time advances automatically whenever there are
-         no in-flight activities, child workflows, or Nexus operations.
+        Configuration for time skipping during a workflow execution.
+         When enabled, virtual time advances automatically whenever there is no in-flight work.
+         In-flight work includes activities, child workflows, Nexus operations, signal/cancel external workflow operations,
+         and possibly other features added in the future.
+         User timers are not classified as in-flight work and will be skipped over.
     TimeoutFailureInfo:
       type: object
       properties:
@@ -15909,7 +15911,7 @@ components:
             - EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_FAILED
             - EVENT_TYPE_WORKFLOW_EXECUTION_PAUSED
             - EVENT_TYPE_WORKFLOW_EXECUTION_UNPAUSED
-            - EVENT_TYPE_WORKFLOW_EXECUTION_TIME_SKIPPED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_TIME_SKIPPING_STATE_CHANGED
           type: string
           format: enum
       description: EventReference is a direct reference to a history event through the event ID.
@@ -15980,7 +15982,7 @@ components:
             - EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_FAILED
             - EVENT_TYPE_WORKFLOW_EXECUTION_PAUSED
             - EVENT_TYPE_WORKFLOW_EXECUTION_UNPAUSED
-            - EVENT_TYPE_WORKFLOW_EXECUTION_TIME_SKIPPED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_TIME_SKIPPING_STATE_CHANGED
           type: string
           format: enum
       description: RequestIdReference is a indirect reference to a history event through the request ID.
@@ -16368,7 +16370,7 @@ components:
         timeSkippingConfig:
           allOf:
             - $ref: '#/components/schemas/TimeSkippingConfig'
-          description: "Time skipping configuration upserted in this event. \n It means the time-skipping config is changed, and the full latest config is upserted."
+          description: If set, the time-skipping configuration was changed. Contains the full updated configuration.
     WorkflowExecutionPauseInfo:
       type: object
       properties:
@@ -16674,27 +16676,26 @@ components:
         identity:
           type: string
           description: id of the client who requested termination
-    WorkflowExecutionTimeSkippedEventAttributes:
+    WorkflowExecutionTimeSkippingStateChangedEventAttributes:
       type: object
       properties:
         targetTime:
           type: string
-          description: The virtual time after time skipping is applied.
+          description: The virtual time after time skipping was applied.
           format: date-time
         disabledAfterBound:
           type: boolean
           description: |-
-            when true, automatic time-skipping was enabled with a bound
-             and now that bound has been reached and time-skipping is disabled automatically.
+            when true, time skipping was disabled automatically due to a bound being reached.
              (-- api-linter: core::0140::prepositions=disabled
                  aip.dev/not-precedent: "after" is used to indicate temporal ordering. --)
         wallClockTime:
           type: string
-          description: The wall-clock time when the time-skipping event happened.
+          description: The wall-clock time when the time-skipping state changed event was generated.
           format: date-time
       description: |-
-        Attributes for an event indicating that virtual time was advanced for a workflow execution,
-         either via a manual time-skipping API call or automatic time skipping.
+        Attributes for an event indicating that time skipping state changed for a workflow execution,
+         either time was advanced or time skipping was disabled automatically due to a bound being reached.
          The worker_may_ignore field in HistoryEvent should always be set true for this event.
     WorkflowExecutionTimedOutEventAttributes:
       type: object

openapi/openapiv3.yaml

@@ -173,6 +173,6 @@ enum EventType {
     EVENT_TYPE_WORKFLOW_EXECUTION_PAUSED = 58;
     // An event that indicates that the previously paused workflow execution has been unpaused.
     EVENT_TYPE_WORKFLOW_EXECUTION_UNPAUSED = 59;
-    // An event that indicates that some duration was skipped for this workflow execution.
-    EVENT_TYPE_WORKFLOW_EXECUTION_TIME_SKIPPED = 60;
+    // An event that indicates time skipping advanced time or was disabled automatically after a bound was reached.
+    EVENT_TYPE_WORKFLOW_EXECUTION_TIME_SKIPPING_STATE_CHANGED = 60;
 }

temporal/api/enums/v1/event_type.proto

@@ -873,8 +873,7 @@ message WorkflowExecutionOptionsUpdatedEventAttributes {
     // Priority override upserted in this event. Represents the full priority; not just partial fields.
     // Ignored if nil.
     temporal.api.common.v1.Priority priority = 6;
-    // Time skipping configuration upserted in this event. 
-    // It means the time-skipping config is changed, and the full latest config is upserted.
+    // If set, the time-skipping configuration was changed. Contains the full updated configuration.
     temporal.api.workflow.v1.TimeSkippingConfig time_skipping_config = 7;
 }
 
@@ -968,21 +967,20 @@ message WorkflowExecutionUnpausedEventAttributes {
     string request_id = 3;
 }
 
-// Attributes for an event indicating that virtual time was advanced for a workflow execution,
-// either via a manual time-skipping API call or automatic time skipping.
+// Attributes for an event indicating that time skipping state changed for a workflow execution,
+// either time was advanced or time skipping was disabled automatically due to a bound being reached.
 // The worker_may_ignore field in HistoryEvent should always be set true for this event.
-message WorkflowExecutionTimeSkippedEventAttributes {
+message WorkflowExecutionTimeSkippingStateChangedEventAttributes {
 
-    // The virtual time after time skipping is applied.
+    // The virtual time after time skipping was applied.
     google.protobuf.Timestamp target_time = 1;
 
-    // when true, automatic time-skipping was enabled with a bound
-    // and now that bound has been reached and time-skipping is disabled automatically.
+    // when true, time skipping was disabled automatically due to a bound being reached.
     // (-- api-linter: core::0140::prepositions=disabled
     //     aip.dev/not-precedent: "after" is used to indicate temporal ordering. --)
     bool disabled_after_bound = 2;
 
-    // The wall-clock time when the time-skipping event happened.
+    // The wall-clock time when the time-skipping state changed event was generated.
     google.protobuf.Timestamp wall_clock_time = 3;
 }
 
@@ -1222,7 +1220,7 @@ message HistoryEvent {
         NexusOperationCancelRequestFailedEventAttributes nexus_operation_cancel_request_failed_event_attributes = 62;
         WorkflowExecutionPausedEventAttributes workflow_execution_paused_event_attributes = 63;
         WorkflowExecutionUnpausedEventAttributes workflow_execution_unpaused_event_attributes = 64;
-        WorkflowExecutionTimeSkippedEventAttributes workflow_execution_time_skipped_event_attributes = 65;
+        WorkflowExecutionTimeSkippingStateChangedEventAttributes workflow_execution_time_skipping_state_changed_event_attributes = 65;
     }
 }
 

temporal/api/history/v1/message.proto

@@ -573,12 +573,15 @@ message WorkflowExecutionOptions {
     TimeSkippingConfig time_skipping_config = 3;
 }
 
-// Configuration for automatic time skipping during a workflow execution.
-// When enabled, virtual time advances automatically whenever there are
-// no in-flight activities, child workflows, or Nexus operations.
+// Configuration for time skipping during a workflow execution.
+// When enabled, virtual time advances automatically whenever there is no in-flight work.
+// In-flight work includes activities, child workflows, Nexus operations, signal/cancel external workflow operations,
+// and possibly other features added in the future.
+// User timers are not classified as in-flight work and will be skipped over.
+// When time advances, it skips to the earlier of the next user timer or the configured bound, if either exists.
 message TimeSkippingConfig {
 
-    // Enables or disables automatic time skipping for this workflow execution.
+    // Enables or disables time skipping for this workflow execution.
     // By default, this field is propagated to transitively related workflows (child workflows/start-as-new/reset) 
     // at the time they are started.
     // Changes made after a transitively related workflow has started are not propagated.

temporal/api/workflow/v1/message.proto

@@ -197,7 +197,7 @@ message StartWorkflowExecutionRequest {
     temporal.api.common.v1.Priority priority = 27;
     // Deployment Options of the worker who will process the eager task. Passed when `request_eager_execution=true`.
     temporal.api.deployment.v1.WorkerDeploymentOptions eager_worker_deployment_options = 28;
-    // Automatic time-skipping configuration. If not set, automatic time-skipping is disabled.
+    // Time-skipping configuration. If not set, time skipping is disabled.
     temporal.api.workflow.v1.TimeSkippingConfig time_skipping_config = 29;
 }
 
@@ -838,7 +838,7 @@ message SignalWithStartWorkflowExecutionRequest {
     temporal.api.workflow.v1.VersioningOverride versioning_override = 25;
     // Priority metadata
     temporal.api.common.v1.Priority priority = 26;
-    // Time skipping configuration. If not set, automatic time-skipping is disabled.
+    // Time-skipping configuration. If not set, time skipping is disabled.
     temporal.api.workflow.v1.TimeSkippingConfig time_skipping_config = 27;
 }
 
@@ -2959,4 +2959,4 @@ message DeleteActivityExecutionRequest {
 }
 
 message DeleteActivityExecutionResponse {
-}
+}