rivetkit 2.3.0-rc.9 → 2.3.1

package/src/workflow/context.ts

@@ -1,41 +1,40 @@
-// @ts-nocheck
-import type { RunContext } from "@/actor/config";
+import type {
+	BranchConfig,
+	BranchOutput,
+	EntryKindType,
+	LoopConfig,
+	LoopResult,
+	StepConfig,
+	TryBlockConfig,
+	TryBlockResult,
+	TryStepConfig,
+	TryStepResult,
+	WorkflowContextInterface,
+	WorkflowQueueMessage,
+} from "@rivetkit/workflow-engine";
 import type {
 	QueueFilterName,
 	QueueNextBatchOptions,
 	QueueNextOptions,
 	QueueResultMessageForName,
 } from "@/actor/config";
-import type { Client } from "@/client/client";
-import type { Registry } from "@/registry";
+import { RAW_STATE_SYMBOL, type RunContext } from "@/actor/config";
 import type {
-	BaseActorDefinition,
 	AnyActorDefinition,
+	BaseActorDefinition,
 } from "@/actor/definition";
-import type {
-	AnyDatabaseProvider,
-	InferDatabaseClient,
-} from "@/common/database/config";
 import type {
 	EventSchemaConfig,
 	InferEventArgs,
 	InferSchemaMap,
 	QueueSchemaConfig,
 } from "@/actor/schema";
-import type { WorkflowContextInterface } from "@rivetkit/workflow-engine";
+import type { Client } from "@/client/client";
 import type {
-	BranchConfig,
-	BranchOutput,
-	EntryKindType,
-	LoopConfig,
-	LoopResult,
-	StepConfig,
-	TryBlockConfig,
-	TryBlockResult,
-	TryStepConfig,
-	TryStepResult,
-	WorkflowQueueMessage,
-} from "@rivetkit/workflow-engine";
+	AnyDatabaseProvider,
+	InferDatabaseClient,
+} from "@/common/database/config";
+import type { Registry } from "@/registry";
 import { WORKFLOW_GUARD_KV_KEY } from "./constants";
 
 type WorkflowActorQueueNextOptions<
@@ -56,7 +55,177 @@ type WorkflowActorQueueNextBatchOptions<
 type WorkflowActorQueueNextBatchOptionsFallback<TCompletable extends boolean> =
 	Omit<QueueNextBatchOptions<string, TCompletable>, "signal">;
 
-type ActorWorkflowLoopConfig<
+// Step run callbacks receive a WorkflowStepContext, which is the only place
+// actor data (state/db/vars/client) may be touched.
+type WorkflowStepRun<
+	T,
+	TState,
+	TConnParams,
+	TConnState,
+	TVars,
+	TInput,
+	TDatabase extends AnyDatabaseProvider,
+	TEvents extends EventSchemaConfig,
+	TQueues extends QueueSchemaConfig,
+> = (
+	step: WorkflowStepContext<
+		TState,
+		TConnParams,
+		TConnState,
+		TVars,
+		TInput,
+		TDatabase,
+		TEvents,
+		TQueues
+	>,
+) => Promise<T>;
+
+// Step rollback callbacks compensate a committed step, so they also run with a
+// WorkflowStepContext to mutate actor data.
+type WorkflowStepRollback<
+	T,
+	TState,
+	TConnParams,
+	TConnState,
+	TVars,
+	TInput,
+	TDatabase extends AnyDatabaseProvider,
+	TEvents extends EventSchemaConfig,
+	TQueues extends QueueSchemaConfig,
+> = (
+	step: WorkflowStepContext<
+		TState,
+		TConnParams,
+		TConnState,
+		TVars,
+		TInput,
+		TDatabase,
+		TEvents,
+		TQueues
+	>,
+	output: T,
+) => Promise<void>;
+
+// Orchestration callbacks (try/loop/race/join) receive a WorkflowContext,
+// because inside them you sequence further steps rather than touch actor data.
+type WorkflowContextRun<
+	T,
+	TState,
+	TConnParams,
+	TConnState,
+	TVars,
+	TInput,
+	TDatabase extends AnyDatabaseProvider,
+	TEvents extends EventSchemaConfig,
+	TQueues extends QueueSchemaConfig,
+> = (
+	ctx: WorkflowContext<
+		TState,
+		TConnParams,
+		TConnState,
+		TVars,
+		TInput,
+		TDatabase,
+		TEvents,
+		TQueues
+	>,
+) => Promise<T>;
+
+export type WorkflowStepConfig<
+	T,
+	TState,
+	TConnParams,
+	TConnState,
+	TVars,
+	TInput,
+	TDatabase extends AnyDatabaseProvider,
+	TEvents extends EventSchemaConfig,
+	TQueues extends QueueSchemaConfig,
+> = Omit<StepConfig<T>, "run" | "rollback"> & {
+	run: WorkflowStepRun<
+		T,
+		TState,
+		TConnParams,
+		TConnState,
+		TVars,
+		TInput,
+		TDatabase,
+		TEvents,
+		TQueues
+	>;
+	rollback?: WorkflowStepRollback<
+		T,
+		TState,
+		TConnParams,
+		TConnState,
+		TVars,
+		TInput,
+		TDatabase,
+		TEvents,
+		TQueues
+	>;
+};
+
+export type WorkflowTryStepConfig<
+	T,
+	TState,
+	TConnParams,
+	TConnState,
+	TVars,
+	TInput,
+	TDatabase extends AnyDatabaseProvider,
+	TEvents extends EventSchemaConfig,
+	TQueues extends QueueSchemaConfig,
+> = Omit<TryStepConfig<T>, "run" | "rollback"> & {
+	run: WorkflowStepRun<
+		T,
+		TState,
+		TConnParams,
+		TConnState,
+		TVars,
+		TInput,
+		TDatabase,
+		TEvents,
+		TQueues
+	>;
+	rollback?: WorkflowStepRollback<
+		T,
+		TState,
+		TConnParams,
+		TConnState,
+		TVars,
+		TInput,
+		TDatabase,
+		TEvents,
+		TQueues
+	>;
+};
+
+export type WorkflowTryConfig<
+	T,
+	TState,
+	TConnParams,
+	TConnState,
+	TVars,
+	TInput,
+	TDatabase extends AnyDatabaseProvider,
+	TEvents extends EventSchemaConfig,
+	TQueues extends QueueSchemaConfig,
+> = Omit<TryBlockConfig<T>, "run"> & {
+	run: WorkflowContextRun<
+		T,
+		TState,
+		TConnParams,
+		TConnState,
+		TVars,
+		TInput,
+		TDatabase,
+		TEvents,
+		TQueues
+	>;
+};
+
+export type WorkflowLoopConfig<
 	S,
 	T,
 	TState,
