chore(activity execution): updated explanation of task tokens (#4136)

Author: flippedcoder

docs/encyclopedia/activities/activity-execution.mdx

@@ -39,26 +39,28 @@ An Activity Execution is the full chain of [Activity Task Executions](/tasks#act
 - [How to start an Activity Execution using the .NET SDK](/develop/dotnet/core-application#activity-execution)
 
 :::
-<CaptionedImage
-    src="/diagrams/activity-execution.svg"
-    title="Activity Execution"
-    />
 
-You can customize [Activity Execution timeouts](/encyclopedia/detecting-activity-failures#start-to-close-timeout) and [retry policies](/encyclopedia/retry-policies).
+<CaptionedImage src="/diagrams/activity-execution.svg" title="Activity Execution" />
 
-If an Activity Execution fails (because it exhausted all retries, threw a [non-retryable error](/encyclopedia/retry-policies#non-retryable-errors), or was canceled), the error is returned to the [Workflow](/workflows), which decides how to handle it.
+You can customize [Activity Execution timeouts](/encyclopedia/detecting-activity-failures#start-to-close-timeout) and
+[retry policies](/encyclopedia/retry-policies).
+
+If an Activity Execution fails (because it exhausted all retries, threw a
+[non-retryable error](/encyclopedia/retry-policies#non-retryable-errors), or was canceled), the error is returned to the
+[Workflow](/workflows), which decides how to handle it.
 
 :::note
 
-Temporal guarantees that an Activity Task either runs or timeouts.
-There are multiple failure scenarios when an Activity Task is lost.
-It can be lost during delivery to a Worker or after the Activity Function is called and the Worker crashed.
+Temporal guarantees that an Activity Task either runs or timeouts. There are multiple failure scenarios when an Activity
+Task is lost. It can be lost during delivery to a Worker or after the Activity Function is called and the Worker
+crashed.
 
-Temporal doesn't detect task loss directly.
-It relies on [Start-To-Close timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout).
-If the Activity Task times out, the Activity Execution will be retried according to the Activity Execution Retry Policy.
+Temporal doesn't detect task loss directly. It relies on
+[Start-To-Close timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout). If the Activity Task times
+out, the Activity Execution will be retried according to the Activity Execution Retry Policy.
 
-In scenarios where the Activity Execution Retry Policy is set to `1` and a Timeout occurs, the Activity Execution will not be tried.
+In scenarios where the Activity Execution Retry Policy is set to `1` and a Timeout occurs, the Activity Execution will
+not be tried.
 
 :::
 
@@ -73,40 +75,49 @@ Activities must heartbeat to receive cancellations from a Temporal Service.
 
 An Activity may receive Cancellation if:
 
-- The Activity was requested to be Cancelled. This can often cascade from Workflow Cancellation, but not always—SDKs have ways to stop Cancellation from cascading. {/* TODO link to workflow cancellation */}
-- The Activity was considered failed by the Server because any of the Activity timeouts have triggered (for example, the Server didn't receive a heartbeat within the Activity's Heartbeat timeout). The [Cancelled Failure](/references/failures#cancelled-failure) that the Activity receives will have `message: 'TIMED_OUT'`.
-- The Workflow Run reached a [Closed state](/workflow-execution#workflow-execution-status), in which case the Cancelled Failure will have `message: 'NOT_FOUND'`.
+- The Activity was requested to be Cancelled. This can often cascade from Workflow Cancellation, but not always—SDKs
+  have ways to stop Cancellation from cascading. {/* TODO link to workflow cancellation */}
+- The Activity was considered failed by the Server because any of the Activity timeouts have triggered (for example, the
+  Server didn't receive a heartbeat within the Activity's Heartbeat timeout). The
+  [Cancelled Failure](/references/failures#cancelled-failure) that the Activity receives will have
+  `message: 'TIMED_OUT'`.
+- The Workflow Run reached a [Closed state](/workflow-execution#workflow-execution-status), in which case the Cancelled
+  Failure will have `message: 'NOT_FOUND'`.
 - In some SDKs:
   - The Worker is shutting down.
-  - An Activity sends a Heartbeat but the Heartbeat details can't be converted by the Worker's configured [Data Converter](/dataconversion). This fails the Activity Task Execution with an Application Failure.
-  - The Activity timed out on the Worker side and is not Heartbeating or the Temporal Service hasn't relayed a Cancellation.
+  - An Activity sends a Heartbeat but the Heartbeat details can't be converted by the Worker's configured
+    [Data Converter](/dataconversion). This fails the Activity Task Execution with an Application Failure.
+  - The Activity timed out on the Worker side and is not Heartbeating or the Temporal Service hasn't relayed a
+    Cancellation.
 
-There are different ways to receive Cancellation depending on the SDK. {/* TODO link to dev guide */}
-An Activity may accept or ignore Cancellation:
+There are different ways to receive Cancellation depending on the SDK. {/* TODO link to dev guide */} An Activity may
+accept or ignore Cancellation:
 
 - To allow Cancellation to happen, let the Cancellation Failure propagate.
 - To ignore Cancellation, catch it and continue executing.
 
 Some SDKs have ways to shield tasks from being stopped while still letting the Cancellation propagate.
 
-The Workflow can also decide if it wants to wait for the Activity Cancellation to be accepted or to proceed without waiting.
+The Workflow can also decide if it wants to wait for the Activity Cancellation to be accepted or to proceed without
+waiting.
 
-Cancellation can only be requested a single time.
-If you try to cancel your Activity Execution more than once, it will not receive more than one Cancellation request.
+Cancellation can only be requested a single time. If you try to cancel your Activity Execution more than once, it will
+not receive more than one Cancellation request.
 
 ## What is an Activity Id? {#activity-id}
 
-The identifier for an [Activity Execution](#activity-execution).
-The identifier can be generated by the system, or it can be provided by the Workflow code that spawns the Activity Execution.
-The identifier is unique among the open Activity Executions of a [Workflow Run](/workflow-execution/workflowid-runid#run-id).
-(A single Workflow Run may reuse an Activity Id if an earlier Activity Execution with the same Id has closed.)
+The identifier for an [Activity Execution](#activity-execution). The identifier can be generated by the system, or it
+can be provided by the Workflow code that spawns the Activity Execution. The identifier is unique among the open
+Activity Executions of a [Workflow Run](/workflow-execution/workflowid-runid#run-id). (A single Workflow Run may reuse
+an Activity Id if an earlier Activity Execution with the same Id has closed.)
 
 An Activity Id can be used to [complete the Activity asynchronously](#asynchronous-activity-completion).
 
 ## What is Asynchronous Activity Completion? {#asynchronous-activity-completion}
 
-Asynchronous Activity Completion is a feature that enables an Activity Function to return without causing the Activity Execution to complete.
-The Temporal Client can then be used from anywhere to both Heartbeat Activity Execution progress and eventually complete the Activity Execution and provide a result.
+Asynchronous Activity Completion is a feature that enables an Activity Function to return without causing the Activity
+Execution to complete. The Temporal Client can then be used from anywhere to both Heartbeat Activity Execution progress
+and eventually complete the Activity Execution and provide a result.
 
 How to complete an Activity Asynchronously in:
 
@@ -119,45 +130,56 @@ How to complete an Activity Asynchronously in:
 
 ### When to use Async Completion
 
-When an external system has the final result of a computation that is started by an Activity, there are three main ways of getting the result to the Workflow:
+When an external system has the final result of a computation that is started by an Activity, there are three main ways
+of getting the result to the Workflow:
 
 1. The external system uses Async Completion to complete the Activity with the result.
-2. The Activity completes normally, without the result. Later, the external system sends a Signal to the Workflow with the result.
-3. A subsequent Activity [polls the external system](https://community.temporal.io/t/what-is-the-best-practice-for-a-polling-activity/328/2) for the result.
+2. The Activity completes normally, without the result. Later, the external system sends a Signal to the Workflow with
+   the result.
+3. A subsequent Activity
+   [polls the external system](https://community.temporal.io/t/what-is-the-best-practice-for-a-polling-activity/328/2)
+   for the result.
 
-If you don't have control over the external system—that is, you can't add Async Completion or a Signal to its code—then
+If you don't have control over the external system — that is, you can't add Async Completion or a Signal to its code —
+then:
 
 - you can poll (#3), or
-- if the external system can reliably call a webhook (and retry calling in the case of failure), you can write a webhook handler that sends a Signal to the Workflow (#2).
+- if the external system can reliably call a webhook (and retry calling in the case of failure), you can write a webhook
+  handler that sends a Signal to the Workflow (#2).
 
-The decision between using #1 vs #2 involves a few factors.
-Use Async Completion if
+The decision between using #1 vs #2 involves a few factors. Use Async Completion if:
 
 - the external system is unreliable and might fail to Signal, or
 - you want the external process to Heartbeat or receive Cancellation.
 
-Otherwise, if the external system can reliably be trusted to do the task and Signal back with the result, and it doesn't need to Heartbeat or receive Cancellation, then you may want to use Signals.
+Otherwise, if the external system can reliably be trusted to do the task and Signal back with the result, and it doesn't
+need to Heartbeat or receive Cancellation, then you may want to use Signals.
 
-The benefit to using Signals has to do with the timing of failure retries.
-For example, consider an external process that is waiting for a human to review something and respond, and they could take up to a week to do so.
-If you use Async Completion (#1), you would
+The benefit to using Signals has to do with the timing of failure retries. For example, consider an external process
+that is waiting for a human to review something and respond, and they could take up to a week to do so. If you use Async
+Completion (#1), you would:
 
-- set a [Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout) of one week on the Activity,
+- set a [Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout) of one week on the
+  Activity,
 - in the Activity, notify the external process you need the human review, and
 - have the external process Asynchronously Complete the Activity when the human responds.
 
-If the Activity fails on the second step to notify the external system and doesn't throw an error (for example, if the Worker dies), then the Activity won't be retried for a week, when the Start-To-Close Timeout is hit.
+If the Activity fails on the second step to notify the external system and doesn't throw an error (for example, if the
+Worker dies), then the Activity won't be retried for a week, when the Start-To-Close Timeout is hit.
 
 If you use Signals, you would:
 
-- set a [Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout) of one minute on the Activity,
+- set a [Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout) of one minute on the
+  Activity,
 - in the Activity, notify the external process you need the human review,
 - complete the Activity without the result, and
 - have the external process Signal the Workflow when the human responds.
 
-If the Activity fails on the second step to notify the external system and doesn't throw an error, then the Activity will be retried in a minute.
+If the Activity fails on the second step to notify the external system and doesn't throw an error, then the Activity
+will be retried in a minute.
 
-In the second scenario, the failure is retried sooner. This is particularly helpful in scenarios like this in which the external process might take a long time.
+In the second scenario, the failure is retried sooner. This is particularly helpful in scenarios like this in which the
+external process might take a long time.
 
 ### What is a Task Token? {#task-token}
 
@@ -166,4 +188,11 @@ A Task Token is a unique identifier for an [Activity Task Execution](/tasks#acti
 [Asynchronous Activity Completion](#asynchronous-activity-completion) calls take either of the following as arguments:
 
 - a Task Token, or
-- an [Activity Id](#activity-id), a [Workflow Id](/workflow-execution/workflowid-runid#workflow-id), and optionally a [Run Id](/workflow-execution/workflowid-runid#run-id).
+- an [Activity Id](#activity-id), a [Workflow Id](/workflow-execution/workflowid-runid#workflow-id), and optionally a
+  [Run Id](/workflow-execution/workflowid-runid#run-id).
+
+Since a Task Token is unique for an Activity execution, retries can cause a remote service using the Task Token to end
+up with an invalid one. For example, an Activity might fail after passing its current Task Token to a remote service,
+but before returning the complete async error, leaving that service with a Task Token that's no longer valid.
+
+To avoid this risk, you can provide the Activity Id and Workflow Id to the remote service instead of the Task Token.