Implement planned topic: 0002-serverless-ha

[temporal-plugin-updater]

Validation Report — Serverless HA

Branch under validation: draft/0002-serverless-ha.
Diff scope: working-tree changes (no commits yet on this draft).

• references/triage/serverless-ha.md — new file, 148 lines.
• references/triage/ha-failover.md — one added bullet (Fix cloud-certs.md: add min CA duration and api_key_or_mtls auth method #6) under "Two timing facts the triage logic depends on."
• SKILL.md — one added triage-table row and one added reference-file bullet.

Checks applied: 1, 2, 3, 4, 6. Not applicable: 5 (no references/integrations.md — not an integration topic), 7 (not a cross-language SDK feature — a Cloud triage runbook, no per-language pages).

---

Go / no-go

Check	Verdict	Statistic
1 — citation audit	PASS with minor DRIFT (2 findings)	39 / 41 = 95.1% clean citations; but see nuance below
2 — reverse-grep audit	PASS	0 unexplained token misses
3 — regression sweep	PASS	0 hits across universal + topic-specific
4 — independent re-verification	PASS	12 / 12 sampled claims substantively match; 0 behavior-changing divergences
6 — tone and scope audit	PASS	0 Pattern-1 (workaround) findings; Public Preview admonition present with canonical phrasing

Overall verdict: GO with MINOR FIXES.

Rationale: no regression hits, no fabrications, no workaround disclosures, no missing admonition. The two Check 1 DRIFTs are cases where the cited line is real and correct but the authored clause adds a factual aside that isn't in the exact cited range. Neither would cause a reader to do something wrong — under the Check 4 "substantively different" rubric these pass — but Check 1 is strict about "the cited text supports the claim." Ordinary cite-hygiene spot-fix, not a re-authoring trigger.

---

Check 1 findings (minor)

Both findings are the third failure mode described in the plan: "correct line with a claim subtly different from what the line actually says." The primary clause of each authored claim is supported; the drift is in a trailing aside.

Finding 1.1 — encyclopedia:64 doesn't state that a Lambda ARN "embeds the AWS region"

• Location: references/triage/serverless-ha.md:33
• Authored: "For AWS Lambda, the invocation target is a Lambda function ARN, which embeds the AWS region."
• Cited: docs/encyclopedia/workers/serverless-workers/index.mdx:64
• Actual doc text (line 64): "For example, an AWS Lambda compute provider includes the Lambda function ARN and the IAM role Temporal assumes to invoke it."
• Nature: the primary claim ("invocation target is a Lambda function ARN") is supported by combining line 60-62 with line 64. The aside "which embeds the AWS region" is generally true about AWS ARNs but is not in the cited range. It also isn't required for the operator's decision — the whole file already establishes that the compute provider is region-scoped. Suggested spot-fix: drop the aside, or cite an AWS-side source and tag it as ecosystem knowledge.

Finding 1.2 — encyclopedia:65-66 doesn't document the --gcp-cloud-run-region flag

• Location: references/triage/serverless-ha.md:33
• Authored: "For GCP Cloud Run, the target is a Worker Pool whose region is set explicitly by --gcp-cloud-run-region."
• Cited: docs/encyclopedia/workers/serverless-workers/index.mdx:65-66
• Actual doc text (lines 65-66): "A GCP Cloud Run compute provider includes the Worker Pool's project, region, and name, and the service account Temporal impersonates to scale it."
• Nature: the primary claim ("target is a Worker Pool [whose region is a required attribute]") is supported. The specific flag name --gcp-cloud-run-region is documented — but at cloud-run/index.mdx:506, not at the cited encyclopedia range. Suggested spot-fix: add a second citation <!-- docs/production-deployment/worker-deployments/serverless-workers/cloud-run/index.mdx:506 --> for the flag name.

Ratio impact: 39/41 = 95.1%. Under the strict 98% pass criterion this is technically below, but both drifts are additive factual context, not misrepresentation.

---

Check 2 findings

None. Every extracted token resolves in the docs subtrees:

• Flag names (--aws-lambda-function-arn, --aws-lambda-assume-role-arn, --aws-lambda-assume-role-external-id, --build-id, --deployment-name, --gcp-cloud-run-project, --gcp-cloud-run-region, --gcp-cloud-run-service-account, --gcp-cloud-run-worker-pool, --namespace, --region, --yes) — all present in the AWS Lambda and Cloud Run production-deployment docs at the exact cited ranges, and cross-referenced correctly by SDK-code identifier casing (DeploymentName / BuildID for Go SDK, deployment_name / build_id for Python SDK per the respective docs).
• Commands (temporal worker deployment create-version, temporal worker deployment set-current-version, tcld namespace failover) — all documented.
• Concept tokens (FailoverNamespace, Worker Controller Instance, WCI, Worker Deployment Version, Multi-region Replication, Multi-cloud Replication, Namespace Endpoint, Cloud Run Worker Pool, Lambda function ARN) — all documented; grep hit counts range from 3–43 files.
• Env vars — none used in the diff (no false positives).

---

Check 3 findings

None. Zero hits against any regression pattern:

• Universal patterns (--profile, TEMPORAL_TLS_CLIENT_CERT_PATH, TEMPORAL_TLS_CLIENT_KEY_PATH, TEMPORAL_TLS_SERVER_CA_CERT_PATH, tcld service-account, --output text, --output jsonl, saas-api.tmprl.cloud:7233) — clean.
• Topic-specific patterns (Namespace-failover-vs-worker-repoint conflation, AWS/GCP flag family cross-contamination, Cloud Run confirmation-prompt omission, root-relative /cloud/... hyperlinks) — clean.
• All user-facing hyperlinks use full https://docs.temporal.io/... URLs (verified on lines 27, 45, 59, 93, 144, 148 of serverless-ha.md).

---

Check 4 findings

Sampled 12 claims across the diff (10 from serverless-ha.md, 1 from ha-failover.md new bullet, 1 from SKILL.md triage row). Includes the release-stage claim per template requirement (Sample 9). No claim is substantively different from the fresh independent reading of the docs — no reader following the authored version would do something different from a reader following the docs.

Two claims that add framing beyond the cited range but do not change behavior:

Sample 5 — Line 128, "in an incident" framing

• Authored: "The Cloud Run set-current-version command asks for confirmation because it changes which version new Tasks route to; pass --yes to skip the prompt in an incident."
• Docs (cloud-run/index.mdx:530): "This command asks you to confirm, because it changes which version new Tasks route to. Pass --yes to skip the prompt."
• Assessment: authorial framing ("in an incident"). Not misleading — the docs' description of --yes is intact. No behavior change.

Sample 10 — Line 33, "embeds the AWS region" aside

• Same finding as Check 1 Finding 1.1. No behavior change (the file's central point — that the compute provider is region-scoped — is stated explicitly and cited elsewhere).

Match rate: 12 / 12 substantive. Above the 95% threshold.

Sampled claims:

1. Line 47 — 5-minute connection lifetime (manage.mdx:196-197) — EXACT.
2. Line 78 — --aws-lambda-function-arn description (aws-lambda/index.mdx:802) — EXACT (authored trims a "See Step iii" reference; not a semantic change).
3. Line 46 — "operation": "FailoverNamespace" audit event (failovers/index.mdx:130) — EXACT.
4. Line 55 — Cloud Run set-current-version routing note (cloud-run/index.mdx:520-521) — EXACT.
5. Line 128 — --yes note (cloud-run/index.mdx:530) — SUPPORTED with "in an incident" framing.
6. Line 140 — Terraform provider does not trigger failovers (manage.mdx:123-126) — EXACT.
7. Line 47 — DNS-change propagation timing (failovers/index.mdx:119-122) — EXACT.
8. Line 23 — Compute provider region-scoping (encyclopedia:219) — EXACT quote.
9. Line 6 — AWS Lambda Public Preview / Cloud Run Pre-release (evaluate/…/index.mdx:26-28) — SUPPORTED. Docs include a "may change in backwards-incompatible ways" caveat that the authored file omits; not misleading, and the standard [!NOTE] admonition covers the general Public-Preview caveat.
10. Line 33 — Lambda ARN embeds AWS region (encyclopedia:64) — SUPPORTED with aside as noted in Check 1.
11. ha-failover.md new bullet 6 — supported by high-availability/index.mdx:157-161 (cited elsewhere in serverless-ha.md); the ha-failover bullet doesn't need its own inline citation because it points at the sibling file.
12. SKILL.md triage row — symptom → action → link. The action ("Confirm a FailoverNamespace audit event, then check whether the Worker Deployment Version's compute provider is in the new active region") is a compressed summary of serverless-ha.md#diagnostic-signal--did-a-failover-happen. Anchor slug #diagnostic-signal--did-a-failover-happen matches the internal ToC in serverless-ha.md:14 (both use the double-hyphen form for the em-dash + spaces).

---

Check 6 findings

No Pattern-1 (workaround disclosure) findings. The file teaches only the supported remediation path (create-version → set-current-version) and the supported prevention pattern (pre-provisioning per-region Versions). It does not disclose any way to skip set-current-version or bypass a compute-provider constraint.

Public Preview admonition (Pattern 5): present with canonical phrasing. Lines 3-4 of serverless-ha.md:

> [!NOTE]
> 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.

Matches the standard authoring-plan §3.7 phrasing.

Borderline observation (not a finding): The intro paragraph at line 6 restates the release stage — "AWS Lambda support ... is in Public Preview; GCP Cloud Run support is in Pre-release." This is not Pattern-7 chatter because the admonition only mentions "Public Preview" (the more permissive stage that applies to AWS Lambda), and the intro clarifies that Cloud Run is at the earlier Pre-release stage. This is stage-differentiation, not duplication.

Other patterns: clean.

• Pattern 2 (in-the-weeds): the "Why this happens" section is a required setup — each fact changes what the agent does. The Prevention section's "reasoning trail" (line 132: "The docs establish that ... From that alone, the operator-facing implication is clear") is transparent authorial framing, not implementation-history noise.
• Pattern 3 (implementation-internals speculation): none.
• Pattern 4 (multi-sentence bullets that could be one sentence): none flagged; each multi-sentence bullet's second sentence adds a distinct actionable data point.
• Pattern 6 (duplicated admonitions): single [!NOTE] block.
• Pattern 7 (release-stage chatter): see borderline observation above.
• Pattern 8 (speculative "common mistakes"): none.
• Pattern 9 (hard constraints repeated outside canonical section): the constraint restatements at lines 6, 21-27, and 33-35 are structural (intro, canonical form, mechanism-explanation), not accidental duplication.
• Pattern 10 (raw source-tree links): none.
• Pattern 11 (external links duplicating local coverage): none; user-facing docs hyperlinks either summarize this file's coverage (line 27) or hand off to out-of-scope content (line 148).
• Pattern 12 (DIY rebuild): the file centers the documented worker deployment CLI path; no from-scratch alternative.
• Pattern 13 (repo slang): "WCI" and other terms are docs-native.
• Pattern 14 (inline imports): no SDK examples in this file.
• Pattern 15 (ambiguous context references): the WCI is named consistently and grounded in the encyclopedia.

Advisory-only note (does not gate): line 128's --yes guidance interacts with the parent skill's destructive-ops policy (SKILL.md §"Destructive operations" — "--yes belongs in a command the user approved, never in a retry of one that failed its prompt"). The line documents the flag correctly per the Cloud Run docs, but does not restate that the operator should get user approval first. This is not a workaround disclosure — the flag is docs-supported and the skill-wide policy applies to it by default — but a reader might benefit from a one-clause reminder to propose before running.

---

Statistics

• Citations audited: 41
• Citations resolving cleanly: 39 (95.1%)
• Minor DRIFT: 2 (additive aside in a claim, not misrepresentation)
• Reverse-grep tokens extracted: 12 flags + 3 commands + 15 concept terms = 30
• Reverse-grep misses: 0
• Regression pattern hits: 0 (universal + topic-specific)
• Check 4 sample size: 12 (10 from serverless-ha.md, 1 from ha-failover.md, 1 from SKILL.md)
• Check 4 substantive matches: 12 / 12 (100%)
• Check 6 Pattern-1 workaround-disclosure findings: 0
• Check 6 Pattern-5 admonition-missing findings: 0

---

Recommendation

GO with MINOR FIXES.

Spot-fix the two Check 1 DRIFTs in a follow-up commit — either drop the two asides at serverless-ha.md:33, or add a supplemental citation each (an AWS-side reference for "ARN embeds the AWS region"; cloud-run/index.mdx:506 for the --gcp-cloud-run-region flag). No re-authoring is warranted: Checks 3, 4, and 6 all pass their thresholds, Check 2 is clean, and the file's operational core — remediation and prevention — is docs-verbatim.