@@ -69,7 +238,7 @@ type ActorWorkflowLoopConfig<
 	TQueues extends QueueSchemaConfig,
 > = Omit<LoopConfig<S, T>, "run"> & {
 	run: (
-		ctx: ActorWorkflowContext<
+		ctx: WorkflowContext<
 			TState,
 			TConnParams,
 			TConnState,
@@ -80,10 +249,12 @@ type ActorWorkflowLoopConfig<
 			TQueues
 		>,
 		state: S,
-	) => Promise<LoopResult<S, T> | (S extends undefined ? void : never)>;
+	) => Promise<
+		LoopResult<S, T> | (S extends undefined ? undefined | void : never)
+	>;
 };
 
-type ActorWorkflowBranchConfig<
+export type WorkflowBranchConfig<
 	TOutput,
 	TState,
 	TConnParams,
@@ -94,8 +265,54 @@ type ActorWorkflowBranchConfig<
 	TEvents extends EventSchemaConfig,
 	TQueues extends QueueSchemaConfig,
 > = {
-	run: (
-		ctx: ActorWorkflowContext<
+	run: WorkflowContextRun<
+		TOutput,
+		TState,
+		TConnParams,
+		TConnState,
+		TVars,
+		TInput,
+		TDatabase,
+		TEvents,
+		TQueues
+	>;
+};
+
+// Marks a step context inactive once its step has finished. Module-private so it
+// never appears on the public surface.
+const DEACTIVATE_STEP = Symbol("workflow.step.deactivate");
+
+/**
+ * The context handed to a workflow step (`step` / `tryStep` callbacks). This is
+ * the only scope where actor data (state, vars, db, client) and side effects
+ * (broadcast, queue.send) are reachable. It is valid only while its step is
+ * executing; using it after the step resolves throws.
+ */
+export class WorkflowStepContext<
+	TState,
+	TConnParams,
+	TConnState,
+	TVars,
+	TInput,
+	TDatabase extends AnyDatabaseProvider,
+	TEvents extends EventSchemaConfig = Record<never, never>,
+	TQueues extends QueueSchemaConfig = Record<never, never>,
+> {
+	#runCtx: RunContext<
+		TState,
+		TConnParams,
+		TConnState,
+		TVars,
+		TInput,
+		TDatabase,
+		TEvents,
+		TQueues
+	>;
+	#active = true;
+	#onGuardViolation: () => void;
+
+	constructor(
+		runCtx: RunContext<
 			TState,
 			TConnParams,
 			TConnState,
@@ -105,10 +322,133 @@ type ActorWorkflowBranchConfig<
 			TEvents,
 			TQueues
 		>,
-	) => Promise<TOutput>;
-};
+		onGuardViolation: () => void,
+	) {
+		this.#runCtx = runCtx;
+		this.#onGuardViolation = onGuardViolation;
+	}
+
+	[DEACTIVATE_STEP](): void {
+		this.#active = false;
+	}
+
+	#ensureActive(feature: string): void {
+		if (!this.#active) {
+			this.#onGuardViolation();
+			throw new Error(
+				`${feature} is only available inside workflow steps`,
+			);
+		}
+	}
+
+	get actorId(): string {
+		return this.#runCtx.actorId;
+	}
+
+	get name(): string {
+		return this.#runCtx.name;
+	}
+
+	get key(): string[] {
+		return this.#runCtx.key;
+	}
 
