Implement planned topic: 0024-worker-connections

[skill-temporal-developer-updater]

Validation Report — worker-connections (TypeScript)

Skill root: .
Files validated:

• references/typescript/worker-connections.md (new, 112 lines)
• references/typescript/typescript.md (one-line pointer added at line 182)

Source of truth used: ../documentation/docs/develop/typescript/
Cited docs files:

• docs/develop/typescript/client/temporal-client.mdx
• docs/develop/typescript/set-up.mdx
• docs/develop/typescript/workers/run-process.mdx

Integration topic? No. Check 5 skipped.

---

Go/no-go

Check	Result
1. Citation audit	PASS — 23/23 resolve, all substantively supported
2. Reverse-grep audit	PASS — every factual token found in the docs subtree
3. Regression patterns	PASS — zero hits on universal or topic-specific patterns
4. Independent re-verification (10-claim sample)	PASS — 10/10 match
5. Integration-layout audit	N/A — not an integration topic
6. Tone and scope audit	PASS — zero workaround-disclosure findings

Overall verdict: GO.

---

Check 1 findings

None. All 23 citations resolve to existing files and the cited text substantively supports the authored claim.

A few citations have a narrower line range than ideal — the claim is correct, but the supporting text in the docs sits just outside the cited window. These are stylistic, not factual:

• Line 10 (temporal-client.mdx:612-615): the cite supports "used by a Temporal Application or by code inside an Activity (typically wrapped by Client)" but not the "from @temporalio/client" half of the bullet. That half is supported by lines 487-489 of the same file (cited on the parallel bullet at line 9).
• Line 102 (run-process.mdx:270-272): cite supports "call Worker.shutdown() for programmatic shutdown" but not "then close the connection" — that's the universal pattern from set-up.mdx:230-234.
• Line 109 (temporal-client.mdx:610-615): cite supports the role distinction (NativeConnection = Worker, Connection = App/Activity) but the specific API shapes Worker.create({ connection }) and new Client({ connection }) are documented in earlier code examples (e.g. lines 467-468, 489-490). The claim is correct; the cite is just on the role-distinction prose rather than on the code examples.

No action required — these don't affect generated code.

---

Check 2 findings

None. All extracted factual tokens are present in the docs:

Token	Occurrences in docs
NativeConnection	30 (across 5 files)
loadClientConnectConfig	28 (across 4 files)
@temporalio/envconfig	16 (across 3 files)
@temporalio/worker	26 (across 12 files)
@temporalio/client	19 (across 10 files)
setApiKey	2 in temporal-client.mdx (lines 473, 476) — both in the Connection (client) section, never in the NativeConnection section. The skill correctly limits the claim to client Connection.
SIGUSR2 (and the other three signals)	run-process.mdx:255-256
TEMPORAL_CONFIG_FILE	5 occurrences, including temporal-client.mdx:88
temporal.toml	7 occurrences, including temporal-client.mdx:90
tmprl.cloud	9 occurrences across 4 files
Worker.shutdown	2 in run-process.mdx
localhost:7233	12 occurrences across 5 files
connectionOptions (from config.connectionOptions)	18 occurrences
apiKey: (as a NativeConnection.connect option)	temporal-client.mdx:257, 465, 590

---

Check 3 findings

None.

Greps for the universal regression patterns (--profile, TEMPORAL_TLS_CLIENT_CERT_PATH, TEMPORAL_TLS_CLIENT_KEY_PATH, TEMPORAL_TLS_SERVER_CA_CERT_PATH, tcld service-account, --output text|jsonl, saas-api.tmprl.cloud) returned no matches in the authored file.

The topic-specific regression check — "Import NativeConnection from @temporalio/client" appearing as guidance — returned three matches, all framed as negative warnings: lines 14, 94, and 108. Each one tells the reader not to do this, with the correct path (@temporalio/worker) given alongside or in context. Not findings.

