[SDK Ergonomics] NEXUS-519: Support Query-backed Nexus Operations

[mavemuri]

What changed?

Adds server support for WorkflowQuery-backed Nexus Operations

Why?

Part of effort to expose all Temporal primitives as Nexus Operations

How did you test it?

• built
• run locally and tested manually
• covered by existing tests
• added new unit test(s)
• added new functional test(s)

TODO:

• [SDK Ergonomics] NEXUS-519: Add link to QueryWorkflowResponse api#842

[mavemuri]

placeholder until api change is merged

[github-actions]

Claude finished @mavemuri's task in 7m 1s —— View job

---

Review complete

• Read review skill + .github/copilot-instructions.md
• Analyzed the diff (common/nexus/links.go, service/history/api/queryworkflow/api.go, tests/query_workflow_test.go, go.mod/go.sum, matching test import)
• Traced the link through the frontend passthrough (workflow_handler.go:3282), common/links.Validate, and the ConvertNexusLinksToProtoLinks callers
• Posted 5 inline comments

Overall the change looks sound: the resp.GetResponse() == nil guard makes the deferred block safe on every return path, the defer is registered after the early error returns so only real responses get a link, and the functional test covers both the "Query processed" (direct-through-matching) and "Query rejected" (early-return) branches. Findings are inline — the one worth a real decision is that common/links.Validate rejects the Link_Workflow variant, so the link this PR returns can't be attached to a follow-up request.
• Branch: mavemuri/nexus-query

[github-actions]

common/links.Validate has no *commonpb.Link_Workflow_ case — it falls into default: and returns InvalidArgument: "unsupported link variant" (common/links/validator.go:60-61).

That makes the link this PR returns a dead end for the main thing links are for: taking a link you got back and attaching it to a follow-up request. A client that does

qResp, _ := c.WorkflowService().QueryWorkflow(ctx, ...)
c.WorkflowService().StartWorkflowExecution(ctx, &workflowservice.StartWorkflowExecutionRequest{
    ..., Links: []*commonpb.Link{qResp.GetLink()},
})

gets InvalidArgument: unsupported link variant. Same for SignalWorkflowExecution, SignalWithStart, and UpdateWorkflowExecution (service/frontend/workflow_handler.go:693, 2241, 2286, 2350, 2445) plus the CHASM validators (chasm/lib/workflow/validator.go:220, chasm/lib/activity/link_validator.go:34).

Strictly this gap predates the PR — updateworkflow already emits Link_Workflow for rejected updates — but this change makes the variant reachable from every query response, so it's worth closing here. Adding the case alongside the Link_Activity_ one is a few lines:

case *commonpb.Link_Workflow_:
	if t.Workflow.GetNamespace() == "" {
		return serviceerror.NewInvalidArgument("workflow link must not have an empty namespace field")
	}
	if t.Workflow.GetWorkflowId() == "" {
		return serviceerror.NewInvalidArgument("workflow link must not have an empty workflow ID field")
	}
	if t.Workflow.GetRunId() == "" {
		return serviceerror.NewInvalidArgument("workflow link must not have an empty run ID field")
	}

[github-actions]

Beyond the replace placeholder you already flagged below: this line also downgrades the require from v1.63.4 (which main just moved to in #11264) to the older v1.62.15-0.20260622232249-060670b1b866 pseudo-version. The replace masks that today, so it's easy to miss — but if the replace is dropped without also restoring the require, the module silently regresses to a pre-v1.63.4 API.

When temporalio/api#842 lands, the cleanup is: delete the replace, set this back to the released tag (>= v1.63.4), and restore the two go.temporal.io/api lines that were removed from go.sum.

[Quinn-With-Two-Ns]

High level looks good, but I would address all the AI's comments except for #11274 (comment) of course

[github-actions]

The two sibling cases use this repo's own converters (ConvertNexusLinkToLinkWorkflowEvent, ConvertNexusLinkToLinkActivity in common/nexus/link_converter.go), while this one reaches into go.temporal.io/api/temporalnexus. That's the only use of go.temporal.io/api/temporalnexus anywhere in the repo, and it is the sole reason for the api-go fork pin in go.mod.

common/nexus/link_converter.go opens with an explicit policy for exactly this situation:

This file is duplicated in sdk-go/temporalnexus/link_converter.go. Any changes here or there must be replicated. This is temporary until the temporal repo updates to the most recent SDK version.

Adding a local ConvertNexusLinkToLinkWorkflow next to the existing converters would keep all three URL path formats defined in one place, keep this switch internally consistent, and drop the need for the replace directive entirely. It's a small function and the file already owns the urlPath*Template/regex conventions it would follow.

[mavemuri]

rejected
real fix is to eventually point all the converters to the helper from api-go for consistency
This pr intentionally addresses one to keep it scoped while avoid additional duplication. Cleaning up all the duplicates will be a different, more scoped pr

[github-actions]

This pins go.temporal.io/api to an unreleased fork via the replace at the bottom of the file, and at the same time downgrades the require line from v1.63.4 to v1.62.15-0.20260622232249-060670b1b866.

replace directives are only honored in the main module — they are ignored for anyone consuming go.temporal.io/server as a dependency. So downstream consumers will resolve the older v1.62.15-… api, which has neither QueryWorkflowResponse.Link nor temporalnexus.ConvertNexusLinkToLinkWorkflow, and common/nexus/links.go will fail to compile for them. Even with the replace kept in place locally, the require line shouldn't go backwards.

Flagging as blocking merge, consistent with the PR's own TODO on temporalio/api#842: once that's released, drop the replace and set require go.temporal.io/api to the released tag (≥ v1.63.4).

[mavemuri]

ignore
this is a placeholder until the relevant api/api-go changes are reviewed and merged(already noted in TODO in this pr conversation)
it is kept this way for now for convenience of reviewing and running CI/tests etc

[github-actions]

The "as long as there isn't an error" clause just restates the guard three lines above. What isn't obvious from the code is why this is a Link_Workflow rather than a Link_WorkflowEvent — same rationale as the rejected-update case in updateworkflow/api.go.

Suggested change

	// Add link to Workflow regardless of query status as long as there isn't an error.
	// Queries never write a history event, so link to the workflow itself.