-export class ActorWorkflowContext<
+	get log() {
+		return this.#runCtx.log;
+	}
+
+	get abortSignal(): AbortSignal {
+		return this.#runCtx.abortSignal;
+	}
+
+	get state(): TState extends never ? never : TState {
+		this.#ensureActive("state");
+		return this.#runCtx.state as TState extends never ? never : TState;
+	}
+
+	get vars(): TVars extends never ? never : TVars {
+		this.#ensureActive("vars");
+		return this.#runCtx.vars as TVars extends never ? never : TVars;
+	}
+
+	get db(): TDatabase extends never ? never : InferDatabaseClient<TDatabase> {
+		this.#ensureActive("db");
+		return this.#runCtx.db as TDatabase extends never
+			? never
+			: InferDatabaseClient<TDatabase>;
+	}
+
+	client<R extends Registry<any> = Registry<any>>(): Client<R> {
+		this.#ensureActive("client");
+		return this.#runCtx.client<R>();
+	}
+
+	broadcast<K extends keyof TEvents & string>(
+		name: K,
+		...args: InferEventArgs<InferSchemaMap<TEvents>[K]>
+	): void;
+	broadcast(
+		name: keyof TEvents extends never ? string : never,
+		...args: Array<unknown>
+	): void;
+	broadcast(name: string, ...args: Array<unknown>): void {
+		this.#ensureActive("broadcast");
+		this.#runCtx.broadcast(
+			name as never,
+			...(args as unknown[] as never[]),
+		);
+	}
+
+	get queue() {
+		const self = this;
+		function send<K extends keyof TQueues & string>(
+			name: K,
+			body: InferSchemaMap<TQueues>[K],
+		): Promise<void>;
+		function send(
+			name: keyof TQueues extends never ? string : never,
+			body: unknown,
+		): Promise<void>;
+		async function send(name: string, body: unknown): Promise<void> {
+			self.#ensureActive("queue.send");
+			await self.#runCtx.queue.send(name as never, body as never);
+		}
+		return { send };
+	}
+
+	/**
+	 * Holds the actor awake for the duration of the provided promise. The actor
+	 * cannot idle-sleep or finalize the sleep grace period until the promise
+	 * settles.
+	 */
+	keepAwake<T>(promise: Promise<T>): Promise<T> {
+		this.#ensureActive("keepAwake");
+		return this.#runCtx.keepAwake(promise);
+	}
+
+	/**
+	 * Registers a promise that the sleep grace period will wait on. Use this for
+	 * best-effort flush/cleanup work that may complete inside the grace window.
+	 */
+	waitUntil(promise: Promise<void>): void {
+		this.#ensureActive("waitUntil");
+		this.#runCtx.waitUntil(promise);
+	}
+
+	destroy(): void {
+		this.#ensureActive("destroy");
+		this.#runCtx.destroy();
+	}
+}
+
+/**
+ * The context handed to the workflow function and to orchestration callbacks
+ * (`try` / `loop` / `race` / `join`). It exposes the deterministic, replayable
+ * workflow primitives (step, sleep, queue waits, control flow). It deliberately
+ * does NOT expose actor data; reach `state`, `db`, `vars`, `client`, and
+ * `broadcast` through the step context passed to `step` / `tryStep`.
+ */
+export class WorkflowContext<
 	TState,
 	TConnParams,
 	TConnState,
@@ -117,8 +457,7 @@ export class ActorWorkflowContext<
 	TDatabase extends AnyDatabaseProvider,
 	TEvents extends EventSchemaConfig = Record<never, never>,
 	TQueues extends QueueSchemaConfig = Record<never, never>,
