Add eager start support for standalone activities by wenlong-gu · Pull Request #12349 · temporalio/temporal

wenlong-gu · 2026-10-02T15:07:28Z

What changed?

This PR adds eager start support for Standalone Activities (SAA). When an eligible client requests eager start, the server can return the first Activity task directly in the StartActivityExecution response, avoiding the initial task-queue dispatch round trip.

The PR falls back to normal Matching dispatch when eager delivery is not admitted.

Why?

The eager start feature has been implemented for WFA, so this change is to mirror that flow to save latency.

How did you test it?

Local benchmark

Measured 200 paired runs using an in-process Temporal server test cluster:

Path	p50	p95	p99
Normal SAA	2.372 ms	58.654 ms	88.855 ms
Eager SAA	1.588 ms	5.028 ms	7.362 ms

This is approximately 33% lower p50 and 91–92% lower p95/p99 latency in the
local environment. It measures server-side task delivery only; it excludes SDK
worker scheduling, Activity business-code execution, network latency, and
production load.

CLAassistant · 2026-10-02T15:07:46Z

All committers have signed the CLA.

…-saa # Conflicts: # chasm/lib/activity/responses.go

Copilot

Copilot review overview

🟡 Changes recommended

The eager response omits standard execution metadata, loses SDK metadata, and lacks the documented rollout metrics.

Review effort: Balanced
Findings: 4

Open (4)

Eager task omits the standalone activity execution object · New
Eager starts do not persist worker SDK metadata · New
Eager-start rollout metrics are not implemented · New
Parity test does not explicitly enable standalone eager start · New

What changed in this PR

Adds eager delivery of the first standalone Activity task, bypassing initial Matching dispatch while preserving persisted state and timeout protection.

Changes:

Adds namespace-gated eager-start handling and task construction.
Extends state-machine, parity, and functional coverage.
Documents lifecycle, safety, and performance behavior.

File	Description
`tests/activity_workflow_driver.go`	Adds eager workflow Activity driver.
`tests/activity_standalone_test.go`	Tests eager response deduplication.
`tests/activity_standalone_driver.go`	Supports eager standalone tasks.
`tests/activity_parity_test.go`	Adds eager retry parity coverage.
`tests/activity_driver.go`	Models eagerly started attempts.
`docs/architecture/saa-eager-start-plan.md`	Documents design and validation.
`chasm/lib/activity/statemachine.go`	Adds atomic eager-start transition.
`chasm/lib/activity/statemachine_test.go`	Tests eager transition tasks.
`chasm/lib/activity/responses.go`	Builds eager worker responses and tokens.
`chasm/lib/activity/model/vocabulary.go`	Adds eager model configuration.
`chasm/lib/activity/model/model.go`	Models initially started state.
`chasm/lib/activity/model/model_test.go`	Tests eager model behavior.
`chasm/lib/activity/handler.go`	Creates and returns eager tasks.
`chasm/lib/activity/frontend.go`	Applies eligibility fallback.
`chasm/lib/activity/frontend_test.go`	Tests fallback conditions.
`chasm/lib/activity/config.go`	Adds namespace eager-start configuration.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

fretz12 · 2026-10-06T20:56:40Z

can you make the PR desc follow the standard template? And personally I'd prefer to just keep it concise and to the point rather than too much AI noise

