feat(workflow-engine): add getVersion primitive for workflow versioning

[abcxff]

docs(workflows): document getVersion version-gate primitive

[abcxff]

Stack for rivet-dev/rivet

• #5368 fix(frontend): render version_check workflow entries with ic …
• #5369 feat(workflow-engine): add getVersion primitive for workflow … 👈
• main

Get stack: forklift get 5369
Push local edits: forklift submit
Merge when ready: forklift merge 5369

_{change wpnprqor}

[claude]

Review

Solid feature with strong test coverage (fresh/old-in-flight/per-iteration cutover/retirement/divergence cases in version.test.ts). The core getVersion/hasUnvisitedUnderCurrentScope heuristic in workflow-engine/src/context.ts checks out: pinning via a persisted version_check entry keeps replays deterministic, and the "any unvisited descendant under this scope" signal correctly distinguishes a fresh location from one an old in-flight instance already ran past, including per-iteration isolation inside loops.

Bugs / gaps

1. frontend/src/components/actors/workflow/workflow-to-xyflow.ts:136-179 — getEntrySummary has no case "version_check". It falls through to default: return "", so the new node type renders with a blank summary line in the graph, even though the whole point of persisting resolved/latest is diagnostics. Every other entry kind shows a meaningful one-line summary (sleep state, step result, join progress, etc.); this one won't unless the user opens the raw-data inspector. Worth adding e.g. `v${resolved}` (optionally noting when resolved !== latest).

2. frontend/src/components/actors/workflow/xyflow-nodes.tsx:121-154 — TypeIcon also has no case "version_check", so it silently falls to the generic faCircleCheck default icon instead of a dedicated one, even though a distinct color was correctly added to TYPE_COLORS for this type a few lines above.

   Both switches use a catch-all default rather than exhaustively enumerating the union, which is exactly what CLAUDE.md's "Match statements" rule calls out for TS discriminated unions ("enumerate every variant explicitly so adding a new variant later is a compile error instead of a silent behavior change"). Contrast with rivetkit-typescript/packages/rivetkit/src/workflow/inspector.ts::toWorkflowEntryKind, which uses default: assertUnreachable(kind as never) and consequently did force the new case to be added. These two frontend switches don't have that guard, so the gap compiled silently.

Minor

• hasUnvisitedUnderCurrentScope (workflow-engine/src/context.ts:2660) takes an excludeKey param, but it's unreachable in practice: it's only invoked when existing (the lookup of that exact key) was undefined, meaning the key can't be present in this.storage.history.entries for the scan to find. Could drop the param, or is it defensive for a future call site?
• Same file: hasUnvisitedUnderCurrentScope duplicates the prefix-scan loop in validateComplete (lines 571-593) almost verbatim (same prefix === "" ? true : key.startsWith(...) logic). Could factor into a shared isKeyUnderCurrentScope(key) helper.
• getVersion is called on every loop iteration in the documented usage pattern (examples/docs/actors-workflows/get-version.ts), and each call does a full scan of this.storage.history.entries. This mirrors the existing validateComplete cost (already run every iteration), so it's not a new class of problem, but it does double the per-iteration scan cost for any loop that adopts version gating — worth being aware of for very long-running loops even with history pruning bounding the total size.
• rivetkit-typescript/packages/rivetkit/src/workflow/context.ts:963-965 — getVersion returns this.#wrapActive(...) directly from a non-async method, while every sibling method (step, try, loop, removed, etc.) is declared async and does return await this.#wrapActive(...). Functionally equivalent, just inconsistent with the file's convention.
• examples/docs/actors-workflows/get-version.ts:9-30 has inconsistent indentation inside the ctx.loop(...) callback (body indented 8 spaces instead of 6, closing }); at 6 instead of 4). Looks like it wasn't run through the formatter.

Nice

• The vendored transport codec (rivetkit/src/common/bare/transport/v1.ts) and the workflow-engine/schemas/v1.bare source stay in sync, and VersionCheckEntry is appended at the end of the EntryKind union, so no existing tag numbers shift — consistent with the vbare backward-compatibility rule in CLAUDE.md.
• The loop cutover test (Workflow Engine getVersion per-iteration cutover) is a good end-to-end simulation of the actual redeploy scenario this feature targets.

[railway-app]

🚅 Deployed to the rivet-pr-5369 environment in rivet-frontend

Service	Status	Web	Updated (UTC)
kitchen-sink	😴 Sleeping (View Logs)	Web	Jul 4, 2026 at 3:40 am
website	😴 Sleeping (View Logs)	Web	Jul 3, 2026 at 9:17 pm
ladle	❌ Build Failed (View Logs)	Web	Jul 3, 2026 at 9:07 pm
frontend-inspector	❌ Build Failed (View Logs)	Web	Jul 3, 2026 at 9:07 pm
frontend-cloud	❌ Build Failed (View Logs)	Web	Jul 3, 2026 at 9:07 pm
mcp-hub	✅ Success (View Logs)	Web	Jul 3, 2026 at 9:06 pm