-> implements WorkflowContextInterface
-{
+> {
 	#inner: WorkflowContextInterface;
 	#runCtx: RunContext<
 		TState,
@@ -130,9 +469,6 @@ export class ActorWorkflowContext<
 		TEvents,
 		TQueues
 	>;
-	#actorAccessDepth = 0;
-	#allowActorAccess = false;
-	#guardViolation = false;
 
 	constructor(
 		inner: WorkflowContextInterface,
@@ -159,6 +495,22 @@ export class ActorWorkflowContext<
 		return this.#inner.abortSignal;
 	}
 
+	get actorId(): string {
+		return this.#runCtx.actorId;
+	}
+
+	get name(): string {
+		return this.#runCtx.name;
+	}
+
+	get key(): string[] {
+		return this.#runCtx.key;
+	}
+
+	get log() {
+		return this.#runCtx.log;
+	}
+
 	get queue() {
 		const self = this;
 		function next<
@@ -178,10 +530,9 @@ export class ActorWorkflowContext<
 				TCompletable
 			>
 		>;
-		async function next(
-			name: string,
-			opts?: WorkflowActorQueueNextOptions<string, boolean>,
-		): Promise<WorkflowQueueMessage<unknown>> {
+		// The implementation signature stays broad so the schema-typed public
+		// overloads above remain compatible with it.
+		async function next(name: string, opts?: any): Promise<any> {
 			const message = await self.#inner.queue.next(name, opts);
 			return self.#toActorQueueMessage(message);
 		}
@@ -207,108 +558,232 @@ export class ActorWorkflowContext<
 				>
 			>
 		>;
-		async function nextBatch(
-			name: string,
-			opts?: WorkflowActorQueueNextBatchOptions<string, boolean>,
-		): Promise<Array<WorkflowQueueMessage<unknown>>> {
+		async function nextBatch(name: string, opts?: any): Promise<any> {
 			const messages = await self.#inner.queue.nextBatch(name, opts);
 			return messages.map((message) =>
 				self.#toActorQueueMessage(message),
 			);
 		}
 
-		function send<K extends keyof TQueues & string>(
-			name: K,
-			body: InferSchemaMap<TQueues>[K],
-		): Promise<void>;
-		function send(
-			name: keyof TQueues extends never ? string : never,
-			body: unknown,
-		): Promise<void>;
-		async function send(name: string, body: unknown): Promise<void> {
-			self.#ensureActorAccess("queue.send");
-			await self.#runCtx.queue.send(name as never, body as never);
-		}
-
 		return {
 			next,
 			nextBatch,
-			send,
 		};
 	}
 
+	step<T>(
+		name: string,
+		run: WorkflowStepRun<
+			T,
+			TState,
+			TConnParams,
+			TConnState,
+			TVars,
+			TInput,
+			TDatabase,
+			TEvents,
+			TQueues
+		>,
+	): Promise<T>;
+	step<T>(
+		config: WorkflowStepConfig<
+			T,
+			TState,
+			TConnParams,
+			TConnState,
+			TVars,
+			TInput,
+			TDatabase,
+			TEvents,
+			TQueues
+		>,
+	): Promise<T>;
 	async step<T>(
-		nameOrConfig: string | Parameters<WorkflowContextInterface["step"]>[0],
-		run?: () => Promise<T>,
+		nameOrConfig:
+			| string
+			| WorkflowStepConfig<
+					T,
+					TState,
+					TConnParams,
+					TConnState,
+					TVars,
+					TInput,
+					TDatabase,
+					TEvents,
+					TQueues
+			  >,
+		run?: WorkflowStepRun<
+			T,
+			TState,
+			TConnParams,
+			TConnState,
+			TVars,
+			TInput,
+			TDatabase,
+			TEvents,
+			TQueues
+		>,
 	): Promise<T> {
 		if (typeof nameOrConfig === "string") {
 			if (!run) {
 				throw new Error("Step run function missing");
 			}
+			const stepRun = run;
 			return await this.#wrapActive(() =>
-				this.#inner.step(nameOrConfig, () =>
-					this.#withActorAccess(run),
-				),
+				this.#inner.step(nameOrConfig, () => this.#runStep(stepRun)),
 			);
 		}
-		const stepConfig = nameOrConfig as StepConfig<T>;
+		const stepConfig = nameOrConfig;
+		const rollback = stepConfig.rollback;
 		const config: StepConfig<T> = {
 			...stepConfig,
-			run: () => this.#withActorAccess(stepConfig.run),
+			run: () => this.#runStep(stepConfig.run),
+			rollback: rollback
+				? (_ctx, output) => this.#runRollback(rollback, output)
+				: undefined,
 		};
 		return await this.#wrapActive(() => this.#inner.step(config));
 	}
 
+	tryStep<T>(
+		name: string,
+		run: WorkflowStepRun<
+			T,
+			TState,
+			TConnParams,
+			TConnState,
+			TVars,
+			TInput,
+			TDatabase,
+			TEvents,
+			TQueues
+		>,
+	): Promise<TryStepResult<T>>;
+	tryStep<T>(
+		config: WorkflowTryStepConfig<
+			T,
+			TState,
+			TConnParams,
+			TConnState,
+			TVars,
+			TInput,
+			TDatabase,
+			TEvents,
+			TQueues
+		>,
+	): Promise<TryStepResult<T>>;
 	async tryStep<T>(
 		nameOrConfig:
 			| string
-			| Parameters<WorkflowContextInterface["tryStep"]>[0],
-		run?: () => Promise<T>,
+			| WorkflowTryStepConfig<
+					T,
+					TState,
+					TConnParams,
+					TConnState,
+					TVars,
+					TInput,
+					TDatabase,
+					TEvents,
+					TQueues
+			  >,
+		run?: WorkflowStepRun<
+			T,
+			TState,
+			TConnParams,
+			TConnState,
+			TVars,
+			TInput,
+			TDatabase,
+			TEvents,
+			TQueues
+		>,
 	): Promise<TryStepResult<T>> {
 		if (typeof nameOrConfig === "string") {
 			if (!run) {
 				throw new Error("Step run function missing");
 			}
+			const stepRun = run;
 			return await this.#wrapActive(() =>
-				this.#inner.tryStep(nameOrConfig, () =>
-					this.#withActorAccess(run),
-				),
+				this.#inner.tryStep(nameOrConfig, () => this.#runStep(stepRun)),
 			);
 		}
-		const stepConfig = nameOrConfig as TryStepConfig<T>;
+		const stepConfig = nameOrConfig;
+		const rollback = stepConfig.rollback;
 		const config: TryStepConfig<T> = {
 			...stepConfig,
-			run: () => this.#withActorAccess(stepConfig.run),
+			run: () => this.#runStep(stepConfig.run),
+			rollback: rollback
+				? (_ctx, output) => this.#runRollback(rollback, output)
+				: undefined,
 		};
 		return await this.#wrapActive(() => this.#inner.tryStep(config));
 	}
 