Side note (out of scope for this validation): the docs themselves at temporal-client.mdx:551-552 use TEMPORAL_TLS_CLIENT_CERT_PATH and TEMPORAL_TLS_CLIENT_KEY_PATH in a bash export block. The skill does not propagate these — it relies on loadClientConnectConfig which reads its own set of variables. This is a docs discrepancy, not a skill bug.

---

Check 4 findings

10/10 sampled claims match the docs.

Sample (every-other-citation, with the duplicates collapsed): citations at authored lines 9, 12, 45, 47, 62, 70, 72, 92, 102, 109.

#	Authored line	Cite	Result
1	9	temporal-client.mdx:487-489	Match — NativeConnection imported from @temporalio/worker, used by Workers.
2	12	temporal-client.mdx:614-615	Match — both classes accept the same options.
3	45	set-up.mdx:207-210	Match — await NativeConnection.connect(options) returns a NativeConnection.
4	47	set-up.mdx:230-234	Match — await connection.close() in finally after worker.run().
5	62	temporal-client.mdx:558-572	Match — code shape (imports + loadClientConnectConfig() + NativeConnection.connect(config.connectionOptions)) is identical.
6	70	run-process.mdx:162-163	Match — address shape <Namespace>.<ID>.tmprl.cloud:<port>.
7	72	run-process.mdx:165	Match — mTLS private key required.
8	92	temporal-client.mdx:473-477	Match — setApiKey documented on the Connection object.
9	102	run-process.mdx:270-272	Match (with note in Check 1) — Worker.shutdown() is the programmatic shutdown API; the "then close the connection" half is the universal finally-block pattern, not in this specific range but consistent with the rest of the docs.
10	109	temporal-client.mdx:610-615	Match (with note in Check 1) — Worker.create taking connection vs Client taking connection is consistent with the earlier code examples on the same page.

No substantive divergences.

---

Check 5 findings

N/A — not an integration topic. references/typescript/integrations/ does not exist and the topic is a core SDK reference (Worker connection lifecycle), not a plugin/contrib module.

---

Check 6 findings

None.

• Workaround / escape-hatch (pattern 1): zero. The closest candidate is line 94 ("Do not assume the same method exists on NativeConnection — the local docs do not describe it"), which is a boundary statement, not a workaround disclosure. It tells the agent the limit, not how to get around it.
• In-the-weeds rationale (pattern 2): zero. The file is API-shape-focused throughout.
• Multi-sentence bullets (pattern 3): zero. Each bullet under "Key points," "Lifecycle and shutdown," and "Common mistakes" is one sentence (with one short clarifying clause at most).
• Public Preview without admonition (pattern 4): N/A. No cited docs page marks any of the referenced APIs as Public Preview.

Bonus observation (informational, not a finding): the file contains a <!-- VERIFY: … --> comment at line 96 explicitly acknowledging that worker-side connection-replacement APIs (analogous to setApiKey for the client Connection) are not documented in the local docs clone and pointing at the TypeScript API reference site as the likely authoritative source. This is good authoring hygiene — the skill refrains from making a claim it can't ground. It does mean the topic has a small known gap (Worker-side runtime connection mutation isn't covered); that's a scope decision, not a factual error.

---

Statistics

• Citation count: 23
• Citation pass rate: 23 / 23 = 100%
• Reverse-grep tokens checked: ≥ 14 distinct factual tokens (classes, packages, methods, env vars, file paths, signal names, endpoint shapes)
• Reverse-grep miss count: 0
• Regression patterns checked: 7 universal + 3 topic-specific = 10
• Regression pattern hits: 0
• Check 4 sample size: 10
• Check 4 match rate: 10 / 10 = 100%

---

Verdict: GO

The skill is grounded, citations resolve, no fabrications, no regressions, no workaround disclosures. Recommend merging as-is.

Optional polish (does not gate merge):

• The four cite-range narrownesses noted in Check 1 could be widened (e.g. line 102 could additionally cite set-up.mdx:230-234 for the "then close the connection" half).

End of report.