@workflow/core 5.0.0-beta.4 → 5.0.0-beta.41

package/dist/runtime/quickjs-runtime.d.ts

@@ -0,0 +1,228 @@
+/**
+ * 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 and the workflow primitives. (Serialization lives on
+ *      the host — see quickjs-serde.ts — so no serde code is evaluated
+ *      in the VM.)
+ *   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 '@workflow/world';
+import { type Snapshot } from 'quickjs-wasi';
+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;
+}
+/**
+ * Eval filename used when hydrating the baseline VM. The baseline is
+ * shared by EVERY workflow in the bundle, so the filename baked into
+ * its compiled code (and therefore into snapshot-path stack frames)
+ * must be workflow-independent — hydrating under the first caller's
+ * workflowId would break `remapErrorStack`'s filename matching for
+ * every other workflow in the bundle. Remap call sites match this
+ * constant IN ADDITION to the run's module specifier (which covers
+ * fresh-path frames).
+ */
+export declare const BASELINE_BUNDLE_FILENAME = "workflow-bundle.js";
+type BaselineEntry = {
+    state: 'ready';
+    snapshot: Snapshot;
+    /**
+     * Raw box pointer of the serde capture root created BEFORE the
+     * bundle evaluated (see captureSerdeRoot). The box lives in the
+     * snapshot's memory image at this offset; every restored VM
+     * re-adopts it so serde initialization executes no guest code
+     * after user code has run — capture-before-user-code semantics,
+     * identical to the fresh path.
+     */
+    serdeRootPtr: number;
+} | {
+    state: 'ineligible';
+    reason: string;
+};
+/** Test-only: reset the baseline cache between test cases. */
+export declare function __clearBaselineSnapshotCacheForTests(): void;
+/** Test-only: observe how a bundle was classified. */
+export declare function __peekBaselineEntryForTests(workflowCode: string): Promise<BaselineEntry | undefined>;
+/**
+ * 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>;
+export {};
+//# sourceMappingURL=quickjs-runtime.d.ts.map

package/dist/runtime/quickjs-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quickjs-runtime.d.ts","sourceRoot":"","sources":["../../src/runtime/quickjs-runtime.ts"],"names":[],"mappings":"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"}