@rivetkit/workflow-engine 2.3.0-rc.1 → 2.3.0-rc.11

package/dist/tsup/index.d.cts

@@ -345,6 +345,8 @@ interface StepConfig<T> {
     retryBackoffMax?: number;
     /** Timeout in ms for step execution (default: 30000). Set to 0 to disable. */
     timeout?: number;
+    /** If true, step timeouts retry like any other error instead of failing immediately as critical. Default: false. */
+    retryOnTimeout?: boolean;
 }
 type TryStepCatchKind = "critical" | "timeout" | "exhausted" | "rollback";
 interface TryStepFailure {
@@ -398,7 +400,7 @@ type LoopResult<S, T> = {
  * Stateless loops (state = undefined) may return void/undefined, which is treated as
  * `Loop.continue(undefined)`.
  */
-type LoopIterationResult<S, T> = Promise<LoopResult<S, T> | (S extends undefined ? void : never)>;
+type LoopIterationResult<S, T> = Promise<LoopResult<S, T> | (S extends undefined ? undefined : never)>;
 /**
  * Configuration for a loop.
  */
@@ -410,6 +412,12 @@ interface LoopConfig<S, T> {
     historyPruneInterval?: number;
     /** Number of past iterations to retain when pruning. Defaults to historyPruneInterval. */
     historySize?: number;
+    /** @deprecated Use historyPruneInterval. */
+    commitInterval?: number;
+    /** @deprecated Use historyPruneInterval. */
+    historyEvery?: number;
+    /** @deprecated Use historySize. */
+    historyKeep?: number;
 }
 /**
  * Configuration for a branch in join/race.
@@ -707,7 +715,9 @@ declare class WorkflowContextImpl implements WorkflowContextInterface {
      *
      * Note: This does NOT cancel the underlying operation. JavaScript Promises
      * cannot be cancelled once started. When a timeout occurs:
-     * - The step is marked as failed with StepTimeoutError
+     * - The step is rejected with StepTimeoutError. By default this is treated
+     *   as a critical failure with no retry. Set retryOnTimeout: true on the
+     *   step config to retry timeouts like any other error.
      * - The underlying async operation continues running in the background
      * - Any side effects from the operation may still occur
      *
@@ -773,6 +783,11 @@ declare class WorkflowContextImpl implements WorkflowContextInterface {
     private executeRemoved;
 }
 
+/**
+ * Extract structured error information from an error.
+ */
+declare function extractErrorInfo(error: unknown): WorkflowError;
+
 /**
  * Thrown from steps to prevent retry.
  * Use this when an error is unrecoverable and retrying would be pointless.
@@ -877,11 +892,6 @@ declare class EntryInProgressError extends Error {
     constructor();
 }
 
-/**
- * Extract structured error information from an error.
- */
-declare function extractErrorInfo(error: unknown): WorkflowError;
-
 /**
  * Check if a path segment is a loop iteration marker.
  */

package/dist/tsup/index.d.ts

@@ -345,6 +345,8 @@ interface StepConfig<T> {
     retryBackoffMax?: number;
     /** Timeout in ms for step execution (default: 30000). Set to 0 to disable. */
     timeout?: number;
+    /** If true, step timeouts retry like any other error instead of failing immediately as critical. Default: false. */
+    retryOnTimeout?: boolean;
 }
 type TryStepCatchKind = "critical" | "timeout" | "exhausted" | "rollback";
 interface TryStepFailure {
@@ -398,7 +400,7 @@ type LoopResult<S, T> = {
  * Stateless loops (state = undefined) may return void/undefined, which is treated as
  * `Loop.continue(undefined)`.
  */
-type LoopIterationResult<S, T> = Promise<LoopResult<S, T> | (S extends undefined ? void : never)>;
+type LoopIterationResult<S, T> = Promise<LoopResult<S, T> | (S extends undefined ? undefined : never)>;
 /**
  * Configuration for a loop.
  */
@@ -410,6 +412,12 @@ interface LoopConfig<S, T> {
     historyPruneInterval?: number;
     /** Number of past iterations to retain when pruning. Defaults to historyPruneInterval. */
     historySize?: number;
+    /** @deprecated Use historyPruneInterval. */
+    commitInterval?: number;
+    /** @deprecated Use historyPruneInterval. */
+    historyEvery?: number;
+    /** @deprecated Use historySize. */
+    historyKeep?: number;
 }
 /**
  * Configuration for a branch in join/race.
@@ -707,7 +715,9 @@ declare class WorkflowContextImpl implements WorkflowContextInterface {
      *
      * Note: This does NOT cancel the underlying operation. JavaScript Promises
      * cannot be cancelled once started. When a timeout occurs:
-     * - The step is marked as failed with StepTimeoutError
+     * - The step is rejected with StepTimeoutError. By default this is treated
+     *   as a critical failure with no retry. Set retryOnTimeout: true on the
+     *   step config to retry timeouts like any other error.
      * - The underlying async operation continues running in the background
      * - Any side effects from the operation may still occur
      *
@@ -773,6 +783,11 @@ declare class WorkflowContextImpl implements WorkflowContextInterface {
     private executeRemoved;
 }
 
+/**
+ * Extract structured error information from an error.
+ */
+declare function extractErrorInfo(error: unknown): WorkflowError;
+
 /**
  * Thrown from steps to prevent retry.
  * Use this when an error is unrecoverable and retrying would be pointless.
@@ -877,11 +892,6 @@ declare class EntryInProgressError extends Error {
     constructor();
 }
 
-/**
- * Extract structured error information from an error.
- */
-declare function extractErrorInfo(error: unknown): WorkflowError;
-
 /**
  * Check if a path segment is a loop iteration marker.
  */

package/dist/tsup/index.js

@@ -43,7 +43,7 @@ import {
   resolveName,
   runWorkflow,
   setEntry
-} from "./chunk-UMFB2AR3.js";
+} from "./chunk-DFNXCZ47.js";
 export {
   CancelledError,
   CriticalError,

package/dist/tsup/testing.cjs

@@ -47,7 +47,7 @@
 
 
 
-var _chunk4SWXLWKLcjs = require('./chunk-4SWXLWKL.cjs');
+var _chunkU2W3KHJCcjs = require('./chunk-U2W3KHJC.cjs');
 
 // src/testing.ts
 var InMemoryWorkflowMessageDriver = class {
@@ -97,7 +97,7 @@ var InMemoryWorkflowMessageDriver = class {
   }
   async waitForMessages(messageNames, abortSignal) {
     if (abortSignal.aborted) {
-      throw new (0, _chunk4SWXLWKLcjs.EvictedError)();
+      throw new (0, _chunkU2W3KHJCcjs.EvictedError)();
     }
     const nameSet = messageNames.length > 0 ? new Set(messageNames) : void 0;
     if (this.#messages.some(
@@ -118,7 +118,7 @@ var InMemoryWorkflowMessageDriver = class {
         },
         abortSignal,
         onAbort: () => {
-          waiter.reject(new (0, _chunk4SWXLWKLcjs.EvictedError)());
+          waiter.reject(new (0, _chunkU2W3KHJCcjs.EvictedError)());
         }
       };
       abortSignal.addEventListener("abort", waiter.onAbort, {
@@ -158,56 +158,56 @@ var InMemoryDriver = (_class = class {constructor() { _class.prototype.__init.ca
   __init4() {this.workerPollInterval = 100}
   __init5() {this.messageDriver = this.#inMemoryMessageDriver}
   async get(key) {
-    await _chunk4SWXLWKLcjs.sleep.call(void 0, this.latency);
-    const entry = this.kv.get(_chunk4SWXLWKLcjs.keyToHex.call(void 0, key));
+    await _chunkU2W3KHJCcjs.sleep.call(void 0, this.latency);
+    const entry = this.kv.get(_chunkU2W3KHJCcjs.keyToHex.call(void 0, key));
     return _nullishCoalesce((entry == null ? void 0 : entry.value), () => ( null));
   }
   async set(key, value) {
-    await _chunk4SWXLWKLcjs.sleep.call(void 0, this.latency);
-    this.kv.set(_chunk4SWXLWKLcjs.keyToHex.call(void 0, key), { key, value });
+    await _chunkU2W3KHJCcjs.sleep.call(void 0, this.latency);
+    this.kv.set(_chunkU2W3KHJCcjs.keyToHex.call(void 0, key), { key, value });
   }
   async delete(key) {
-    await _chunk4SWXLWKLcjs.sleep.call(void 0, this.latency);
-    this.kv.delete(_chunk4SWXLWKLcjs.keyToHex.call(void 0, key));
+    await _chunkU2W3KHJCcjs.sleep.call(void 0, this.latency);
+    this.kv.delete(_chunkU2W3KHJCcjs.keyToHex.call(void 0, key));
   }
   async deletePrefix(prefix) {
-    await _chunk4SWXLWKLcjs.sleep.call(void 0, this.latency);
+    await _chunkU2W3KHJCcjs.sleep.call(void 0, this.latency);
     for (const [hexKey, entry] of this.kv) {
-      if (_chunk4SWXLWKLcjs.keyStartsWith.call(void 0, entry.key, prefix)) {
+      if (_chunkU2W3KHJCcjs.keyStartsWith.call(void 0, entry.key, prefix)) {
         this.kv.delete(hexKey);
       }
     }
   }
   async deleteRange(start, end) {
-    await _chunk4SWXLWKLcjs.sleep.call(void 0, this.latency);
+    await _chunkU2W3KHJCcjs.sleep.call(void 0, this.latency);
     for (const [hexKey, entry] of this.kv) {
-      if (_chunk4SWXLWKLcjs.compareKeys.call(void 0, entry.key, start) >= 0 && _chunk4SWXLWKLcjs.compareKeys.call(void 0, entry.key, end) < 0) {
+      if (_chunkU2W3KHJCcjs.compareKeys.call(void 0, entry.key, start) >= 0 && _chunkU2W3KHJCcjs.compareKeys.call(void 0, entry.key, end) < 0) {
         this.kv.delete(hexKey);
       }
     }
   }
   async list(prefix) {
-    await _chunk4SWXLWKLcjs.sleep.call(void 0, this.latency);
+    await _chunkU2W3KHJCcjs.sleep.call(void 0, this.latency);
     const results = [];
     for (const entry of this.kv.values()) {
-      if (_chunk4SWXLWKLcjs.keyStartsWith.call(void 0, entry.key, prefix)) {
+      if (_chunkU2W3KHJCcjs.keyStartsWith.call(void 0, entry.key, prefix)) {
         results.push({ key: entry.key, value: entry.value });
       }
     }
-    return results.sort((a, b) => _chunk4SWXLWKLcjs.compareKeys.call(void 0, a.key, b.key));
+    return results.sort((a, b) => _chunkU2W3KHJCcjs.compareKeys.call(void 0, a.key, b.key));
   }
   async batch(writes) {
-    await _chunk4SWXLWKLcjs.sleep.call(void 0, this.latency);
+    await _chunkU2W3KHJCcjs.sleep.call(void 0, this.latency);
     for (const { key, value } of writes) {
-      this.kv.set(_chunk4SWXLWKLcjs.keyToHex.call(void 0, key), { key, value });
+      this.kv.set(_chunkU2W3KHJCcjs.keyToHex.call(void 0, key), { key, value });
     }
   }
   async setAlarm(workflowId, wakeAt) {
-    await _chunk4SWXLWKLcjs.sleep.call(void 0, this.latency);
+    await _chunkU2W3KHJCcjs.sleep.call(void 0, this.latency);
     this.alarms.set(workflowId, wakeAt);
   }
   async clearAlarm(workflowId) {
-    await _chunk4SWXLWKLcjs.sleep.call(void 0, this.latency);
+    await _chunkU2W3KHJCcjs.sleep.call(void 0, this.latency);
     this.alarms.delete(workflowId);
   }
   async waitForMessages(messageNames, abortSignal) {
@@ -218,7 +218,7 @@ var InMemoryDriver = (_class = class {constructor() { _class.prototype.__init.ca
     }
     while (true) {
       if (abortSignal.aborted) {
-        throw new (0, _chunk4SWXLWKLcjs.EvictedError)();
+        throw new (0, _chunkU2W3KHJCcjs.EvictedError)();
       }
       const messages = await this.messageDriver.receiveMessages({
         names: messageNames.length > 0 ? messageNames : void 0,
@@ -228,7 +228,7 @@ var InMemoryDriver = (_class = class {constructor() { _class.prototype.__init.ca
       if (messages.length > 0) {
         return;
       }
-      await _chunk4SWXLWKLcjs.sleep.call(void 0, Math.max(1, this.latency));
+      await _chunkU2W3KHJCcjs.sleep.call(void 0, Math.max(1, this.latency));
     }
   }
   /**
@@ -324,5 +324,5 @@ var InMemoryDriver = (_class = class {constructor() { _class.prototype.__init.ca
 
 
 
-exports.CancelledError = _chunk4SWXLWKLcjs.CancelledError; exports.CriticalError = _chunk4SWXLWKLcjs.CriticalError; exports.DEFAULT_LOOP_HISTORY_PRUNE_INTERVAL = _chunk4SWXLWKLcjs.DEFAULT_LOOP_HISTORY_PRUNE_INTERVAL; exports.DEFAULT_MAX_RETRIES = _chunk4SWXLWKLcjs.DEFAULT_MAX_RETRIES; exports.DEFAULT_RETRY_BACKOFF_BASE = _chunk4SWXLWKLcjs.DEFAULT_RETRY_BACKOFF_BASE; exports.DEFAULT_RETRY_BACKOFF_MAX = _chunk4SWXLWKLcjs.DEFAULT_RETRY_BACKOFF_MAX; exports.DEFAULT_STEP_TIMEOUT = _chunk4SWXLWKLcjs.DEFAULT_STEP_TIMEOUT; exports.EntryInProgressError = _chunk4SWXLWKLcjs.EntryInProgressError; exports.EvictedError = _chunk4SWXLWKLcjs.EvictedError; exports.HistoryDivergedError = _chunk4SWXLWKLcjs.HistoryDivergedError; exports.InMemoryDriver = InMemoryDriver; exports.JoinError = _chunk4SWXLWKLcjs.JoinError; exports.Loop = _chunk4SWXLWKLcjs.Loop; exports.MessageWaitError = _chunk4SWXLWKLcjs.MessageWaitError; exports.RaceError = _chunk4SWXLWKLcjs.RaceError; exports.RollbackCheckpointError = _chunk4SWXLWKLcjs.RollbackCheckpointError; exports.RollbackError = _chunk4SWXLWKLcjs.RollbackError; exports.SleepError = _chunk4SWXLWKLcjs.SleepError; exports.StepExhaustedError = _chunk4SWXLWKLcjs.StepExhaustedError; exports.StepFailedError = _chunk4SWXLWKLcjs.StepFailedError; exports.WorkflowContextImpl = _chunk4SWXLWKLcjs.WorkflowContextImpl; exports.appendLoopIteration = _chunk4SWXLWKLcjs.appendLoopIteration; exports.appendName = _chunk4SWXLWKLcjs.appendName; exports.createEntry = _chunk4SWXLWKLcjs.createEntry; exports.createHistorySnapshot = _chunk4SWXLWKLcjs.createHistorySnapshot; exports.createStorage = _chunk4SWXLWKLcjs.createStorage; exports.deleteEntriesWithPrefix = _chunk4SWXLWKLcjs.deleteEntriesWithPrefix; exports.emptyLocation = _chunk4SWXLWKLcjs.emptyLocation; exports.extractErrorInfo = _chunk4SWXLWKLcjs.extractErrorInfo; exports.flush = _chunk4SWXLWKLcjs.flush; exports.generateId = _chunk4SWXLWKLcjs.generateId; exports.getEntry = _chunk4SWXLWKLcjs.getEntry; exports.getOrCreateMetadata = _chunk4SWXLWKLcjs.getOrCreateMetadata; exports.isLocationPrefix = _chunk4SWXLWKLcjs.isLocationPrefix; exports.isLoopIterationMarker = _chunk4SWXLWKLcjs.isLoopIterationMarker; exports.loadMetadata = _chunk4SWXLWKLcjs.loadMetadata; exports.loadStorage = _chunk4SWXLWKLcjs.loadStorage; exports.locationToKey = _chunk4SWXLWKLcjs.locationToKey; exports.locationsEqual = _chunk4SWXLWKLcjs.locationsEqual; exports.parentLocation = _chunk4SWXLWKLcjs.parentLocation; exports.registerName = _chunk4SWXLWKLcjs.registerName; exports.replayWorkflowFromStep = _chunk4SWXLWKLcjs.replayWorkflowFromStep; exports.resolveName = _chunk4SWXLWKLcjs.resolveName; exports.runWorkflow = _chunk4SWXLWKLcjs.runWorkflow; exports.setEntry = _chunk4SWXLWKLcjs.setEntry;
+exports.CancelledError = _chunkU2W3KHJCcjs.CancelledError; exports.CriticalError = _chunkU2W3KHJCcjs.CriticalError; exports.DEFAULT_LOOP_HISTORY_PRUNE_INTERVAL = _chunkU2W3KHJCcjs.DEFAULT_LOOP_HISTORY_PRUNE_INTERVAL; exports.DEFAULT_MAX_RETRIES = _chunkU2W3KHJCcjs.DEFAULT_MAX_RETRIES; exports.DEFAULT_RETRY_BACKOFF_BASE = _chunkU2W3KHJCcjs.DEFAULT_RETRY_BACKOFF_BASE; exports.DEFAULT_RETRY_BACKOFF_MAX = _chunkU2W3KHJCcjs.DEFAULT_RETRY_BACKOFF_MAX; exports.DEFAULT_STEP_TIMEOUT = _chunkU2W3KHJCcjs.DEFAULT_STEP_TIMEOUT; exports.EntryInProgressError = _chunkU2W3KHJCcjs.EntryInProgressError; exports.EvictedError = _chunkU2W3KHJCcjs.EvictedError; exports.HistoryDivergedError = _chunkU2W3KHJCcjs.HistoryDivergedError; exports.InMemoryDriver = InMemoryDriver; exports.JoinError = _chunkU2W3KHJCcjs.JoinError; exports.Loop = _chunkU2W3KHJCcjs.Loop; exports.MessageWaitError = _chunkU2W3KHJCcjs.MessageWaitError; exports.RaceError = _chunkU2W3KHJCcjs.RaceError; exports.RollbackCheckpointError = _chunkU2W3KHJCcjs.RollbackCheckpointError; exports.RollbackError = _chunkU2W3KHJCcjs.RollbackError; exports.SleepError = _chunkU2W3KHJCcjs.SleepError; exports.StepExhaustedError = _chunkU2W3KHJCcjs.StepExhaustedError; exports.StepFailedError = _chunkU2W3KHJCcjs.StepFailedError; exports.WorkflowContextImpl = _chunkU2W3KHJCcjs.WorkflowContextImpl; exports.appendLoopIteration = _chunkU2W3KHJCcjs.appendLoopIteration; exports.appendName = _chunkU2W3KHJCcjs.appendName; exports.createEntry = _chunkU2W3KHJCcjs.createEntry; exports.createHistorySnapshot = _chunkU2W3KHJCcjs.createHistorySnapshot; exports.createStorage = _chunkU2W3KHJCcjs.createStorage; exports.deleteEntriesWithPrefix = _chunkU2W3KHJCcjs.deleteEntriesWithPrefix; exports.emptyLocation = _chunkU2W3KHJCcjs.emptyLocation; exports.extractErrorInfo = _chunkU2W3KHJCcjs.extractErrorInfo; exports.flush = _chunkU2W3KHJCcjs.flush; exports.generateId = _chunkU2W3KHJCcjs.generateId; exports.getEntry = _chunkU2W3KHJCcjs.getEntry; exports.getOrCreateMetadata = _chunkU2W3KHJCcjs.getOrCreateMetadata; exports.isLocationPrefix = _chunkU2W3KHJCcjs.isLocationPrefix; exports.isLoopIterationMarker = _chunkU2W3KHJCcjs.isLoopIterationMarker; exports.loadMetadata = _chunkU2W3KHJCcjs.loadMetadata; exports.loadStorage = _chunkU2W3KHJCcjs.loadStorage; exports.locationToKey = _chunkU2W3KHJCcjs.locationToKey; exports.locationsEqual = _chunkU2W3KHJCcjs.locationsEqual; exports.parentLocation = _chunkU2W3KHJCcjs.parentLocation; exports.registerName = _chunkU2W3KHJCcjs.registerName; exports.replayWorkflowFromStep = _chunkU2W3KHJCcjs.replayWorkflowFromStep; exports.resolveName = _chunkU2W3KHJCcjs.resolveName; exports.runWorkflow = _chunkU2W3KHJCcjs.runWorkflow; exports.setEntry = _chunkU2W3KHJCcjs.setEntry;
 //# sourceMappingURL=testing.cjs.map

package/dist/tsup/testing.js

@@ -47,7 +47,7 @@ import {
   runWorkflow,
   setEntry,
   sleep
-} from "./chunk-UMFB2AR3.js";
+} from "./chunk-DFNXCZ47.js";
 
 // src/testing.ts
 var InMemoryWorkflowMessageDriver = class {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rivetkit/workflow-engine",
-	"version": "2.3.0-rc.1",
+	"version": "2.3.0-rc.11",
 	"description": "Durable workflow engine with reentrant execution",
 	"license": "Apache-2.0",
 	"keywords": [

package/schemas/serde.ts

@@ -18,7 +18,6 @@ import type {
 	EntryMetadata as InternalEntryMetadata,
 	EntryStatus as InternalEntryStatus,
 	Location as InternalLocation,
-	LoopIterationMarker as InternalLoopIterationMarker,
 	PathSegment as InternalPathSegment,
 	SleepState as InternalSleepState,
 	WorkflowState as InternalWorkflowState,
@@ -27,7 +26,6 @@ import {
 	CURRENT_VERSION,
 	ENTRY_METADATA_VERSIONED,
 	ENTRY_VERSIONED,
-	WORKFLOW_METADATA_VERSIONED,
 } from "./versioned.js";
 
 // === Helper: ArrayBuffer to/from utilities ===
@@ -74,7 +72,7 @@ function assertString(
 /**
  * Validate that a value is a number.
  */
-function assertNumber(
+function _assertNumber(
 	value: unknown,
 	context: string,
 ): asserts value is number {

package/src/context.ts

@@ -21,7 +21,7 @@ import {
 	StepExhaustedError,
 	StepFailedError,
 } from "./errors.js";
-import { buildLoopIterationRange, buildEntryMetadataKey } from "./keys.js";
+import { buildEntryMetadataKey, buildLoopIterationRange } from "./keys.js";
 import {
 	appendLoopIteration,
 	appendName,
@@ -36,13 +36,12 @@ import {
 	flush,
 	getOrCreateMetadata,
 	loadMetadata,
-	setEntry,
 	type PendingDeletions,
+	setEntry,
 } from "./storage.js";
 import type {
 	BranchConfig,
 	BranchOutput,
-	BranchStatus,
 	Entry,
 	EntryKindType,
 	EntryMetadata,
@@ -66,11 +65,11 @@ import type {
 	WorkflowError,
 	WorkflowErrorEvent,
 	WorkflowErrorHandler,
+	WorkflowMessageDriver,
 	WorkflowQueue,
 	WorkflowQueueMessage,
 	WorkflowQueueNextBatchOptions,
 	WorkflowQueueNextOptions,
-	WorkflowMessageDriver,
 } from "./types.js";
 import { sleep } from "./utils.js";
 
@@ -505,8 +504,7 @@ export class WorkflowContextImpl implements WorkflowContextInterface {
 	 * Throws HistoryDivergedError if duplicate detected.
 	 */
 	private checkDuplicateName(name: string): void {
-		const fullKey =
-			locationToKey(this.storage, this.currentLocation) + "/" + name;
+		const fullKey = `${locationToKey(this.storage, this.currentLocation)}/${name}`;
 		if (this.usedNamesInExecution.has(fullKey)) {
 			throw new HistoryDivergedError(
 				`Duplicate entry name "${name}" at location "${locationToKey(this.storage, this.currentLocation)}". ` +
@@ -580,7 +578,7 @@ export class WorkflowContextImpl implements WorkflowContextInterface {
 			const isUnderPrefix =
 				prefix === ""
 					? true // Root: all keys are children
-					: key.startsWith(prefix + "/") || key === prefix;
+					: key.startsWith(`${prefix}/`) || key === prefix;
 
 			if (isUnderPrefix) {
 				if (!this.visitedKeys.has(key)) {
@@ -825,10 +823,7 @@ export class WorkflowContextImpl implements WorkflowContextInterface {
 			const maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
 
 			if (metadata.attempts > maxRetries) {
-				// Prefer step history error, but fall back to metadata since
-				// driver implementations may persist metadata without the history
-				// entry error (e.g. partial writes/crashes between attempts).
-				const lastError = stepData.error ?? metadata.error;
+				const lastError = metadata.error;
 				const exhaustedError = new StepExhaustedError(
 					config.name,
 					lastError,
@@ -941,28 +936,26 @@ export class WorkflowContextImpl implements WorkflowContextInterface {
 			});
 			return output;
 		} catch (error) {
-			// Timeout errors are treated as critical (no retry)
-			if (error instanceof StepTimeoutError) {
-				if (entry.kind.type === "step") {
-					entry.kind.data.error = String(error);
-				}
-				entry.dirty = true;
+			if (entry.kind.type === "step") {
+				entry.kind.data.error = String(error);
+			}
+			entry.dirty = true;
+
+			// Timeout errors are treated as critical by default. Steps opt
+			// into retrying on timeout with retryOnTimeout: true.
+			if (error instanceof StepTimeoutError && !config.retryOnTimeout) {
 				metadata.status = "exhausted";
 				metadata.error = String(error);
-				await this.flushStorage();
 				await this.notifyStepError(config, metadata.attempts, error, {
 					willRetry: false,
 				});
 				throw markErrorReported(
-					attachTryStepFailure(
-						new CriticalError(error.message),
-						{
-							kind: "timeout",
-							stepName: config.name,
-							attempts: metadata.attempts,
-							error: extractErrorInfo(error),
-						},
-					),
+					attachTryStepFailure(new CriticalError(error.message), {
+						kind: "timeout",
+						stepName: config.name,
+						attempts: metadata.attempts,
+						error: extractErrorInfo(error),
+					}),
 				);
 			}
 
@@ -970,13 +963,8 @@ export class WorkflowContextImpl implements WorkflowContextInterface {
 				error instanceof CriticalError ||
 				error instanceof RollbackError
 			) {
-				if (entry.kind.type === "step") {
-					entry.kind.data.error = String(error);
-				}
-				entry.dirty = true;
 				metadata.status = "exhausted";
 				metadata.error = String(error);
-				await this.flushStorage();
 				await this.notifyStepError(config, metadata.attempts, error, {
 					willRetry: false,
 				});
@@ -993,15 +981,10 @@ export class WorkflowContextImpl implements WorkflowContextInterface {
 				);
 			}
 
-			if (entry.kind.type === "step") {
-				entry.kind.data.error = String(error);
-			}
-			entry.dirty = true;
 			const willRetry = metadata.attempts <= maxRetries;
 			metadata.status = willRetry ? "failed" : "exhausted";
 			metadata.error = String(error);
 
-			await this.flushStorage();
 			if (willRetry) {
 				const retryDelay = calculateBackoff(
 					metadata.attempts,
@@ -1026,7 +1009,10 @@ export class WorkflowContextImpl implements WorkflowContextInterface {
 				attachTryStepFailure(
 					new StepExhaustedError(config.name, String(error)),
 					{
-						kind: "exhausted",
+						kind:
+							error instanceof StepTimeoutError
+								? "timeout"
+								: "exhausted",
 						stepName: config.name,
 						attempts: metadata.attempts,
 						error: extractErrorInfo(error),
@@ -1045,7 +1031,9 @@ export class WorkflowContextImpl implements WorkflowContextInterface {
 	 *
 	 * Note: This does NOT cancel the underlying operation. JavaScript Promises
 	 * cannot be cancelled once started. When a timeout occurs:
-	 * - The step is marked as failed with StepTimeoutError
+	 * - The step is rejected with StepTimeoutError. By default this is treated
+	 *   as a critical failure with no retry. Set retryOnTimeout: true on the
+	 *   step config to retry timeouts like any other error.
 	 * - The underlying async operation continues running in the background
 	 * - Any side effects from the operation may still occur
 	 *
@@ -1224,8 +1212,12 @@ export class WorkflowContextImpl implements WorkflowContextInterface {
 		}
 
 		const historyPruneInterval =
-			config.historyPruneInterval ?? DEFAULT_LOOP_HISTORY_PRUNE_INTERVAL;
-		const historySize = config.historySize ?? historyPruneInterval;
+			config.historyPruneInterval ??
+			config.commitInterval ??
+			config.historyEvery ??
+			DEFAULT_LOOP_HISTORY_PRUNE_INTERVAL;
+		const historySize =
+			config.historySize ?? config.historyKeep ?? historyPruneInterval;
 
 		// Track the last iteration we pruned up to so we only delete
 		// newly-expired iterations instead of re-scanning from 0.

package/src/index.ts

@@ -13,6 +13,7 @@ export {
 } from "./context.js";
 // Driver
 export type { EngineDriver, KVEntry, KVWrite } from "./driver.js";
+export { extractErrorInfo } from "./error-utils.js";
 // Errors
 export {
 	CancelledError,
@@ -29,7 +30,6 @@ export {
 	StepExhaustedError,
 	StepFailedError,
 } from "./errors.js";
-export { extractErrorInfo } from "./error-utils.js";
 
 // Location utilities
 export {
@@ -82,9 +82,6 @@ export type {
 	PathSegment,
 	RaceEntry,
 	RemovedEntry,
-	WorkflowEntryMetadataSnapshot,
-	WorkflowHistoryEntry,
-	WorkflowHistorySnapshot,
 	RollbackCheckpointEntry,
 	RollbackContextInterface,
 	RunWorkflowOptions,
@@ -102,20 +99,23 @@ export type {
 	TryStepFailure,
 	TryStepResult,
 	WorkflowContextInterface,
+	WorkflowEntryMetadataSnapshot,
 	WorkflowError,
 	WorkflowErrorEvent,
 	WorkflowErrorHandler,
 	WorkflowFunction,
 	WorkflowHandle,
-	WorkflowRollbackErrorEvent,
+	WorkflowHistoryEntry,
+	WorkflowHistorySnapshot,
+	WorkflowMessageDriver,
 	WorkflowQueue,
 	WorkflowQueueMessage,
 	WorkflowQueueNextBatchOptions,
 	WorkflowQueueNextOptions,
-	WorkflowMessageDriver,
 	WorkflowResult,
-	WorkflowRunMode,
+	WorkflowRollbackErrorEvent,
 	WorkflowRunErrorEvent,
+	WorkflowRunMode,
 	WorkflowState,
 	WorkflowStepErrorEvent,
 } from "./types.js";
@@ -185,9 +185,9 @@ import type {
 	RunWorkflowOptions,
 	Storage,
 	WorkflowErrorEvent,
-	WorkflowHistorySnapshot,
 	WorkflowFunction,
 	WorkflowHandle,
+	WorkflowHistorySnapshot,
 	WorkflowMessageDriver,
 	WorkflowResult,
 	WorkflowRunMode,

package/src/location.ts

@@ -159,7 +159,7 @@ export function getChildEntries(
 		const isChild =
 			parentKey === ""
 				? true
-				: key.startsWith(parentKey + "/") || key === parentKey;
+				: key.startsWith(`${parentKey}/`) || key === parentKey;
 
 		if (isChild) {
 			// Return the actual entry's location, not the parent location

package/src/storage.ts

@@ -40,6 +40,9 @@ import type {
 	WorkflowHistorySnapshot,
 } from "./types.js";
 
+export const MAX_KV_BATCH_ENTRIES = 128;
+export const MAX_KV_BATCH_PAYLOAD_BYTES = 976 * 1024;
+
 /**
  * Create an empty storage instance.
  */
@@ -238,6 +241,8 @@ export async function flush(
 	pendingDeletions?: PendingDeletions,
 ): Promise<void> {
 	const writes: KVWrite[] = [];
+	const dirtyEntries: Entry[] = [];
+	const dirtyMetadata: EntryMetadata[] = [];
 	let historyUpdated = false;
 
 	// Flush only new names (those added since last flush)
@@ -263,7 +268,7 @@ export async function flush(
 				key: buildHistoryKey(entry.location),
 				value: serializeEntry(entry),
 			});
-			entry.dirty = false;
+			dirtyEntries.push(entry);
 			historyUpdated = true;
 		}
 	}
@@ -275,7 +280,7 @@ export async function flush(
 				key: buildEntryMetadataKey(id),
 				value: serializeEntryMetadata(metadata),
 			});
-			metadata.dirty = false;
+			dirtyMetadata.push(metadata);
 			historyUpdated = true;
 		}
 	}
@@ -313,7 +318,9 @@ export async function flush(
 	}
 
 	if (writes.length > 0) {
-		await driver.batch(writes);
+		for (const chunk of splitBatchWrites(writes)) {
+			await driver.batch(chunk);
+		}
 	}
 
 	// Apply pending deletions after the batch write. These are collected
@@ -336,6 +343,12 @@ export async function flush(
 	}
 
 	// Update flushed tracking after successful write
+	for (const entry of dirtyEntries) {
+		entry.dirty = false;
+	}
+	for (const metadata of dirtyMetadata) {
+		metadata.dirty = false;
+	}
 	storage.flushedNameCount = storage.nameRegistry.length;
 	storage.flushedState = storage.state;
 	storage.flushedOutput = storage.output;
@@ -346,6 +359,40 @@ export async function flush(
 	}
 }
 
+function splitBatchWrites(writes: KVWrite[]): KVWrite[][] {
+	const chunks: KVWrite[][] = [];
+	let chunk: KVWrite[] = [];
+	let chunkBytes = 0;
+
+	for (const write of writes) {
+		const writeBytes = write.key.byteLength + write.value.byteLength;
+		if (writeBytes > MAX_KV_BATCH_PAYLOAD_BYTES) {
+			throw new Error(
+				`KV batch write is ${writeBytes} bytes, exceeding the ${MAX_KV_BATCH_PAYLOAD_BYTES} byte limit`,
+			);
+		}
+
+		if (
+			chunk.length >= MAX_KV_BATCH_ENTRIES ||
+			(chunk.length > 0 &&
+				chunkBytes + writeBytes > MAX_KV_BATCH_PAYLOAD_BYTES)
+		) {
+			chunks.push(chunk);
+			chunk = [];
+			chunkBytes = 0;
+		}
+
+		chunk.push(write);
+		chunkBytes += writeBytes;
+	}
+
+	if (chunk.length > 0) {
+		chunks.push(chunk);
+	}
+
+	return chunks;
+}
+
 /**
  * Delete entries with a given location prefix (used for loop forgetting).
  * Also cleans up associated metadata from both memory and driver.