Polish / code review suggestions

dandavison · dandavison · commit 47e7e231a330 · 2025-12-18T20:06:25.000-05:00
diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json
diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml
@@ -171,7 +171,7 @@ paths:
       description: |-
         RespondActivityTaskFailed is called by workers when processing an activity task fails.
 
-         This results in a new `ACTIVITY_TASK_CANCELED` event being written to the workflow history
+         For workflow activities, this results in a new `ACTIVITY_TASK_CANCELED` event being written to the workflow history
          and a new workflow task created for the workflow. Fails with `NotFound` if the task token is
          no longer valid due to activity timeout, already being completed, or never having existed.
       operationId: RespondActivityTaskCanceled
@@ -245,7 +245,7 @@ paths:
         RespondActivityTaskCompleted is called by workers when they successfully complete an activity
          task.
 
-         This results in a new `ACTIVITY_TASK_COMPLETED` event being written to the workflow history
+         For workflow activities, this results in a new `ACTIVITY_TASK_COMPLETED` event being written to the workflow history
          and a new workflow task created for the workflow. Fails with `NotFound` if the task token is
          no longer valid due to activity timeout, already being completed, or never having existed.
       operationId: RespondActivityTaskCompleted
@@ -391,10 +391,17 @@ paths:
       description: |-
         RecordActivityTaskHeartbeat is optionally called by workers while they execute activities.
 
-         If worker fails to heartbeat within the `heartbeat_timeout` interval for the activity task,
-         then it will be marked as timed out and an `ACTIVITY_TASK_TIMED_OUT` event will be written to
-         the workflow history. Calling `RecordActivityTaskHeartbeat` will fail with `NotFound` in
-         such situations, in that event, the SDK should request cancellation of the activity.
+         If a worker fails to heartbeat within the `heartbeat_timeout` interval for the activity task,
+         then the current attempt times out. Depending on RetryPolicy, this may trigger a retry or
+         time out the activity.
+
+         For workflow activities, an `ACTIVITY_TASK_TIMED_OUT` event will be written to the workflow
+         history. Calling `RecordActivityTaskHeartbeat` will fail with `NotFound` in such situations,
+         in that event, the SDK should request cancellation of the activity.
+
+         The request may contain response `details` which will be persisted by the server and may be
+         used by the activity to checkpoint progress. The `cancel_requested` field in the response
+         indicates whether cancellation has been requested for the activity.
       operationId: RecordActivityTaskHeartbeat
       parameters:
         - name: namespace
@@ -648,7 +655,7 @@ paths:
         - WorkflowService
       description: |-
         DescribeActivityExecution returns information about an activity execution.
-         Supported use cases include:
+         It can be used to:
          - Get current activity info without waiting
          - Long-poll for next state change and return new activity info
          Response can optionally include activity input or outcome (if the activity has completed).
@@ -710,7 +717,7 @@ paths:
       description: |-
         StartActivityExecution starts a new activity execution.
 
-         Returns an `ExecutionAlreadyStarted` error if an instance already exists with same activity ID in this namespace
+         Returns an `ActivityExecutionAlreadyStarted` error if an instance already exists with same activity ID in this namespace
          unless permitted by the specified ID conflict policy.
       operationId: StartActivityExecution
       parameters:
@@ -721,6 +728,10 @@ paths:
             type: string
         - name: activityId
           in: path
+          description: |-
+            Identifier for this activity. Required. This identifier should be meaningful in the user's
+             own system. It must be unique among activities in the same namespace, subject to the rules
+             imposed by id_reuse_policy and id_conflict_policy.
           required: true
           schema:
             type: string
@@ -750,13 +761,10 @@ paths:
       description: |-
         RequestCancelActivityExecution requests cancellation of an activity execution.
 
-         Requesting to cancel an activity does not automatically transition the activity to canceled status. If the
-         activity has a currently running attempt, the activity will only transition to canceled status if the current
-         attempt is unsuccessful.
-         TODO: Clarify what happens if there are no more allowed retries after the current attempt.
-
-         It returns success if the requested activity is already closed.
-         TODO: This ^^ is copied from RequestCancelWorkflowExecution, do we want to preserve this behavior?
+         Cancellation is cooperative: this call records the request, but the activity must detect and
+         acknowledge it for the activity to reach CANCELED status. The cancellation signal is
+         delivered via `cancel_requested` in the heartbeat response; SDKs surface this via
+         language-idiomatic mechanisms (context cancellation, exceptions, abort signals).
       operationId: RequestCancelActivityExecution
       parameters:
         - name: namespace