## Task overview Part 1 of 3 for ACT-1118, adding eager start for Standalone Activities (SAA). Today, an SAA start must create the activity, enqueue a dispatch task, send it through Matching, and wait for a worker poll. This adds queue latency even when the caller has a ready local worker. The complete solution lets an eligible `StartActivityExecution` request return the first Activity task directly in its response. The server persists the activity before returning that task and skips only the initial Matching dispatch. For safety, an eager task is returned only for a newly created execution. Same-request-ID retries and conflicts such as `USE_EXISTING` return the existing execution without re-delivering the task, because Activity code may have external side effects. ## Scope of this PR Adds the additive public API contract: - `StartActivityExecutionRequest.request_eager_execution` - `StartActivityExecutionResponse.eager_activity_task` There is no runtime server behavior in this PR. ## Related PRs - API-Go: temporalio/api-go#319 updates this proto submodule and regenerates the Go API types. - Temporal: temporalio/temporal#12349 implements request eligibility, the eager state transition, task construction, retry/conflict safety, and tests. ## Validation - API linter passes. ## Benchmark context This contract-only PR has no runtime behavior. The Temporal implementation was measured locally in an in-process server test cluster over 200 paired runs: | Path | p50 | p95 | p99 | |---|---:|---:|---:| | Normal SAA | 2.372 ms | 58.654 ms | 88.855 ms | | Eager SAA | 1.588 ms | 5.028 ms | 7.362 ms | The measurement covers server-side task delivery only; it excludes SDK worker scheduling, user Activity execution, network latency, and production load.

## Task overview Part 1 of 3 for ACT-1118, adding eager start for Standalone Activities (SAA). Today, an SAA start must create the activity, enqueue a dispatch task, send it through Matching, and wait for a worker poll. This adds queue latency even when the caller has a ready local worker. The complete solution lets an eligible `StartActivityExecution` request return the first Activity task directly in its response. The server persists the activity before returning that task and skips only the initial Matching dispatch. For safety, an eager task is returned only for a newly created execution. Same-request-ID retries and conflicts such as `USE_EXISTING` return the existing execution without re-delivering the task, because Activity code may have external side effects. ## Scope of this PR Adds the additive public API contract: - `StartActivityExecutionRequest.request_eager_execution` - `StartActivityExecutionResponse.eager_activity_task` There is no runtime server behavior in this PR. ## Related PRs - API-Go: #319 updates this proto submodule and regenerates the Go API types. - Temporal: temporalio/temporal#12349 implements request eligibility, the eager state transition, task construction, retry/conflict safety, and tests. ## Validation - API linter passes. ## Benchmark context This contract-only PR has no runtime behavior. The Temporal implementation was measured locally in an in-process server test cluster over 200 paired runs: | Path | p50 | p95 | p99 | |---|---:|---:|---:| | Normal SAA | 2.372 ms | 58.654 ms | 88.855 ms | | Eager SAA | 1.588 ms | 5.028 ms | 7.362 ms | The measurement covers server-side task delivery only; it excludes SDK worker scheduling, user Activity execution, network latency, and production load.

# Conflicts: # go.mod # go.sum # tests/mixedbrain/go.mod # tests/mixedbrain/go.sum

## Task overview Part 1 of 3 for ACT-1118, adding eager start for Standalone Activities (SAA). Today, an SAA start must create the activity, enqueue a dispatch task, send it through Matching, and wait for a worker poll. This adds queue latency even when the caller has a ready local worker. The complete solution lets an eligible `StartActivityExecution` request return the first Activity task directly in its response. The server persists the activity before returning that task and skips only the initial Matching dispatch. For safety, an eager task is returned only for a newly created execution. Same-request-ID retries and conflicts such as `USE_EXISTING` return the existing execution without re-delivering the task, because Activity code may have external side effects. ## Scope of this PR Adds the additive public API contract: - `StartActivityExecutionRequest.request_eager_execution` - `StartActivityExecutionResponse.eager_activity_task` There is no runtime server behavior in this PR. ## Related PRs - API-Go: temporalio/api-go#319 updates this proto submodule and regenerates the Go API types. - Temporal: temporalio/temporal#12349 implements request eligibility, the eager state transition, task construction, retry/conflict safety, and tests. ## Validation - API linter passes. ## Benchmark context This contract-only PR has no runtime behavior. The Temporal implementation was measured locally in an in-process server test cluster over 200 paired runs: | Path | p50 | p95 | p99 | |---|---:|---:|---:| | Normal SAA | 2.372 ms | 58.654 ms | 88.855 ms | | Eager SAA | 1.588 ms | 5.028 ms | 7.362 ms | The measurement covers server-side task delivery only; it excludes SDK worker scheduling, user Activity execution, network latency, and production load.

