Implement planned topic: 0027-worker-version-reporting

[skill-temporal-developer-updater]

Validation Report — Worker Version Reporting (TypeScript)

Branch: draft/0027-worker-version-reporting
Scope: unstaged diff to references/typescript/versioning.md (this branch has no commits beyond main; the change is in the working tree). Roughly 30 lines added under a new H3 "Build ID reporting without enabling Worker Versioning" plus four citation comments appended to pre-existing bullets.
Plan: VALIDATION_PLAN.md
Validator constraint: authored files and ../documentation/docs/ only; no authoring artifacts read.

---

Go / no-go

Check	Result
1 — citation audit	FAIL (88.9% resolve, below 98% threshold)
2 — reverse-grep audit	FAIL (central claim has no grounding in docs; the author's own <!-- VERIFY: ... --> flag was not resolved)
3 — regression on known bugs	PASS (zero hits)
4 — independent re-verification (n = 9)	FAIL (≤ 78% match)
5 — integration-layout	SKIPPED (not an integration topic)
6 — tone and scope audit	FAIL — MAJOR (workaround-disclosure pattern; pre-shipped <!-- VERIFY: ... --> editorial marker)

Overall verdict: RE-RUN AUTHORING. The four bullets added to the pre-existing "Configuration options" list are fine and individually well-cited; the new "Build ID reporting without enabling Worker Versioning" section is not grounded in the documentation and discloses a configuration the docs do not describe as supported. Send the new section back through authoring; keep the four-bullet citation addition.

---

Check 1 findings — citation audit

9 citation comments added by the diff. 8 resolve cleanly; 1 has a wrong path.

Finding 1.1 — wrong file path

• Diff line 214 (skill file): <!-- docs/develop/typescript/versioning.mdx:36-38 -->
• Cited file does not exist. find documentation/docs -name versioning.mdx finds language versioning pages at docs/develop/{lang}/workflows/versioning.mdx (note the /workflows/ segment). There is no docs/develop/typescript/versioning.mdx.
• The intended file is presumably docs/develop/typescript/workflows/versioning.mdx. Lines 36–38 there are:

  :::danger
Support for the experimental Worker Versioning method before 2025 will be removed from Temporal Server in March 2026. Refer to the [latest Worker Versioning docs](/worker-versioning) for guidance. You can still refer to the [Worker Versioning Legacy](/develop/typescript/worker-versioning-legacy) docs if needed.
:::

• The cited text does support the authored claim ("the deprecated pre-2025 Worker Versioning API will be removed from Temporal Server in March 2026"), so this is a path-citation bug rather than a fabricated claim.

Statistics: 8 / 9 = 88.9 % clean. Below the 98 % threshold.

---

Check 2 findings — reverse-grep audit

Finding 2.1 — central claim not found in docs (matches the author's VERIFY marker)

The new H3 section (lines 185–214 of references/typescript/versioning.md) asserts:

"The TypeScript workerDeploymentOptions shape lets you supply a version (with deploymentName and buildId) without setting useWorkerVersioning: true and without defaultVersioningBehavior. In that configuration, the Worker still reports its Build ID and deployment name to the Temporal Server when it polls — so the Worker Deployment Version becomes visible in describe output — but the Worker does not participate in Worker Versioning routing or Workflow pinning."

Grep results across ../documentation/docs/:

• useWorkerVersioning (camelCase) appears only inside the TS Worker-Versioning example at production-deployment/worker-deployments/worker-versioning.mdx:214 and the deprecated useVersioning at develop/typescript/worker-versioning-legacy.mdx. Both contexts present it as part of enabling Worker Versioning, not as an independently optional flag.
• worker-versioning.mdx:141-148 treats UseVersioning, Version, and DefaultVersioningBehavior as the trio of "configuration parameters to toggle on Worker Versioning" — no mention of supplying Version without UseVersioning.
• No occurrence anywhere in the docs of a version-without-useWorkerVersioning configuration, "Build ID reporting" as a stand-alone mode, or "reports Build ID without enabling versioning routing".
• The closest related sentence — kubernetes-controller.mdx:40: "When a Worker starts polling for Workflow and Activity Tasks, it reports its Deployment Version to the Temporal Server." — sits in a Worker Versioning context, not a "without enabling versioning" context.

The author flagged this themselves in the <!-- VERIFY: ... --> comment on line 187, which asks for confirmation against @temporalio/worker typings that this configuration is "a supported shape rather than just permitted by the type system." The validator cannot resolve a VERIFY that targets SDK source. The unresolved VERIFY itself is the finding: shipping with an editorial-review marker indicates the claim wasn't grounded before publication.

Finding 2.2 — <!-- VERIFY: ... --> marker left in shipped prose

references/typescript/versioning.md:187 carries the full multi-sentence editorial note inside an HTML comment. It is invisible to a human reader of the rendered markdown, but agents that strip HTML comments may behave correctly and agents that don't will see editor's-notebook content. Either way, a VERIFY is an authoring-pass artifact; it must be either resolved (claim re-grounded) or the surrounding section removed.

---

Check 3 findings — regression on known bugs

Zero hits.

• No --profile, TEMPORAL_TLS_CLIENT_*_PATH, tcld service-account, --output text/jsonl, or saas-api.tmprl.cloud:7233 in the diff.
• The legacy top-level buildId / useVersioning fields are referenced only in the explicit "Do not use the legacy top-level buildId / useVersioning fields" warning at line 214 — the supported "don't do X, do Y" form. Acceptable.
• buildId / deploymentName camelCase is correct throughout.
• Public-Preview admonition (line 151) is preexisting and outside the diff.

---

Check 4 findings — independent re-verification (n = 9)

Sample size: all 9 cited claims in the diff.

#	Authored claim	Doc text (read independently)	Verdict
1	useWorkerVersioning enables Worker Versioning	worker-versioning.mdx:144 — "UseVersioning: This enables the Versioning functionality for this Worker."	MATCH
2	version.deploymentName is the logical service name	worker-versioning.mdx:145-146 — describes Version as deployment-name + build-ID pair	MATCH
3	version.buildId identifies a build	same as #2	MATCH
4	defaultVersioningBehavior optional; if unset, every Workflow type must declare its own	worker-versioning.mdx:147-148 — "(Optional) The Default Versioning Behavior. If unset, you'll be required to specify the behavior on each Workflow."	MATCH
5	Build ID + deployment name appear in temporal worker deployment describe-version in the version-without-useWorkerVersioning configuration	worker-versioning.mdx:645-665 shows describe-version output, but for fully versioned workers. The cited lines do not establish that the report-only configuration makes Deployment Versions visible. The citation supports a weaker claim ("describe-version exists and shows these fields") than the authored sentence requires.	MISMATCH — citation does not support the conditional
6	Pinning/Auto-Upgrade requires useWorkerVersioning: true	worker-versioning.mdx:144 states UseVersioning "enables the Versioning functionality." The inverse (no useVersioning → no pinning) is plausibly inferred but not stated at the cited line. Inverse is reasonable but the citation is adjacency rather than direct support.	WEAK
7	Serverless Workers always enable Worker Deployment Versioning; each Workflow must declare a versioning behavior	aws-lambda.mdx:62-66 — exact phrasing match	MATCH
8	Legacy Worker Versioning API will be removed from Temporal Server in March 2026	workflows/versioning.mdx:36-38 — "Support for the experimental Worker Versioning method before 2025 will be removed from Temporal Server in March 2026."	MATCH (claim) / FAIL (path — see Check 1.1)
9	Legacy top-level buildId / useVersioning fields are the deprecated pre-2025 API	worker-versioning-legacy.mdx:35-44 — shows Worker.create({ buildId, useVersioning: true }) form under a Deprecated caution	MATCH

Match rate: 6 strict matches + 1 path-only failure (claim still correct) + 1 weak + 1 mismatch = 6 / 9 strict = 66.7 % or, charitably counting #6 and #8 as matches, 7–8 / 9 ≈ 77–88 %. Either way below the 95 % threshold.

The mismatch (#5) and the weak citation (#6) both load-bear for the new H3 section's "use this configuration to get Build IDs into visibility without committing to versioning routing" thesis. Without those two, the section's "When to use" bullet has no factual grounding.

---

Check 5 findings

Not an integration topic. Skipped.

---

Check 6 findings — tone and scope

Finding 6.1 — workaround disclosure (MAJOR, pattern 1)

The entire new H3 "Build ID reporting without enabling Worker Versioning" section (lines 185–214) reads as a classic workaround-disclosure pattern:

• The documented configuration sets useWorkerVersioning: true together with version.
• The diff tells the agent: "the type system also accepts version alone, here's a configuration that does that, and here's when to reach for it."
• The author's own <!-- VERIFY: ... --> admits this may be "permitted by the type system" rather than "a supported shape."
• The motivating use case in the "When to use" bullet — "You want the Worker's Build ID and deployment name to appear in Temporal Server visibility ... without committing to versioned routing yet" — is exactly the "you can technically..." form the tone-audit calls out.

Agents reading this will adopt the configuration. If it turns out to be type-permitted but unsupported (server-side rejection, undefined server-side behavior, or behavior that changes when the SDK is updated), the result is broken user code attributable to skill guidance.

Per the plan's verdict rubric, a pattern-1 finding alone is MAJOR.

Finding 6.2 — editorial marker shipped in prose (pattern 2)

references/typescript/versioning.md:187 contains the multi-sentence <!-- VERIFY: ... --> comment in the middle of the prose. This is an authoring-pass artifact and should be either resolved (with a new citation) or removed with its surrounding section.

Other patterns

Patterns 2 (other instances), 3, and 4 — clean.

---

Statistics

• Lines added in diff: ~36
• Citation comments added: 9
  • Path-clean: 8 (88.9 %)
  • Path-broken but claim-correct: 1 (Clean up various parts of the skill, and address code review #8)
• Tokens reverse-grepped: 7 distinct (TypeScript field names + CLI commands + the central "report without enable" claim)
  • Found in docs: 6
  • Found only in legacy/deprecated contexts: 1 (useVersioning at top-level — appropriately framed as "don't use")
  • Unsubstantiated by docs: 1 (the version-without-useWorkerVersioning reporting mode)
• Sample size for Check 4: 9 (full census of new citations)
• Strict-match rate: 6 / 9 = 66.7 % (or 7–8 / 9 ≈ 77–88 % counting [WIP] Add support for Go #6 and Clean up various parts of the skill, and address code review #8 charitably)
• Regression-pattern hits: 0
• Major tone findings: 1
• Minor tone findings: 1

---

Recommended action

RE-RUN AUTHORING for the new H3 section (references/typescript/versioning.md:185–214). Three possible outcomes:

1. Source confirms the configuration is supported. Replace the <!-- VERIFY: ... --> with a real citation (SDK source, release notes, or a docs PR) and rewrite the "Build ID reporting" framing so it doesn't read like a workaround.
2. Source confirms the configuration is type-permitted but unsupported. Delete the section entirely. Do not document undocumented shapes.
3. Source is ambiguous. Delete the section; ask in the #topic-ai channel or file a docs issue for clarification before re-adding.

Keep, with one path fix: the four citation comments appended to the pre-existing "Configuration options" bullets (lines 180–183) are correct and add real grounding to existing prose. The defaultVersioningBehavior bullet (line 183) is a useful addition.

Path fix: change <!-- docs/develop/typescript/versioning.mdx:36-38 --> on line 214 to <!-- docs/develop/typescript/workflows/versioning.mdx:36-38 -->.