Implement planned topic: 0009-versioned-continue-as-new

[skill-temporal-developer-updater]

Validation Report — versioned-continue-as-new

Branch: draft/0009-versioned-continue-as-new
Scope under review: uncommitted modifications to six existing files —
references/core/versioning.md plus references/{go,python,typescript,java,dotnet}/versioning.md.
Each file adds a new ## Upgrading on Continue-as-New section; references/core/versioning.md also splits the existing "Long-running workflows" row in the "Choosing an Approach" table into two rows.
Validator session: independent of authoring (no read of AUTHORING_LOG.md or authoring plan).
Docs root: ../documentation/docs/.

Go / No-Go

Check	Result
1. Citation audit	PASS (all citations resolve; one minor synthesis noted)
2. Reverse-grep audit	PASS (zero unexplained misses)
3. Regression on known bugs	PASS (zero hits)
4. Independent re-verification (10 sampled claims)	PASS (10/10 substantively match)
5. Integration-layout audit	N/A (topic is not a third-party integration)
6. Tone & scope audit	PASS (no workaround-disclosure findings; Public Preview admonition present in all 6 files)

Overall verdict: GO.

Source of truth (§2)

• Primary:
  • docs/production-deployment/worker-deployments/worker-versioning.mdx — section ## Upgrading on Continue-as-New {#upgrade-on-continue-as-new} (lines 530–618) and the workflow-duration table (lines 261–266).
  • docs/encyclopedia/workers/worker-versioning.mdx — ## Versioning Definitions (line 79) for Target Worker Deployment Version.
• Secondary: none. The Go code example is copied/adapted directly from the docs (no out-of-docs Go SDK source needed).

Check 1 findings — citation audit

Extracted 28 <!-- docs/… --> comments across the 6 files; each was resolved by reading the cited range in the docs.

Citation	Files using it	Status
worker-versioning.mdx:541-545 (Public Preview note)	all 6	✓ direct
worker-versioning.mdx:532-533 (long-running upgrade at CaN boundary)	core	✓ supported with one synthesis (see below)
worker-versioning.mdx:535-539 ("This pattern is for" list)	core	✓ direct quote of the docs bullets
worker-versioning.mdx:549-554 (how it works steps 1–3)	core	✓ direct
encyclopedia/workers/worker-versioning.mdx:79 (Target Version)	core	✓ direct
worker-versioning.mdx:556-559 (target_worker_deployment_version_changed)	core, python, ts, java, dotnet	✓ direct
worker-versioning.mdx:561-605 (Go code source)	go, python, ts, java, dotnet	✓ direct (Go file reproduces it almost verbatim)
worker-versioning.mdx:570-571 (flag refreshed after WFT)	go	✓ direct
worker-versioning.mdx:574-577 (check before Activities/Updates/child WFs)	go	✓ direct
worker-versioning.mdx:582-583 (info.GetTargetWorkerDeploymentVersionChanged())	go	✓ direct
worker-versioning.mdx:584-591 (Continue-as-new options + InitialVersioningBehavior)	core, go	✓ direct
worker-versioning.mdx:587-591 (passing AutoUpgrade)	python, ts, java, dotnet	✓ direct
worker-versioning.mdx:611-613 (lazy moving / Signal to wake)	all 6	✓ direct
worker-versioning.mdx:614-616 (interface compatibility)	all 6	✓ direct
worker-versioning.mdx:532, 549 (Pinned Workflows only)	all 6	✓ supported (line 549 explicitly says Pinned)
worker-versioning.mdx:265 (PINNED + upgrade-on-CaN table row)	core	✓ direct
worker-versioning.mdx:266 (AUTO_UPGRADE + patching table row)	core, twice	✓ direct
worker-versioning.mdx:277 (Compliance audit row)	core	✓ direct

Single minor synthesis (not a finding): references/core/versioning.md:146 claims "Long-running Pinned Workflows that use Continue-as-New can upgrade…" citing docs :532-533. The cited lines read "Long-running Workflows that use Continue-as-New can upgrade…" without the "Pinned" qualifier. The qualifier is correctly inferred from the surrounding section (the docs at :549 say "By default, Pinned Workflows stay on their original Worker Deployment Version even when they Continue-as-New" and the workflow-duration row at :265 ties this pattern to PINNED). A reader following the authored claim arrives at the right behavior; flagging only for completeness.

Pass criterion (≥98%): met. 28/28 citations resolve cleanly.