+	try<T>(
+		name: string,
+		run: WorkflowContextRun<
+			T,
+			TState,
+			TConnParams,
+			TConnState,
+			TVars,
+			TInput,
+			TDatabase,
+			TEvents,
+			TQueues
+		>,
+	): Promise<TryBlockResult<T>>;
+	try<T>(
+		config: WorkflowTryConfig<
+			T,
+			TState,
+			TConnParams,
+			TConnState,
+			TVars,
+			TInput,
+			TDatabase,
+			TEvents,
+			TQueues
+		>,
+	): Promise<TryBlockResult<T>>;
 	async try<T>(
-		nameOrConfig: string | Parameters<WorkflowContextInterface["try"]>[0],
-		run?: (
-			ctx: ActorWorkflowContext<
-				TState,
-				TConnParams,
-				TConnState,
-				TVars,
-				TInput,
-				TDatabase,
-				TEvents,
-				TQueues
-			>,
-		) => Promise<T>,
+		nameOrConfig:
+			| string
+			| WorkflowTryConfig<
+					T,
+					TState,
+					TConnParams,
+					TConnState,
+					TVars,
+					TInput,
+					TDatabase,
+					TEvents,
+					TQueues
+			  >,
+		run?: WorkflowContextRun<
+			T,
+			TState,
+			TConnParams,
+			TConnState,
+			TVars,
+			TInput,
+			TDatabase,
+			TEvents,
+			TQueues
+		>,
 	): Promise<TryBlockResult<T>> {
 		if (typeof nameOrConfig === "string") {
 			if (!run) {
 				throw new Error("Try run function missing");
 			}
+			const tryRun = run;
 			return await this.#wrapActive(() =>
 				this.#inner.try(nameOrConfig, async (ctx) =>
-					run(this.#createChildContext(ctx)),
+					tryRun(this.#createChildContext(ctx)),
 				),
 			);
 		}
-		const tryConfig = nameOrConfig as TryBlockConfig<T>;
+		const tryConfig = nameOrConfig;
 		const config: TryBlockConfig<T> = {
 			...tryConfig,
 			run: async (ctx) => tryConfig.run(this.#createChildContext(ctx)),
@@ -316,10 +791,10 @@ export class ActorWorkflowContext<
 		return await this.#wrapActive(() => this.#inner.try(config));
 	}
 
-	async loop<T>(
+	loop<T>(
 		name: string,
 		run: (
-			ctx: ActorWorkflowContext<
+			ctx: WorkflowContext<
 				TState,
 				TConnParams,
 				TConnState,
@@ -329,16 +804,10 @@ export class ActorWorkflowContext<
 				TEvents,
 				TQueues
 			>,
-		) => Promise<LoopResult<undefined, T> | void>,
-	): Promise<T>;
-	async loop<T>(
-		name: string,
-		run: (
-			ctx: WorkflowContextInterface,
-		) => Promise<LoopResult<undefined, T> | void>,
+		) => Promise<LoopResult<undefined, T> | undefined | void>,
 	): Promise<T>;
-	async loop<S, T>(
-		config: ActorWorkflowLoopConfig<
+	loop<S, T>(
+		config: WorkflowLoopConfig<
 			S,
 			T,
 			TState,
@@ -351,12 +820,10 @@ export class ActorWorkflowContext<
 			TQueues
 		>,
 	): Promise<T>;
-	async loop<S, T>(config: LoopConfig<S, T>): Promise<T>;
 	async loop(
 		nameOrConfig:
 			| string
-			| LoopConfig<any, any>
-			| ActorWorkflowLoopConfig<
+			| WorkflowLoopConfig<
 					any,
 					any,
 					TState,
@@ -369,7 +836,7 @@ export class ActorWorkflowContext<
 					TQueues
 			  >,
 		run?: (
-			ctx: ActorWorkflowContext<
+			ctx: WorkflowContext<
 				TState,
 				TConnParams,
 				TConnState,
@@ -379,22 +846,32 @@ export class ActorWorkflowContext<
 				TEvents,
 				TQueues
 			>,
-		) => Promise<LoopResult<undefined, any> | void>,
+		) => Promise<LoopResult<undefined, any> | undefined | void>,
 	): Promise<any> {
 		if (typeof nameOrConfig === "string") {
 			if (!run) {
 				throw new Error("Loop run function missing");
 			}
+			const loopRun = run;
 			return await this.#wrapActive(() =>
-				this.#inner.loop(nameOrConfig, async (ctx) =>
-					run(this.#createChildContext(ctx)),
+				this.#inner.loop(
+					nameOrConfig,
+					// A void return (no explicit Loop result) is undefined at
+					// runtime, which the engine treats as continue.
+					async (
+						ctx,
+					): Promise<LoopResult<undefined, any> | undefined> =>
+						(await loopRun(this.#createChildContext(ctx))) ??
+						undefined,
 				),
 			);
 		}
+		const loopConfig = nameOrConfig;
 		const wrapped: LoopConfig<any, any> = {
-			...nameOrConfig,
-			run: async (ctx, state) =>
-				nameOrConfig.run(this.#createChildContext(ctx), state),
+			...loopConfig,
+			run: (async (ctx, state) =>
+				(await loopConfig.run(this.#createChildContext(ctx), state)) ??
+				undefined) as LoopConfig<any, any>["run"],
 		};
 		return await this.#wrapActive(() => this.#inner.loop(wrapped));
 	}
@@ -407,11 +884,6 @@ export class ActorWorkflowContext<
 		return this.#inner.sleepUntil(name, timestampMs);
 	}
 
-	destroy(): void {
-		this.#ensureActorAccess("destroy");
-		this.#runCtx.destroy();
-	}
-
 	async rollbackCheckpoint(name: string): Promise<void> {
 		await this.#wrapActive(() => this.#inner.rollbackCheckpoint(name));
 	}
@@ -419,7 +891,7 @@ export class ActorWorkflowContext<
 	async join<
 		T extends Record<
 			string,
-			ActorWorkflowBranchConfig<
+			WorkflowBranchConfig<
 				unknown,
 				TState,
 				TConnParams,
@@ -439,7 +911,10 @@ export class ActorWorkflowContext<
 		name: string,
 		branches: T,
 	): Promise<{ [K in keyof T]: BranchOutput<T[K]> }>;
-	async join(name: string, branches: Record<string, BranchConfig<unknown>>) {
+	async join(
+		name: string,
+		branches: Record<string, { run: (ctx: any) => Promise<unknown> }>,
+	) {
 		const wrappedBranches = Object.fromEntries(
 			Object.entries(branches).map(([key, branch]) => [
 				key,
@@ -458,25 +933,17 @@ export class ActorWorkflowContext<
 		name: string,
 		branches: Array<{
 			name: string;
-			run: (
-				ctx: ActorWorkflowContext<
-					TState,
-					TConnParams,
-					TConnState,
-					TVars,
-					TInput,
-					TDatabase,
-					TEvents,
-					TQueues
-				>,
-			) => Promise<T>;
-		}>,
-	): Promise<{ winner: string; value: T }>;
-	async race<T>(
-		name: string,
-		branches: Array<{
-			name: string;
-			run: (ctx: WorkflowContextInterface) => Promise<T>;
+			run: WorkflowContextRun<
+				T,
+				TState,
+				TConnParams,
+				TConnState,
+				TVars,
+				TInput,
+				TDatabase,
+				TEvents,
+				TQueues
+			>;
 		}>,
 	): Promise<{ winner: string; value: T }> {
 		const wrappedBranches = branches.map((branch) => ({
@@ -497,82 +964,58 @@ export class ActorWorkflowContext<
 		return this.#inner.isEvicted();
 	}
 
-	get state(): TState extends never ? never : TState {
-		this.#ensureActorAccess("state");
-		return this.#runCtx.state as TState extends never ? never : TState;
-	}
-
-	get vars(): TVars extends never ? never : TVars {
-		this.#ensureActorAccess("vars");
-		return this.#runCtx.vars as TVars extends never ? never : TVars;
-	}
-
-	client<R extends Registry<any> = Registry<any>>(): Client<R> {
-		this.#ensureActorAccess("client");
-		return this.#runCtx.client<R>();
-	}
-
-	get db(): TDatabase extends never ? never : InferDatabaseClient<TDatabase> {
-		this.#ensureActorAccess("db");
-		return this.#runCtx.db as TDatabase extends never
-			? never
-			: InferDatabaseClient<TDatabase>;
-	}
-
-	get log() {
-		return this.#runCtx.log;
-	}
-
-	/** @deprecated No-op. Use `keepAwake(promise)` or `waitUntil(promise)` instead. */
-	setPreventSleep(_prevent: boolean): void {
-		this.#ensureActorAccess("setPreventSleep");
-	}
-
-	/** @deprecated No-op. Always returns `false`. */
-	get preventSleep(): boolean {
-		this.#ensureActorAccess("preventSleep");
-		return false;
-	}
-
-	/**
-	 * Holds the actor awake for the duration of the provided promise. The
-	 * actor cannot idle-sleep or finalize the sleep grace period until the
-	 * promise settles.
-	 */
-	keepAwake<T>(promise: Promise<T>): Promise<T> {
-		this.#ensureActorAccess("keepAwake");
-		return this.#runCtx.keepAwake(promise);
-	}
-
-	/**
-	 * Registers a promise that the sleep grace period will wait on. Use this
-	 * for best-effort flush/cleanup work that may complete inside the grace
-	 * window. For work the actor must stay running through, prefer
-	 * `c.keepAwake(promise)` which also blocks idle sleep.
-	 */
-	waitUntil(promise: Promise<void>): void {
-		this.#ensureActorAccess("waitUntil");
-		this.#runCtx.waitUntil(promise);
-	}
+	// Runs a user step body inside a fresh step context, snapshotting actor
+	// state/vars so a thrown step rolls back its mutations, and deactivating the
+	// step context once the body settles so it cannot be used after the step.
+	async #runStep<T>(
+		run: WorkflowStepRun<
+			T,
+			TState,
+			TConnParams,
+			TConnState,
+			TVars,
+			TInput,
+			TDatabase,
+			TEvents,
+			TQueues
+		>,
+	): Promise<T> {
+		const stepCtx = new WorkflowStepContext<
+			TState,
+			TConnParams,
+			TConnState,
+			TVars,
+			TInput,
+			TDatabase,
+			TEvents,
+			TQueues
+		>(this.#runCtx, () => this.#markGuardTriggered());
 
-	get actorId(): string {
-		return this.#runCtx.actorId;
-	}
+		let stateSnapshot: { state: TState } | null = null;
+		try {
+			stateSnapshot = { state: this.#runCtx[RAW_STATE_SYMBOL]() };
+		} catch (error) {
+			this.#runCtx.log.debug({
+				msg: "failed to get state, likely due to being stateless workflow",
+				error,
+			});
+		}
+		if (stateSnapshot) {
+			stateSnapshot.state = structuredClone(stateSnapshot.state);
+		}
+		const varsSnapshot = structuredClone(this.#runCtx.vars);
 
-	broadcast<K extends keyof TEvents & string>(
-		name: K,
-		...args: InferEventArgs<InferSchemaMap<TEvents>[K]>
-	): void;
-	broadcast(
-		name: keyof TEvents extends never ? string : never,
-		...args: Array<unknown>
-	): void;
-	broadcast(name: string, ...args: Array<unknown>): void {
-		this.#ensureActorAccess("broadcast");
-		this.#runCtx.broadcast(
-			name as never,
-			...(args as unknown[] as never[]),
-		);
+		try {
+			return await run(stepCtx);
+		} catch (error) {
+			if (stateSnapshot) {
+				this.#runCtx.state = stateSnapshot.state;
+			}
+			this.#runCtx.vars = varsSnapshot;
+			throw error;
+		} finally {
+			stepCtx[DEACTIVATE_STEP]();
+		}
 	}
 
 	#toActorQueueMessage<T>(
@@ -593,41 +1036,45 @@ export class ActorWorkflowContext<
 		};
 	}
 
-	async #wrapActive<T>(run: () => Promise<T>): Promise<T> {
-		return await this.#runCtx.internalKeepAwake(run);
-	}
-
-	async #withActorAccess<T>(run: () => Promise<T>): Promise<T> {
-		this.#actorAccessDepth++;
-		if (this.#actorAccessDepth === 1) {
-			this.#allowActorAccess = true;
-		}
+	// Runs a step rollback compensation with an active step context. Rollbacks
+	// intentionally mutate actor state, so their writes are not snapshotted.
+	async #runRollback<T>(
+		rollback: WorkflowStepRollback<
+			T,
+			TState,
+			TConnParams,
+			TConnState,
+			TVars,
+			TInput,
+			TDatabase,
+			TEvents,
+			TQueues
+		>,
+		output: T,
+	): Promise<void> {
+		const stepCtx = new WorkflowStepContext<
+			TState,
+			TConnParams,
+			TConnState,
+			TVars,
+			TInput,
+			TDatabase,
+			TEvents,
+			TQueues
+		>(this.#runCtx, () => this.#markGuardTriggered());
 		try {
-			return await run();
+			await rollback(stepCtx, output);
 		} finally {
-			this.#actorAccessDepth--;
-			if (this.#actorAccessDepth === 0) {
-				this.#allowActorAccess = false;
-			}
-		}
-	}
-
-	#ensureActorAccess(feature: string): void {
-		if (!this.#allowActorAccess) {
-			this.#guardViolation = true;
-			this.#markGuardTriggered();
-			throw new Error(
-				`${feature} is only available inside workflow steps`,
-			);
+			stepCtx[DEACTIVATE_STEP]();
 		}
 	}
 
-	consumeGuardViolation(): boolean {
-		const violated = this.#guardViolation;
-		this.#guardViolation = false;
-		return violated;
+	async #wrapActive<T>(run: () => Promise<T>): Promise<T> {
+		return await this.#runCtx.internalKeepAwake(run);
 	}
 
+	// Records that a step context was used outside its step. Mirrors the value
+	// onto actor state and a KV flag so callers can observe the violation.
 	#markGuardTriggered(): void {
 		try {
 			const state = this.#runCtx.state as Record<string, unknown>;
@@ -658,7 +1105,7 @@ export class ActorWorkflowContext<
 
 	#createChildContext(
 		ctx: WorkflowContextInterface,
-	): ActorWorkflowContext<
+	): WorkflowContext<
 		TState,
 		TConnParams,
 		TConnState,
@@ -668,7 +1115,7 @@ export class ActorWorkflowContext<
 		TEvents,
 		TQueues
 	> {
-		return new ActorWorkflowContext(ctx, this.#runCtx);
+		return new WorkflowContext(ctx, this.#runCtx);
 	}
 }
 
@@ -684,7 +1131,7 @@ export type WorkflowContextOf<AD extends AnyActorDefinition> =
 		infer Q extends QueueSchemaConfig,
 		any
 	>
-		? ActorWorkflowContext<S, CP, CS, V, I, DB, E, Q>
+		? WorkflowContext<S, CP, CS, V, I, DB, E, Q>
 		: never;
 
 export type WorkflowLoopContextOf<AD extends AnyActorDefinition> =
@@ -694,4 +1141,16 @@ export type WorkflowBranchContextOf<AD extends AnyActorDefinition> =
 	WorkflowContextOf<AD>;
 
 export type WorkflowStepContextOf<AD extends AnyActorDefinition> =
-	WorkflowContextOf<AD>;
+	AD extends BaseActorDefinition<
+		infer S,
+		infer CP,
+		infer CS,
+		infer V,
+		infer I,
+		infer DB extends AnyDatabaseProvider,
+		infer E extends EventSchemaConfig,
+		infer Q extends QueueSchemaConfig,
+		any
+	>
+		? WorkflowStepContext<S, CP, CS, V, I, DB, E, Q>
+		: never;