@@ -833,7 +841,7 @@ paths:
         TerminateActivityExecution terminates an existing activity execution immediately.
 
          Termination does not reach the worker and the activity code cannot react to it. A terminated activity may have a
-         running attempt and will be requested to be canceled by the server when it heartbeats.
+         running attempt.
       operationId: TerminateActivityExecution
       parameters:
         - name: namespace
@@ -869,7 +877,7 @@ paths:
     get:
       tags:
         - WorkflowService
-      description: CountActivityExecutions is a visibility API to count of activity executions in a specific namespace.
+      description: CountActivityExecutions is a visibility API to count activity executions in a specific namespace.
       operationId: CountActivityExecutions
       parameters:
         - name: namespace
@@ -3957,7 +3965,7 @@ paths:
       description: |-
         RespondActivityTaskFailed is called by workers when processing an activity task fails.
 
-         This results in a new `ACTIVITY_TASK_CANCELED` event being written to the workflow history
+         For workflow activities, this results in a new `ACTIVITY_TASK_CANCELED` event being written to the workflow history
          and a new workflow task created for the workflow. Fails with `NotFound` if the task token is
          no longer valid due to activity timeout, already being completed, or never having existed.
       operationId: RespondActivityTaskCanceled
@@ -4031,7 +4039,7 @@ paths:
         RespondActivityTaskCompleted is called by workers when they successfully complete an activity
          task.
 
-         This results in a new `ACTIVITY_TASK_COMPLETED` event being written to the workflow history
+         For workflow activities, this results in a new `ACTIVITY_TASK_COMPLETED` event being written to the workflow history
          and a new workflow task created for the workflow. Fails with `NotFound` if the task token is
          no longer valid due to activity timeout, already being completed, or never having existed.
       operationId: RespondActivityTaskCompleted
@@ -4177,10 +4185,17 @@ paths:
       description: |-
         RecordActivityTaskHeartbeat is optionally called by workers while they execute activities.
 
-         If worker fails to heartbeat within the `heartbeat_timeout` interval for the activity task,
-         then it will be marked as timed out and an `ACTIVITY_TASK_TIMED_OUT` event will be written to
-         the workflow history. Calling `RecordActivityTaskHeartbeat` will fail with `NotFound` in
-         such situations, in that event, the SDK should request cancellation of the activity.
+         If a worker fails to heartbeat within the `heartbeat_timeout` interval for the activity task,
+         then the current attempt times out. Depending on RetryPolicy, this may trigger a retry or
+         time out the activity.
+
+         For workflow activities, an `ACTIVITY_TASK_TIMED_OUT` event will be written to the workflow
+         history. Calling `RecordActivityTaskHeartbeat` will fail with `NotFound` in such situations,
+         in that event, the SDK should request cancellation of the activity.
+
+         The request may contain response `details` which will be persisted by the server and may be
+         used by the activity to checkpoint progress. The `cancel_requested` field in the response
+         indicates whether cancellation has been requested for the activity.
       operationId: RecordActivityTaskHeartbeat
       parameters:
         - name: namespace
@@ -4434,7 +4449,7 @@ paths:
         - WorkflowService
       description: |-
         DescribeActivityExecution returns information about an activity execution.
-         Supported use cases include:
+         It can be used to:
          - Get current activity info without waiting
          - Long-poll for next state change and return new activity info
          Response can optionally include activity input or outcome (if the activity has completed).
@@ -4496,7 +4511,7 @@ paths:
       description: |-
         StartActivityExecution starts a new activity execution.
 
-         Returns an `ExecutionAlreadyStarted` error if an instance already exists with same activity ID in this namespace
+         Returns an `ActivityExecutionAlreadyStarted` error if an instance already exists with same activity ID in this namespace
          unless permitted by the specified ID conflict policy.
       operationId: StartActivityExecution
       parameters:
@@ -4507,6 +4522,10 @@ paths:
             type: string
         - name: activityId
           in: path
+          description: |-
+            Identifier for this activity. Required. This identifier should be meaningful in the user's
+             own system. It must be unique among activities in the same namespace, subject to the rules
+             imposed by id_reuse_policy and id_conflict_policy.
           required: true
           schema:
             type: string
@@ -4536,13 +4555,10 @@ paths:
       description: |-
         RequestCancelActivityExecution requests cancellation of an activity execution.
 