Check 2 findings — reverse-grep audit

Token classes extracted from authored files and grep-verified against the docs subtree:

Token	Where used	Found in docs?
target_worker_deployment_version_changed	core	✓ worker-versioning.mdx:559
GetTargetWorkerDeploymentVersionChanged	go	✓ worker-versioning.mdx:570, 571, 573, 576, 583, 613
NewContinueAsNewErrorWithOptions	go	✓ worker-versioning.mdx:584
ContinueAsNewErrorOptions	go	✓ worker-versioning.mdx:586
InitialVersioningBehavior	core, go, python, ts, java, dotnet	✓ worker-versioning.mdx:587, 590
ContinueAsNewVersioningBehaviorAutoUpgrade	go	✓ worker-versioning.mdx:587, 590
workflow.GetInfo / workflow.Sleep	go	✓ worker-versioning.mdx:578, 582
AutoUpgrade / AUTO_UPGRADE (enum/string)	all 6	✓ worker-versioning.mdx (multiple)
Pinned / PINNED	all 6	✓ worker-versioning.mdx (multiple)
Target Version / Target Worker Deployment Version	all 6	✓ encyclopedia/workers/worker-versioning.mdx:79, worker-versioning.mdx (multiple)
Public Preview	all 6	✓ worker-versioning.mdx:541
@workflow.run (Python SDK decorator, inside pseudocode comment)	python	✓ worker-versioning.mdx:400 (Python example block)
@WorkflowMethod / @WorkflowVersioningBehavior / VersioningBehavior.PINNED (Java)	java	✓ worker-versioning.mdx:382, 388
[WorkflowRun] / [Workflow(VersioningBehavior = VersioningBehavior.Pinned)] (.NET)	dotnet	✓ worker-versioning.mdx:423 (.NET example block)
workflowInfo() / continueAsNew (TS)	ts	✓ documented across docs/develop/typescript/workflows/*
workflow.info() (Python)	python	✓ documented in docs/develop/python/workflows/continue-as-new.mdx
Workflow.ContinueAsNewAsync (.NET)	dotnet	✓ documented across docs/develop/dotnet/… examples

Note on pseudocode shape. The four non-Go language files (python, ts, java, dotnet) carry a single <!-- VERIFY: … --> comment in front of each pseudocode block, which states explicitly that the docs only contain a Go example and that the SDK method/property names for that language must be confirmed against the SDK before relying on the snippet. The pseudocode itself uses only widely-documented decorator/annotation tokens — no Python-/TS-/Java-/.NET-specific method names for the target-version-changed flag or for the Continue-as-New InitialVersioningBehavior option are committed to. This is a defensible alternative to the standard <!-- undocumented: source = … --> form when the docs themselves are language-incomplete; downstream tooling may want to standardize this notation, but it is not a Check 2 fabrication.

Pass criterion (zero unexplained misses): met.

Check 3 findings — regression on known bugs

Diff was grep-scanned for each universal regression pattern:

Pattern	Hits in diff
--profile (as flag in temporal command)	0
TEMPORAL_TLS_CLIENT_CERT_PATH	0
TEMPORAL_TLS_CLIENT_KEY_PATH	0
TEMPORAL_TLS_SERVER_CA_CERT_PATH	0
tcld service-account (any usage)	0
--output text / --output jsonl	0
saas-api.tmprl.cloud:7233	0

Pass criterion (zero hits): met.

Check 4 findings — independent re-verification (sample)

Sampled 10 claims by reading the docs cold and comparing to the authored text.

#	Authored claim (file)	Doc lines	Match?
1	"Each Workflow run remains pinned to its version (no patching needed during a run)." (core:158)	worker-versioning.mdx:552 (verbatim)	✓
2	"When the Workflow performs Continue-as-New with the upgrade option, the new run starts on the Target Version." (core:160)	worker-versioning.mdx:554 (verbatim)	✓
3	Bulleted list of pattern targets — Entity / Batch / AI agent (core:150-152)	worker-versioning.mdx:537-539 (verbatim bullet content)	✓
4	"The flag is refreshed after each Workflow Task completes; check it from code that runs as part of a Workflow Task (for example, before accepting an Update, starting an Activity, or starting a child Workflow)." (core:164)	worker-versioning.mdx:570-571, 574-577 (combined paraphrase)	✓
5	Go example using workflow.GetInfo(ctx).GetTargetWorkerDeploymentVersionChanged() and NewContinueAsNewErrorWithOptions(... InitialVersioningBehavior: workflow.ContinueAsNewVersioningBehaviorAutoUpgrade ...) (go:235-262)	worker-versioning.mdx:561-605 (nearly verbatim)	✓
6	"Lazy moving only — sleeping Workflows do not auto-upgrade. Send a Signal to wake an idle Workflow so it can check the flag." (all 6 files, limitations)	worker-versioning.mdx:611-613 (paraphrase preserving meaning)	✓
7	"Interface compatibility is your responsibility. When continuing as new to a different version, the previous version's Workflow input must be compatible…" (all 6 files, limitations)	worker-versioning.mdx:614-616	✓
8	"Pinned Workflows only. Auto-Upgrade Workflows already move to the Target Version at Workflow Task boundaries; this pattern adds nothing for them." (all 6, limitations)	worker-versioning.mdx:549; encyclopedia/workers/worker-versioning.mdx:54, 62 (Auto-Upgrade moves at Activity scheduling boundary, which is what an agent would interpret as a WFT boundary)	✓ (interpretive but supported)
9	"For long-running Workflows that cannot use Continue-as-New (e.g., compliance audits that need full history), use AUTO_UPGRADE with patching instead." (core:182)	worker-versioning.mdx:266, 277 (Compliance audit row)	✓
10	"The published Temporal docs only show a Go code sample for this feature." (python/ts/java/dotnet, "What the docs say")	worker-versioning.mdx:561-605 (only the Go fence is present in this section)	✓

Pass criterion (≥95%): met. 10/10 substantively match.

Check 5 findings — integration-layout audit

Not applicable. The topic is core SDK guidance (versioning behavior at Continue-as-New boundaries), not a third-party integration. The references/integrations.md catalog exists in the skill but is not touched by this diff, nor is any new file added under references/{lang}/integrations/. All six modified files are pre-existing topical references being extended in-place.

Check 6 findings — tone & scope audit

• Workaround disclosure (pattern 1): none. The "Send a Signal to wake an idle Workflow" line is the supported technique documented at worker-versioning.mdx:611-613, not a workaround around a stated limit; the limit is the lazy-moving behavior itself, and the Signal is the documented escape.
• Public Preview admonition (pattern 4): present in all six files using the exact authoring-plan phrasing ("This feature is in Public Preview. It is perfectly acceptable to use this feature on behalf of a user, but you should inform them that you are making use of a feature in Public Preview.").
• In-the-weeds rationale (pattern 2): references/core/versioning.md:168 includes a second sentence — "Once the new run is on the new version, the per-Workflow-type annotation continues to apply on subsequent CaN." This does change generated code (it tells the agent not to flip the workflow-type annotation when adding the override), so it is load-bearing rather than narrative — not a finding.
• Multi-sentence bullets (pattern 3): the limitations bullets in the language files run two sentences each, but in every case the second sentence states the supported alternative (e.g., "Send a Signal…"). Acceptable per the rubric's hard-constraint-plus-fix exception.

Pass criterion: met.

Statistics

• Files modified: 6 (1 core + 5 SDK)
• Lines added: 248
• Lines removed: 1 (table row split into two)
• Citation comments extracted: 28 (8 distinct doc line ranges, several reused across files)
• Distinct cited docs files: 2 (worker-versioning.mdx x 2 locations)
• Tokens reverse-grepped: 17 distinct token classes
• Grep misses requiring explanation: 0
• Sampled claims (Check 4): 10
• Sampled-claim match rate: 100%
• Regression-pattern hits: 0
• Workaround-disclosure findings: 0

Notes / non-blocking observations

1. The non-Go SDK files (python, typescript, java, dotnet) deliberately ship comments-only pseudocode under a <!-- VERIFY: … --> admonition because the upstream docs publish only a Go sample. This is a sensible posture for a Public Preview feature with incomplete cross-SDK docs, but the project may want to standardize the admonition format (<!-- VERIFY: … --> vs. <!-- undocumented: source = … -->) in a future authoring-plan revision.
2. references/core/versioning.md:146 inserts the word "Pinned" into a paraphrase of worker-versioning.mdx:532-533 where the docs themselves say "Long-running Workflows" (without the qualifier). The narrowing is correct under the broader section context, so this is logged as a synthesis rather than a fabrication; no fix required.

End of report.