rivetkit 2.3.11-rc.9 → 2.3.11

package/src/registry/native.ts

@@ -15,6 +15,8 @@ import {
 	disposeRunInspector,
 	getRunFunction,
 	getRunInspectorConfig,
+	getRunInspectorKind,
+	hasRunInspectorConfig,
 	RAW_STATE_SYMBOL,
 	type ScheduledEventInfo,
 	type WorkflowInspectorConfig,
@@ -44,7 +46,15 @@ import {
 } from "@/client/client";
 import { convertRegistryConfigToClientConfig } from "@/client/config";
 import { HEADER_CONN_PARAMS } from "@/common/actor-router-consts";
-import type { AnyDatabaseProvider } from "@/common/database/config";
+import type {
+	AnyDatabaseProvider,
+	SqliteProfilingOptions,
+} from "@/common/database/config";
+import {
+	bindNativeStateTransactionContext,
+	db as defaultDb,
+	registerNativeStateTransactionOpener,
+} from "@/common/database/mod";
 import { wrapJsNativeDatabase } from "@/common/database/native-database";
 import { assertJsonCompatValue, type JsonCompatValue } from "@/common/encoding";
 import { isResponseLike, type ResponseLike } from "@/common/fetch-like";
@@ -83,6 +93,7 @@ import {
 	validateQueueBody,
 	validateQueueComplete,
 } from "./native-validation";
+import { RunHandlerCoordinator } from "./run-handler-coordinator";
 import type {
 	ActorContextHandle,
 	ActorFactoryHandle,
@@ -129,10 +140,14 @@ type NativeOnStateChangeHandler = (
 ) => void | Promise<void>;
 type NativePersistConnState = {
 	state: unknown;
-	// Memoized deep write-through proxy and the state object it wraps. Rebuilt
-	// only when the underlying state object identity changes.
-	stateProxy?: unknown;
-	stateProxyTarget?: unknown;
+};
+
+type NativeStateTransactionScope = {
+	actorContext: ActorContextHandleAdapter;
+	actorStateBaseline: unknown;
+	connectionStateBaselines: Map<string, Uint8Array>;
+	committed: boolean;
+	release: () => void;
 };
 
 const defaultRuntimeLoaders: RuntimeLoaders = {
@@ -278,14 +293,14 @@ type NativePersistActorState = {
 	state: unknown;
 	isInOnStateChange: boolean;
 	connStates: Map<string, NativePersistConnState>;
-	// Memoized deep write-through proxy and the state object it wraps. Rebuilt
-	// only when the underlying state object identity changes.
-	stateProxy?: unknown;
-	stateProxyTarget?: unknown;
 	// Set when a coalesced save and onStateChange flush is pending for the
 	// current event loop tick.
 	saveScheduled?: boolean;
 	pendingSaveHandle?: ReturnType<typeof setImmediate>;
+	activeStateTransactionOwner?: symbol;
+	pendingStateTransactionOwners?: Set<symbol>;
+	stateTransactionTail?: Promise<void>;
+	stateTransactionSaveDeferred?: boolean;
 };
 type NativeDestroyGate = {
 	destroyCompletion?: Promise<void>;
@@ -371,6 +386,15 @@ function stateMutationReentrantError(): RivetError {
 	);
 }
 
+function stateTransactionConflictError(): RivetError {
+	return new RivetError(
+		"actor",
+		"state_transaction_conflict",
+		"State cannot be mutated by another action while an experimental state-aware database transaction is active.",
+		{ public: true, statusCode: 409 },
+	);
+}
+
 function databaseNotConfiguredError(): RivetError {
 	return new RivetError(
 		"actor",
@@ -388,6 +412,14 @@ function databaseClientNotReadyError(): RivetError {
 		{ public: true },
 	);
 }
+function runHandlerNotConfiguredError(): RivetError {
+	return new RivetError(
+		"actor",
+		"run_handler_unavailable",
+		"Cannot schedule a run wake because this actor does not define a run handler.",
+		{ public: true, statusCode: 409 },
+	);
+}
 
 function stateNotEnabledError(): RivetError {
 	return new RivetError(
@@ -540,10 +572,11 @@ function getOrCreateNativeSqlDatabase(
 		execute: (sql, params) => runtime.actorSqlExecute(ctx, sql, params),
 		executeBatch: (statements) =>
 			runtime.actorSqlExecuteBatch(ctx, statements),
-		beginTransaction: async (timeoutMs) => {
+		beginTransaction: async (timeoutMs, name) => {
 			const transaction = await runtime.actorSqlBeginTransaction(
 				ctx,
 				timeoutMs,
+				name,
 			);
 			return {
 				exec: (sql) =>
@@ -559,6 +592,40 @@ function getOrCreateNativeSqlDatabase(
 					runtime.actorSqlTransactionRollback(transaction),
 			};
 		},
+		beginStateTransaction: async (timeoutMs, context) => {
+			const scope = context as NativeStateTransactionScope | undefined;
+			if (!scope) {
+				throw new Error(
+					"actor state transaction context is not configured",
+				);
+			}
+			const transaction = await runtime.actorBeginStateTransaction(
+				ctx,
+				timeoutMs,
+			);
+			return {
+				exec: async () => {
+					throw new Error(
+						"actor state transactions only support single-statement execute calls",
+					);
+				},
+				execute: (sql, params) =>
+					runtime.actorStateTransactionExecute(
+						transaction,
+						sql,
+						params,
+					),
+				commit: async () => {
+					await runtime.actorStateTransactionCommit(
+						transaction,
+						scope.actorContext.serializeForTick("save"),
+					);
+					scope.committed = true;
+				},
+				rollback: () =>
+					runtime.actorStateTransactionRollback(transaction),
+			};
+		},
 		query: (sql, params) => runtime.actorSqlQuery(ctx, sql, params),
 		run: (sql, params) => runtime.actorSqlRun(ctx, sql, params),
 		metrics: () => runtime.actorSqlMetrics(ctx),
@@ -1234,6 +1301,9 @@ class NativeConnAdapter {
 	#schemas: NativeValidationConfig;
 	#ctx?: ActorContextHandle;
 	#queueHibernationRemoval?: (connId: string) => void;
+	#assertCanMutateState?: () => void;
+	#stateProxy?: unknown;
+	#stateProxyTarget?: unknown;
 
 	constructor(
 		runtime: CoreRuntime,
@@ -1241,12 +1311,14 @@ class NativeConnAdapter {
 		schemas: NativeValidationConfig = {},
 		ctx?: ActorContextHandle,
 		queueHibernationRemoval?: (connId: string) => void,
+		assertCanMutateState?: () => void,
 	) {
 		this.#runtime = runtime;
 		this.#conn = conn;
 		this.#schemas = schemas;
 		this.#ctx = ctx;
 		this.#queueHibernationRemoval = queueHibernationRemoval;
+		this.#assertCanMutateState = assertCanMutateState;
 		(
 			this as NativeConnAdapter & {
 				[CONN_STATE_MANAGER_SYMBOL]?: unknown;
@@ -1285,34 +1357,38 @@ class NativeConnAdapter {
 		// allocates fresh on-change caches and rewraps the whole tree. Memoize
 		// the proxy keyed on the underlying state object so repeated reads and
 		// deep read cascades reuse a single proxy.
-		const connState = getNativeConnPersistState(
-			this.#runtime,
-			this.#ctx,
-			this.#conn,
-		);
 		if (
-			connState.stateProxy === undefined ||
-			connState.stateProxyTarget !== nextState
+			this.#stateProxy === undefined ||
+			this.#stateProxyTarget !== nextState
 		) {
-			connState.stateProxyTarget = nextState;
-			connState.stateProxy = this.#createStateProxy(nextState);
+			this.#stateProxyTarget = nextState;
+			this.#stateProxy = this.#createStateProxy(nextState);
 		}
-		return connState.stateProxy;
+		return this.#stateProxy;
 	}
 
 	#createStateProxy(state: unknown): unknown {
+		const assertCurrentState = () => {
+			this.#assertCanMutateState?.();
+			if (this.#ctx && this.#readState() !== state) {
+				throw stateTransactionConflictError();
+			}
+		};
 		return createWriteThroughProxy(
 			state,
 			(nextValue) => {
+				assertCurrentState();
 				this.#writeState(nextValue, { writeNative: true });
 			},
 			(newValue) => {
+				assertCurrentState();
 				assertJsonCompatValue(newValue);
 			},
 		);
 	}
 
 	set state(value: unknown) {
+		this.#assertCanMutateState?.();
 		const nextValue = unwrapWriteThroughProxy(value);
 		assertJsonCompatValue(nextValue);
 		this.#writeState(nextValue, { writeNative: true });
@@ -1734,8 +1810,9 @@ function wrapQueueMessage(
 	schemas: NativeValidationConfig["queues"],
 ) {
 	const name = callNativeSync(() => message.name());
+	const id = callNativeSync(() => message.id());
 	return {
-		id: Number(callNativeSync(() => message.id())),
+		id: id <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(id) : id,
 		name,
 		body: validateQueueBody(
 			schemas,
@@ -1919,6 +1996,32 @@ class NativeQueueAdapter {
 			cleanup?.();
 		}
 	}
+	async waitForAvailable(
+		names?: readonly string[],
+		options?: { timeout?: number; signal?: AbortSignal },
+	): Promise<void> {
+		await this.waitForNamesAvailable(names ?? [], options);
+	}
+
+	async complete(
+		message: { id: number | bigint; name: string },
+		response?: unknown,
+	): Promise<void> {
+		const validatedResponse = validateQueueComplete(
+			this.#schemas,
+			message.name,
+			response,
+		);
+		await callNative(() =>
+			this.#runtime.actorQueueCompletePersisted(
+				this.#ctx,
+				BigInt(message.id),
+				message.name,
+				encodeValue(validatedResponse),
+			),
+		);
+		this.#pendingCompletableMessageIds.delete(message.id.toString());
+	}
 
 	async enqueueAndWait(
 		name: string,
@@ -2498,15 +2601,18 @@ class NativeConnectionMap implements ReadonlyMap<string, NativeConnAdapter> {
 	#runtime: CoreRuntime;
 	#ctx: ActorContextHandle;
 	#schemas: NativeValidationConfig;
+	#assertCanMutateState: () => void;
 
 	constructor(
 		runtime: CoreRuntime,
 		ctx: ActorContextHandle,
 		schemas: NativeValidationConfig,
+		assertCanMutateState: () => void,
 	) {
 		this.#runtime = runtime;
 		this.#ctx = ctx;
 		this.#schemas = schemas;
+		this.#assertCanMutateState = assertCanMutateState;
 	}
 
 	#connToAdapter(conn: ConnHandle): NativeConnAdapter {
@@ -2522,6 +2628,7 @@ class NativeConnectionMap implements ReadonlyMap<string, NativeConnAdapter> {
 						connId,
 					),
 				),
+			this.#assertCanMutateState,
 		);
 	}
 
@@ -2609,10 +2716,13 @@ export class ActorContextHandleAdapter {
 	#queue?: NativeQueueAdapter;
 	#request?: Request;
 	#schedule?: NativeScheduleAdapter;
-	#sql?: ReturnType<typeof wrapJsNativeDatabase>;
-	#runHandlerActiveProvider?: () => boolean;
+	#run?: { setWakeAt(timestamp: number | null): Promise<void> };
+	#runHandlerConfigured: boolean;
 	#onStateChange?: NativeOnStateChangeHandler;
 	#stateEnabled: boolean;
+	#stateProxy?: unknown;
+	#stateProxyTarget?: unknown;
+	readonly #stateTransactionOwner = Symbol("actor-state-transaction-owner");
 
 	constructor(
 		runtime: CoreRuntime,
@@ -2622,16 +2732,16 @@ export class ActorContextHandleAdapter {
 		databaseProvider?: AnyDatabaseProvider,
 		request?: Request,
 		stateEnabled = true,
-		runHandlerActiveProvider?: () => boolean,
 		onStateChange?: NativeOnStateChangeHandler,
 		dispatchCancelToken?: CancellationTokenHandle,
+		runHandlerConfigured = false,
 	) {
 		this.#runtime = runtime;
 		this.#ctx = ctx;
 		this.#clientFactory = clientFactory;
 		this.#schemas = schemas;
 		this.#dispatchCancelToken = dispatchCancelToken;
-		this.#runHandlerActiveProvider = runHandlerActiveProvider;
+		this.#runHandlerConfigured = runHandlerConfigured;
 		this.#onStateChange = onStateChange;
 		this.#stateEnabled = stateEnabled;
 		if (databaseProvider) {
@@ -2654,13 +2764,6 @@ export class ActorContextHandleAdapter {
 		return this.#kv;
 	}
 
-	get sql() {
-		if (!this.#sql) {
-			this.#sql = getOrCreateNativeSqlDatabase(this.#runtime, this.#ctx);
-		}
-		return this.#sql;
-	}
-
 	async actorRuntimeSocket(): Promise<{ path: string }> {
 		return await callNative(() =>
 			this.#runtime.actorRuntimeSocketProvision(this.#ctx),
@@ -2679,7 +2782,7 @@ export class ActorContextHandleAdapter {
 		const runtimeState = getNativeRuntimeState(this.#runtime, this.#ctx);
 		const cachedClient = runtimeState.databaseClient;
 		if (cachedClient) {
-			this.#db = cachedClient.client;
+			this.#db = this.#bindDatabaseClient(cachedClient.client);
 			return this.#db;
 		}
 
@@ -2697,29 +2800,35 @@ export class ActorContextHandleAdapter {
 		if (!this.#stateEnabled) {
 			throw stateNotEnabledError();
 		}
-		const actorState = getNativePersistState(this.#runtime, this.#ctx);
 		const nextState = this.#readState();
 		// Reading `c.state` rebuilds the deep write-through proxy, which
 		// allocates fresh on-change caches and rewraps the whole tree. Memoize
 		// the proxy keyed on the underlying state object so repeated reads and
 		// deep read cascades reuse a single proxy.
 		if (
-			actorState.stateProxy === undefined ||
-			actorState.stateProxyTarget !== nextState
+			this.#stateProxy === undefined ||
+			this.#stateProxyTarget !== nextState
 		) {
-			actorState.stateProxyTarget = nextState;
-			actorState.stateProxy = createWriteThroughProxy(
+			const assertCurrentState = () => {
+				this.#assertCanMutateState();
+				if (this.#readState() !== nextState) {
+					throw stateTransactionConflictError();
+				}
+			};
+			this.#stateProxyTarget = nextState;
+			this.#stateProxy = createWriteThroughProxy(
 				nextState,
 				(nextValue) => {
+					assertCurrentState();
 					this.#writeState(nextValue, { scheduleSave: true });
 				},
 				(newValue) => {
-					this.#assertCanMutateState();
+					assertCurrentState();
 					assertJsonCompatValue(newValue);
 				},
 			);
 		}
-		return actorState.stateProxy;
+		return this.#stateProxy;
 	}
 
 	set state(value: unknown) {
@@ -2769,6 +2878,30 @@ export class ActorContextHandleAdapter {
 		return this.#queue;
 	}
 
+	get run() {
+		if (!this.#run) {
+			this.#run = {
+				setWakeAt: async (timestamp: number | null) => {
+					if (timestamp !== null && !this.#runHandlerConfigured) {
+						throw runHandlerNotConfiguredError();
+					}
+					if (
+						timestamp !== null &&
+						(!Number.isSafeInteger(timestamp) || timestamp < 0)
+					) {
+						throw new TypeError(
+							"Run wake timestamp must be a non-negative safe integer or null",
+						);
+					}
+					await callNative(() =>
+						this.#runtime.actorSetRunWakeAt(this.#ctx, timestamp),
+					);
+				},
+			};
+		}
+		return this.#run;
+	}
+
 	get schedule(): NativeScheduleAdapter {
 		if (!this.#schedule) {
 			this.#schedule = new NativeScheduleAdapter(
@@ -2810,6 +2943,7 @@ export class ActorContextHandleAdapter {
 				this.#runtime,
 				this.#ctx,
 				this.#schemas,
+				() => this.#assertCanMutateState(),
 			);
 		}
 		return this.#connMap;
@@ -2890,12 +3024,12 @@ export class ActorContextHandleAdapter {
 		const runtimeState = getNativeRuntimeState(this.#runtime, this.#ctx);
 		const cachedClient = runtimeState.databaseClient;
 		if (cachedClient) {
-			this.#db = cachedClient.client;
+			this.#db = this.#bindDatabaseClient(cachedClient.client);
 			return this.#db;
 		}
 
 		const actorId = this.actorId;
-		const client = await this.#databaseProvider.createClient({
+		const createdClient = await this.#databaseProvider.createClient({
 			actorId,
 			kv: {
 				batchPut: async (entries) => {
@@ -2916,21 +3050,147 @@ export class ActorContextHandleAdapter {
 			log: {
 				debug: (obj) => logger().debug(obj),
 			},
-			nativeDatabaseProvider: {
-				open: async (requestedActorId) => {
-					void requestedActorId;
-					return getOrCreateNativeSqlDatabase(
+			nativeDatabaseProvider: registerNativeStateTransactionOpener(
+				{
+					open: async (requestedActorId) => {
+						void requestedActorId;
+						return getOrCreateNativeSqlDatabase(
+							this.#runtime,
+							this.#ctx,
+						);
+					},
+				},
+				async (timeoutMs, context) =>
+					await getOrCreateNativeSqlDatabase(
 						this.#runtime,
 						this.#ctx,
-					);
-				},
-			},
+					).beginStateTransaction(timeoutMs, context),
+			),
 		});
 		runtimeState.databaseClient = {
-			client,
+			client: createdClient,
 		};
-		this.#db = client;
-		return client;
+		this.#db = this.#bindDatabaseClient(createdClient);
+		return this.#db;
+	}
+
+	#bindDatabaseClient(client: unknown): unknown {
+		return bindNativeStateTransactionContext(client, {
+			enter: async () => await this.#enterStateTransaction(),
+			exit: (scope) =>
+				this.#exitStateTransaction(
+					scope as NativeStateTransactionScope,
+				),
+		});
+	}
+
+	async #enterStateTransaction(): Promise<NativeStateTransactionScope> {
+		const actorState = getNativePersistState(this.#runtime, this.#ctx);
+		let pendingOwners = actorState.pendingStateTransactionOwners;
+		if (!pendingOwners) {
+			pendingOwners = new Set();
+			actorState.pendingStateTransactionOwners = pendingOwners;
+		}
+		if (
+			actorState.activeStateTransactionOwner ===
+				this.#stateTransactionOwner ||
+			pendingOwners.has(this.#stateTransactionOwner)
+		) {
+			throw stateTransactionConflictError();
+		}
+		pendingOwners.add(this.#stateTransactionOwner);
+		const predecessor =
+			actorState.stateTransactionTail ?? Promise.resolve();
+		let release!: () => void;
+		const hold = new Promise<void>((resolve) => {
+			release = resolve;
+		});
+		actorState.stateTransactionTail = predecessor.then(
+			async () => await hold,
+		);
+		try {
+			await predecessor;
+			pendingOwners.delete(this.#stateTransactionOwner);
+			actorState.activeStateTransactionOwner =
+				this.#stateTransactionOwner;
+			return {
+				actorContext: this,
+				actorStateBaseline: this.#stateEnabled
+					? structuredClone(this.#readState())
+					: undefined,
+				connectionStateBaselines: new Map(
+					callNativeSync(() =>
+						this.#runtime.actorConns(this.#ctx),
+					).map((conn) => [
+						callNativeSync(() => this.#runtime.connId(conn)),
+						new Uint8Array(
+							callNativeSync(() => this.#runtime.connState(conn)),
+						),
+					]),
+				),
+				committed: false,
+				release,
+			};
+		} catch (error) {
+			pendingOwners.delete(this.#stateTransactionOwner);
+			if (
+				actorState.activeStateTransactionOwner ===
+				this.#stateTransactionOwner
+			) {
+				actorState.activeStateTransactionOwner = undefined;
+			}
+			release();
+			throw error;
+		}
+	}
+
+	#exitStateTransaction(scope: NativeStateTransactionScope): void {
+		const actorState = getNativePersistState(this.#runtime, this.#ctx);
+		try {
+			if (!scope.committed) {
+				this.#restoreStateTransactionBaseline(scope);
+			}
+		} finally {
+			if (
+				actorState.activeStateTransactionOwner ===
+				this.#stateTransactionOwner
+			) {
+				actorState.activeStateTransactionOwner = undefined;
+			}
+			if (actorState.stateTransactionSaveDeferred) {
+				actorState.stateTransactionSaveDeferred = false;
+				this.#scheduleSave();
+			}
+			scope.release();
+		}
+	}
+
+	#restoreStateTransactionBaseline(scope: NativeStateTransactionScope): void {
+		const actorState = getNativePersistState(this.#runtime, this.#ctx);
+		if (actorState.pendingSaveHandle !== undefined) {
+			clearImmediate(actorState.pendingSaveHandle);
+		}
+		actorState.pendingSaveHandle = undefined;
+		actorState.saveScheduled = false;
+
+		if (this.#stateEnabled) {
+			actorState.state = structuredClone(scope.actorStateBaseline);
+		}
+		for (const conn of callNativeSync(() =>
+			this.#runtime.actorConns(this.#ctx),
+		)) {
+			const connId = callNativeSync(() => this.#runtime.connId(conn));
+			const baseline = scope.connectionStateBaselines.get(connId);
+			if (baseline === undefined) {
+				continue;
+			}
+			callNativeSync(() => this.#runtime.connSetState(conn, baseline));
+			const cached = actorState.connStates.get(connId);
+			if (cached) {
+				cached.state = decodeValue(baseline);
+			}
+		}
+		this.#scheduleSave();
 	}
 
 	async prepare(): Promise<void> {
@@ -2953,7 +3213,6 @@ export class ActorContextHandleAdapter {
 
 	async closeDatabase(): Promise<void> {
 		this.#db = undefined;
-		this.#sql = undefined;
 		await closeNativeDatabaseClient(this.#runtime, this.#ctx);
 		await closeNativeSqlDatabase(this.#runtime, this.#ctx);
 	}
@@ -2978,6 +3237,7 @@ export class ActorContextHandleAdapter {
 		maxWait?: number;
 	}): Promise<void> {
 		if (opts?.immediate) {
+			this.#assertCanAwaitStateSave();
 			await callNative(() =>
 				this.#runtime.actorRequestSaveAndWait(this.#ctx, {
 					immediate: true,
@@ -3003,11 +3263,22 @@ export class ActorContextHandleAdapter {
 	async saveStateAndWorkflowBatch(
 		writes: Array<{ key: Uint8Array; value: Uint8Array }>,
 	): Promise<void> {
+		this.#assertCanAwaitStateSave();
 		await callNative(() =>
 			this.#runtime.actorSaveStateAndWorkflowBatch(this.#ctx, writes),
 		);
 	}
 
+	#assertCanAwaitStateSave(): void {
+		const actorState = getNativePersistState(this.#runtime, this.#ctx);
+		if (
+			actorState.activeStateTransactionOwner ===
+			this.#stateTransactionOwner
+		) {
+			throw stateTransactionConflictError();
+		}
+	}
+
 	serializeForTick(reason: SerializeStateReason): RuntimeStateDeltaPayload {
 		void reason;
 		const actorState = getNativePersistState(this.#runtime, this.#ctx);
@@ -3071,10 +3342,6 @@ export class ActorContextHandleAdapter {
 		return promise;
 	}
 
-	runHandlerActive(): boolean {
-		return this.#runHandlerActiveProvider?.() ?? false;
-	}
-
 	internalKeepAwake<T>(run: Promise<T> | (() => Promise<T>)): Promise<T> {
 		const promise = typeof run === "function" ? run() : run;
 		// Track only completion, swallowing the outcome. The real result/error
@@ -3175,7 +3442,6 @@ export class ActorContextHandleAdapter {
 		// down so the request-save and onStateChange always run.
 		this.#flushStateChange();
 		this.#abortSignalCleanup?.();
-		this.#sql = undefined;
 	}
 
 	#createActorAbortSignal(): AbortSignal {
@@ -3222,6 +3488,19 @@ export class ActorContextHandleAdapter {
 		if (actorState.isInOnStateChange) {
 			throw stateMutationReentrantError();
 		}
+		if (
+			actorState.activeStateTransactionOwner !==
+				this.#stateTransactionOwner &&
+			(actorState.activeStateTransactionOwner !== undefined ||
+				(actorState.pendingStateTransactionOwners?.size ?? 0) > 0)
+		) {
+			throw stateTransactionConflictError();
+		}
+	}
+
+	/** @internal */
+	assertCanMutateState(): void {
+		this.#assertCanMutateState();
 	}
 
 	// Coalesce the request-save and onStateChange work to once per event loop
@@ -3245,6 +3524,15 @@ export class ActorContextHandleAdapter {
 		if (!actorState.saveScheduled) {
 			return;
 		}
+		if (actorState.activeStateTransactionOwner !== undefined) {
+			actorState.saveScheduled = false;
+			if (actorState.pendingSaveHandle !== undefined) {
+				clearImmediate(actorState.pendingSaveHandle);
+				actorState.pendingSaveHandle = undefined;
+			}
+			actorState.stateTransactionSaveDeferred = true;
+			return;
+		}
 		actorState.saveScheduled = false;
 		if (actorState.pendingSaveHandle !== undefined) {
 			clearImmediate(actorState.pendingSaveHandle);
@@ -3446,10 +3734,6 @@ class NativeWorkflowRuntimeAdapter {
 		};
 	}
 
-	isRunHandlerActive(): boolean {
-		return this.#ctx.runHandlerActive();
-	}
-
 	async restartRunHandler(): Promise<void> {
 		await this.#ctx.restartRunHandler();
 	}
@@ -3497,28 +3781,33 @@ function withConnContext(
 	stateEnabled = true,
 	onStateChange?: NativeOnStateChangeHandler,
 	dispatchCancelToken?: CancellationTokenHandle,
+	runHandlerConfigured = false,
 ) {
-	return Object.assign(
-		new ActorContextHandleAdapter(
+	const actorContext = new ActorContextHandleAdapter(
+		runtime,
+		ctx,
+		clientFactory,
+		schemas,
+		databaseProvider,
+		request,
+		stateEnabled,
+		onStateChange,
+		dispatchCancelToken,
+		runHandlerConfigured,
+	);
+	return Object.assign(actorContext, {
+		conn: new NativeConnAdapter(
 			runtime,
-			ctx,
-			clientFactory,
+			conn,
 			schemas,
-			databaseProvider,
-			request,
-			stateEnabled,
-			undefined,
-			onStateChange,
-			dispatchCancelToken,
-		),
-		{
-			conn: new NativeConnAdapter(runtime, conn, schemas, ctx, (connId) =>
+			ctx,
+			(connId) =>
 				callNativeSync(() =>
 					runtime.actorQueueHibernationRemoval(ctx, connId),
 				),
-			),
-		},
-	);
+			() => actorContext.assertCanMutateState(),
+		),
+	});
 }
 
 function buildActorConfig(
@@ -3531,12 +3820,16 @@ function buildActorConfig(
 	const canHibernate = options.canHibernateWebSocket;
 	const usesRemoteSqlite =
 		sqliteBackendForConfig(registryConfig) === "remote";
+	const sqliteProfiling = (
+		config.db as { sqliteProfiling?: SqliteProfilingOptions } | undefined
+	)?.sqliteProfiling;
 
 	return {
 		name: options.name as string | undefined,
 		icon: options.icon as string | undefined,
-		hasDatabase: config.db !== undefined || usesRemoteSqlite,
+		hasDatabase: true,
 		remoteSqlite: usesRemoteSqlite,
+		sqliteProfiling,
 		enableActorRuntimeSocket: options.enableActorRuntimeSocket === true,
 		hasState:
 			config.state !== undefined ||
@@ -3681,7 +3974,10 @@ export function buildNativeFactory(
 	definition: AnyActorDefinition,
 ): ActorFactoryHandle {
 	const config = definition.config as Record<string, any>;
-	const databaseProvider = config.db as AnyDatabaseProvider;
+	const databaseProvider = (config.db ?? defaultDb()) as Exclude<
+		AnyDatabaseProvider,
+		undefined
+	>;
 	const actionHandlers = flattenActionHandlers(config.actions);
 	const schemaConfig: NativeValidationConfig = {
 		actionInputSchemas: flattenActionInputSchemas(
@@ -3699,16 +3995,21 @@ export function buildNativeFactory(
 			),
 			{ encoding: "bare" },
 		);
-	const nativeRunHandlerActiveByActorId = new Map<string, boolean>();
-	const isNativeRunHandlerActive = (ctx: ActorContextHandle) =>
-		nativeRunHandlerActiveByActorId.get(
-			callNativeSync(() => runtime.actorId(ctx)),
-		) ?? false;
-	const getNativeWorkflowInspector = (ctx: ActorContextHandle) =>
-		getRunInspectorConfig(
-			config.run,
-			callNativeSync(() => runtime.actorId(ctx)),
-		)?.workflow as NativeWorkflowInspectorConfig | undefined;
+	const run = getRunFunction(config.run);
+	const runHandlerCoordinator =
+		getRunInspectorKind(config.run) === "workflow"
+			? new RunHandlerCoordinator(config.run)
+			: undefined;
+	const getNativeWorkflowInspector = (ctx: ActorContextHandle) => {
+		const actorId = callNativeSync(() => runtime.actorId(ctx));
+		const restart = () =>
+			callNativeSync(() => runtime.actorRestartRunHandler(ctx));
+		return (runHandlerCoordinator?.getInspector(actorId, restart)
+			?.workflow ??
+			getRunInspectorConfig(config.run, actorId)?.workflow) as
+			| NativeWorkflowInspectorConfig
+			| undefined;
+	};
 	const onStateChange =
 		typeof config.onStateChange === "function"
 			? (actorCtx: ActorContextHandleAdapter, nextState: unknown) => {
@@ -3741,9 +4042,9 @@ export function buildNativeFactory(
 			databaseProvider,
 			request,
 			stateEnabled,
-			() => isNativeRunHandlerActive(ctx),
 			onStateChange,
 			cancelToken,
+			run !== undefined,
 		);
 	const makeConnCtx = (
 		ctx: ActorContextHandle,
@@ -3762,6 +4063,7 @@ export function buildNativeFactory(
 			stateEnabled,
 			onStateChange,
 			cancelToken,
+			run !== undefined,
 		);
 	const maybeHandleNativeInspectorRequest = async (
 		ctx: ActorContextHandle,
@@ -3830,6 +4132,7 @@ export function buildNativeFactory(
 		const workflowState = async () =>
 			(await getNativeWorkflowInspector(ctx)?.getState?.()) ?? null;
 		const actorCtx = makeActorCtx(ctx, jsRequest);
+		const sql = getOrCreateNativeSqlDatabase(runtime, ctx);
 		try {
 			if (
 				url.pathname === "/inspector/state" &&
@@ -4001,7 +4304,7 @@ export function buildNativeFactory(
 				url.pathname === "/inspector/database/schema" &&
 				jsRequest.method === "GET"
 			) {
-				const db = actorCtx.sql;
+				const db = sql;
 				const tables = queryRows(
 					await db.query(
 						"SELECT name, type FROM sqlite_master WHERE type IN ('table', 'view') AND name NOT LIKE 'sqlite_%' AND name NOT LIKE '__drizzle_%' ORDER BY name",
@@ -4055,7 +4358,7 @@ export function buildNativeFactory(
 				);
 				const quoted = `"${table.replace(/"/g, '""')}"`;
 				const rows = queryRows(
-					await actorCtx.sql.query(
+					await sql.query(
 						`SELECT * FROM ${quoted} LIMIT ? OFFSET ?`,
 						[
 							Math.max(0, Math.min(limit, 500)),
@@ -4098,15 +4401,11 @@ export function buildNativeFactory(
 					const bindings = normalizeSqlitePropertyBindings(
 						body.properties as Record<string, unknown>,
 					);
-					const rows = queryRows(
-						await actorCtx.sql.query(body.sql, bindings),
-					);
+					const rows = queryRows(await sql.query(body.sql, bindings));
 					return jsonResponse({ rows: jsonSafe(rows) });
 				}
 				const args = Array.isArray(body.args) ? body.args : [];
-				const rows = queryRows(
-					await actorCtx.sql.query(body.sql, args),
-				);
+				const rows = queryRows(await sql.query(body.sql, args));
 				return jsonResponse({ rows: jsonSafe(rows) });
 			}
 			if (
@@ -4135,7 +4434,7 @@ export function buildNativeFactory(
 					rpcs: Object.keys(actionHandlers).sort(),
 					queueSize: inspectorSnapshot.queueSize,
 					isStateEnabled: stateEnabled,
-					isDatabaseEnabled: databaseProvider !== undefined,
+					isDatabaseEnabled: true,
 					isWorkflowEnabled:
 						getNativeWorkflowInspector(ctx) !== undefined,
 					workflowState: await workflowState(),
@@ -4391,6 +4690,7 @@ export function buildNativeFactory(
 			async (error: unknown, payload: { ctx: ActorContextHandle }) => {
 				const { ctx } = unwrapTsfnPayload(error, payload);
 				const actorCtx = makeActorCtx(ctx);
+				const actorId = callNativeSync(() => runtime.actorId(ctx));
 				// TODO: Move this save hook into cleanupNativeSleepRuntimeState
 				// so immediate and deferred sleep cleanup share one save-state
 				// path instead of passing a callback through cleanup.
@@ -4421,6 +4721,8 @@ export function buildNativeFactory(
 							saveActorState,
 						);
 					} finally {
+						runHandlerCoordinator?.destroy(actorId);
+						disposeRunInspector(config.run, actorId);
 						await actorCtx.dispose();
 					}
 				}
@@ -4430,16 +4732,16 @@ export function buildNativeFactory(
 			async (error: unknown, payload: { ctx: ActorContextHandle }) => {
 				const { ctx } = unwrapTsfnPayload(error, payload);
 				const actorCtx = makeActorCtx(ctx);
+				const actorId = callNativeSync(() => runtime.actorId(ctx));
+				// Close run control before user cleanup so replay cannot race actor
+				// destruction. Recreating this actor id receives a fresh controller.
+				runHandlerCoordinator?.destroy(actorId);
+				disposeRunInspector(config.run, actorId);
 				try {
 					if (typeof config.onDestroy === "function") {
 						await config.onDestroy(actorCtx);
 					}
 				} finally {
-					const actorId = callNativeSync(() => runtime.actorId(ctx));
-					// Release actorId-keyed state so it does not accumulate per
-					// destroyed actor.
-					nativeRunHandlerActiveByActorId.delete(actorId);
-					disposeRunInspector(config.run, actorId);
 					resolveNativeDestroy(runtime, ctx);
 					await actorCtx.closeDatabase();
 					clearNativeRuntimeState(runtime, ctx);
@@ -4520,6 +4822,7 @@ export function buildNativeFactory(
 											connId,
 										),
 									),
+								() => actorCtx.assertCanMutateState(),
 							);
 							try {
 								const nextConnState = hasStaticConnState
@@ -4575,6 +4878,7 @@ export function buildNativeFactory(
 											connId,
 										),
 									),
+								() => actorCtx.assertCanMutateState(),
 							);
 							try {
 								await config.onConnect(
@@ -4618,6 +4922,7 @@ export function buildNativeFactory(
 													connId,
 												),
 											),
+										() => actorCtx.assertCanMutateState(),
 									),
 								);
 							}
@@ -4826,7 +5131,6 @@ export function buildNativeFactory(
 					)
 				: undefined,
 		run: (() => {
-			const run = getRunFunction(config.run);
 			if (!run) {
 				return undefined;
 			}
@@ -4838,67 +5142,75 @@ export function buildNativeFactory(
 				) => {
 					const { ctx } = unwrapTsfnPayload(error, payload);
 					const actorId = callNativeSync(() => runtime.actorId(ctx));
-					const actorCtx = makeActorCtx(ctx);
-					nativeRunHandlerActiveByActorId.set(actorId, true);
-					try {
-						await run(actorCtx);
-					} finally {
-						// Delete rather than set(false): an absent entry already
-						// reads as inactive, and deleting keeps this map bounded
-						// to currently-running handlers instead of accumulating an
-						// entry per actor id forever.
-						nativeRunHandlerActiveByActorId.delete(actorId);
-						await actorCtx.dispose();
+					const executeRun = async () => {
+						const actorCtx = makeActorCtx(ctx);
+						try {
+							await run(actorCtx);
+						} finally {
+							await actorCtx.dispose();
+						}
+					};
+					if (runHandlerCoordinator) {
+						const outcome = await runHandlerCoordinator.run(
+							actorId,
+							() =>
+								callNativeSync(() =>
+									runtime.actorRestartRunHandler(ctx),
+								),
+							executeRun,
+						);
+						// Only a start suppressed behind a failed replay must preserve a
+						// consumed durable wake. Closed actors must remain closed.
+						return outcome !== "suppressed";
 					}
+					await executeRun();
+					return true;
 				},
 			);
 		})(),
-		getWorkflowHistory:
-			getRunInspectorConfig(config.run) !== undefined
-				? wrapNativeCallback(
-						async (
-							error: unknown,
-							payload: { ctx: ActorContextHandle },
-						) => {
-							const { ctx } = unwrapTsfnPayload(error, payload);
-							const history =
-								getNativeWorkflowInspector(ctx)?.getHistory();
-							return history == null
-								? undefined
-								: toUint8Array(history);
+		getWorkflowHistory: hasRunInspectorConfig(config.run)
+			? wrapNativeCallback(
+					async (
+						error: unknown,
+						payload: { ctx: ActorContextHandle },
+					) => {
+						const { ctx } = unwrapTsfnPayload(error, payload);
+						const history =
+							getNativeWorkflowInspector(ctx)?.getHistory();
+						return history == null
+							? undefined
+							: toUint8Array(history);
+					},
+				)
+			: undefined,
+		replayWorkflow: hasRunInspectorConfig(config.run)
+			? wrapNativeCallback(
+					async (
+						error: unknown,
+						payload: {
+							ctx: ActorContextHandle;
+							entryId?: string;
 						},
-					)
-				: undefined,
-		replayWorkflow:
-			getRunInspectorConfig(config.run) !== undefined
-				? wrapNativeCallback(
-						async (
-							error: unknown,
-							payload: {
-								ctx: ActorContextHandle;
-								entryId?: string;
-							},
-						) => {
-							const { ctx, entryId } = unwrapTsfnPayload(
-								error,
-								payload,
-							);
-							const workflowInspector =
-								getNativeWorkflowInspector(ctx);
-							if (!workflowInspector?.replayFromStep) {
-								return undefined;
-							}
+					) => {
+						const { ctx, entryId } = unwrapTsfnPayload(
+							error,
+							payload,
+						);
+						const workflowInspector =
+							getNativeWorkflowInspector(ctx);
+						if (!workflowInspector?.replayFromStep) {
+							return undefined;
+						}
 
-							const history =
-								(await workflowInspector.replayFromStep(
-									entryId,
-								)) ?? null;
-							return history == null
-								? undefined
-								: toUint8Array(history);
-						},
-					)
-				: undefined,
+						const history =
+							(await workflowInspector.replayFromStep(entryId)) ??
+							null;
+						return history == null
+							? undefined
+							: toUint8Array(history);
+					},
+				)
+			: undefined,
 		actions: Object.fromEntries(
 			Object.entries(actionHandlers).map(([name, handler]) => [
 				name,
@@ -4980,6 +5292,7 @@ export function buildNativeFactory(
 					stateEnabled,
 					onStateChange,
 					cancelToken,
+					run !== undefined,
 				);
 				try {
 					if (