eve 0.31.0 → 0.31.2

package/dist/src/compiled/@workflow/core/runtime/quickjs-runtime.d.ts

@@ -0,0 +1,193 @@
+/**
+ * QuickJS WASM workflow VM.
+ *
+ * An alternative engine for the event-replay execution model: the workflow
+ * code runs inside a QuickJS WASM VM (via quickjs-wasi) instead of a
+ * `node:vm` context. Every invocation creates a fresh VM, re-executes the
+ * workflow function from the top, and replays the recorded event log to
+ * resolve awaited primitives — the same replay semantics as the `node:vm`
+ * engine.
+ *
+ * The workflow primitives (useStep, sleep, createHook) are implemented as
+ * JavaScript code running inside the QuickJS VM. The host communicates with
+ * the VM by evaluating small JS snippets to read pending operations and
+ * resolve/reject promises.
+ *
+ * The VM bootstrap is deliberately split into two phases:
+ *   1. Static initialization (`initWorkflowVM`) — run-independent setup:
+ *      VM creation, the serde bundle, and the workflow primitives.
+ *   2. Per-run initialization (inline in `runQuickJSWorkflow`) — seeded
+ *      PRNG/ULID host functions, workflow bundle evaluation, run metadata,
+ *      workflow input, and start.
+ * Keeping the phases separate is groundwork for VM-memory snapshotting:
+ * a follow-up can persist/restore the VM at the phase boundary (e.g. a
+ * build-time initial snapshot) without restructuring this module. Note
+ * that bundle evaluation currently sits in the per-run phase so that
+ * module-scope user code observes the seeded `Math.random`, matching the
+ * `node:vm` engine's replay determinism.
+ */
+import type { Event, RunInput, WorkflowRun, WorldCapabilities } from '#compiled/@workflow/world/index.js';
+import type { DecryptionKey } from '../serialization/encryption.js';
+export interface PendingStep {
+    type: 'step';
+    correlationId: string;
+    stepId: string;
+    /** Format-prefixed devalue-serialized step input (args + closureVars) */
+    input: Uint8Array;
+    /** Whether a step_created event already exists for this step */
+    hasCreatedEvent: boolean;
+}
+export interface PendingWait {
+    type: 'wait';
+    correlationId: string;
+    /** ISO string of when to resume */
+    resumeAt: string;
+    /** Whether a wait_created event already exists for this wait */
+    hasCreatedEvent: boolean;
+}
+export interface PendingHook {
+    type: 'hook';
+    correlationId: string;
+    token: string;
+    /** Earliest token reuse time, as milliseconds since the Unix epoch. */
+    tokenRetentionUntil?: number;
+    isWebhook: boolean;
+    metadata?: unknown;
+    hasCreatedEvent: boolean;
+    /**
+     * True for internal system hooks (e.g. AbortController's hook), which
+     * are exempt from user-hook token namespace conflict checks.
+     */
+    isSystem?: boolean;
+    /**
+     * Set when the workflow called AbortController.abort() during this
+     * invocation. The host must record the abort: create a hook_received
+     * event carrying `abortPayload` and write/close the abort stream.
+     */
+    abortRequested?: boolean;
+    /** VM-serialized `{ aborted: true, reason }` payload for the abort. */
+    abortPayload?: Uint8Array;
+    /** Set by the completion drain when a system hook is implicitly disposed. */
+    disposed?: boolean;
+    /**
+     * True when the workflow is awaiting hook.getConflict() for this hook.
+     * The entrypoint re-invokes the workflow right after writing
+     * hook_created so replay can confirm creation and resolve the awaiter.
+     */
+    hasGetConflictAwaiter?: boolean;
+}
+export interface PendingAttribute {
+    type: 'attribute';
+    correlationId: string;
+    /** Normalized attribute changes (plain JSON-able objects) */
+    changes: unknown[];
+    allowReservedAttributes?: boolean;
+    /** Whether an attr_set event already exists for this write */
+    hasCreatedEvent: boolean;
+}
+export interface PendingHookDispose {
+    type: 'hook_dispose';
+    correlationId: string;
+    /**
+     * Token of the hook being disposed. Used by the entrypoint to order
+     * same-token hook operations sequentially in code order.
+     */
+    token?: string;
+    hasCreatedEvent: boolean;
+}
+export type PendingOperation = PendingStep | PendingWait | PendingHook | PendingAttribute | PendingHookDispose;
+export interface QuickJSRuntimeResult {
+    /** The workflow completed — result is format-prefixed devalue bytes */
+    completed?: {
+        result: Uint8Array;
+        /**
+         * Leftover pending operations that still need durable side effects at
+         * completion: abort recordings, system-hook disposals, fire-and-forget
+         * attribute/hook/step events. Mirrors the node:vm engine's
+         * drainPendingQueueItems. The entrypoint dispatches these WITHOUT
+         * queueing steps or requeuing the run.
+         */
+        drainOperations?: PendingOperation[];
+    };
+    /** The workflow suspended with pending operations */
+    suspended?: {
+        pendingOperations: PendingOperation[];
+    };
+    /** The workflow failed */
+    failed?: {
+        message: string;
+        stack?: string;
+        name?: string;
+        /** See completed.drainOperations — same semantics on failure. */
+        drainOperations?: PendingOperation[];
+        /**
+         * Format-prefixed devalue bytes of the original thrown value
+         * (Error subclass with cause chain, plain object, primitive, etc.).
+         * Set when the VM-side rejection handler successfully serializes
+         * the thrown value. The host uses these bytes to reconstruct the
+         * original value through the standard error hydration pipeline,
+         * preserving type identity (TypeError, FatalError) and non-Error
+         * throws verbatim. Falls back to the message/stack/name fields
+         * when this is undefined (e.g. extractError pseudo-failures).
+         */
+        valueBytes?: Uint8Array;
+    };
+}
+export interface QuickJSRuntimeOptions {
+    /** The compiled workflow bundle code (workflow mode output from SWC) */
+    workflowCode: string;
+    /** The workflow ID (e.g. "workflow//./workflows/1_simple//simple") */
+    workflowId: string;
+    /** The workflow run entity */
+    workflowRun: WorkflowRun;
+    /** Features supported by the World executing this workflow. */
+    worldCapabilities?: WorldCapabilities;
+    /**
+     * The full event log for the run. Every invocation replays the complete
+     * log from the start (same replay semantics as the `node:vm` engine).
+     */
+    events: Event[];
+    /** Encryption key for decrypting event payloads (undefined if unencrypted) */
+    encryptionKey?: DecryptionKey;
+    /**
+     * The local port the workflow server is listening on, used to populate
+     * `workflowMetadata.url`. Resolved at call time on the host side so the
+     * VM doesn't have to probe the filesystem. Ignored on Vercel — VERCEL_URL
+     * takes precedence there.
+     */
+    port?: number;
+    /**
+     * Fallback workflow input from the queue message's resilient-start
+     * payload. Used when the fetched event log lacks a `run_created` event
+     * (eventually-consistent read after the parent's start() wrote it).
+     */
+    runInput?: RunInput;
+}
+/**
+ * A live QuickJS workflow invocation. When the initial `result` is
+ * `suspended`, the VM is kept alive so the caller can feed newly recorded
+ * events (e.g. terminal events of inline-executed steps) into the SAME VM
+ * via `continueWithEvents` — resuming execution exactly where it left off
+ * without a fresh-VM re-replay. Terminal results dispose the VM
+ * automatically; `dispose()` must be called when abandoning a suspended
+ * session (idempotent).
+ */
+export interface QuickJSWorkflowSession {
+    result: QuickJSRuntimeResult;
+    /**
+     * Process newly recorded events in the live VM and re-evaluate the
+     * workflow state. Only valid while the last result was `suspended`.
+     * Resets the VM's interrupt budget for the new execution burst.
+     */
+    continueWithEvents(newEvents: Event[]): Promise<QuickJSRuntimeResult>;
+    /** Dispose the VM if it is still alive. Safe to call multiple times. */
+    dispose(): void;
+}
+/**
+ * Run a workflow invocation to its first settled state and dispose the
+ * VM. Convenience wrapper over {@link startQuickJSWorkflow} for callers
+ * (and tests) that don't use live-VM continuation.
+ */
+export declare function runQuickJSWorkflow(options: QuickJSRuntimeOptions): Promise<QuickJSRuntimeResult>;
+export declare function startQuickJSWorkflow(options: QuickJSRuntimeOptions): Promise<QuickJSWorkflowSession>;
+//# sourceMappingURL=quickjs-runtime.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/run.d.ts