Add eager start support for standalone activities

bb4ae6c

wenlong-gu mentioned this pull request Oct 2, 2026

Add eager standalone activity start API temporalio/api#876

Merged

wenlong-gu mentioned this pull request Oct 2, 2026

Add eager standalone activity start Go API temporalio/api-go#319

Closed

wenlong-gu marked this pull request as ready for review October 2, 2026 15:25

wenlong-gu requested review from a team as code owners October 2, 2026 15:25

wenlong-gu added 2 commits October 2, 2026 11:59

Add eager activity parity coverage

7e83905

Merge remote-tracking branch 'origin/main' into codex/saa-eager-start…

b02e5d6

…-saa # Conflicts: # chasm/lib/activity/responses.go

wenlong-gu requested review from fretz12 and a balanced review from Copilot October 2, 2026 19:36

Copilot started reviewing on behalf of wenlong-gu October 2, 2026 20:59 View session

Copilot AI reviewed Oct 2, 2026

View reviewed changes

Comment thread chasm/lib/activity/responses.go Outdated

Comment thread chasm/lib/activity/statemachine.go

Comment thread docs/architecture/saa-eager-start-plan.md Outdated

Comment thread tests/activity_parity_test.go

fretz12 reviewed Oct 5, 2026

View reviewed changes

Comment thread docs/architecture/saa-eager-start-plan.md Outdated

wenlong-gu added 5 commits October 5, 2026 15:16

Use eager activity API dependency

76f9b8c

Address eager standalone activity review comments

d9e4ced

Fix mixed brain module dependencies

a4e52c3

Support temporary API dependency replacements

7bb39d1

Format eager activity metrics

d69cb31

fretz12 reviewed Oct 6, 2026

View reviewed changes

wenlong-gu added 7 commits October 7, 2026 09:23

Build eager activity task response transactionally

b7bd052

Align eager activity execution metrics

ef78df7

Honor Matching grants for eager activities

bb028b0

Test eager activity response loss recovery

969beae

Clean up standalone activity state transitions

aa3ef43

Resolve eager activity lint findings

dbc41ea

Remove temporary API dependency scaffolding

1bab344

wenlong-gu added 2 commits October 8, 2026 16:35

Update API dependency after eager activity API merge

8af210a

Merge upstream main into eager standalone activity start

e75545e

# Conflicts: # go.mod # go.sum # tests/mixedbrain/go.mod # tests/mixedbrain/go.sum

wenlong-gu force-pushed the codex/saa-eager-start-saa branch from 63cae51 to e75545e Compare October 9, 2026 00:43

Merge upstream main into eager standalone activity start

ec8317d

fretz12 reviewed Oct 12, 2026

View reviewed changes

Comment thread chasm/lib/activity/responses.go

Comment thread chasm/lib/activity/handler.go

Comment thread chasm/lib/activity/handler.go Outdated

wenlong-gu added 2 commits October 12, 2026 11:59

Persist eager activity acceptance state

8b891d3

Add eager dispatch observability

0242b8f

wenlong-gu requested a review from a team as a code owner October 12, 2026 20:25

wenlong-gu added 2 commits October 12, 2026 15:29

Simplify eager dispatch reconciliation TODO

1f944bf

Align SAA eager dispatch metrics

3ca4494

Navigation Menu

Repository navigation

Add eager start support for standalone activities - #12349

Add eager start support for standalone activities#12349
wenlong-gu wants to merge 22 commits into
temporalio:mainfrom
wenlong-gu:codex/saa-eager-start-saa

wenlong-gu commented Oct 2, 2026 •

edited

Loading

Uh oh!

CLAassistant commented Oct 2, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fretz12 commented Oct 6, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

wenlong-gu commented Oct 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changed?

Why?

How did you test it?

Local benchmark

Uh oh!

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

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

wenlong-gu commented Oct 2, 2026 •

edited

Loading

CLAassistant commented Oct 2, 2026 •

edited

Loading

fretz12 commented Oct 6, 2026 •

edited

Loading