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

Author: flippedcoder

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). 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.
 
 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.
+- 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.
+  - 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.
+- 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.
   - 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. 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.
 
 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/encyclopedia/retry-policies.mdx

@@ -3,8 +3,7 @@ id: retry-policies
 title: What is a Temporal Retry Policy?
 sidebar_label: Retry Policies
 description:
-  Optimize your Workflow and Activity Task Executions with a custom Retry Policy on Temporal. Understand default
-  retries, intervals, backoff, and maximum attempts for error handling.
+  Optimize your Workflow and Activity Task Executions with a custom Retry Policy on Temporal Understand default retries, intervals, backoff, and maximum attempts for error handling.
 toc_max_heading_level: 4
 keywords:
   - activities
@@ -18,22 +17,17 @@ import { CaptionedImage, RelatedReadContainer, RelatedReadItem } from '@site/src
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-A Retry Policy is a collection of settings that tells Temporal how and when to try again after something fails in a
-Workflow Execution or Activity Task Execution.
+A Retry Policy is a collection of settings that tells Temporal how and when to try again after something fails in a Workflow Execution or Activity Task Execution.
 
 ## Overview
 
-Temporal's default behavior is to automatically retry an Activity that fails, so transient or intermittent failures
-require no action on your part. This behavior is defined by the Retry Policy.
+Temporal's default behavior is to automatically retry an Activity that fails, so transient or intermittent failures require no action on your part. This behavior is defined by the Retry Policy.
 
-A Retry Policy is declarative. You do not need to implement your own logic for handling the retries; you only need to
-specify the desired behavior and Temporal will provide it.
+A Retry Policy is declarative. You do not need to implement your own logic for handling the retries; you only need to specify the desired behavior and Temporal will provide it.
 
-In contrast to the Activities it contains, a Workflow Execution itself is not associated with a Retry Policy by default.
-This may seem counterintuitive, but Workflows and Activities perform different roles. Activities are intended for
-operations that may fail, so having a default Retry Policy increases the likelihood that they will ultimately complete
-successfully, even if the initial attempt failed. On the other hand, Workflows must be deterministic and are not
-intended to perform failure-prone operations. While it is possible to assign a Retry Policy to a Workflow Execution,
+In contrast to the Activities it contains, a Workflow Execution itself is not associated with a Retry Policy by default. This may seem counterintuitive, but Workflows and Activities perform different roles. Activities are intended for operations that may fail, so having a default Retry Policy increases the likelihood that they will ultimately complete successfully, even if the initial attempt failed.
+
+On the other hand, Workflow code must be deterministic to support replay, and failure-prone or non-deterministic operations (API calls, LLM invocations, etc.) should be placed in Activities, which have built-in retry support. While it is possible to assign a Retry Policy to a Workflow Execution,
 this is not the default and it is uncommon to do so.
 
 Retry Policies do not apply to Workflow Task Executions, which retry until the Workflow Execution Timeout (which is
@@ -136,14 +130,9 @@ re-execute upon failure; this is not typically true of Workflows. In most use ca
 an issue with the design or deployment of your application; for example, a permanent failure that may require different
 input data.
 
-Retrying an entire Workflow Execution is not recommended due to Temporal's deterministic design. Since Workflows replay
-the same sequence of events to reach the same state, retrying the whole workflow would repeat the same logic without
-resolving the underlying issue that caused the failure. This repetition does not address problems related to external
-dependencies or unchanged conditions and can lead to unnecessary resource consumption and higher costs. Instead, it's
-more efficient to retry only the failed Activities. This approach targets specific points of failure, allowing the
-workflow to progress without redundant operations, thereby saving on resources and ensuring a more focused and effective
-error recovery process. If you need to retry parts of your Workflow Definition, we recommend you implement this in your
-Workflow code.
+Retrying an entire Workflow Execution is not recommended due to the deterministic nature of Workflow replay. Since Workflows replay the same sequence of events to reach the same state, retrying the whole Workflow would repeat the same logic without resolving the underlying issue that caused the failure. This repetition doesn't address problems related to external dependencies or unchanged conditions and can lead to unnecessary resource consumption and higher costs.
+
+Instead, retry failed Activities within the Workflow, which is Temporal's default behavior. This approach targets specific points of failure, allowing the Workflow to progress without redundant operations, thereby saving on resources and ensuring a more focused and effective error recovery process. If you need to retry parts of your Workflow Definition, we recommend you implement this in your Workflow code.
 
 ## Custom Retry Policy
 

docs/encyclopedia/workflow/workflow-definition.mdx

@@ -160,6 +160,12 @@ A critical aspect of developing Workflow Definitions is ensuring that they are d
 Generally speaking, this means you must take care to ensure that any time your Workflow code is executed it makes the same Workflow API calls in the same sequence, given the same input.
 Some changes to those API calls are safe to make.
 
+:::tip Note on determinism
+
+Workflow code must be deterministic to support replay. To handle non-deterministic operations like API calls, LLM/AI invocations, database queries, and other external interactions, put them in Activities. Activities execute outside the replay path and are automatically retried so they don't cause non-determinism errors.
+
+:::
+
 For example, you can change:
 
 - The input parameters, return values, and execution timeouts of Child Workflows and Activities