Document replay-safe Workflow APIs per SDK (#5054)

* Document replay-safe Workflow APIs per SDK

Add a heading per topic under the Workflow logic requirements section so
readers can find the replay-safe alternative for what they need.

- Ruby and .NET: add Logging, Random/UUIDs, Current time, and Detecting
  replay sections. Neither page previously named any replacement API.
- Go: add the same four sections. Go has no built-in seeded random or
  UUID helper, so that section shows the Side Effect approach.
- Java: add the same four sections, and point the existing
  "non-deterministic functions" bullet at the new one.
- TypeScript: lead the Random/UUIDs section with the SDK's own uuid4()
  instead of the uuid npm package.

Each documented API was run against a dev server and its history replayed
through the SDK replayer.

* Remove counter-examples from Random numbers sections

Show only the recommended API. Also removes the pre-existing bad example
from the Python page.

* Use WorkflowUnsafe.isReplaying() in Java replay detection

Workflow.isReplaying() is deprecated in favor of the unsafe package
method, which also matches the other SDKs.

Author: lennessyy

docs/develop/dotnet/workflows/basics.mdx

@@ -86,6 +86,77 @@ This means there are several things Workflows shouldn't do such as:
 - Make any random calls
 - Make any not-guaranteed-deterministic calls (e.g. iterating over a dictionary)
 
+The SDK provides replay-safe alternatives for common needs.
+
+### Logging
+
+Use [`Workflow.Logger`](https://dotnet.temporal.io/api/Temporalio.Workflows.Workflow.html#Temporalio_Workflows_Workflow_Logger)
+instead of `Console.WriteLine` or a logger you resolve yourself.
+The SDK logger appends Workflow details to every log and skips logging during replay:
+
+```csharp
+[Workflow]
+public class MyWorkflow
+{
+    [WorkflowRun]
+    public async Task<string> RunAsync(string name)
+    {
+        Workflow.Logger.LogInformation("Starting workflow for {Name}", name);
+        // ...
+    }
+}
+```
+
+For logger configuration, see [Observability: Log from a Workflow](/develop/dotnet/platform/observability#logging).
+
+### Random numbers and GUIDs
+
+Use [`Workflow.Random`](https://dotnet.temporal.io/api/Temporalio.Workflows.Workflow.html#Temporalio_Workflows_Workflow_Random)
+to get a deterministic random instance seeded per Workflow Execution, and
+[`Workflow.NewGuid()`](https://dotnet.temporal.io/api/Temporalio.Workflows.Workflow.html#Temporalio_Workflows_Workflow_NewGuid)
+instead of `Guid.NewGuid()`:
+
+```csharp
+var value = Workflow.Random.Next(1, 100);
+var uniqueId = Workflow.NewGuid();
+```
+
+### Current time
+
+Use [`Workflow.UtcNow`](https://dotnet.temporal.io/api/Temporalio.Workflows.Workflow.html#Temporalio_Workflows_Workflow_UtcNow)
+instead of `DateTime.Now` or `DateTime.UtcNow`. It returns the time of the last Workflow Task, which is consistent
+across replays:
+
+```csharp
+var currentTime = Workflow.UtcNow;
+```
+
+To wait, use `Workflow.DelayAsync` instead of `Task.Delay` or `Thread.Sleep`.
+
+### Detecting replay (advanced)
+
+Use [`Workflow.Unsafe.IsReplaying`](https://dotnet.temporal.io/api/Temporalio.Workflows.Workflow.Unsafe.html#Temporalio_Workflows_Workflow_Unsafe_IsReplaying)
+to guard code that should only run on the first execution, such as emitting metrics or sending external notifications
+from an [Interceptor](/develop/dotnet/workers/interceptors).
+
+:::caution
+
+Never use this to affect Workflow business logic. Branching on replay status breaks determinism.
+
+:::
+
+```csharp
+if (!Workflow.Unsafe.IsReplaying)
+{
+    EmitMetric("workflow_started", 1);
+}
+```
+
+If your goal is to always take action when something new is happening, check that
+[`Workflow.Unsafe.IsReplayingHistoryEvents`](https://dotnet.temporal.io/api/Temporalio.Workflows.Workflow.Unsafe.html#Temporalio_Workflows_Workflow_Unsafe_IsReplayingHistoryEvents)
+is false instead. That is false during read-only operations like Queries and Update validators. This is what the SDK's
+built-in logger and tracing interceptors use internally.
+
 ### .NET Task Determinism
 
 Some calls in .NET do unsuspecting non-deterministic things and are easy to accidentally use.

docs/develop/go/workflows/basics.mdx

@@ -224,3 +224,63 @@ The Temporal Go SDK has APIs to handle equivalent Go constructs:
   Learn more on the [Go SDK Selectors](https://legacy-documentation-sdks.temporal.io/go/selectors) page.
 - `workflow.Context` This is a replacement for `context.Context`.
   See [Tracing](/develop/go/platform/observability#tracing) for more information about context propagation.
+
+#### Logging
+
+Use [`workflow.GetLogger(ctx)`](https://pkg.go.dev/go.temporal.io/sdk/workflow#GetLogger) instead of the standard
+`log` package or `fmt.Println`. The SDK logger skips log messages during replay to avoid duplicates:
+
+```go
+func MyWorkflow(ctx workflow.Context, name string) (string, error) {
+	logger := workflow.GetLogger(ctx)
+	logger.Info("Starting workflow", "name", name)
+	// ...
+}
+```
+
+For logger configuration, see [Observability: Log from a Workflow](/develop/go/platform/observability#logging).
+
+#### Random numbers and UUIDs
+
+The Go SDK does not provide a seeded random source or a UUID helper. Generate these inside a
+[Side Effect](/develop/go/workflows/side-effects), which records the result in the Event History and returns the
+recorded value on replay:
+
+```go
+var id string
+encodedID := workflow.SideEffect(ctx, func(ctx workflow.Context) interface{} {
+	return uuid.New().String()
+})
+encodedID.Get(&id)
+```
+
+An Activity works for this too, and is the better choice when the value comes from an external system. A Side Effect is
+cheaper for purely local generation.
+
+#### Current time
+
+Use [`workflow.Now(ctx)`](https://pkg.go.dev/go.temporal.io/sdk/workflow#Now) instead of `time.Now()`. It returns the
+time of the last Workflow Task, which is consistent across replays:
+
+```go
+currentTime := workflow.Now(ctx)
+```
+
+To wait, use [`workflow.Sleep(ctx, d)`](https://pkg.go.dev/go.temporal.io/sdk/workflow#Sleep) instead of `time.Sleep`.
+
+#### Detecting replay (advanced)
+
+Use [`workflow.IsReplaying(ctx)`](https://pkg.go.dev/go.temporal.io/sdk/workflow#IsReplaying) to guard code that should
+only run on the first execution, such as emitting metrics or sending external notifications from an Interceptor.
+
+:::caution
+
+Never use this to affect Workflow business logic. Branching on replay status breaks determinism.
+
+:::
+
+```go
+if !workflow.IsReplaying(ctx) {
+	emitMetric("workflow_started", 1)
+}
+```

docs/develop/java/workflows/basics.mdx

@@ -253,7 +253,7 @@ When defining Workflows using the Temporal Java SDK, the Workflow code must be w
 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.
-- 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.
+- 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 replay-safe replacements. See [Random numbers and UUIDs](#random-numbers-and-uuids).
   - 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`.
@@ -265,4 +265,71 @@ The following constraints apply when writing Workflow Definitions:
 - 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.
 
+The SDK provides replay-safe alternatives for common needs.
+
+### Logging
+
+Use [`Workflow.getLogger()`](https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/workflow/Workflow.html)
+instead of `System.out.println` or a logger you create yourself. The SDK logger skips log messages during replay to
+avoid duplicates:
+
+```java
+public class MyWorkflowImpl implements MyWorkflow {
+  private static final Logger logger = Workflow.getLogger(MyWorkflowImpl.class);
+
+  @Override
+  public String execute(String name) {
+    logger.info("Starting workflow for {}", name);
+    // ...
+  }
+}
+```
+
+For logger configuration, see [Observability: Log from a Workflow](/develop/java/platform/observability#logging).
+
+### Random numbers and UUIDs
+
+Use [`Workflow.newRandom()`](https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/workflow/Workflow.html)
+to get a `Random` instance seeded per Workflow Execution, and
+[`Workflow.randomUUID()`](https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/workflow/Workflow.html)
+instead of `UUID.randomUUID()`:
+
+```java
+int value = Workflow.newRandom().nextInt(100);
+UUID uniqueId = Workflow.randomUUID();
+```
+
+### Current time
+
+Use [`Workflow.currentTimeMillis()`](https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/workflow/Workflow.html)
+instead of `System.currentTimeMillis()` or `Instant.now()`. It returns the time of the last Workflow Task, which is
+consistent across replays:
+
+```java
+long currentTime = Workflow.currentTimeMillis();
+```
+
+To wait, use [`Workflow.sleep()`](https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/workflow/Workflow.html)
+instead of `Thread.sleep()`.
+
+### Detecting replay (advanced)
+
+Use [`WorkflowUnsafe.isReplaying()`](https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/workflow/unsafe/WorkflowUnsafe.html)
+to guard code that should only run on the first execution, such as emitting metrics or sending external notifications
+from an Interceptor. `Workflow.isReplaying()` is deprecated in favor of this method.
+
+:::caution
+
+Never use this to affect Workflow business logic. Branching on replay status breaks determinism.
+
+:::
+
+```java
+import io.temporal.workflow.unsafe.WorkflowUnsafe;
+
+if (!WorkflowUnsafe.isReplaying()) {
+  emitMetric("workflow_started", 1);
+}
+```
+
 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/python/workflows/basics.mdx

@@ -202,13 +202,8 @@ Use [`workflow.random()`](https://python.temporal.io/temporalio.workflow.html#ra
 For UUIDs, use [`workflow.uuid4()`](https://python.temporal.io/temporalio.workflow.html#uuid4) instead of `uuid.uuid4()`:
 
 ```python
-# Good - deterministic across replays
 value = workflow.random().randint(1, 100)
 unique_id = workflow.uuid4()
-
-# Bad - different result on every replay
-import random
-value = random.randint(1, 100)
 ```
 
 #### Current time

docs/develop/ruby/workflows/basics.mdx

@@ -98,3 +98,75 @@ Ruby Workflows. This means there are several things Workflows cannot do such as:
 To prevent illegal Workflow calls, a call tracer is put on the Workflow thread that raises an exception if any illegal
 calls are made.
 Which calls are illegal is configurable in the Worker options.
+
+The SDK provides replay-safe alternatives for common needs.
+
+### Logging
+
+Use [`Temporalio::Workflow.logger`](https://ruby.temporal.io/Temporalio/Workflow.html#logger-class_method) instead of
+`puts` or a `Logger` you create yourself. The `Logger` class is on the default illegal call list, and the SDK logger
+appends Workflow details to every log and skips logging during replay:
+
+```ruby
+class MyWorkflow < Temporalio::Workflow::Definition
+  def execute(name)
+    Temporalio::Workflow.logger.info("Starting workflow for #{name}")
+    # ...
+  end
+end
+```
+
+For logger configuration, see [Observability: Log from a Workflow](/develop/ruby/platform/observability#logging).
+
+### Random numbers and UUIDs
+
+Use [`Temporalio::Workflow.random`](https://ruby.temporal.io/Temporalio/Workflow.html#random-class_method) to get a
+`Random` instance seeded per Workflow Execution. The SDK requires `random/formatter`, so this instance also has the
+standard library's [`Random::Formatter#uuid`](https://rubyapi.org/4.0/o/random/formatter#method-i-uuid) method. Use it
+instead of `SecureRandom.uuid`:
+
+```ruby
+value = Temporalio::Workflow.random.rand(1..100)
+unique_id = Temporalio::Workflow.random.uuid
+```
+
+Don't use `SecureRandom`, `Kernel#rand`, `Kernel#srand`, or `Random.new` in Workflow code. They're on the default
+illegal call list, and the call tracer raises a `Temporalio::Workflow::NondeterminismError` when it detects them.
+
+Access the instance each time you need it rather than storing it in an instance variable. The SDK may recreate it with a
+different seed, such as after a Workflow reset.
+
+### Current time
+
+Use [`Temporalio::Workflow.now`](https://ruby.temporal.io/Temporalio/Workflow.html#now-class_method) instead of
+`Time.now`. It returns the UTC time of the last Workflow Task, which is consistent across replays:
+
+```ruby
+current_time = Temporalio::Workflow.now
+```
+
+To wait, use [`Temporalio::Workflow.sleep`](https://ruby.temporal.io/Temporalio/Workflow.html#sleep-class_method)
+instead of `Kernel#sleep`.
+
+### Detecting replay (advanced)
+
+Use [`Temporalio::Workflow::Unsafe.replaying?`](https://ruby.temporal.io/Temporalio/Workflow/Unsafe.html#replaying?-class_method)
+to guard code that should only run on the first execution, such as emitting metrics or sending external notifications
+from an Interceptor.
+
+:::caution
+
+Never use this to affect Workflow business logic. Branching on replay status breaks determinism.
+
+:::
+
+```ruby
+unless Temporalio::Workflow::Unsafe.replaying?
+  emit_metric('workflow_started', 1)
+end
+```
+
+If your goal is to always take action when something new is happening, check that
+[`Temporalio::Workflow::Unsafe.replaying_history_events?`](https://ruby.temporal.io/Temporalio/Workflow/Unsafe.html#replaying_history_events?-class_method)
+is false instead. That is false during read-only operations like Queries and Update validators. This is what the SDK's
+built-in logger uses internally.

docs/develop/typescript/workflows/basics.mdx

@@ -158,16 +158,19 @@ For logger configuration, see [Observability: Log from a Workflow](/develop/type
 
 #### Random numbers and UUIDs
 
-`Math.random()` is replaced by a deterministic version in the sandbox, so you can use it directly. It produces the same sequence of values on replay. UUID libraries that rely on `Math.random()` (such as the `uuid` package) are also safe to use. Avoid `crypto.randomUUID()`, which is not available in the sandbox:
+`Math.random()` is replaced by a deterministic version in the sandbox, so you can use it directly. It produces the same sequence of values on replay.
+
+For UUIDs, use [`uuid4()`](https://typescript.temporal.io/api/namespaces/workflow#uuid4) from `@temporalio/workflow`. It draws from the sandbox's deterministic random source, so it needs no extra dependency. Avoid `crypto.randomUUID()`, which is not available in the sandbox:
 
 ```ts
-import { v4 as uuid4 } from 'uuid';
+import { uuid4 } from '@temporalio/workflow';
 
-// Safe - Math.random() is deterministic in the Workflow sandbox
 const value = Math.random();
 const id = uuid4();
 ```
 
+Third-party UUID libraries that rely on `Math.random()` (such as the `uuid` package) are also safe, but the built-in avoids the dependency.
+
 #### Current time
 
 `Date.now()` and `new Date()` are replaced by deterministic versions that return the time of the last Workflow Task completion. The value only advances when you `await` something (like `sleep()`):