Implement planned topic: 0023-buffered-metrics

[skill-temporal-developer-updater]

Validation Report — buffered metrics (TypeScript observability section)

Phase 1 — filled plan

{{SKILL_NAME}}: buffered-metrics (TypeScript SDK custom metric meter)
{{SKILL_ROOT}}: . (this skill repo)
Change under validation: working-tree edit to references/typescript/observability.md (unstaged on draft/0023-buffered-metrics; git log main..HEAD is empty — the validated work is the unstaged diff against main). One file touched, ~20 added lines forming a new "Custom metric meter (buffered metrics)" subsection plus a one-paragraph clarification of the two existing telemetryOptions.metrics shapes.
Integration topic? No. No references/integrations.md row added; no SKILL.md change. Check 5 does not apply.

§2 — Source of truth (filled):

• Primary: ../documentation/docs/
  • docs/develop/typescript/platform/observability.mdx (cited)
  • docs/develop/dotnet/platform/observability.mdx (cited, used as a peer-SDK pointer)
• Secondary: none cited in the diff. The diff points readers to the TypeScript SDK typedoc at https://typescript.temporal.io/ for unverified token names, but does so via <!-- VERIFY: ... --> comments rather than treating the typedoc as a confirmed secondary source.

Check 2 — token patterns (filled):

• TS option keys / config tokens: telemetryOptions, metrics, prometheus, bindAddress, otel, url, Runtime.install, @temporalio/worker.
• Working / unverified token names introduced by the diff: customMetricMeter, metricMeter, RuntimeMetricMeter, UpDownCounter, instrument-type tokens Counter, Histogram, Gauge.
• Cross-SDK tokens cited from the .NET section: CustomMetricMeter, Telemetry, Metrics.
• Phrase tokens: "buffered metrics", "custom metric meter".

Check 3 — regression table: universal patterns only. No skill-specific regression entries apply (no flags, env-vars, ports, or tcld subcommands appear in the diff).

---

Go / no-go

Check	Verdict
1 — Citation audit	PASS (2/2 citations resolve and substantively support the claim)
2 — Reverse-grep audit	FAIL (multiple introduced tokens not in ../documentation/docs/, and the marker used is non-standard — see findings)
3 — Regression on known bugs	PASS (zero hits)
4 — Sampled re-verification	PASS (both sampled claims match docs)
5 — Integration-layout audit	N/A (not an integration topic)

Overall verdict: MINOR FIXES — borderline RE-RUN AUTHORING.

Rationale: Check 3 is clean and Check 4 is 2/2 on the small citation set, so the bar for RE-RUN AUTHORING isn't strictly met. Check 2 has unexplained-but-self-flagged tokens (the diff acknowledges them as unverified and marks them with <!-- VERIFY: ... -->). However, the entire "Custom metric meter (buffered metrics)" subsection makes a substantive conceptual claim about the TypeScript SDK that has no support anywhere in ../documentation/docs/develop/typescript/ — and the TS docs that are cited (lines 37-40) document only prometheus and otel shapes, with no mention of a custom metric meter or buffered metrics. The diff candidly admits this and defers token-level claims to the external typedoc. That is a transparency win but a grounding loss against §2's source of truth.

Recommendation: treat as MINOR FIXES if the maintainer is comfortable shipping a self-flagged-unverified section; otherwise RE-RUN AUTHORING after the typedoc has been consulted so the section can either (a) drop to a one-line "TypeScript also supports a custom metric meter; see the typedoc" pointer, or (b) be re-grounded against the typedoc with <!-- undocumented: source = typescript.temporal.io/... --> tags in the canonical format.

---

Check 1 findings — citation audit

Two inline citation comments are introduced by the diff. Both resolve cleanly.

