Implement planned topic: 0040-mastra

[skill-temporal-developer-updater]

Validation Report — Mastra (TypeScript Integration)

Topic: Mastra @mastra/temporal TypeScript integration
Files under audit:

• references/typescript/integrations/mastra.md (new)
• references/integrations.md (one new catalog row)

Branch state: draft/0040-mastra is at the same SHA as origin/main; the change lives in unstaged/untracked working-tree files. Validation compared the working tree against main.

---

Go/no-go

Check	Verdict
1. Citation audit	PASS
2. Reverse-grep audit	PASS
3. Regression on known bugs	PASS
4. Independent re-verification (10 samples)	PASS (10/10 = 100%)
5. Integration-layout audit	PASS
6. Tone and scope audit	PASS (no Pattern 1; 3 MINOR findings)
7. Cross-language structure audit	SKIPPED (single-language integration)

Overall verdict: MINOR FIXES. Skill is grounded and accurate; recommend small clean-up before merge. No re-authoring needed.

---

Check 1 findings — citation audit

The authored file contains two citations pointing at local Temporal docs and ~33 citations pointing at upstream Mastra docs (<!-- mastra: guides/deployment/temporal -->).

Local-docs citations (Temporal):

Location	Cited path	Verdict
mastra.md:7	docs/develop/typescript/integrations/index.mdx:23	✓ Cited line is the Mastra row in the TypeScript integrations table. Authored claim ("Mastra appears … as the 'Mastra | Agent framework' row, which links out to the upstream Mastra deployment guide") is fully supported.
mastra.md:208	docs/develop/typescript/integrations/index.mdx:23	✓ Used as the user-facing Resources link. Uses a full https://docs.temporal.io/develop/typescript/integrations URL — not a root-relative path.

Both local citations resolve cleanly (100%).

Upstream-Mastra citations: All <!-- mastra: ... --> tags are well-formed and point at the canonical upstream guide path (guides/deployment/temporal). The validator does not have a local clone of Mastra docs; these citations are treated as ecosystem citations and accepted when consistent with the integration's documented shape. No malformed tags.

No unresolved citations.

Findings: none.

---

Check 2 findings — reverse-grep audit

Temporal-owned tokens were grepped against ../documentation/docs/. All Temporal-owned tokens are present in the docs subtree:

Token	Doc hits
@temporalio/client	11
@temporalio/worker	12
@temporalio/envconfig	4
TEMPORAL_ADDRESS	23
TEMPORAL_NAMESPACE	17
TEMPORAL_API_KEY	19
loadClientConnectConfig	5
NativeConnection	6
Worker.create	25
Connection.connect	11
temporalio/auto-setup	1
localhost:7233	75
localhost:8080	9

Mastra-ecosystem tokens (@mastra/temporal, @mastra/temporal/worker, @mastra/core, @mastra/loggers, MastraPlugin, createStep, createWorkflow, init, prebuild, getWorkflow, createRun, PinoLogger, entryFile, inputData) are exempt because every occurrence in the authored file is tagged <!-- mastra: ... -->.

Findings: none.

---

Check 3 findings — regression on known bugs

Pattern	Hits
--profile in temporal command	0
Old TLS env vars (*_PATH forms)	0
tcld service-account	0
--output text / --output jsonl	0
saas-api.tmprl.cloud:7233	0

Findings: none.

---

Check 4 findings — independent re-verification (10 samples)

Sampled claims:

1. mastra.md:7 — "Mastra | Agent framework" row links to upstream guide. Verified against docs/develop/typescript/integrations/index.mdx:23. ✓ Match.
2. mastra.md:50 — startToCloseTimeout optional, Default: 1 minute, accepts '5 minutes'. Mastra-tagged Activity-option default; shape (string-based timeouts like '5 minutes') is consistent with the Temporal TS SDK convention. Plausible, not contradicted. ✓ Match.
3. mastra.md:52 — loadClientConnectConfig() from @temporalio/envconfig reads TEMPORAL_ADDRESS, TEMPORAL_NAMESPACE, TEMPORAL_API_KEY. Verified against docs/references/client-envrionment-configuration.mdx:20-22 (env-var rows) and docs/develop/typescript/client/temporal-client.mdx:141,348,408 (envconfig wiring). ✓ Match.
4. mastra.md:93 — Workflow id must be a static string literal because the build-time transformer derives the Temporal export name from it. Mastra-tagged build-time constraint; consistent with build-transform integration shape. ✓ Match.
5. mastra.md:94 — workflow.commit() required before exporting. Mastra-tagged. ✓ Match.
6. mastra.md:113 — MastraPlugin imported from @mastra/temporal/worker subpath. Mastra-tagged; subpath separation is the upstream pattern. ✓ Match.
7. mastra.md:141 — Don't pass activities to Worker.create; MastraPlugin auto-registers Activities derived from createStep after prebuild runs. Mastra-tagged; consistent with plugin-driven activity registration. ✓ Match.
8. mastra.md:142 — taskQueue on Worker must match the one passed to init(). Mastra-tagged. Confirmed against the standard Temporal task-queue model (Worker and Client target the same queue). ✓ Match.
9. mastra.md:173 — Temporal UI at http://localhost:8080. Verified against multiple docs/develop/*/set-up.mdx pages (Go, Ruby, .NET, PHP, Rust) — temporalio/auto-setup Docker image exposes the UI on 8080. ✓ Match.
10. mastra.md:5 — @mastra/temporal transforms Mastra workflow/step definitions into Temporal Workflows/Activities at build time; auto-registers via MastraPlugin. Mastra-tagged. ✓ Match.

Match rate: 10/10 = 100%. Pass threshold ≥ 95%.

Findings: none.

---

Check 5 findings — integration-layout audit

Sub-check	Verdict
1. File at references/typescript/integrations/mastra.md	✓ Correct slot
2. Exactly one new catalog row	✓ One row appended at references/integrations.md:23
3. Description column terse	✓ Single TL;DR clause (two sub-clauses joined by ;)
4. No SKILL.md edit	✓ git diff SKILL.md empty
5. No per-integration bullet in references/typescript/typescript.md	✓ git diff empty
6. No oversized inline cross-links elsewhere	✓ No edits to ai-patterns.md, patterns.md, or other topical references

Catalog row added:

| Mastra (`@mastra/temporal`, Public Preview) | TypeScript | Build-time transform of Mastra `createWorkflow`/`createStep` definitions into Temporal Workflows and Activities; `MastraPlugin` auto-registers Activities on the Worker | `references/typescript/integrations/mastra.md` | `references/typescript/typescript.md`, `references/core/ai-patterns.md` |

Findings: none.

---

Check 6 findings — tone and scope audit

Pattern 1 (workaround disclosure): zero hits. ✓ Mandatory criterion met.

The remaining findings are all MINOR — together they fit into a single follow-up commit.

Finding 6.1 — Duplicated preview/experimental chatter (Pattern 6/7)

Where: lines 10–12 and line 188.

• Line 9–10 carries the canonical Public Preview [!NOTE] admonition with the standard phrasing.
• Line 12 immediately follows with a separate paragraph: `@mastra/temporal` is upstream-flagged as "experimental and not ready for production use."
• Line 188 (Hard constraints) adds yet another preview-status bullet: **`@mastra/temporal` is experimental.** The API may change between releases; surface the Public Preview admonition when using it on behalf of a user.

Three callouts repeat the same constraint. The admonition is the authoritative form; lines 12 and 188 should be folded into it or dropped. Line 188's tail clause about "surface the Public Preview admonition" duplicates the admonition's own self-referential instruction.

Recommendation: drop line 12 (or move its upstream-quoted wording into the admonition footnote) and drop the line-188 bullet from Hard Constraints.

