EDU-3170: Updates Worker Task Queue coverage for Nexus

SME Phil

docs/encyclopedia/workers.mdx

@@ -219,8 +219,7 @@ The Temporal Service interprets the outcome and determines whether to retry the
 ## What is a Task Queue? {#task-queue}
 
 A Task Queue is a lightweight, dynamically allocated queue that one or more [Worker Entities](#worker-entity) poll for [Tasks](#task).
-
-There are three types of Task Queues, Activity Task Queues, Workflow Task Queues, and Nexus Task Queues.
+There are three types of Task Queues: Activity Task Queues, Workflow Task Queues, and Nexus Task Queues.
 
 <div className="tdiw">
   <div className="tditw">
@@ -235,41 +234,62 @@ There are three types of Task Queues, Activity Task Queues, Workflow Task Queues
   </div>
 </div>
 
+A Nexus Endpoint creates an entry point that separates callers from the underlying Nexus Task Queue.
+The Nexus callers only interact with the Nexus Endpoint.
+This endpoint routes Nexus Requests to a target Task Queue that's polled by a Nexus Worker.
+
 <div className="tdiw">
   <div className="tditw">
     <p className="tdit">Nexus Endpoint component</p>
   </div>
   <div className="tdiiw" height="500">
     <img
       className="img_ev3q"
-      src="/diagrams/task-queue-nexus.png"
+      src="/img/encyclopedia/workers/nexus-task-queue.png"
       alt="Task Queue component"
     />
   </div>
 </div>
 
-Task Queues are very lightweight components.
-Task Queues do not require explicit registration but instead are created on demand when a Workflow Execution or Activity spawns or when a Worker Process subscribes to it.
-When a Task Queue is created, both a Workflow Task Queue and an Activity Task Queue are created under the same name.
-There is no limit to the number of Task Queues a Temporal Application can use or a Temporal Service can maintain.
+Task Queues are lightweight components that don’t require explicit registration.
+They’re created on demand when a Workflow Execution, Activity, or Nexus Operation is invoked, and/or when a Worker Process subscribes to start polling.
+When a named Task Queue is created, individual Task Queues for Workflows, Activities, and Nexus are created using the same name.
+A Temporal Application can use, and the Temporal Service can maintain, an unlimited number of Task Queues.
 
 Workers poll for Tasks in Task Queues via synchronous RPC.
 This implementation offers several benefits:
 
 - A Worker Process polls for a message only when it has spare capacity, avoiding overloading itself.
 - In effect, Task Queues enable load balancing across many Worker Processes.
-- Task Queues enable what we call [Task Routing](#task-routing), which is the routing of specific Tasks to specific Worker Processes or even a specific process.
-- Task Queues support server-side throttling, which enables you to limit the Task dispatching rate to the pool of Worker Processes while still supporting Task dispatching at higher rates when spikes happen.
-- When all Worker Processes are down, messages simply persist in a Task Queue, waiting for the Worker Processes to recover.
+- Task Queues enable [Task Routing](#task-routing), which is the routing of specific Tasks to specific Worker Processes or even a specific process.
+- Activity Task Queues support server-side throttling, which enables you to limit the Task dispatching rate to the pool of Worker Processes while still supporting Task dispatching at higher rates when spikes happen.
+- Workflow and Activity Tasks persist in a Task Queue.
+  When a Worker Process goes down, the messages remain until the Worker recovers and can process the Tasks.
+- Nexus and Query Tasks are not persisted.
+  Instead, they are sync matched when, and only when, polled by a Worker.
+  Sync matching immediately matches and delivers a Task to an available Worker without persisting a Task to the Service database.
+  The caller is responsible to retry failed operations.
+  Caller Workflows that invoke Nexus Operations will automatically retry Nexus Tasks until exceeding the Schedule-to-Close timeout.
 - Worker Processes do not need to advertise themselves through DNS or any other network discovery mechanism.
-- Worker Processes do not need to have any open ports, which is more secure.
+- Worker Processes connect directly to the Temporal Service for secure communication without needing to open exposed ports.
+
+Any Worker can pick up any Task on a given Task Queue.
+You must ensure that if a Worker accepts a Task that it can process that task using one of its registered Workflows, Activities, or Nexus Operation handlers.
+This means that all Workers listening to a Task Queue must register all Tasks and Nexus Operations that live on that Queue.
 
-All Workers listening to a given Task Queue must have identical registrations of Activities and/or Workflows.
-The one exception is during a Server upgrade, where it is okay to have registration temporarily misaligned while the binary rolls out.
+There are two exceptions to this "Task Queue Workers with identical registrations" rule.
+First, Worker Versioning may be used.
+During a Worker upgrade binary rollouts, it's okay to have temporarily misaligned registrations.
+Second, dynamic Workflows or Activity components may be used.
+If a Task arrives with a recognized method signature, the Worker can use a pre-registered dynamic stand-in.
+
+When Workers don't have a registered Workflow, Activity, Nexus Operation, or dynamic Workflow or Activity component for a given Task, the Task will fail with a "Not Found" error.
+- "Not Found" Workflow Tasks and Activity Tasks are treated as *retryable* errors.
+- "Not Found" Nexus Operation handlers are *non-retryable* and must be manually retried from the caller Workflow.
 
 #### Where to set Task Queues
 
-There are four places where the name of the Task Queue can be set by the developer.
+There are five places where the name of the Task Queue can be set by the developer.
 
 1. A Task Queue must be set when spawning a Workflow Execution:
 
@@ -322,6 +342,13 @@ A Child Workflow Execution inherits the Task Queue name from its Parent Workflow
 - [How to start a Child Workflow Execution using the TypeScript SDK](/develop/typescript/child-workflows)
 - [How to start a Child Workflow Execution using the .NET SDK](/develop/dotnet/child-workflows)
 
+5. A Task Queue name can be provided when creating a Nexus Endpoint.
+   Nexus Endpoints route requests to the target Task Queue.
+   Nexus Workers poll the target Task Queue to handle the Nexus Tasks, such as starting or cancelling a Nexus Operation.
+
+- [How to run a Nexus Worker using the Go SDK](https://docs.temporal.io/develop/go/nexus#register-a-nexus-service-in-a-worker)
+- [How to run a Nexus Worker using the Java SDK](https://docs.temporal.io/develop/java/nexus#register-a-nexus-service-in-a-worker)
+
 #### Task ordering
 
 Task Queues can be scaled by adding partitions.