#	Cited path:lines	Authored claim	Cited text supports?
1	docs/develop/typescript/platform/observability.mdx:37-40	"The two documented telemetryOptions.metrics shapes are prometheus: { bindAddress } for scraping and otel: { url } for a gRPC OpenTelemetry collector."	Yes. Line 37 introduces telemetry options on Runtime.install; line 39 states metrics: { otel: { url } } is "the URL of a gRPC OpenTelemetry collector"; line 40 states metrics: { prometheus: { bindAddress } } is the address for Prometheus to scrape. Exact match.
2	docs/develop/dotnet/platform/observability.mdx:64-88	The cross-SDK concept of a custom in-process meter is documented for the .NET SDK; its specific tokens (CustomMetricMeter, Telemetry/Metrics property names) are .NET-only and must not be transcribed into the TypeScript section.	Yes. Lines 64-88 form the .NET "Set a custom metric meter" section; line 84 shows Telemetry = new() { Metrics = new() { CustomMetricMeter = new CustomMetricMeter(meter) } }. Tokens are .NET-shaped (C# property syntax, Temporalio.Extensions.DiagnosticSource namespace), so the warning against transcription into TypeScript is correct.

Pass rate: 2/2 = 100% ≥ 98% threshold. PASS.

---

Check 2 findings — reverse-grep audit

Tokens introduced by the diff, grouped by whether they appear in ../documentation/docs/:

Found in docs (grounded)

• telemetryOptions, metrics, prometheus, bindAddress, otel, url, Runtime.install, @temporalio/worker — all appear in docs/develop/typescript/platform/observability.mdx around lines 37-48 and elsewhere.
• CustomMetricMeter, Telemetry, Metrics — appear in docs/develop/dotnet/platform/observability.mdx:84 (the diff correctly tags these as .NET-only).

Not found in ../documentation/docs/ (introduced as working/unverified)

Token	Where in diff	Status
UpDownCounter	"Instrument types: Counter, Histogram, Gauge, and UpDownCounter" + standalone callout as "the newly-added instrument type that motivated this entry"	Not in docs subtree at all. Tagged with adjacent <!-- VERIFY: ... -->.
RuntimeMetricMeter	"(working name: RuntimeMetricMeter)"	Not in docs subtree. Tagged with <!-- VERIFY: ... -->.
customMetricMeter, metricMeter	Speculative spellings in the option-key bullet	Not in docs subtree. Tagged with <!-- VERIFY: ... -->.
Counter, Histogram, Gauge (as TypeScript instrument-type tokens)	Listed as supported instrument types	Not in TS or .NET docs (only the .NET CustomMetricMeter class name appears; the underlying instrument-type names are not documented in ../documentation/docs/). No <!-- VERIFY ... --> tag adjacent to these three.
Phrase "buffered metrics"	Subsection title + body	Not anywhere in ../documentation/docs/. Presented as an alternative name for the feature without citation.

Marker-format finding

The Check 2 spec accepts undocumented tokens only when marked <!-- undocumented: source = … -->. The diff uses a different shape: <!-- VERIFY: typescript.temporal.io — confirm ... -->. Functionally similar (it tells the reader the token is unverified and points to an external source) but not the canonical tag format. A downstream grounded-check tool keyed to the canonical tag will treat these as bare unexplained tokens.

Structural finding (more severe than the per-token misses)

The conceptual claim — "the TypeScript SDK supports an in-process custom metric meter ('buffered metrics')" — has no grounding citation in the TypeScript subtree. The cited line range docs/develop/typescript/platform/observability.mdx:37-40 enumerates only prometheus and otel as the two documented shapes; a custom metric meter is not mentioned there or elsewhere in docs/develop/typescript/platform/observability.mdx. The author justifies the claim by analogy to the .NET docs and by reference to upstream release notes that are not in ../documentation/docs/. Per §2 this falls outside the declared source of truth.

Verdict: Check 2 FAIL at the strict reading. The MINOR-FIXES carve-out in §5 ("≤ 5 unexplained misses that look like typos or missing citation comments") arguably applies if you count Counter/Histogram/Gauge + buffered metrics as four missing-tag cases (the four <!-- VERIFY ... --> items being treated as informally tagged), but the structural miss — a whole concept asserted without TS-docs support — is closer to a §6 grounding shortfall than a typo.

---

Check 3 findings — regression on known bugs

Searched the diff for all seven 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 / --output jsonl, saas-api.tmprl.cloud:7233. Zero hits. The diff is in TypeScript runtime territory and touches none of the CLI/TLS surfaces these patterns cover.

PASS.

---

Check 4 findings — sampled re-verification

The diff introduces only two doc citations, so the full population was sampled (sample size = 2; sampling rate = 100%).

Sample 1 — TS observability:37-40. Independent reading of lines 37-40 yields: Runtime.install accepts telemetry options; the two metrics shapes documented at this location are metrics: { otel: { url } } (gRPC OpenTelemetry collector URL) and metrics: { prometheus: { bindAddress } } (Prometheus scrape address). The authored sentence — "The two documented telemetryOptions.metrics shapes are prometheus: { bindAddress } for scraping and otel: { url } for a gRPC OpenTelemetry collector" — matches to the level a reader following either version would behave identically. Match.

Sample 2 — .NET observability:64-88. Independent reading: lines 64-88 form the .NET "Set a custom metric meter" section; the example wires a custom meter via Telemetry.Metrics.CustomMetricMeter = new CustomMetricMeter(meter) from Temporalio.Extensions.DiagnosticSource. The authored claim — that this is the .NET expression of a cross-SDK concept and that its specific tokens (CustomMetricMeter, Telemetry/Metrics property names) are .NET-only and must not be transcribed into the TypeScript section — matches. Match.

Match rate: 2/2 = 100% ≥ 95% threshold. PASS (with the caveat that the sample population is small: only two grounded claims were available to sample because most assertions in the new subsection are deferred to the external typedoc via <!-- VERIFY ... --> markers rather than carrying inline citations).

---

Check 5 findings — integration-layout audit

N/A. This topic is not a third-party integration. No references/integrations.md row was added, no per-integration file was created under references/typescript/integrations/, and no SKILL.md edit appears in the diff. None of the five Check 5 sub-checks apply.

---

Statistics

• Files changed under validation: 1 (references/typescript/observability.md, working tree only — branch is at the same SHA as main).
• Lines added in diff: ~20 (one paragraph + one subsection).
• Inline doc-path citations introduced: 2.
• Citation resolution rate (Check 1): 2/2 = 100%.
• Distinct factual tokens introduced: ~14.
  • Found in docs: ~8 (telemetryOptions, metrics, prometheus, bindAddress, otel, url, Runtime.install, @temporalio/worker; plus CustomMetricMeter, Telemetry, Metrics confined to the .NET-tagged sentence).
  • Not found in docs: 6 (UpDownCounter, RuntimeMetricMeter, customMetricMeter, metricMeter, the TS-side instrument-type tokens Counter/Histogram/Gauge collectively, "buffered metrics").
  • Of those 6, four sit next to <!-- VERIFY: ... --> comments (non-standard but informative); two (Counter/Histogram/Gauge and "buffered metrics") have no adjacent marker.
• Regression-pattern hits (Check 3): 0.
• Sample size (Check 4): 2 (all available citations).
• Sample match rate (Check 4): 2/2 = 100%.
• Check 5 sub-check applicable count: 0/5 (not an integration topic).

---

Summary for the maintainer

The two sentences that do carry citations are clean, and the diff is free of the universal regression bugs. The conceptual section it adds, however, leans on sources outside §2's declared source of truth: an external typedoc and unstated upstream release notes. The author was unusually transparent about that — the <!-- VERIFY ... --> comments, the explicit "working names" disclaimer, and the deliberate decision to omit a code sample all signal "this is a stub". A grounded follow-up pass that consults the typedoc and either (a) shrinks the section to a one-line pointer, or (b) converts each <!-- VERIFY ... --> into a canonical <!-- undocumented: source = … --> tag with a concrete URL anchor, would close the Check 2 gap and lift the verdict to GO.