@@ -1,6 +1,8 @@
 import { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from '../_workflow-serde.js';
 import { type WorkflowRunStatus } from '#compiled/@workflow/world/index.js';
 import { type CancelRunOptions, type StopSleepOptions, type StopSleepResult } from './runs.js';
+/** @internal */
+export declare function getReturnValuePollIntervalMs(): number;
 /**
  * A `ReadableStream` extended with workflow-specific helpers.
  */

package/dist/src/compiled/@workflow/core/runtime/runs.d.ts

@@ -1,4 +1,4 @@
-import { type World } from '#compiled/@workflow/world/index.js';
+import { type BulkCancelWorkflowRunsResult, type World } from '#compiled/@workflow/world/index.js';
 export interface RecreateRunOptions {
     deploymentId?: string;
     specVersion?: number;
@@ -64,6 +64,23 @@ export declare function recreateRunFromExisting(world: World, runId: string, opt
  *   free-text reason (max 512 chars) on the run_cancelled event.
  */
 export declare function cancelRun(world: World, runId: string, options?: CancelRunOptions): Promise<void>;
+/**
+ * Cancel many runs in one call.
+ *
+ * Fast path: if the world implements `runs.cancelMany`, the whole batch is
+ * delegated to it in a single operation (one backend round-trip on
+ * `@workflow/world-vercel`).
+ *
+ * Fallback: for worlds without `cancelMany`, this issues single-run
+ * `cancelRun()` calls with at most {@link CANCEL_RUNS_FALLBACK_CONCURRENCY}
+ * in flight at a time. Fallback successes are reported as `cancelled`;
+ * failures are reported as `failed` with `code: 'internal_error'` and
+ * `retryable: true` — deliberately without per-world error classification.
+ *
+ * @throws if `runIds` is empty, contains duplicates, or exceeds
+ *   {@link BULK_CANCEL_MAX_RUN_IDS}.
+ */
+export declare function cancelRuns(world: World, runIds: string[], options?: CancelRunOptions): Promise<BulkCancelWorkflowRunsResult>;
 /**
  * Re-enqueue a workflow run.
  */

package/dist/src/compiled/@workflow/core/runtime/suspension-handler.d.ts

@@ -98,6 +98,13 @@ export interface SuspensionHandlerResult {
      * durably creating the user's hooks doesn't count as runtime overhead.
      */
     hookCreationMs: number;
+    /**
+     * Whether serializing this suspension's new step inputs was passive (did
+     * not execute workflow-owned code such as getters, proxy traps, or custom
+     * serializers). `false` means the retained VM may have diverged from what
+     * a cold replay would compute, so the caller must demote to replay.
+     */
+    retainedStepInputsSafe: boolean;
 }
 /**
  * Handles a workflow suspension by processing all pending operations (hooks, steps, waits).

package/dist/src/compiled/@workflow/core/runtime/vm-mode.d.ts

@@ -0,0 +1,44 @@
+/**
+ * VM engine selection for workflow execution.
+ *
+ * The Node.js `node:vm` engine is the default. The QuickJS WASM engine is
+ * opt-in via the `WORKFLOW_VM` env var or `executionContext.workflowVm`.
+ *
+ * Both engines implement the same event-replay execution model: on every
+ * workflow handler invocation the workflow function is re-executed from the
+ * top and the recorded event log resolves awaited primitives. The QuickJS
+ * engine runs the workflow code in a QuickJS WASM VM (via quickjs-wasi)
+ * instead of a `node:vm` context, which makes it usable on platforms that
+ * do not implement `node:vm` (e.g. Cloudflare Workers) and is the
+ * foundation for VM-memory snapshotting.
+ */
+import type { WorkflowRun } from '#compiled/@workflow/world/index.js';
+/**
+ * Known workflow VM engines. Any other `WORKFLOW_VM` value is treated as
+ * a misconfiguration and rejected at startup.
+ */
+export declare const WORKFLOW_VMS: readonly ["node", "quickjs"];
+export type WorkflowVmMode = (typeof WORKFLOW_VMS)[number];
+/**
+ * Read and validate the `WORKFLOW_VM` env var.
+ *
+ * Returns the configured engine, or `undefined` if unset/empty.
+ * Throws {@link WorkflowRuntimeError} if the value is set but not one of
+ * the known engines — catching misconfiguration early is better than
+ * silently falling back to the default.
+ */
+export declare function getWorkflowVmFromEnv(env?: NodeJS.ProcessEnv): WorkflowVmMode | undefined;
+/**
+ * Whether to use the QuickJS WASM VM for a given run.
+ *
+ * The run's `executionContext.workflowVm` (stamped by the SDK at `start()`
+ * when `WORKFLOW_VM` is set on the client) takes precedence so a run keeps
+ * executing on the engine it started on. When the run doesn't specify an
+ * engine, the `WORKFLOW_VM` env var on the workflow handler decides.
+ * The default is the `node:vm` engine.
+ *
+ * Throws if `WORKFLOW_VM` or `executionContext.workflowVm` is set to an
+ * unknown value.
+ */
+export declare function useQuickJSVm(workflowRun: WorkflowRun): boolean;
+//# sourceMappingURL=vm-mode.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/vm-serde-bundle.generated.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Auto-generated by scripts/build-vm-serde-bundle.js
+ * Do not edit manually.
+ *
+ * This is the VM serialization bundle — a self-contained IIFE that sets up
+ * the serialize/deserialize functions inside the QuickJS WASM VM. It
+ * includes devalue and all workflow-mode reducers/revivers. (TextEncoder,
+ * TextDecoder, and Headers are provided by quickjs-wasi's native C
+ * extensions — no JS polyfills are bundled.)
+ *
+ * Size: 25.6 KB minified
+ */
+export declare const VM_SERDE_BUNDLE: string;
+//# sourceMappingURL=vm-serde-bundle.generated.d.ts.map

package/dist/src/compiled/@workflow/core/runtime.d.ts

@@ -4,7 +4,7 @@ export { WorkflowSuspension } from './global.js';
 export { type HealthCheckOptions, type HealthCheckResult, healthCheck, } from './runtime/helpers.js';
 export { getHookByToken, type ResumedHook, resumeHook, resumeWebhook, } from './runtime/resume-hook.js';
 export { getRun, Run, type WorkflowReadableStream, type WorkflowReadableStreamOptions, } from './runtime/run.js';
-export { type CancelRunOptions, cancelRun, listStreams, type ReadStreamOptions, type RecreateRunOptions, type ReenqueueRunOptions, readStream, recreateRunFromExisting, reenqueueRun, type StopSleepOptions, type StopSleepResult, wakeUpRun, } from './runtime/runs.js';
+export { type CancelRunOptions, cancelRun, cancelRuns, listStreams, type ReadStreamOptions, type RecreateRunOptions, type ReenqueueRunOptions, readStream, recreateRunFromExisting, reenqueueRun, type StopSleepOptions, type StopSleepResult, wakeUpRun, } from './runtime/runs.js';
 export { type StartOptions, type StartOptionsBase, type StartOptionsWithDeploymentId, type StartOptionsWithoutDeploymentId, start, } from './runtime/start.js';
 export { createWorld, createWorldFromModule, getWorld, getWorldHandlers, setWorld, type WorldFactoryModule, } from './runtime/world.js';
 /**