-         Requesting to cancel an activity does not automatically transition the activity to canceled status. If the
-         activity has a currently running attempt, the activity will only transition to canceled status if the current
-         attempt is unsuccessful.
-         TODO: Clarify what happens if there are no more allowed retries after the current attempt.
-
-         It returns success if the requested activity is already closed.
-         TODO: This ^^ is copied from RequestCancelWorkflowExecution, do we want to preserve this behavior?
+         Cancellation is cooperative: this call records the request, but the activity must detect and
+         acknowledge it for the activity to reach CANCELED status. The cancellation signal is
+         delivered via `cancel_requested` in the heartbeat response; SDKs surface this via
+         language-idiomatic mechanisms (context cancellation, exceptions, abort signals).
       operationId: RequestCancelActivityExecution
       parameters:
         - name: namespace
@@ -4619,7 +4635,7 @@ paths:
         TerminateActivityExecution terminates an existing activity execution immediately.
 
          Termination does not reach the worker and the activity code cannot react to it. A terminated activity may have a
-         running attempt and will be requested to be canceled by the server when it heartbeats.
+         running attempt.
       operationId: TerminateActivityExecution
       parameters:
         - name: namespace
@@ -4655,7 +4671,7 @@ paths:
     get:
       tags:
         - WorkflowService
-      description: CountActivityExecutions is a visibility API to count of activity executions in a specific namespace.
+      description: CountActivityExecutions is a visibility API to count activity executions in a specific namespace.
       operationId: CountActivityExecutions
       parameters:
         - name: namespace
@@ -7308,10 +7324,7 @@ components:
           format: date-time
         attempt:
           type: integer
-          description: |-
-            The attempt this activity is currently on.
-             Incremented each time a new attempt is started.
-             TODO(dandavison): Confirm if this is on scheduled or started.
+          description: The attempt this activity is currently on. Incremented each time a new attempt is scheduled.
           format: int32
         executionDuration:
           pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$
@@ -7368,6 +7381,9 @@ components:
         stateTransitionCount:
           type: string
           description: Incremented each time the activity's state is mutated in persistence.
+        stateSizeBytes:
+          type: string
+          description: Updated once on scheduled and once on terminal status.
         searchAttributes:
           $ref: '#/components/schemas/SearchAttributes'
         header:
@@ -9867,23 +9883,11 @@ components:
           $ref: '#/components/schemas/Link_WorkflowEvent'
         batchJob:
           $ref: '#/components/schemas/Link_BatchJob'
-        activity:
-          $ref: '#/components/schemas/Link_Activity'
       description: |-
         Link can be associated with history events. It might contain information about an external entity
          related to the history event. For example, workflow A makes a Nexus call that starts workflow B:
          in this case, a history event in workflow A could contain a Link to the workflow started event in
          workflow B, and vice-versa.
-    Link_Activity:
-      type: object
-      properties:
-        namespace:
-          type: string
-        activityId:
-          type: string
-        runId:
-          type: string
-      description: A link to an activity.
     Link_BatchJob:
       type: object
       properties:
@@ -13048,8 +13052,14 @@ components:
           description: A unique identifier for this start request. Typically UUIDv4.
         activityId:
           type: string
+          description: |-
+            Identifier for this activity. Required. This identifier should be meaningful in the user's
+             own system. It must be unique among activities in the same namespace, subject to the rules
+             imposed by id_reuse_policy and id_conflict_policy.
         activityType:
-          $ref: '#/components/schemas/ActivityType'
+          allOf:
+            - $ref: '#/components/schemas/ActivityType'
+          description: The type of the activity, a string that corresponds to a registered activity on a worker.
         taskQueue:
           allOf:
             - $ref: '#/components/schemas/TaskQueue'
diff --git a/temporal/api/common/v1/message.proto b/temporal/api/common/v1/message.proto
@@ -240,17 +240,9 @@ message Link {
         string job_id = 1;
     }
 
-    // A link to an activity.
-    message Activity {
-        string namespace = 1;
-        string activity_id = 2;
-        string run_id = 3;
-    }
-
     oneof variant {
         WorkflowEvent workflow_event = 1;
         BatchJob batch_job = 2;
-        Activity activity = 3;
     }
 }
 
diff --git a/temporal/api/enums/v1/activity.proto b/temporal/api/enums/v1/activity.proto
@@ -12,30 +12,43 @@ option csharp_namespace = "Temporalio.Api.Enums.V1";
 // Status of a standalone activity.
 // The status is updated once, when the activity is originally scheduled, and again when the activity reaches a terminal
 // status.
