Propagate Nexus serialization context to workflows and standalone activities by JoshuaFrenchwood · Pull Request #3171 · temporalio/sdk-java

JoshuaFrenchwood · 2026-10-27T19:14:54Z

What was changed

Nexus operation handlers now propagate their NexusSerializationContext to the workflows and
standalone activities (SAA) they start.

Workflows: start and update-with-start send the handler's context
(propagated_nexus_serialization_context). The worker encodes the workflow's result and closing
failure with it. Clients decode the result with the context the server returns in the history,
including detached handles and runs after continue-as-new.
Standalone activities: the start request carries the context. The worker encodes the result,
failure and last-attempt failure with it. Get-result and describe decode those with the context
the server returns.
Standalone Nexus operations: handles prefer the context returned by the server when polling,
and fall back to the start request's context on older servers.
Everything else keeps the workflow or activity context: inputs, memo, signals, queries,
heartbeat details, and static summary and details.
Pins the dev server used in tests to 1.9.3-nexus-serialization-context.

Why?

A Nexus handler returns the result and failure of the execution it starts to the Nexus caller. The
caller decodes them with the operation's NexusSerializationContext. Until now the backing
execution encoded them with its own workflow or activity context, so a codec keyed on the context
couldn't decode them. Per-endpoint encryption is one example.

Checklist

Closes
How was this tested:

Unit tests for the client invokers (start, get-result, poll, describe), for activity task
execution, and for workflow replay with an injected propagated context.
- End-to-end NexusSerializationContextPropagationTest on the dev server: a caller workflow goes
  through a Nexus endpoint to a handler that starts a workflow, a continue-as-new workflow or an
  SAA. It checks history payload contexts, describe, and handles obtained by ID.
- StandaloneNexusSerializationContextTest against an external server, for standalone Nexus
  operations.

Any docs updates needed?

Newer servers convert a Nexus operation error sent in the old failure format to the new format, wrapping the handler's failure in an OperationError. Unwrap it whenever it is present, so the old-format assertions hold against both the pinned and older servers.

Drop tests whose code path another test already covers: the async result and failure decodes that share their converter with the sync paths, the start-before-operation edge case, and the end-to-end workflow failure case covered by the replay and client unit tests.

Evanthx

Had a few questions!

VegetarianOrc

Overall looking correct to me!

One thing I think we're missing here is threading the correct context to manual activity completion. Right now looks like manual activity completion will encode the result w/ the activity context and then be forwarded to the Nexus Operation result.

VegetarianOrc · 2026-10-28T00:09:06Z

+  /**
+   * The data converter for the result or failure in a poll response. An activity started from a
+   * Nexus operation handler uses the handler's Nexus context, which the server returns with the
+   * response; other activities use an activity context.
+   */
+  private DataConverter resultDataConverter(PollActivityExecutionResponse response) {
+    SerializationContext context =
+        response.hasPropagatedNexusSerializationContext()
+            ? PropagatedNexusSerializationContext.fromProto(
+                response.getPropagatedNexusSerializationContext())
+            // Currently, result doesn't have access to activity type and serialization context
+            // doesn't hold activity ID.
+            : new ActivitySerializationContext(namespace, null, null, null, null, false);
+    return dataConverter.withContext(context);
  }


Codex is pointing out an edge case in how we're handling heartbeat details in the event of a timeout that I think is real and worth considering.

Activity heartbeats and details encoded w/ activity context.

Activity stops heartbeating

Server times out the activity and embeds the activity-encoded last heartbeat details into the failure proto

Client selects the nexus context to decode the failure. A custom codec may fail to decode the failure proto.

Ahh yes that needs a fix, working on it now thanks.

Updated this. For activity heartbeats, they now use NexusSerializationContext to encode details when started by a nexus caller.

Also included a fix for async completion of an SAA with NexusSerializationContext.

An activity completed through local manual completion reports its result, failure and heartbeats through a client the worker creates. For a standalone activity started from a Nexus operation handler, give that client the handler's Nexus context, matching the worker's own completion and heartbeat paths. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

VegetarianOrc

This looks good to me!

VegetarianOrc · 2026-10-29T19:28:47Z

