@rivetkit/workflow-engine 2.1.0-rc.1

package/dist/tsup/index.d.cts

@@ -0,0 +1,884 @@
+import { Logger } from 'pino';
+
+/**
+ * Index into the entry name registry.
+ * Names are stored once and referenced by this index to avoid repetition.
+ */
+type NameIndex = number;
+/**
+ * A segment in a location path.
+ * Either a name index (for named entries) or a loop iteration marker.
+ */
+type PathSegment = NameIndex | LoopIterationMarker;
+/**
+ * Marker for a loop iteration in a location path.
+ */
+interface LoopIterationMarker {
+    loop: NameIndex;
+    iteration: number;
+}
+/**
+ * Location identifies where an entry exists in the workflow execution tree.
+ * It forms a path from the root through loops, joins, and branches.
+ */
+type Location = PathSegment[];
+/**
+ * Current state of a sleep entry.
+ */
+type SleepState = "pending" | "completed" | "interrupted";
+/**
+ * Status of an entry in the workflow.
+ */
+type EntryStatus = "pending" | "running" | "completed" | "failed" | "exhausted";
+/**
+ * Status of a branch in join/race.
+ */
+type BranchStatusType = "pending" | "running" | "completed" | "failed" | "cancelled";
+/**
+ * Current state of the workflow.
+ */
+type WorkflowState = "pending" | "running" | "sleeping" | "failed" | "completed" | "cancelled" | "rolling_back";
+/**
+ * Step entry data.
+ */
+interface StepEntry {
+    output?: unknown;
+    error?: string;
+}
+/**
+ * Loop entry data.
+ */
+interface LoopEntry {
+    state: unknown;
+    iteration: number;
+    output?: unknown;
+}
+/**
+ * Sleep entry data.
+ */
+interface SleepEntry {
+    deadline: number;
+    state: SleepState;
+}
+/**
+ * Message entry data.
+ */
+interface MessageEntry {
+    name: string;
+    data: unknown;
+}
+/**
+ * Rollback checkpoint entry data.
+ */
+interface RollbackCheckpointEntry {
+    name: string;
+}
+/**
+ * Branch status for join/race entries.
+ */
+interface BranchStatus {
+    status: BranchStatusType;
+    output?: unknown;
+    error?: string;
+}
+/**
+ * Join entry data.
+ */
+interface JoinEntry {
+    branches: Record<string, BranchStatus>;
+}
+/**
+ * Race entry data.
+ */
+interface RaceEntry {
+    winner: string | null;
+    branches: Record<string, BranchStatus>;
+}
+/**
+ * Removed entry data - placeholder for removed steps in workflow migrations.
+ */
+interface RemovedEntry {
+    originalType: EntryKindType;
+    originalName?: string;
+}
+/**
+ * All possible entry kind types.
+ */
+type EntryKindType = "step" | "loop" | "sleep" | "message" | "rollback_checkpoint" | "join" | "race" | "removed";
+/**
+ * Type-specific entry data.
+ */
+type EntryKind = {
+    type: "step";
+    data: StepEntry;
+} | {
+    type: "loop";
+    data: LoopEntry;
+} | {
+    type: "sleep";
+    data: SleepEntry;
+} | {
+    type: "message";
+    data: MessageEntry;
+} | {
+    type: "rollback_checkpoint";
+    data: RollbackCheckpointEntry;
+} | {
+    type: "join";
+    data: JoinEntry;
+} | {
+    type: "race";
+    data: RaceEntry;
+} | {
+    type: "removed";
+    data: RemovedEntry;
+};
+/**
+ * An entry in the workflow history.
+ */
+interface Entry {
+    id: string;
+    location: Location;
+    kind: EntryKind;
+    dirty: boolean;
+}
+/**
+ * Metadata for an entry (stored separately, lazily loaded).
+ */
+interface EntryMetadata {
+    status: EntryStatus;
+    error?: string;
+    attempts: number;
+    lastAttemptAt: number;
+    createdAt: number;
+    completedAt?: number;
+    rollbackCompletedAt?: number;
+    rollbackError?: string;
+    dirty: boolean;
+}
+/**
+ * A message in the queue.
+ */
+interface Message {
+    /** Unique message ID. */
+    id: string;
+    name: string;
+    data: unknown;
+    sentAt: number;
+    /**
+     * Optional completion callback for queue-backed drivers.
+     *
+     * This is runtime-only and is not persisted.
+     */
+    complete?: (response?: unknown) => Promise<void>;
+}
+/**
+ * Options for receiving queue messages in workflows.
+ */
+interface WorkflowQueueNextOptions {
+    /**
+     * Queue names to receive from.
+     * If omitted, receives from all queue names.
+     */
+    names?: readonly string[];
+    /** Maximum number of messages to receive. Defaults to 1. */
+    count?: number;
+    /**
+     * Timeout in milliseconds.
+     * Omit to wait indefinitely.
+     */
+    timeout?: number;
+    /** Whether returned messages must be manually completed. */
+    completable?: boolean;
+}
+/**
+ * Message returned by workflow queue operations.
+ */
+interface WorkflowQueueMessage<TBody = unknown> {
+    id: string | bigint;
+    name: string;
+    body: TBody;
+    createdAt: number;
+    complete?(response?: unknown): Promise<void>;
+}
+/**
+ * Workflow queue interface.
+ */
+interface WorkflowQueue {
+    next<TBody = unknown>(name: string, opts?: WorkflowQueueNextOptions): Promise<Array<WorkflowQueueMessage<TBody>>>;
+    send(name: string, body: unknown): Promise<void>;
+}
+/**
+ * Workflow history - maps location keys to entries.
+ */
+interface History {
+    entries: Map<string, Entry>;
+}
+/**
+ * History entry snapshot without internal dirty flags.
+ */
+type WorkflowHistoryEntry = Omit<Entry, "dirty">;
+/**
+ * Entry metadata snapshot without internal dirty flags.
+ */
+type WorkflowEntryMetadataSnapshot = Omit<EntryMetadata, "dirty">;
+/**
+ * Snapshot of workflow history for observers.
+ */
+interface WorkflowHistorySnapshot {
+    nameRegistry: string[];
+    entries: WorkflowHistoryEntry[];
+    entryMetadata: ReadonlyMap<string, WorkflowEntryMetadataSnapshot>;
+}
+/**
+ * Structured error information for workflow failures.
+ */
+interface WorkflowError {
+    /** Error name/type (e.g., "TypeError", "CriticalError") */
+    name: string;
+    /** Error message */
+    message: string;
+    /** Stack trace if available */
+    stack?: string;
+    /** Custom error properties (for structured errors) */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Complete storage state for a workflow.
+ */
+interface Storage {
+    nameRegistry: string[];
+    flushedNameCount: number;
+    history: History;
+    entryMetadata: Map<string, EntryMetadata>;
+    output?: unknown;
+    state: WorkflowState;
+    flushedState?: WorkflowState;
+    error?: WorkflowError;
+    flushedError?: WorkflowError;
+    flushedOutput?: unknown;
+}
+/**
+ * Driver interface for workflow message persistence.
+ */
+interface WorkflowMessageDriver {
+    addMessage(message: Message): Promise<void>;
+    /**
+     * Receive messages directly from the host queue implementation.
+     * The operation must be non-blocking and return immediately.
+     */
+    receiveMessages(opts: {
+        names?: readonly string[];
+        count: number;
+        completable: boolean;
+    }): Promise<Message[]>;
+    /**
+     * Complete a previously consumed message with an optional response payload.
+     */
+    completeMessage(messageId: string, response?: unknown): Promise<void>;
+}
+/**
+ * Context available to rollback handlers.
+ */
+interface RollbackContextInterface {
+    readonly workflowId: string;
+    readonly abortSignal: AbortSignal;
+    isEvicted(): boolean;
+}
+/**
+ * Configuration for a step.
+ */
+interface StepConfig<T> {
+    name: string;
+    run: () => Promise<T>;
+    rollback?: (ctx: RollbackContextInterface, output: T) => Promise<void>;
+    /** If true, step result is not persisted (use for idempotent operations). */
+    ephemeral?: boolean;
+    /** Maximum number of retry attempts (default: 3). */
+    maxRetries?: number;
+    /** Base delay in ms for exponential backoff (default: 100). */
+    retryBackoffBase?: number;
+    /** Maximum delay in ms for exponential backoff (default: 30000). */
+    retryBackoffMax?: number;
+    /** Timeout in ms for step execution (default: 30000). Set to 0 to disable. */
+    timeout?: number;
+}
+/**
+ * Result from a loop iteration.
+ */
+type LoopResult<S, T> = {
+    continue: true;
+    state: S;
+} | {
+    break: true;
+    value: T;
+};
+/**
+ * Configuration for a loop.
+ */
+interface LoopConfig<S, T> {
+    name: string;
+    state?: S;
+    run: (ctx: WorkflowContextInterface, state: S) => Promise<LoopResult<S, T>>;
+    commitInterval?: number;
+    /** Trim loop history every N iterations. Defaults to commitInterval or 20. */
+    historyEvery?: number;
+    /** Retain the last N iterations of history. Defaults to commitInterval or 20. */
+    historyKeep?: number;
+}
+/**
+ * Configuration for a branch in join/race.
+ */
+interface BranchConfig<T> {
+    run: (ctx: WorkflowContextInterface) => Promise<T>;
+}
+/**
+ * Extract the output type from a BranchConfig.
+ */
+type BranchOutput<T> = T extends BranchConfig<infer O> ? O : never;
+/**
+ * The workflow context interface exposed to workflow functions.
+ */
+interface WorkflowContextInterface {
+    readonly workflowId: string;
+    readonly abortSignal: AbortSignal;
+    readonly queue: WorkflowQueue;
+    step<T>(name: string, run: () => Promise<T>): Promise<T>;
+    step<T>(config: StepConfig<T>): Promise<T>;
+    loop<T>(name: string, run: (ctx: WorkflowContextInterface) => Promise<LoopResult<undefined, T>>): Promise<T>;
+    loop<S, T>(config: LoopConfig<S, T>): Promise<T>;
+    sleep(name: string, durationMs: number): Promise<void>;
+    sleepUntil(name: string, timestampMs: number): Promise<void>;
+    rollbackCheckpoint(name: string): Promise<void>;
+    join<T extends Record<string, BranchConfig<unknown>>>(name: string, branches: T): Promise<{
+        [K in keyof T]: BranchOutput<T[K]>;
+    }>;
+    race<T>(name: string, branches: Array<{
+        name: string;
+        run: (ctx: WorkflowContextInterface) => Promise<T>;
+    }>): Promise<{
+        winner: string;
+        value: T;
+    }>;
+    removed(name: string, originalType: EntryKindType): Promise<void>;
+    isEvicted(): boolean;
+}
+/**
+ * Workflow function type.
+ */
+type WorkflowRunMode = "yield" | "live";
+interface RunWorkflowOptions {
+    mode?: WorkflowRunMode;
+    logger?: Logger;
+    onHistoryUpdated?: (history: WorkflowHistorySnapshot) => void;
+}
+type WorkflowFunction<TInput = unknown, TOutput = unknown> = (ctx: WorkflowContextInterface, input: TInput) => Promise<TOutput>;
+/**
+ * Result returned when a workflow run completes or yields.
+ */
+interface WorkflowResult<TOutput = unknown> {
+    state: WorkflowState;
+    output?: TOutput;
+    sleepUntil?: number;
+    waitingForMessages?: string[];
+}
+/**
+ * Handle for managing a running workflow.
+ *
+ * Returned by `runWorkflow()`. The workflow starts executing immediately.
+ * Use `.result` to await completion, and other methods to interact with
+ * the running workflow.
+ */
+interface WorkflowHandle<TOutput = unknown> {
+    readonly workflowId: string;
+    /**
+     * Promise that resolves when the workflow completes or yields.
+     */
+    readonly result: Promise<WorkflowResult<TOutput>>;
+    /**
+     * Send a message to the workflow.
+     * The message is delegated to the runtime message driver.
+     * In live mode, this wakes workflows waiting on queue messages.
+     */
+    message(name: string, data: unknown): Promise<void>;
+    /**
+     * Wake the workflow immediately by setting an alarm for now.
+     */
+    wake(): Promise<void>;
+    /**
+     * Reset exhausted retries and schedule the workflow to run again.
+     */
+    recover(): Promise<void>;
+    /**
+     * Request the workflow to stop gracefully.
+     * The workflow will throw EvictedError at its next yield point,
+     * flush its state, and resolve the result promise.
+     */
+    evict(): void;
+    /**
+     * Cancel the workflow permanently.
+     * Sets the workflow state to "cancelled" and clears any pending alarms.
+     * Unlike evict(), this marks the workflow as permanently stopped.
+     */
+    cancel(): Promise<void>;
+    /**
+     * Get the workflow output if completed.
+     */
+    getOutput(): Promise<TOutput | undefined>;
+    /**
+     * Get the current workflow state.
+     */
+    getState(): Promise<WorkflowState>;
+}
+
+/**
+ * A key-value entry returned from list operations.
+ */
+interface KVEntry {
+    key: Uint8Array;
+    value: Uint8Array;
+}
+/**
+ * A write operation for batch writes.
+ */
+interface KVWrite {
+    key: Uint8Array;
+    value: Uint8Array;
+}
+/**
+ * The engine driver provides the KV and scheduling interface.
+ * Implementations must provide these methods to integrate with different backends.
+ *
+ * IMPORTANT: Each workflow instance must have its own isolated driver/KV namespace.
+ * The workflow engine is the sole reader/writer of its KV during execution.
+ * KV operations do not include workflow IDs because isolation is provided externally
+ * by the host system (e.g., Cloudflare Durable Objects, dedicated actor processes).
+ *
+ * External systems may only enqueue messages through the configured message driver
+ * (via WorkflowHandle.message()).
+ * See architecture.md "Isolation Model" for details.
+ */
+interface EngineDriver {
+    /**
+     * Get a value by key.
+     * Returns null if the key doesn't exist.
+     */
+    get(key: Uint8Array): Promise<Uint8Array | null>;
+    /**
+     * Set a value by key.
+     */
+    set(key: Uint8Array, value: Uint8Array): Promise<void>;
+    /**
+     * Delete a key.
+     */
+    delete(key: Uint8Array): Promise<void>;
+    /**
+     * Delete all keys with a given prefix.
+     */
+    deletePrefix(prefix: Uint8Array): Promise<void>;
+    /**
+     * List all key-value pairs with a given prefix.
+     *
+     * IMPORTANT: Results MUST be sorted by key in lexicographic byte order.
+     * The workflow engine relies on this ordering for deterministic history
+     * replay and name registry reconstruction. Failing to sort will cause
+     * non-deterministic replay behavior.
+     */
+    list(prefix: Uint8Array): Promise<KVEntry[]>;
+    /**
+     * Batch write multiple key-value pairs.
+     * Should be atomic if possible.
+     */
+    batch(writes: KVWrite[]): Promise<void>;
+    /**
+     * Set an alarm to wake the workflow at a specific time.
+     * @param workflowId The workflow to wake
+     * @param wakeAt Timestamp in milliseconds when to wake
+     */
+    setAlarm(workflowId: string, wakeAt: number): Promise<void>;
+    /**
+     * Clear any pending alarm for a workflow.
+     */
+    clearAlarm(workflowId: string): Promise<void>;
+    /**
+     * How often the worker polls for work (in milliseconds).
+     * Affects the threshold for in-memory vs scheduled sleeps.
+     */
+    readonly workerPollInterval: number;
+    /** Queue-backed message driver used for workflow messaging. */
+    readonly messageDriver: WorkflowMessageDriver;
+    /**
+     * Wait for incoming messages when running in live mode.
+     * Implementations should resolve when any of the specified message names are available.
+     */
+    waitForMessages(messageNames: string[], abortSignal: AbortSignal): Promise<void>;
+}
+
+/**
+ * Default values for step configuration.
+ * These are exported so users can reference them when overriding.
+ */
+declare const DEFAULT_MAX_RETRIES = 3;
+declare const DEFAULT_RETRY_BACKOFF_BASE = 100;
+declare const DEFAULT_RETRY_BACKOFF_MAX = 30000;
+declare const DEFAULT_LOOP_COMMIT_INTERVAL = 20;
+declare const DEFAULT_LOOP_HISTORY_EVERY = 20;
+declare const DEFAULT_LOOP_HISTORY_KEEP = 20;
+declare const DEFAULT_STEP_TIMEOUT = 30000;
+/**
+ * Internal representation of a rollback handler.
+ */
+interface RollbackAction<T = unknown> {
+    entryId: string;
+    name: string;
+    output: T;
+    rollback: (ctx: RollbackContextInterface, output: T) => Promise<void>;
+}
+/**
+ * Internal implementation of WorkflowContext.
+ */
+declare class WorkflowContextImpl implements WorkflowContextInterface {
+    readonly workflowId: string;
+    private storage;
+    private driver;
+    private messageDriver;
+    private entryInProgress;
+    private abortController;
+    private currentLocation;
+    private visitedKeys;
+    private mode;
+    private rollbackActions?;
+    private rollbackCheckpointSet;
+    /** Track names used in current execution to detect duplicates */
+    private usedNamesInExecution;
+    private pendingCompletableMessageIds;
+    private historyNotifier?;
+    private logger?;
+    constructor(workflowId: string, storage: Storage, driver: EngineDriver, messageDriver: WorkflowMessageDriver, location?: Location, abortController?: AbortController, mode?: "forward" | "rollback", rollbackActions?: RollbackAction[], rollbackCheckpointSet?: boolean, historyNotifier?: () => void, logger?: Logger);
+    get abortSignal(): AbortSignal;
+    get queue(): WorkflowQueue;
+    isEvicted(): boolean;
+    private assertNotInProgress;
+    private checkEvicted;
+    private flushStorage;
+    /**
+     * Create a new branch context for parallel/nested execution.
+     */
+    createBranch(location: Location, abortController?: AbortController): WorkflowContextImpl;
+    /**
+     * Log a debug message using the configured logger.
+     */
+    private log;
+    /**
+     * Mark a key as visited.
+     */
+    private markVisited;
+    /**
+     * Check if a name has already been used at the current location in this execution.
+     * Throws HistoryDivergedError if duplicate detected.
+     */
+    private checkDuplicateName;
+    private stopRollback;
+    private stopRollbackIfMissing;
+    private stopRollbackIfIncomplete;
+    private registerRollbackAction;
+    /**
+     * Ensure a rollback checkpoint exists before registering rollback handlers.
+     */
+    private ensureRollbackCheckpoint;
+    /**
+     * Validate that all expected entries in the branch were visited.
+     * Throws HistoryDivergedError if there are unvisited entries.
+     */
+    validateComplete(): void;
+    /**
+     * Evict the workflow.
+     */
+    evict(): void;
+    /**
+     * Wait for eviction message.
+     *
+     * The event listener uses { once: true } to auto-remove after firing,
+     * preventing memory leaks if this method is called multiple times.
+     */
+    waitForEviction(): Promise<never>;
+    step<T>(nameOrConfig: string | StepConfig<T>, run?: () => Promise<T>): Promise<T>;
+    private executeStep;
+    /**
+     * Execute a promise with timeout.
+     *
+     * 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 underlying async operation continues running in the background
+     * - Any side effects from the operation may still occur
+     *
+     * For cancellable operations, pass ctx.abortSignal to APIs that support AbortSignal:
+     *
+     *     return fetch(url, { signal: ctx.abortSignal });
+
+     *   });
+     *
+     * Or check ctx.isEvicted() periodically in long-running loops.
+     */
+    private executeStepRollback;
+    private executeWithTimeout;
+    loop<S, T>(nameOrConfig: string | LoopConfig<S, T>, run?: (ctx: WorkflowContextInterface) => Promise<LoopResult<undefined, T>>): Promise<T>;
+    private executeLoop;
+    /**
+     * Delete old loop iteration entries to save storage space.
+     *
+     * Loop locations always end with a NameIndex (number) because loops are
+     * created via appendName(). Even for nested loops, the innermost loop's
+     * location ends with its name index:
+     *
+     *   ctx.loop("outer") → location: [outerIndex]
+     *     iteration 0    → location: [{ loop: outerIndex, iteration: 0 }]
+     *       ctx.loop("inner") → location: [{ loop: outerIndex, iteration: 0 }, innerIndex]
+     *
+     * This function removes iterations older than (currentIteration - historyKeep)
+     * every historyEvery iterations.
+     */
+    private forgetOldIterations;
+    sleep(name: string, durationMs: number): Promise<void>;
+    sleepUntil(name: string, timestampMs: number): Promise<void>;
+    private executeSleep;
+    rollbackCheckpoint(name: string): Promise<void>;
+    private executeRollbackCheckpoint;
+    private queueSend;
+    private queueNext;
+    private executeQueueNext;
+    private normalizeQueueNames;
+    private messageNamesLabel;
+    private receiveMessagesNow;
+    private recordQueueMessages;
+    private recordQueueCountEntry;
+    private readReplayQueueMessages;
+    private toWorkflowQueueMessage;
+    private createQueueMessage;
+    private markQueueMessageCompleted;
+    private completeMessage;
+    private toHistoryQueueMessage;
+    private fromHistoryQueueMessage;
+    join<T extends Record<string, BranchConfig<unknown>>>(name: string, branches: T): Promise<{
+        [K in keyof T]: BranchOutput<T[K]>;
+    }>;
+    private executeJoin;
+    race<T>(name: string, branches: Array<{
+        name: string;
+        run: (ctx: WorkflowContextInterface) => Promise<T>;
+    }>): Promise<{
+        winner: string;
+        value: T;
+    }>;
+    private executeRace;
+    removed(name: string, originalType: EntryKindType): Promise<void>;
+    private executeRemoved;
+}
+
+/**
+ * Thrown from steps to prevent retry.
+ * Use this when an error is unrecoverable and retrying would be pointless.
+ */
+declare class CriticalError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown from steps to force rollback without retry.
+ */
+declare class RollbackError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when rollback is used without a checkpoint.
+ */
+declare class RollbackCheckpointError extends Error {
+    constructor();
+}
+/**
+ * Internal: Workflow should sleep until deadline.
+ * This is thrown to yield control back to the scheduler.
+ * Optionally, the workflow can also wake early if certain messages arrive.
+ */
+declare class SleepError extends Error {
+    readonly deadline: number;
+    readonly messageNames?: string[] | undefined;
+    constructor(deadline: number, messageNames?: string[] | undefined);
+}
+/**
+ * Internal: Workflow is waiting for messages.
+ * This is thrown to yield control back to the scheduler.
+ */
+declare class MessageWaitError extends Error {
+    readonly messageNames: string[];
+    constructor(messageNames: string[]);
+}
+/**
+ * Internal: Workflow was evicted.
+ * This is thrown when the workflow is being gracefully stopped.
+ */
+declare class EvictedError extends Error {
+    constructor();
+}
+/**
+ * Workflow code changed incompatibly.
+ * Thrown when history doesn't match the current workflow code.
+ */
+declare class HistoryDivergedError extends Error {
+    constructor(message: string);
+}
+/**
+ * Step exhausted all retries.
+ */
+declare class StepExhaustedError extends Error {
+    readonly stepName: string;
+    readonly lastError?: string | undefined;
+    constructor(stepName: string, lastError?: string | undefined);
+}
+/**
+ * Step failed (will be retried).
+ * Internal error used to trigger retry logic.
+ */
+declare class StepFailedError extends Error {
+    readonly stepName: string;
+    readonly originalError: unknown;
+    readonly attempts: number;
+    constructor(stepName: string, originalError: unknown, attempts: number);
+}
+/**
+ * Join had branch failures.
+ */
+declare class JoinError extends Error {
+    readonly errors: Record<string, Error>;
+    constructor(errors: Record<string, Error>);
+}
+/**
+ * Race had all branches fail.
+ */
+declare class RaceError extends Error {
+    readonly errors: Array<{
+        name: string;
+        error: string;
+    }>;
+    constructor(message: string, errors: Array<{
+        name: string;
+        error: string;
+    }>);
+}
+/**
+ * Branch was cancelled (used by race).
+ */
+declare class CancelledError extends Error {
+    constructor();
+}
+/**
+ * Entry is currently being processed.
+ * Thrown when user forgets to await a step.
+ */
+declare class EntryInProgressError extends Error {
+    constructor();
+}
+
+/**
+ * Check if a path segment is a loop iteration marker.
+ */
+declare function isLoopIterationMarker(segment: PathSegment): segment is LoopIterationMarker;
+/**
+ * Register a name in the registry and return its index.
+ * If the name already exists, returns the existing index.
+ */
+declare function registerName(storage: Storage, name: string): NameIndex;
+/**
+ * Resolve a name index to its string value.
+ */
+declare function resolveName(storage: Storage, index: NameIndex): string;
+/**
+ * Convert a location to a KV key string.
+ * Named entries use their string name, loop iterations use ~N format.
+ */
+declare function locationToKey(storage: Storage, location: Location): string;
+/**
+ * Append a named segment to a location.
+ */
+declare function appendName(storage: Storage, location: Location, name: string): Location;
+/**
+ * Append a loop iteration segment to a location.
+ */
+declare function appendLoopIteration(storage: Storage, location: Location, loopName: string, iteration: number): Location;
+/**
+ * Create an empty location (root).
+ */
+declare function emptyLocation(): Location;
+/**
+ * Get the parent location (all segments except the last).
+ */
+declare function parentLocation(location: Location): Location;
+/**
+ * Check if one location is a prefix of another.
+ */
+declare function isLocationPrefix(prefix: Location, location: Location): boolean;
+/**
+ * Compare two locations for equality.
+ */
+declare function locationsEqual(a: Location, b: Location): boolean;
+
+/**
+ * Create an empty storage instance.
+ */
+declare function createStorage(): Storage;
+/**
+ * Create a snapshot of workflow history for observers.
+ */
+declare function createHistorySnapshot(storage: Storage): WorkflowHistorySnapshot;
+/**
+ * Generate a UUID v4.
+ */
+declare function generateId(): string;
+/**
+ * Create a new entry.
+ */
+declare function createEntry(location: Location, kind: EntryKind): Entry;
+/**
+ * Create or get metadata for an entry.
+ */
+declare function getOrCreateMetadata(storage: Storage, entryId: string): EntryMetadata;
+/**
+ * Load storage from the driver.
+ */
+declare function loadStorage(driver: EngineDriver): Promise<Storage>;
+/**
+ * Load metadata for an entry (lazy loading).
+ */
+declare function loadMetadata(storage: Storage, driver: EngineDriver, entryId: string): Promise<EntryMetadata>;
+/**
+ * Flush all dirty data to the driver.
+ */
+declare function flush(storage: Storage, driver: EngineDriver, onHistoryUpdated?: () => void): Promise<void>;
+/**
+ * Delete entries with a given location prefix (used for loop forgetting).
+ * Also cleans up associated metadata from both memory and driver.
+ */
+declare function deleteEntriesWithPrefix(storage: Storage, driver: EngineDriver, prefixLocation: Location, onHistoryUpdated?: () => void): Promise<void>;
+/**
+ * Get an entry by location.
+ */
+declare function getEntry(storage: Storage, location: Location): Entry | undefined;
+/**
+ * Set an entry by location.
+ */
+declare function setEntry(storage: Storage, location: Location, entry: Entry): void;
+
+declare const Loop: {
+    continue: <S>(state: S) => {
+        continue: true;
+        state: S;
+    };
+    break: <T>(value: T) => {
+        break: true;
+        value: T;
+    };
+};
+
+declare function runWorkflow<TInput, TOutput>(workflowId: string, workflowFn: WorkflowFunction<TInput, TOutput>, input: TInput, driver: EngineDriver, options?: RunWorkflowOptions): WorkflowHandle<TOutput>;
+
+export { type BranchConfig, type BranchOutput, type BranchStatus, type BranchStatusType, CancelledError, CriticalError, DEFAULT_LOOP_COMMIT_INTERVAL, DEFAULT_LOOP_HISTORY_EVERY, DEFAULT_LOOP_HISTORY_KEEP, DEFAULT_MAX_RETRIES, DEFAULT_RETRY_BACKOFF_BASE, DEFAULT_RETRY_BACKOFF_MAX, DEFAULT_STEP_TIMEOUT, type EngineDriver, type Entry, EntryInProgressError, type EntryKind, type EntryKindType, type EntryMetadata, type EntryStatus, EvictedError, type History, HistoryDivergedError, type JoinEntry, JoinError, type KVEntry, type KVWrite, type Location, Loop, type LoopConfig, type LoopEntry, type LoopIterationMarker, type LoopResult, type Message, type MessageEntry, MessageWaitError, type NameIndex, type PathSegment, type RaceEntry, RaceError, type RemovedEntry, type RollbackCheckpointEntry, RollbackCheckpointError, type RollbackContextInterface, RollbackError, type RunWorkflowOptions, type SleepEntry, SleepError, type SleepState, type StepConfig, type StepEntry, StepExhaustedError, StepFailedError, type Storage, WorkflowContextImpl, type WorkflowContextInterface, type WorkflowEntryMetadataSnapshot, type WorkflowFunction, type WorkflowHandle, type WorkflowHistoryEntry, type WorkflowHistorySnapshot, type WorkflowMessageDriver, type WorkflowQueue, type WorkflowQueueMessage, type WorkflowQueueNextOptions, type WorkflowResult, type WorkflowRunMode, type WorkflowState, appendLoopIteration, appendName, createEntry, createHistorySnapshot, createStorage, deleteEntriesWithPrefix, emptyLocation, flush, generateId, getEntry, getOrCreateMetadata, isLocationPrefix, isLoopIterationMarker, loadMetadata, loadStorage, locationToKey, locationsEqual, parentLocation, registerName, resolveName, runWorkflow, setEntry };