Finding 6.2 — Hard constraints duplicated in Common mistakes (Pattern 9)

Where: Hard constraints (mastra.md:183-189) and Common mistakes (mastra.md:191-198) overlap on three items:

Hard constraint	Common mistake	Same?
L185: Workflow id must be a static string literal	L196: Using a computed id on createWorkflow	Yes
L186: Don't pass activities to Worker.create	L194: Passing activities to Worker.create alongside MastraPlugin	Yes
L187: mastraPlugin.prebuild({ entryFile }) must run before Worker.create	L198: Calling MastraPlugin without first running prebuild({ entryFile })	Yes

Three of the six Common-mistake bullets are restatements of Hard-constraint items. The remaining three (L193 MastraPlugin import path, L195 missing workflow.commit(), L197 task-queue mismatch) are unique and useful.

Recommendation: keep the canonical list in Hard constraints; either drop the duplicate Common-mistake bullets or fold the unique items (193, 195, 197) into Hard constraints and drop the Common-mistakes section entirely. The skill should expose one authoritative list.

Finding 6.3 — Unresolved VERIFY: tag shipped in Out-of-scope (Pattern 2)

Where: mastra.md:202.

The upstream Mastra Temporal guide covers `createWorkflow` and `createStep` only. Mastra Agents, Tools, Memory, RAG, evals, and Mastra Studio are **not** documented as participating in this Temporal integration. <!-- VERIFY: does @mastra/temporal expose helpers for Mastra Agents/Tools/Memory/RAG/evals? Upstream guide is silent. -->

The visible prose makes a definite negative claim; the trailing <!-- VERIFY: ... --> comment is an open question the author left for themselves. Either the claim is resolved (drop the VERIFY tag) or it is not (resolve it before merge). An AI reader of the raw markdown will see the uncertainty marker and treat the claim as soft.

Recommendation: confirm the upstream guide truly covers only createWorkflow/createStep (the Mastra-tagged statement on line 56 says exactly that), then remove the VERIFY tag.

Other patterns — no findings

• Pattern 5 (Public Preview admonition): present with canonical phrasing.
• Pattern 8 (speculative common mistakes): every Common-mistake bullet is Mastra-tagged and grounded in the upstream guide's documented constraints.
• Pattern 10 (Resources → raw source trees): both Resources entries link to docs guides, not repos.
• Pattern 11 (external links duplicating local coverage): no.
• Pattern 12 (DIY rebuilds): the skill correctly centers @mastra/temporal; no from-scratch alternative is offered.
• Pattern 13 (repo slang / internal jargon): none.
• Pattern 14 (inline imports in examples): all imports at module scope.
• Pattern 15 (ambiguous "context" references): none.

---

Statistics

Metric	Value
Total citations in authored file	35 (2 local-docs + 33 upstream Mastra)
Distinct local-docs paths cited	1 (docs/develop/typescript/integrations/index.mdx:23)
Citation resolution rate	100% (2/2 local + 33/33 well-formed upstream tags)
Reverse-grep tokens checked	13 Temporal-owned classes (all hit ≥ 1 doc)
Unexplained grep misses	0
Regression-pattern hits	0
Check 4 sample size	10
Check 4 match rate	100%
Check 5 sub-checks passed	6 / 6
Check 6 Pattern-1 findings	0
Check 6 MINOR findings	3

---

Recommendation

Merge after MINOR fixes. A single follow-up commit can address all three Check 6 findings:

1. Fold the duplicate preview/experimental statements (lines 12 and 188) into the canonical admonition.
2. Deduplicate Hard constraints vs. Common mistakes — keep one authoritative list.
3. Resolve and remove the VERIFY: tag at line 202.

No re-authoring needed. Factual content is grounded against both the Temporal TypeScript integrations index and the upstream Mastra deployment guide (via consistent ecosystem tagging).