+ * <p>When a handler starts a workflow or a standalone activity, this context is propagated to it
+ * through the server. Both use it only for their result and failures, which are returned to the
+ * caller, and a standalone activity also uses it for its heartbeat details, which the server puts
+ * into its timeout failure. A workflow's input, memo, static summary and details, signals, queries
+ * and updates keep the {@link WorkflowSerializationContext}; a standalone activity's input and
+ * static summary and details keep the {@link ActivitySerializationContext}. Clients reading their
+ * results, including handles obtained by ID, use the context the server returns. This requires a
+ * server that propagates the context; older servers ignore it.
+ *
+ * <p>A standalone activity completed asynchronously through {@link
+ * io.temporal.client.ActivityCompletionClient} gets this context only if it is passed in: read it
+ * from {@link io.temporal.activity.ActivityInfo#getNexusSerializationContext()}, store it with the
+ * task token, and pass it to {@link
+ * io.temporal.client.ActivityCompletionClient#withContext(NexusSerializationContext)}.


This is pretty detailed and seems accurate but I think overwhelming for users. Maybe let's take a shot at providing a more high level description about how the nexus context is used appropriately, and leave out the details of what remains the same in each scenario.

Agreed, updated

Evanthx

LGTM

JoshuaFrenchwood requested review from Evanthx and atol October 27, 2026 19:14

JoshuaFrenchwood requested a review from a team as a code owner October 27, 2026 19:14

JoshuaFrenchwood added 4 commits October 27, 2026 15:44

NexusSerializationContext for async Nexus Operations

478d33d

code cleanup

7f8d87f

Add changelog entry for Nexus serialization context

512ff57

JoshuaFrenchwood force-pushed the nexus-serialization-context-updates branch from 1fcabb1 to 512ff57 Compare October 27, 2026 20:45

JoshuaFrenchwood changed the title ~~Nexus serialization context for Async Nexus Operations~~ Propagate Nexus serialization context to workflows and standalone activities Oct 27, 2026

JoshuaFrenchwood added this pull request to stack #3173 October 27, 2026 20:52

Evanthx requested changes Oct 27, 2026

View reviewed changes

Comment thread temporal-sdk/src/main/java/io/temporal/client/ActivityExecutionDescription.java Resolved

Comment thread temporal-sdk/src/main/java/io/temporal/internal/client/RootWorkflowClientInvoker.java Resolved

VegetarianOrc reviewed Oct 28, 2026

View reviewed changes

JoshuaFrenchwood and others added 3 commits October 28, 2026 10:35

Using NexusSerializationContext for heartbeat details

9d55e26

Allow async completion with the Nexus context

dbd4d6e

JoshuaFrenchwood requested review from Evanthx and VegetarianOrc October 28, 2026 19:51

Opt query and slot tests out of poller auto-enrollment

331b922

VegetarianOrc approved these changes Oct 29, 2026

View reviewed changes

Updating NexusSerializationContext doc

8aec384

Evanthx approved these changes Oct 29, 2026

View reviewed changes

JoshuaFrenchwood merged commit 7dd0511 into main Oct 29, 2026
117 of 128 checks passed

JoshuaFrenchwood deleted the nexus-serialization-context-updates branch October 29, 2026 23:37

Navigation Menu

Repository navigation

Propagate Nexus serialization context to workflows and standalone activities - #3171

Propagate Nexus serialization context to workflows and standalone activities#3171
JoshuaFrenchwood merged 10 commits into
mainfrom
nexus-serialization-context-updates

JoshuaFrenchwood commented Oct 27, 2026 •

edited

Loading

Uh oh!

Evanthx left a comment

Uh oh!

Uh oh!

Uh oh!

VegetarianOrc left a comment

Uh oh!

VegetarianOrc Oct 28, 2026

Uh oh!

JoshuaFrenchwood Oct 28, 2026

Uh oh!

JoshuaFrenchwood Oct 28, 2026

Uh oh!

VegetarianOrc left a comment

Uh oh!

VegetarianOrc Oct 29, 2026

Uh oh!

JoshuaFrenchwood Oct 29, 2026

Uh oh!

Evanthx left a comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

JoshuaFrenchwood commented Oct 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What was changed

Why?

Checklist

Uh oh!

Evanthx left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

VegetarianOrc left a comment

Choose a reason for hiding this comment

Uh oh!

VegetarianOrc Oct 28, 2026

Choose a reason for hiding this comment

Uh oh!

JoshuaFrenchwood Oct 28, 2026

Choose a reason for hiding this comment

Uh oh!

JoshuaFrenchwood Oct 28, 2026

Choose a reason for hiding this comment

Uh oh!

VegetarianOrc left a comment

Choose a reason for hiding this comment

Uh oh!

VegetarianOrc Oct 29, 2026

Choose a reason for hiding this comment

Uh oh!

JoshuaFrenchwood Oct 29, 2026

Choose a reason for hiding this comment

Uh oh!

Evanthx left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

JoshuaFrenchwood commented Oct 27, 2026 •

edited

Loading