refactor(rivetkit): split workflow context into WorkflowContext + WorkflowStepContext

[abcxff]

Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[abcxff]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• chore(rivetkit-wasm): re-enable wasm build #5233
• fix(rivetkit): reap registered tasks and cancel abandoned waiters to stop workflow memory leaks #5232
• refactor(rivetkit): split workflow context into WorkflowContext + WorkflowStepContext #5231 👈 (View in Graphite)
• fix(rivetkit): stop logging benign actor-sleep aborts at error level #5211
• feat(rivetkit): move HTTP listener to Rust + RIVETKIT_RUNTIME_MODE env var #5132 : 1 other dependent PR (#5209 )
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[railway-app]

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

Service	Status	Web	Updated (UTC)
kitchen-sink	❌ Build Failed (View Logs)	Web	Jun 14, 2026 at 3:21 am
website	😴 Sleeping (View Logs)	Web	Jun 12, 2026 at 11:17 am
frontend-inspector	❌ Build Failed (View Logs)	Web	Jun 12, 2026 at 11:06 am
ladle	❌ Build Failed (View Logs)	Web	Jun 12, 2026 at 11:06 am
frontend-cloud	❌ Build Failed (View Logs)	Web	Jun 12, 2026 at 11:06 am
mcp-hub	✅ Success (View Logs)	Web	Jun 12, 2026 at 11:06 am

[claude]

PR Review: refactor(rivetkit): split workflow context into WorkflowContext + WorkflowStepContext

Overview

This PR delivers two coupled refactors to the RivetKit TypeScript API:

1. Workflow context split - ActorWorkflowContext becomes two distinct classes: WorkflowContext (orchestration-only: step/loop/race/join/sleep/queue.next) and WorkflowStepContext (actor data access: state/vars/db/client/broadcast/queue.send). Step callbacks now receive a WorkflowStepContext as their first argument.

2. ActorContext property renames - c.key to c.actorKey and c.name to c.actorName across the entire codebase.

---

Strengths

• Removes all @ts-nocheck suppressions in context.ts, driver.ts, and mod.ts. These files were previously unsound; proper types (KVEntryTuple, ReceivedQueueMessage, typed generics) is a significant quality win.
• Eliminates the actorCtx(ctx) cast hack that every workflow example was forced to use. Receiving step directly as a typed argument is much cleaner.
• Step context deactivation guard (DEACTIVATE_STEP symbol + active flag) is the right mechanism. Using a module-private symbol means it never appears on the public surface, and the finally block in runStep guarantees deactivation even on throw. The test that captures leakedStep and verifies access throws afterward is exactly the right validation.
• runRollback correctly skips state snapshotting - rollbacks are compensation logic that should persist their mutations.
• Coverage is thorough: examples, driver-test-suite fixtures, internal tests, and docs are all updated in one change.

---

Issues and Notes

Breaking API surface (document before merging)

c.key to c.actorKey and c.name to c.actorName are breaking changes for all existing actors. The PR description template is left unfilled and there is no migration note. At minimum, the PR body should describe what to change and why.

WorkflowLoopContextOf and WorkflowBranchContextOf now both resolve to WorkflowContext, which no longer exposes state, vars, db, client, broadcast, or queue.send. This is the desired outcome but should be called out explicitly.

queue.send removed from WorkflowContext.queue

The outer loop/orchestration context queue previously included send; it has been removed and send now lives only on WorkflowStepContext.queue. Any existing code calling loopCtx.queue.send() outside a step will now fail at compile time (better than a runtime error). Worth a comment in the public API docs.

destroy() only callable from inside a step

destroy() moved from WorkflowContext to WorkflowStepContext. Correct - destroy is a side effect and must be inside a step - but it is a behavioral change for anyone calling ctx.destroy() directly in a loop body. Good that the test fixture was updated.

any in implementation overloads

next, nextBatch, and join use any in their implementation signatures to satisfy TypeScript while keeping typed public overloads. Pragmatic tradeoff; end users are not exposed to any.

WorkflowStepContext.queue creates a new object on every access

queue is a getter that allocates a fresh object each call. In hot step paths this creates unnecessary GC pressure. Consider building it once in the constructor or using a lazily initialized field. Minor but worth fixing.

WorkflowBranchContextOf still maps to WorkflowContextOf

Semantically correct - branch callbacks receive a WorkflowContext and should sequence further steps inside it. The alias adds nothing over WorkflowContextOf and could be removed to simplify the public surface.

---

Minor

• Removed local type State aliases that were only needed by the old cast pattern. Good cleanup.
• _helpers.ts deletion is correct; no call sites remain.
• Docs (authentication.mdx, design-patterns.mdx, index.mdx) are consistently updated.

---

Summary

The core design is sound and well-executed. Enforcing step-only actor data access at the type system level rather than through a runtime depth counter plus @ts-nocheck is strictly better. Main asks before merging: fill out the PR description with a migration guide for the c.key/c.name renames and note that WorkflowLoopContextOf / WorkflowBranchContextOf no longer carry actor data accessors. The queue getter allocation is the only code-level item worth fixing.

[abcxff]

Merge activity

• Jun 13, 12:31 AM UTC: A user started a stack merge that includes this pull request via Graphite.
• Jun 13, 12:32 AM UTC: Graphite couldn't merge this pull request because a downstack PR feat(rivetkit): move HTTP listener to Rust + RIVETKIT_RUNTIME_MODE env var #5132 failed to merge.