-// TODO: Should this be a common execution status? Seems like the other archetypes will share this status.
 // (-- api-linter: core::0216::synonyms=disabled
 //     aip.dev/not-precedent: Named consistently with WorkflowExecutionStatus. --)
 enum ActivityExecutionStatus {
     ACTIVITY_EXECUTION_STATUS_UNSPECIFIED = 0;
-    // The activity is not in a terminal status. This does not necessarily mean that there is a currently running
-    // attempt. The activity may be backing off between attempts or waiting for a worker to pick it up.
+
+    // The activity has not reached a terminal status. See PendingActivityState for the run state
+    // (SCHEDULED, STARTED, or CANCEL_REQUESTED).
     ACTIVITY_EXECUTION_STATUS_RUNNING = 1;
-    // The activity completed successfully.
+
+    // The activity completed successfully. An activity can complete even after cancellation is
+    // requested if the worker calls RespondActivityTaskCompleted before acknowledging cancellation.
     ACTIVITY_EXECUTION_STATUS_COMPLETED = 2;
-    // The activity completed with failure.
+
+    // The activity failed. Causes:
+    // - Worker returned a non-retryable failure
+    // - RetryPolicy.maximum_attempts exhausted
+    // - Attempt failed after cancellation was requested (retries blocked)
     ACTIVITY_EXECUTION_STATUS_FAILED = 3;
-    // The activity completed as canceled.
-    // Requesting to cancel an activity does not automatically transition the activity to canceled status. If the
-    // activity has a currently running attempt, the activity will only transition to canceled status if the current
-    // attempt is unsuccessful.
-    // TODO: Clarify what happens if there are no more allowed retries after the current attempt.
+
+    // The activity was canceled. Reached when:
+    // - Cancellation requested while SCHEDULED (immediate), or
+    // - Cancellation requested while STARTED and worker called RespondActivityTaskCanceled.
+    //
+    // Workers discover cancellation requests via heartbeat responses (cancel_requested=true).
+    // Activities that do not heartbeat will not learn of cancellation and may complete, fail, or
+    // time out normally. CANCELED requires explicit worker acknowledgment or immediate cancellation
+    // of a SCHEDULED activity.
     ACTIVITY_EXECUTION_STATUS_CANCELED = 4;
-    // The activity was terminated. Termination does not reach the worker and the activity code cannot react to it.
-    // A terminated activity may have a running attempt and will be requested to be canceled by the server when it
-    // heartbeats.
+
+    // The activity was terminated. Immediate; does not wait for worker acknowledgment.
     ACTIVITY_EXECUTION_STATUS_TERMINATED = 5;
-    // The activity has timed out by reaching the specified shedule-to-start or schedule-to-close timeouts.
-    // TODO: Clarify if there are other conditions where the activity can end up in timed out status.
+
+    // The activity timed out. See TimeoutType for the specific timeout.
+    // - SCHEDULE_TO_START and SCHEDULE_TO_CLOSE timeouts always result in TIMED_OUT.
+    // - START_TO_CLOSE and HEARTBEAT may retry if RetryPolicy permits; TIMED_OUT is
+    //   reached when retry is blocked (RetryPolicy.maximum_attempts exhausted,
+    //   SCHEDULE_TO_CLOSE would be exceeded, or cancellation has been requested).
     ACTIVITY_EXECUTION_STATUS_TIMED_OUT = 6;
 }
 
diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto
@@ -2665,7 +2665,12 @@ message StartActivityExecutionRequest {
     // A unique identifier for this start request. Typically UUIDv4.
     string request_id = 3;
 
+    // Identifier for this activity. Required. This identifier should be meaningful in the user's
+    // own system. It must be unique among activities in the same namespace, subject to the rules
+    // imposed by id_reuse_policy and id_conflict_policy.
     string activity_id = 4;
+
+    // The type of the activity, a string that corresponds to a registered activity on a worker.
     temporal.api.common.v1.ActivityType activity_type = 5;
 
     // Task queue to schedule this activity on.
diff --git a/temporal/api/workflowservice/v1/service.proto b/temporal/api/workflowservice/v1/service.proto

Original file line number	Diff line number	Diff line change
`@@ -240,17 +240,9 @@ message Link {`
`240`	`240`	`string job_id = 1;`
`241`	`241`	`}`
`242`	`242`
`243`		`- // A link to an activity.`
`244`		`- message Activity {`
`245`		`- string namespace = 1;`
`246`		`- string activity_id = 2;`
`247`		`- string run_id = 3;`
`248`		`- }`
`249`		`-`
`250`	`243`	`oneof variant {`
`251`	`244`	`WorkflowEvent workflow_event = 1;`
`252`	`245`	`BatchJob batch_job = 2;`
`253`		`- Activity activity = 3;`
`254`	`246`	`}`
`255`	`247`	`}`
`256`	`248`