Merge branch 'main' into python-workflow-init

Author: fairlydurable

docs/develop/typescript/message-passing.mdx

@@ -129,6 +129,11 @@ export async function greetingWorkflow(): Promise<string> {
   This allows you to use Activities, Child Workflows, durable [`workflow.sleep`](https://typescript.temporal.io/api/namespaces/workflow#sleep) Timers, [`workflow.condition`](https://typescript.temporal.io/api/namespaces/workflow#condition) conditions, and more.
   See [Async handlers](#async-handlers) and [Workflow message passing](/encyclopedia/workflow-message-passing) for guidelines on safely using async Signal and Update handlers.
 
+- Delay calling [`workflow.setHandler`](https://typescript.temporal.io/api/namespaces/workflow#sethandler) until the Workflow initialization needed by Signal (or Update) handlers has finished.
+  This is safe because the SDK buffers messages when there are no registered handlers for them.
+  Note that [`workflow.setHandler`](https://typescript.temporal.io/api/namespaces/workflow#sethandler) will immediately invoke the handler of buffered Signals (or Updates) with matching types.
+  This could lead to out-of-order processing of messages with different types.
+
 - `setHandler` can take `SignalHandlerOptions` (such as `description` and `unfinishedPolicy`) as described in the API reference docs for [`workflow.setHandler`](https://typescript.temporal.io/api/namespaces/workflow#sethandler).
 
 
@@ -196,6 +201,10 @@ wf.setHandler(
   This includes the Update ID, which can be useful for deduplication when using Continue-As-New: see [Ensuring your messages are processed exactly once](/encyclopedia/workflow-message-passing#exactly-once-message-processing).
 - Update (and Signal) handlers can be `async`, letting them use Activities, Child Workflows, durable [`workflow.sleep`](https://typescript.temporal.io/api/namespaces/workflow#sleep) Timers, [`workflow.condition`](https://typescript.temporal.io/api/namespaces/workflow#condition) conditions, and more.
   See [Async handlers](#async-handlers) and [Workflow message passing](/encyclopedia/workflow-message-passing) for safe usage guidelines.
+- Delay calling [`workflow.setHandler`](https://typescript.temporal.io/api/namespaces/workflow#sethandler) until the Workflow initialization needed by Update (or Signal) handlers has finished.
+  This is safe because the SDK buffers messages when there are no registered handlers for them.
+  Note that [`workflow.setHandler`](https://typescript.temporal.io/api/namespaces/workflow#sethandler) will immediately invoke the handler of buffered Updates (or Signals) with matching types.
+  This could lead to out-of-order processing of messages with different types.
 
 ## Send messages {#send-messages}
 

docs/encyclopedia/application-message-passing.mdx

@@ -220,22 +220,44 @@ Every time the Workflow wakes up--generally, it wakes up when it needs to--it wi
 
 This execution is on a single thread–while this means you don’t have to worry about parallelism, you do need to worry about concurrency if you have written Signal and Update handlers that can block. These can run interleaved with the main Workflow and with one another, resulting in potential race conditions. These methods should be made reentrant.
 
+#### Initializing the Workflow first {#workflow-initializers}
+
+Initialize your Workflow's state before handling messages.
+This prevents your handler from reading uninitialized instance variables.
+
+To see why, refer to the [diagram](#message-handler-concurrency).
+It shows that your Workflow processes messages before the first run of your Workflow's main method.
+
+The message handler runs first in several scenarios, such as:
+
+- When using [Signal-with-Start](#signal-with-start).
+- When your Worker experiences delays, such as when the Task Queue it polls gets backlogged.
+- When messages arrive immediately after a Workflow continues as new but before it resumes.
+
+For all languages except Go and TypeScript, use your constructor to set up state.
+Annotate your constructor as a Workflow Initializer and take the same arguments as your Workflow's main method.
+
+Note that you can't make blocking calls from your constructor.
+If you need to block, make your Signal or Update handler [wait](#waiting) for an initialization flag.
+
+In Go and TypeScript, register any message handlers only after completing initialization.
+
 ### Message handler patterns {#message-handler-patterns}
 
 Here are several common patterns for write operations, Signal and Update handlers. They don't apply to pure read operations, i.e. Queries or [Update Validators](#update-validators):
 
-- Synchronous, returning immediately.
-- Waiting for the Workflow to be ready to process them.
+- Returning immediately from a handler
+- Waiting for the Workflow to be ready to process them
 - Kicking off activities and other asynchronous tasks
-- Injecting work into the main Workflow.
-- Finishing handlers before the Workflow completes.
-- Ensuring your messages are processed exactly once.
+- Injecting work into the main Workflow
+- Finishing handlers before the Workflow completes
+- Ensuring your messages are processed exactly once
 
 #### Synchronous handlers
 
 Synchronous handlers don’t kick off any long-running operations or otherwise block. They're guaranteed to run atomically.
 
-#### Waiting
+#### Waiting {#waiting}
 
 A Signal or Update handler can block waiting for the Workflow to reach a certain state using a Wait Condition. See the links below to find out how to use this with your SDK.