Update docs to refine explanations for non-determinism (#4448)

* perf(non-determinism): updated versioning boilerplate to include activities to handle non-deterministic operations

* perf(non-determinism): updated encyclopedia pages to include activities to handle non-deterministic operations

* perf(non-determinism): added callout to use cases page

* perf(non-determinism): added explanation about replay without saying determinism

* Update docs/develop/java/workflows/basics.mdx

Co-authored-by: Spencer Judge <spencer@temporal.io>

* chore(determinism): updated technical details and softened language

* Update docs/develop/dotnet/workflows/basics.mdx

Co-authored-by: Brian MacDonald <brian.macdonald@temporal.io>

* Update docs/develop/dotnet/workflows/basics.mdx

Co-authored-by: Brian MacDonald <brian.macdonald@temporal.io>

* Update docs/develop/java/workflows/basics.mdx

Co-authored-by: Brian MacDonald <brian.macdonald@temporal.io>

* Update docs/develop/java/workflows/basics.mdx

Co-authored-by: Brian MacDonald <brian.macdonald@temporal.io>

* Update docs/develop/java/workflows/basics.mdx

Co-authored-by: Brian MacDonald <brian.macdonald@temporal.io>

* Update docs/develop/java/workflows/basics.mdx

Co-authored-by: Brian MacDonald <brian.macdonald@temporal.io>

* Update docs/develop/typescript/best-practices/debugging.mdx

Co-authored-by: Brian MacDonald <brian.macdonald@temporal.io>

* chore(determinism): updated explanation for Workflow replay

---------

Co-authored-by: Spencer Judge <spencer@temporal.io>
Co-authored-by: Brian MacDonald <brian.macdonald@temporal.io>

Author: 3 people

docs/develop/dotnet/workflows/basics.mdx

@@ -44,11 +44,9 @@ All Workflow Definition parameters must be serializable.
 
 ## Workflow logic requirements {#workflow-logic-requirements}
 
-Workflow logic is constrained by [deterministic execution requirements](/workflow-definition#deterministic-constraints).
-Therefore, each language is limited to the use of certain idiomatic techniques.
-However, each Temporal SDK provides a set of APIs that can be used inside your Workflow to interact with external (to the Workflow) application code.
+Workflow logic is constrained by [deterministic execution requirements](/workflow-definition#deterministic-constraints). Each Temporal SDK provides a set of APIs that can be used inside your Workflow to interact with application code outside the Workflow.
 
-This means there are several things Workflows cannot do such as:
+This means there are several things Workflows shouldn't do such as:
 
 - Perform IO (network, disk, stdio, etc)
 - Access/alter external mutable state
@@ -65,34 +63,28 @@ This is especially true with `Task`s.
 Temporal requires that the deterministic `TaskScheduler.Current` is used, but many .NET async calls will use `TaskScheduler.Default` implicitly (and some analyzers even encourage this).
 Here are some known gotchas to avoid with .NET tasks inside of Workflows:
 
-- Do not use `Task.Run` - this uses the default scheduler and puts work on the thread pool.
-  - Use `Workflow.RunTaskAsync` instead.
-  - Can also use `Task.Factory.StartNew` with current scheduler or instantiate the `Task` and run `Task.Start` on it.
-- Do not use `Task.ConfigureAwait(false)` - this will not use the current context.
-  - If you must use `Task.ConfigureAwait`, use `Task.ConfigureAwait(true)`.
-  - There is no significant performance benefit to `Task.ConfigureAwait` in workflows anyways due to how the scheduler works.
-- Do not use anything that defaults to the default task scheduler.
-- Do not use `Task.Delay`, `Task.Wait`, timeout-based `CancellationTokenSource`, or anything that uses .NET built-in timers.
-  - `Workflow.DelayAsync`, `Workflow.WaitConditionAsync`, or non-timeout-based cancellation token source is suggested.
-- Do not use `Task.WhenAny`.
-  - Use `Workflow.WhenAnyAsync` instead.
+-  Use `Workflow.RunTaskAsync` instead of `Task.Run`. `Task.Run` uses the default scheduler and puts work on the thread pool.
+    - You can also use `Task.Factory.StartNew` with current scheduler or instantiate the `Task` and run `Task.Start` on it.
+- If you need to use `Task.ConfigureAwait`, use `Task.ConfigureAwait(true)`. `Task.ConfigureAwait(false)` won't use the current context.
+  - There is no significant performance benefit to `Task.ConfigureAwait` in workflows because of how the scheduler works.
+- Avoid anything that defaults to the default task scheduler.
+- Use `Workflow.DelayAsync`, `Workflow.WaitConditionAsync`, or non-timeout-based cancellation token sources instead of `Task.Delay`, `Task.Wait`, timeout-based `CancellationTokenSource`, or anything that uses .NET built-in timers.
+- Use `Workflow.WhenAnyAsync` instead of `Task.WhenAny`.
   - Technically this only applies to an enumerable set of tasks with results or more than 2 tasks with results. Other
     uses are safe. See [this issue](https://github.com/dotnet/runtime/issues/87481).
-- Do not use `Task.WhenAll`
-  - Use `Workflow.WhenAllAsync` instead.
+- Use `Workflow.WhenAllAsync` instead of `Task.WhenAll`.
   - Technically `Task.WhenAll` is currently deterministic in .NET and safe, but it is better to use the wrapper to be
     sure.
-- Do not use `CancellationTokenSource.CancelAsync`.
-  - Use `CancellationTokenSource.Cancel` instead.
-- Do not use `System.Threading.Semaphore` or `System.Threading.SemaphoreSlim` or `System.Threading.Mutex`.
-  - Use `Temporalio.Workflows.Semaphore` or `Temporalio.Workflows.Mutex` instead.
+- Use `CancellationTokenSource.Cancel` instead of `CancellationTokenSource.CancelAsync`.
+- Use `Temporalio.Workflows.Semaphore` or `Temporalio.Workflows.Mutex` instead of `System.Threading.Semaphore`, `System.Threading.SemaphoreSlim`, or `System.Threading.Mutex`.
   - _Technically_ `SemaphoreSlim` does work if only the async form of `WaitAsync` is used without no timeouts and
     `Release` is used. But anything else can deadlock the workflow and its use is cumbersome since it must be disposed.
 - Be wary of additional libraries' implicit use of the default scheduler.
   - For example, while there are articles for `Dataflow` about [using a specific scheduler](https://learn.microsoft.com/en-us/dotnet/standard/parallel-programming/how-to-specify-a-task-scheduler-in-a-dataflow-block), there are hidden implicit uses of `TaskScheduler.Default`. For example, see [this bug](https://github.com/dotnet/runtime/issues/83159).
 
 In order to help catch wrong scheduler use, by default the Temporal .NET SDK adds an event source listener for info-level task events.
 While this technically receives events from all uses of tasks in the process, we make sure to ignore anything that is not running in a Workflow in a high performant way (basically one thread local check).
+
 For code that does run in a Workflow and accidentally starts a task in another scheduler, an `InvalidWorkflowOperationException` will be thrown which "pauses" the Workflow (fails the Workflow Task which continually retries until the code is fixed).
 This is unfortunately a runtime-only check, but can help catch mistakes early. If this needs to be turned off for any reason, set `DisableWorkflowTracingEventListener` to `true` in Worker options.
 

docs/develop/dotnet/workflows/versioning.mdx

@@ -31,8 +31,8 @@ import { CaptionedImage } from '@site/src/components';
 
 Since Workflow Executions in Temporal can run for long periods — sometimes months or even years — it's common to need to make changes to a Workflow Definition, even while a particular Workflow Execution is in progress.
 
-The Temporal Platform requires that Workflow code is [deterministic](/workflow-definition#deterministic-constraints).
-If you make a change to your Workflow code that would cause non-deterministic behavior on Replay, you'll need to use one of our Versioning methods to gracefully update your running Workflows.
+The Temporal Platform requires that Workflow code is [deterministic](/workflow-definition#deterministic-constraints). If you make a change to your Workflow code that would cause non-deterministic behavior on Replay, you'll need to use one of our Versioning methods to gracefully update your running Workflows. This only applies to Workflow orchestration logic. Non-deterministic work such as API calls, and database queries should be placed in Activities, which Temporal retries reliably.
+
 With Versioning, you can modify your Workflow Definition so that new executions use the updated code, while existing ones continue running the original version.
 There are two primary Versioning methods that you can use:
 

docs/develop/go/workflows/basics.mdx

@@ -183,9 +183,7 @@ func main() {
 
 ### How to develop Workflow logic {#workflow-logic-requirements}
 
-Workflow logic is constrained by [deterministic execution requirements](/workflow-definition#deterministic-constraints).
-Therefore, each language is limited to the use of certain idiomatic techniques.
-However, each Temporal SDK provides a set of APIs that can be used inside your Workflow to interact with external (to the Workflow) application code.
+Workflow logic is constrained by [deterministic execution requirements](/workflow-definition#deterministic-constraints). Each Temporal SDK provides a set of APIs that can be used inside your Workflow to interact with application code outside the Workflow.
 
 In Go, Workflow Definition code cannot directly do the following:
 

docs/develop/go/workflows/versioning.mdx

@@ -20,8 +20,8 @@ tags:
 
 Since Workflow Executions in Temporal can run for long periods — sometimes months or even years — it's common to need to make changes to a Workflow Definition, even while a particular Workflow Execution is in progress.
 
-The Temporal Platform requires that Workflow code is [deterministic](/workflow-definition#deterministic-constraints).
-If you make a change to your Workflow code that would cause non-deterministic behavior on Replay, you'll need to use one of our Versioning methods to gracefully update your running Workflows.
+The Temporal Platform requires that Workflow code is [deterministic](/workflow-definition#deterministic-constraints). If you make a change to your Workflow code that would cause non-deterministic behavior on Replay, you'll need to use one of our Versioning methods to gracefully update your running Workflows. This only applies to Workflow orchestration logic. Non-deterministic work such as API calls, and database queries should be placed in Activities, which Temporal retries reliably.
+
 With Versioning, you can modify your Workflow Definition so that new executions use the updated code, while existing ones continue running the original version.
 There are two primary Versioning methods that you can use:
 

docs/develop/java/workflows/basics.mdx

@@ -211,34 +211,23 @@ When you set the Workflow Type this way, the value of the `name` parameter does
 
 ## Workflow logic requirements {#workflow-logic-requirements}
 
-Workflow logic is constrained by [deterministic execution requirements](/workflow-definition#deterministic-constraints).
-Therefore, each language is limited to the use of certain idiomatic techniques.
-However, each Temporal SDK provides a set of APIs that can be used inside your Workflow to interact with external (to the Workflow) application code.
+Workflow logic is constrained by [deterministic execution requirements](/workflow-definition#deterministic-constraints). Each Temporal SDK provides a set of APIs that can be used inside your Workflow to interact with external (to the Workflow) application code.
 
 When defining Workflows using the Temporal Java SDK, the Workflow code must be written to execute effectively once and to completion.
 
 The following constraints apply when writing Workflow Definitions:
 
-- Do not use mutable global variables in your Workflow implementations.
-  This will ensure that multiple Workflow instances are fully isolated.
-- Your Workflow code must be deterministic.
-  Do not call non-deterministic functions (such as non-seeded random or `UUID.randomUUID()`) directly from the Workflow code.
-  The Temporal SDK provides specific API for calling non-deterministic code in your Workflows.
-- Do not use programming language constructs that rely on system time.
-  For example, only use `Workflow.currentTimeMillis()` to get the current time inside a Workflow.
-- Do not use native Java `Thread` or any other multi-threaded classes like `ThreadPoolExecutor`.
-  Use `Async.function` or `Async.procedure`, provided by the Temporal SDK, to execute code asynchronously.
-- Do not use synchronization, locks, or other standard Java blocking concurrency-related classes besides those provided by the Workflow class.
-  There is no need for explicit synchronization because multi-threaded code inside a Workflow is executed one thread at a time and under a global lock.
+- Do not use mutable global variables in your Workflow implementations. This will ensure that multiple Workflow instances are fully isolated.
+- Workflow code must be deterministic. If you need to call non-deterministic functions (such as non-seeded random or `UUID.randomUUID()`) directly from the Workflow code, the Temporal SDK provides specific API for calling non-deterministic code in your Workflows.
+  - For operations like calling external APIs, invoking LLMs, querying databases, or performing I/O, use Activities. Activities run outside Workflow replay and are retried reliably.
+- Use Temporal-provided functions instead of that rely on system time. For example, use only `Workflow.currentTimeMillis()` to get the current time inside a Workflow.
+- Use `Async.function` or `Async.procedure`, provided by the Temporal SDK, to execute code asynchronously instead of native Java `Thread` or any other multi-threaded classes like `ThreadPoolExecutor`.
+- Use only the concurrency features provided by the Workflow class. Multi-threaded code inside a Workflow is executed one thread at a time and under a global lock, so there is no need for explicit synchronization.
   - Call `Workflow.sleep` instead of `Thread.sleep`.
   - Use `Promise` and `CompletablePromise` instead of `Future` and `CompletableFuture`.
   - Use `WorkflowQueue` instead of `BlockingQueue`.
-- Use `Workflow.getVersion` when making any changes to the Workflow code.
-  Without this, any deployment of updated Workflow code might break already running Workflows.
-- Do not access configuration APIs directly from a Workflow because changes in the configuration might affect a Workflow Execution path.
-  Pass it as an argument to a Workflow function or use an Activity to load it.
-- Use `DynamicWorkflow` when you need a default Workflow that can handle all Workflow Types that are not registered with a Worker.
-  A single implementation can implement a Workflow Type which by definition is dynamically loaded from some external source.
-  All standard `WorkflowOptions` and determinism rules apply to Dynamic Workflow implementations.
+- Use `Workflow.getVersion` when making any changes to the Workflow code to avoid deployment of updated Workflow code interfering with already-running Workflows.
+- Do not access configuration APIs directly from a Workflow because changes in the configuration might affect a Workflow Execution path. Instead, pass it as an argument to a Workflow function or use an Activity to load it.
+- Use `DynamicWorkflow` when you need a default Workflow that can handle all Workflow Types that are not registered with a Worker. A single implementation can implement a Workflow Type which by definition is dynamically loaded from some external source. All standard `WorkflowOptions` and determinism rules apply to Dynamic Workflow implementations.
 
 Java Workflow reference: [https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/workflow/package-summary.html](https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/workflow/package-summary.html)

docs/develop/java/workflows/versioning.mdx

@@ -21,8 +21,8 @@ tags:
 
 Since Workflow Executions in Temporal can run for long periods — sometimes months or even years — it's common to need to make changes to a Workflow Definition, even while a particular Workflow Execution is in progress.
 
-The Temporal Platform requires that Workflow code is [deterministic](/workflow-definition#deterministic-constraints).
-If you make a change to your Workflow code that would cause non-deterministic behavior on Replay, you'll need to use one of our Versioning methods to gracefully update your running Workflows.
+The Temporal Platform requires that Workflow code is [deterministic](/workflow-definition#deterministic-constraints). If you make a change to your Workflow code that would cause non-deterministic behavior on Replay, you'll need to use one of our Versioning methods to gracefully update your running Workflows. This only applies to Workflow orchestration logic. Non-deterministic work such as API calls, and database queries should be placed in Activities, which Temporal retries reliably.
+
 With Versioning, you can modify your Workflow Definition so that new executions use the updated code, while existing ones continue running the original version.
 There are two primary Versioning methods that you can use:
 

docs/develop/php/workflows/basics.mdx

@@ -96,9 +96,7 @@ interface YourWorkflowDefinitionInterface
 
 ### How to develop Workflow logic {#workflow-logic-requirements}
 
-Workflow logic is constrained by [deterministic execution requirements](/workflow-definition#deterministic-constraints).
-Therefore, each language is limited to the use of certain idiomatic techniques.
-However, each Temporal SDK provides a set of APIs that can be used inside your Workflow to interact with external (to the Workflow) application code.
+Workflow logic is constrained by [deterministic execution requirements](/workflow-definition#deterministic-constraints). Each Temporal SDK provides a set of APIs that can be used inside your Workflow to interact with application code outside the Workflow. used inside your Workflow to interact with external (to the Workflow) application code.
 
 \*\*Temporal uses the [Microsoft Azure Event Sourcing pattern](https://docs.microsoft.com/en-us/azure/architecture/patterns/event-sourcing) to recover the state of a Workflow object including its local variable values.
 

docs/develop/php/workflows/versioning.mdx

@@ -29,8 +29,8 @@ tags:
 
 Since Workflow Executions in Temporal can run for long periods — sometimes months or even years — it's common to need to make changes to a Workflow Definition, even while a particular Workflow Execution is in progress.
 
-The Temporal Platform requires that Workflow code is [deterministic](/workflow-definition#deterministic-constraints).
-If you make a change to your Workflow code that would cause non-deterministic behavior on Replay, you'll need to use one of our Versioning methods to gracefully update your running Workflows.
+The Temporal Platform requires that Workflow code is [deterministic](/workflow-definition#deterministic-constraints). If you make a change to your Workflow code that would cause non-deterministic behavior on Replay, you'll need to use one of our Versioning methods to gracefully update your running Workflows. This only applies to Workflow orchestration logic. Non-deterministic work such as API calls, and database queries should be placed in Activities, which Temporal retries reliably.
+
 With Versioning, you can modify your Workflow Definition so that new executions use the updated code, while existing ones continue running the original version.
 There are two primary Versioning methods that you can use:
 

docs/develop/python/workflows/basics.mdx

@@ -163,7 +163,7 @@ class YourWorkflow:
 **How to develop Workflow logic using the Temporal Python SDK.**
 
 Workflow logic is constrained by [deterministic execution requirements](/workflow-definition#deterministic-constraints).
-Therefore, each language is limited to the use of certain idiomatic techniques. However, each Temporal SDK provides a
+Each Temporal SDK provides a
 set of APIs that can be used inside your Workflow to interact with external (to the Workflow) application code.
 
 Workflow code must be deterministic because the Temporal Server may [replay](/develop/python/best-practices/testing-suite#replay) your Workflow to reconstruct its state. This means:

docs/develop/python/workflows/versioning.mdx

@@ -32,8 +32,8 @@ import { CaptionedImage } from '@site/src/components';
 
 Since Workflow Executions in Temporal can run for long periods — sometimes months or even years — it's common to need to make changes to a Workflow Definition, even while a particular Workflow Execution is in progress.
 
-The Temporal Platform requires that Workflow code is [deterministic](/workflow-definition#deterministic-constraints).
-If you make a change to your Workflow code that would cause non-deterministic behavior on Replay, you'll need to use one of our Versioning methods to gracefully update your running Workflows.
+The Temporal Platform requires that Workflow code is [deterministic](/workflow-definition#deterministic-constraints). If you make a change to your Workflow code that would cause non-deterministic behavior on Replay, you'll need to use one of our Versioning methods to gracefully update your running Workflows. This only applies to Workflow orchestration logic. Non-deterministic work such as API calls, and database queries should be placed in Activities, which Temporal retries reliably.
+
 With Versioning, you can modify your Workflow Definition so that new executions use the updated code, while existing ones continue running the original version.
 There are two primary Versioning methods that you can use: