Implement planned topic: 0034-nexus

[skill-temporal-developer-updater]

Validation Report — nexus

Branch: draft/0034-nexus (validated against main)
Scope: 6 authored reference files + entry-point pointers in SKILL.md and references/{lang}/{lang}.md.

Go/no-go

Check	Threshold	Result	Verdict
1. Citation audit	≥ 98 % resolve cleanly	357 / 359 = 99.4 %	PASS
2. Reverse-grep audit	zero unexplained misses	0 unexplained misses	PASS
3. Regression on known bugs	zero hits	0 hits	PASS
4. Independent re-verification	≥ 95 % of sample matches docs	59 / 60 = 98.3 %	PASS
5. Integration-layout audit	n/a — not an integration topic	skipped	n/a
6. Tone and scope audit	zero workaround disclosures	0 workaround disclosures	PASS

Overall verdict: GO. All four gating checks pass their thresholds. One minor Check 4 finding (single sample) and two minor Check 1 citation overreaches in references/java/nexus.md are documented below as optional spot fixes — they do not require re-authoring.

---

Check 1 findings — citation audit

references/core/nexus.md

None. 126 citations resolved cleanly.

references/python/nexus.md

None. 58 citations resolved cleanly.

references/typescript/nexus.md

None. 38 citations resolved cleanly.

references/go/nexus.md

None. 45 citations resolved cleanly.

references/java/nexus.md

Two minor citation overreaches:

1. Line 11 — claim "Same io.temporal:temporal-sdk Gradle/Maven coordinate as the rest of the Java SDK" is cited to docs/develop/java/nexus/feature-guide.mdx:203 and docs/develop/java/nexus/quickstart.mdx:58-59. Those cited ranges support the io.nexusrpc.* and io.temporal.nexus.* package names but do not mention the Gradle/Maven coordinate. The coordinate is documented in docs/develop/java/set-up.mdx. Fix: swap citation to develop/java/set-up.mdx for the coordinate clause.
2. Line 239 — claim "The key in the map is the Service class simple name (e.g. \"SampleNexusService\")" is cited to feature-guide.mdx:537-539. The cited lines show the literal "SampleNexusService" key value but do not explicitly state the rule "must be the Service class simple name." This is an authorial generalization from one example. Fix: soften wording to "matches the Service class name as a string" or annotate with <!-- VERIFY: ... -->.

references/dotnet/nexus.md

None. 54 citations resolved cleanly.

Aggregate Check 1: 357 / 359 = 99.4 %, above the 98 % threshold.

---

Check 2 findings — reverse-grep audit

All factual tokens (SDK identifiers, decorator/annotation/attribute names, package/module paths, method names, enum values, exception classes, error categories, event names, metric names, Pending-Operation/Callback fields, timeout codes, CLI commands, version numbers, numeric facts) resolve in the cited docs subtrees:

• docs/encyclopedia/nexus/*.mdx
• docs/develop/{python,typescript,go,java,dotnet}/nexus/*.mdx
• docs/evaluate/temporal-cloud/limits.mdx

Items not present in the Nexus docs are correctly wrapped with <!-- VERIFY: ... --> markers in the authored files:

• core line 99 — full set of handler error categories (BAD_REQUEST, UNAUTHENTICATED, UNAUTHORIZED, NOT_FOUND, NOT_IMPLEMENTED, RESOURCE_EXHAUSTED, UNAVAILABLE) and the exhaustive endpoint subcommand set (core line 166).
• python line 216 — schedule_to_start_timeout / start_to_close_timeout not shown in Python Nexus docs.
• typescript lines 195 and 208 — only scheduleToCloseTimeout documented for Nexus; no CancellationType enum surfaced.
• java line 247 — setScheduleToStartTimeout / setStartToCloseTimeout not surfaced in cited files.
• java reverse-grep: io.temporal:temporal-sdk coordinate is not in develop/java/nexus/ — already flagged under Check 1.

NewAsyncOperation is correctly absent from Go docs and correctly framed as a Common-Mistake antipattern in references/go/nexus.md line 290.

Aggregate Check 2: 0 unexplained misses.

---

Check 3 findings — regression on known bugs

Universal regression sweep (--profile, TEMPORAL_TLS_CLIENT_* env vars, tcld service-account, --output text|jsonl, saas-api.tmprl.cloud:7233): no hits across the 6 reference files or the entry-point edits.

Topic-specific regression sweep: invented Go NewAsyncOperation does not appear except as a Common-Mistake antipattern; Java OperationHandler.Sync capitalization is correctly lowercase sync (matching docs); .NET OperationHandler.Sync is correctly capital-S. No hits.

Aggregate Check 3: 0 hits.

---

Check 4 findings — independent re-verification (60 sampled claims)

references/core/nexus.md (10 sampled, 9 match)

Divergence at line 51 — "Terminal events on the caller side are one of: NexusOperationStarted, NexusOperationCompleted, NexusOperationFailed, NexusOperationCanceled, or NexusOperationTimedOut." cited to docs/encyclopedia/nexus/nexus-operations.mdx:169.

• Doc-truth: the cited line lists these five as the set of NexusOperation events recorded in caller Workflow History — not as "terminal" events. NexusOperationStarted is intermediate (it marks the start of an asynchronous Operation; in the same file's async lifecycle at lines 119-128, Started precedes Completed/Failed). The resolution/terminal events are Completed, Failed, Canceled, and TimedOut.
• Impact: a reader treating NexusOperationStarted as a terminal event might short-circuit waits or misclassify the Operation as resolved when in fact the handler Workflow is still running.
• Suggested fix: reword to "The caller's Nexus Machinery records one of these NexusOperation events in caller Workflow History: …" or split into "Started (intermediate, async only)" vs. "Completed / Failed / Canceled / TimedOut (resolution)."

references/python/nexus.md — 10 / 10 match.

references/typescript/nexus.md — 10 / 10 match.

references/go/nexus.md — 10 / 10 match.

references/java/nexus.md — 10 / 10 match.

references/dotnet/nexus.md — 10 / 10 match.

Aggregate Check 4: 59 / 60 = 98.3 %, above the 95 % threshold.

---

Check 5 findings — integration-layout audit

Skipped. Nexus is a Temporal-native feature (encyclopedia topic), not a third-party integration. references/integrations.md was not modified on this branch. The diff places per-language files at the canonical references/{language}/nexus.md paths and adds short pointer bullets to each language entry-point — this is the standard layout for core topics like determinism.md, patterns.md, versioning.md.

---

Check 6 findings — tone and scope audit

Workaround disclosures (pattern 1, must be zero)

None. Grep across all six files for the workaround-disclosure phrases (if you really need, as a last resort, if you must, undocumented way, technically you can, circumvent, bypass, hack, workaround) returned zero hits.

Negative bullets (e.g. "do not use a Client from inside an async handler — use await ctx.start_workflow(...)") consistently follow the "Don't do X, do Y instead" form and name the supported alternative. The handful of "Don't do X" statements (e.g. "Only asynchronous Operations can be canceled") are hard-constraint statements, not workarounds.

Public Preview admonition (pattern 4)

The docs mark Nexus support as Public Preview for TypeScript and .NET; both authored files carry the standard [!NOTE] admonition (verbatim wording) — references/typescript/nexus.md:5-8 and references/dotnet/nexus.md:5-8. Python, Go, Java, and the cross-language core file omit the admonition — correct, since the docs mark these as Generally Available (develop/python/nexus/feature-guide.mdx:20-24, develop/go/nexus/feature-guide.mdx:21-25, develop/java/nexus/feature-guide.mdx:20-25, encyclopedia/nexus/nexus.mdx:21).

In-the-weeds rationale (pattern 2) and multi-sentence bullets (pattern 3)

Spot-check found no notable instances. Bullets are tight; rationale is limited to constraint explanations (e.g. why ctx.requestId is preferred over a fresh UUID — "stable across retries"), which is operational information an agent needs.

Aggregate Check 6: 0 findings.

---

Statistics

Metric	Value
Reference files validated	6 (core/nexus.md, python/nexus.md, typescript/nexus.md, go/nexus.md, java/nexus.md, dotnet/nexus.md)
Entry-point edits validated	SKILL.md + 5 language entry-points
Total inline citations	359
Citations resolved cleanly	357 (99.4 %)
Citations with minor overreach	2 (both in java/nexus.md)
Reverse-grep tokens scanned	several hundred (see Check 2)
Unexplained misses	0
Sample size (Check 4)	60 (10 per reference file)
Sample matches	59 (98.3 %)
Regression-pattern hits	0
Workaround-disclosure findings	0
Layout findings	n/a (skipped)

---

Recommended follow-up (non-blocking spot fixes)

These do not block merge; they are optional cleanups for a follow-up commit.

1. references/core/nexus.md:51 — rewrite the "Terminal events" sentence to distinguish the intermediate NexusOperationStarted event from the resolution events (Completed / Failed / Canceled / TimedOut), or remove the word "Terminal" and re-cite nexus-operations.mdx:169 as "events recorded in caller Workflow History."
2. references/java/nexus.md:11 — split or re-cite the Gradle/Maven coordinate clause so the io.temporal:temporal-sdk claim points at develop/java/set-up.mdx rather than the Nexus feature-guide.
3. references/java/nexus.md:239 — soften the "Service class simple name" wording to match what the docs actually show (a literal interface-name string in the example), or wrap with <!-- VERIFY: ... -->.