[DO NOT MERGE] CI dry-run: QuickJS as the default workflow VM engine

.changeset/quickjs-default-engine.md

@@ -0,0 +1,5 @@
+---
+'@workflow/core': minor
+---
+
+The QuickJS WASM VM is now the default workflow engine. Set `WORKFLOW_VM=node` to opt back into the `node:vm` engine. Existing runs keep executing on the engine stamped in their `executionContext` at start.

.changeset/quickjs-divergence-parity.md

@@ -0,0 +1,5 @@
+---
+'@workflow/core': patch
+---
+
+QuickJS engine: divergence-detection and write-fencing parity with the node:vm engine. Replays now arbitrate the event log at each fixed point (orphaned events, stepName/token/resumeAt mismatches) and escalate `ReplayDivergenceError` through the existing recovery machinery instead of silently delivering wrong payloads or surfacing corruption as `USER_ERROR`; all replay-context event writes now carry the optimistic-concurrency precondition snapshot (closing the documented KNOWN GAP), with `run_failed` left unfenced to match the node engine.

.changeset/quickjs-threshold-snapshots.md

@@ -0,0 +1,6 @@
+---
+'@workflow/core': minor
+'workflow': minor
+---
+
+Add threshold-based VM-memory snapshotting to the QuickJS engine via `WORKFLOW_SNAPSHOT_THRESHOLD` (or per-run `executionContext.snapshotThreshold`). Once the configured number of events has been processed since the last snapshot, suspensions persist a compressed (and encrypted, when configured) VM snapshot through `world.snapshots`; resumptions restore the VM and replay only the delta events, with automatic fallback to full replay on any load/restore failure. `0` (default) disables snapshotting.

.changeset/world-snapshots-interface.md

@@ -0,0 +1,8 @@
+---
+'@workflow/world': minor
+'@workflow/world-local': minor
+'@workflow/world-postgres': minor
+'@workflow/world-vercel': minor
+---
+
+Add an OPTIONAL `snapshots` storage interface (`save`/`load`/`delete` + `SnapshotMetadata`, plus `encodeSnapshotEnvelope`/`decodeSnapshotEnvelope` helpers that pack metadata and bytes into one atomically-storable blob) for VM-memory snapshotting, with implementations in world-local (single envelope file per run), world-postgres (`workflow_snapshots` table storing the envelope), and world-vercel (workflow-server `/v2/runs/:runId/snapshot` endpoints with W3C trace-context injection; delete is 404-idempotent). Inert until the runtime opts in; community World implementations that don't provide `snapshots` are unaffected (the runtime feature-detects and falls back to full replay).

.github/workflows/tests.yml

@@ -254,9 +254,9 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        # Workflow VM engines: node:vm (default) and the opt-in QuickJS
-        # WASM engine (WORKFLOW_VM=quickjs).
-        vm: [node, quickjs]
+        # Workflow VM engines: QuickJS WASM (the default — WORKFLOW_VM left
+        # unset) and the explicit node:vm opt-in (WORKFLOW_VM=node).
+        vm: [quickjs, node]
     env:
       TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
       TURBO_TEAM: ${{ vars.TURBO_TEAM }}
@@ -278,7 +278,8 @@ jobs:
         run: pnpm test
         working-directory: workbench/vitest
         env:
-          WORKFLOW_VM: ${{ matrix.vm }}
+          # quickjs is the engine default — leave WORKFLOW_VM unset for it.
+          WORKFLOW_VM: ${{ matrix.vm == 'node' && 'node' || '' }}
 
   e2e-package-build:
     name: Build Shared E2E Packages
@@ -331,12 +332,14 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        # Workflow VM engines: node:vm (default) and the opt-in QuickJS
-        # WASM engine. The env var is set on the e2e test runner, which is
-        # the client that starts runs against the deployed app — start()
-        # stamps executionContext.workflowVm so the deployed handler
-        # executes each run on the requested engine.
-        vm: [node, quickjs]
+        # Workflow VM engines: QuickJS WASM (the default — WORKFLOW_VM left
+        # unset so the default-selection path is exercised end to end) and
+        # the explicit node:vm opt-in (WORKFLOW_VM=node). The env var is set
+        # on the e2e test runner, which is the client that starts runs
+        # against the deployed app — start() stamps
+        # executionContext.workflowVm so the deployed handler executes each
+        # run on the requested engine.
+        vm: [quickjs, node]
         app:
           - name: "example"
             project-id: "prj_xWq20Dd860HHAfzMjK2Mb6TPVxMa"
@@ -438,13 +441,16 @@ jobs:
         run: echo "ms=$(($(date +%s) * 1000))" >> "$GITHUB_OUTPUT"
 
       - name: Run E2E Tests
-        run: pnpm run test:e2e --reporter=verbose --reporter=json --reporter=./packages/core/e2e/github-reporter.ts "--outputFile=e2e-vercel-prod-$APP_NAME-$WORKFLOW_VM.json"
+        run: pnpm run test:e2e --reporter=verbose --reporter=json --reporter=./packages/core/e2e/github-reporter.ts "--outputFile=e2e-vercel-prod-$APP_NAME-$MATRIX_VM.json"
         env:
           NODE_OPTIONS: "--enable-source-maps"
           DEPLOYMENT_URL: ${{ steps.waitForDeployment.outputs.deployment-url || steps.prodDeployment.outputs.deployment-url }}
           VERCEL_DEPLOYMENT_ID: ${{ steps.waitForDeployment.outputs.deployment-id || steps.prodDeployment.outputs.deployment-id }}
           APP_NAME: ${{ matrix.app.name }}
-          WORKFLOW_VM: ${{ matrix.vm }}
+          # quickjs is the engine default — leave WORKFLOW_VM unset for it
+          # (MATRIX_VM carries the label for file/job naming).
+          WORKFLOW_VM: ${{ matrix.vm == 'node' && 'node' || '' }}
+          MATRIX_VM: ${{ matrix.vm }}
           # changeset-release PRs test main's production deployment, so they
           # must be treated as a production run everywhere downstream.
           WORKFLOW_VERCEL_ENV: ${{ (github.ref == 'refs/heads/main' || startsWith(github.head_ref, 'changeset-release/')) && 'production' || 'preview' }}
@@ -483,8 +489,8 @@ jobs:
         if: always()
         env:
           APP_NAME: ${{ matrix.app.name }}
-          WORKFLOW_VM: ${{ matrix.vm }}
-        run: node .github/scripts/aggregate-e2e-results.js . --job-name "E2E Vercel Prod ($APP_NAME - $WORKFLOW_VM)" >> $GITHUB_STEP_SUMMARY || true
+          MATRIX_VM: ${{ matrix.vm }}
+        run: node .github/scripts/aggregate-e2e-results.js . --job-name "E2E Vercel Prod ($APP_NAME - $MATRIX_VM)" >> $GITHUB_STEP_SUMMARY || true
 
       - name: Upload E2E results
         if: always()
@@ -882,6 +888,7 @@ jobs:
           WORKFLOW_DEV_HMR_LOGS: "1"
           NEXT_CANARY: ${{ matrix.app.canary && '1' || '' }}
           WORKFLOW_VM: ${{ matrix.app.vm || '' }}
+          WORKFLOW_SNAPSHOT_THRESHOLD: ${{ matrix.app.snapshotThreshold || '' }}
 
       - name: Generate E2E summary
         if: always()
@@ -971,6 +978,7 @@ jobs:
           DEPLOYMENT_URL: "http://localhost:${{ matrix.app.name == 'sveltekit' && '4173' || (matrix.app.name == 'astro' && '4321' || '3000') }}"
           NEXT_CANARY: ${{ matrix.app.canary && '1' || '' }}
           WORKFLOW_VM: ${{ matrix.app.vm || '' }}
+          WORKFLOW_SNAPSHOT_THRESHOLD: ${{ matrix.app.snapshotThreshold || '' }}
 
       - name: Generate E2E summary
         if: always()
@@ -1080,6 +1088,7 @@ jobs:
           DEPLOYMENT_URL: "http://localhost:${{ matrix.app.name == 'sveltekit' && '4173' || (matrix.app.name == 'astro' && '4321' || '3000') }}"
           NEXT_CANARY: ${{ matrix.app.canary && '1' || '' }}
           WORKFLOW_VM: ${{ matrix.app.vm || '' }}
+          WORKFLOW_SNAPSHOT_THRESHOLD: ${{ matrix.app.snapshotThreshold || '' }}
 
       - name: Generate E2E summary
         if: always()
@@ -1103,9 +1112,9 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        # Workflow VM engines: node:vm (default) and the opt-in QuickJS
-        # WASM engine (WORKFLOW_VM=quickjs).
-        vm: [node, quickjs]
+        # Workflow VM engines: QuickJS WASM (the default — WORKFLOW_VM left
+        # unset) and the explicit node:vm opt-in (WORKFLOW_VM=node).
+        vm: [quickjs, node]
     env:
       TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
       TURBO_TEAM: ${{ vars.TURBO_TEAM }}
@@ -1216,7 +1225,9 @@ jobs:
           DEV_TEST_CONFIG: '{"generatedStepRegistrationPath":"app/.well-known/workflow/v1/flow/__step_registrations.js","generatedWorkflowPath":"app/.well-known/workflow/v1/flow/route.js","apiFilePath":"app/api/chat/route.ts","apiFileImportPath":"../../..","port":3000,"testWorkflowFile":"96_many_steps.ts"}'
           DEV_SERVER_LOG_PATH: "${{ github.workspace }}/nextjs-server.log"
           WORKFLOW_DEV_HMR_LOGS: "1"
-          WORKFLOW_VM: ${{ matrix.vm }}
+          # quickjs is the engine default — leave WORKFLOW_VM unset for it
+          # (MATRIX_VM carries the label for reporting).
+          WORKFLOW_VM: ${{ matrix.vm == 'node' && 'node' || '' }}
           MATRIX_VM: ${{ matrix.vm }}
 
       - name: Print Next.js server logs

docs/content/docs/v5/configuration/runtime-tuning.mdx

@@ -165,19 +165,31 @@ For example, a workflow can run a 10-minute inline step even with `WORKFLOW_REPL
 
 ### `WORKFLOW_VM`
 
-- Default: `node`
+- Default: `quickjs`
 - Values: `node` or `quickjs`
 - Selects the sandboxed VM engine that executes workflow functions (`"use workflow"`). Step functions are unaffected — they always run with full Node.js access.
-- `node` (default) runs workflow code in a [`node:vm`](https://nodejs.org/api/vm.html) context.
-- `quickjs` (experimental) runs workflow code in a [QuickJS](https://github.com/quickjs-ng/quickjs) VM compiled to WebAssembly (via [`quickjs-wasi`](https://github.com/vercel-labs/quickjs-wasi)). Both engines implement the same event-replay execution model (seeded PRNG, deterministic clock, and correlation-ID sequences are identical), but the **global surface is not identical** — see the differences below before switching an existing deployment. The QuickJS engine is intended for platforms that do not implement `node:vm`, and is the foundation for future VM-memory snapshotting.
-- Global-surface differences under `quickjs` (workflow functions only — step functions always have full Node.js):
+- `quickjs` (default) runs workflow code in a [QuickJS](https://github.com/quickjs-ng/quickjs) VM compiled to WebAssembly (via [`quickjs-wasi`](https://github.com/vercel-labs/quickjs-wasi)). It works on platforms that do not implement `node:vm` (e.g. edge runtimes), and is the foundation for VM-memory snapshotting.
+- `node` runs workflow code in a [`node:vm`](https://nodejs.org/api/vm.html) context instead. Both engines implement the same event-replay execution model (seeded PRNG, deterministic clock, and correlation-ID sequences are identical), but the **global surface is not identical** — review the differences below before flipping an existing deployment either direction.
+- Global-surface differences under `quickjs` relative to `node` (workflow functions only — step functions always have full Node.js):
   - `crypto.getRandomValues()` and `crypto.randomUUID()` are provided and deterministic (seeded like the node engine's). All `crypto.subtle.*` methods throw with guidance to move to a step function — including `digest`, which the node engine supports.
   - `Intl` is not available (QuickJS has no ICU). The `Intl.*` constructors throw, and `toLocaleString`-family methods (including `localeCompare`) throw when called **with an explicit locale** — calling them without arguments keeps the engine default. Perform locale-sensitive formatting in a step function.
   - `WebAssembly` and `Atomics` are not available.
   - `process` exposes only a frozen copy of `env`, matching the node engine.
 - The engine choice is stamped into the run's `executionContext` when the run starts, so a run keeps executing on the engine it started on even if the deployment's `WORKFLOW_VM` changes. Runs without a stamped engine use the handler's `WORKFLOW_VM` value.
 - Unknown values throw at startup.
 
+### `WORKFLOW_SNAPSHOT_THRESHOLD`
+
+- Default: `0` (disabled)
+- Values: non-negative integer
+- Only used by the QuickJS engine (the default; see `WORKFLOW_VM`).
+- When set above `0`, the runtime persists a **VM-memory snapshot** at a suspension once at least this many events have been processed since the last snapshot. Subsequent invocations restore the VM from the snapshot and replay only the events recorded since — instead of re-executing the workflow from the top against the full event log.
+- Short-lived runs below the threshold never pay the snapshot cost; long-running or unbounded runs stop scaling their resume cost with total event-log length. `1` snapshots at every qualifying suspension.
+- Snapshots are an optimization, not a source of truth: the event log remains authoritative, and a missing, corrupt, or incompatible snapshot automatically falls back to a full replay.
+- Snapshot bytes are compressed (zstd, gzip fallback) and encrypted with the run's encryption key (when configured) before being handed to the World's `snapshots` storage. They are deleted when the run reaches a terminal state.
+- Like `WORKFLOW_VM`, the policy is stamped into the run's `executionContext` at start, so a run keeps the snapshot policy it started with.
+- Invalid values throw at startup.
+
 ## Compression and tracing
 
 ### `WORKFLOW_DISABLE_COMPRESSION`

packages/core/scripts/build-quickjs-assets.js

@@ -32,6 +32,16 @@ const files = {
   structuredCloneSo: require_.resolve('quickjs-wasi/structured-clone.so'),
 };
 
+// The installed quickjs-wasi version identifies the exact WASM build the
+// base64 blobs below came from. Persisted into VM snapshot metadata and
+// compared on restore: the QJSS heap-image header is identical across
+// builds, so without this pin a snapshot taken by one build would restore
+// under another and execute as undefined behavior in the interpreter
+// (real hazard during a rolling deploy that bumps quickjs-wasi).
+const quickjsWasiVersion = JSON.parse(
+  readFileSync(require_.resolve('quickjs-wasi/package.json'), 'utf8')
+).version;
+
 let output = `/**
  * Auto-generated by scripts/build-quickjs-assets.js
  * Do not edit manually.
@@ -74,6 +84,14 @@ for (const [name, filePath] of Object.entries(files)) {
 
 output += `export { quickjsWasm };\n\n`;
 
+output += `/**
+ * The quickjs-wasi package version these embedded binaries came from.
+ * Persisted into VM snapshot metadata (engineVersion) and compared on
+ * restore — a heap image only restores under the exact WASM build that
+ * produced it (the QJSS header does not distinguish builds).
+ */
+export const quickjsWasiVersion = ${JSON.stringify(quickjsWasiVersion)};\n\n`;
+
 output += `export const quickjsExtensions: ExtensionDescriptor[] = [
   { name: 'encoding', wasm: encodingSo },
   { name: 'headers', wasm: headersSo },

packages/core/src/runtime-trace-mode.test.ts

@@ -33,6 +33,12 @@ import { workflowEntrypoint } from './runtime.js';
 import { dehydrateWorkflowArguments } from './serialization.js';
 import { getNextTraceCarrier, getWorkflowTraceMode } from './telemetry.js';
 
+// These tests exercise the node:vm engine's replay loop internals against
+// mock worlds. Pin the engine explicitly — QuickJS is the default, and
+// dispatching there would instantiate a WASM VM per entrypoint call (and
+// bypass the node replay loop these tests assert on).
+process.env.WORKFLOW_VM = 'node';
+
 vi.mock('@vercel/functions', () => ({
   waitUntil: vi.fn((p: Promise<unknown>) => {
     p.catch(() => {});

packages/core/src/runtime.test.ts

@@ -25,6 +25,12 @@ import {
   hydrateRunError,
 } from './serialization.js';
 
+// These tests exercise the node:vm engine's replay loop internals against
+// mock worlds. Pin the engine explicitly — QuickJS is the default, and
+// dispatching there would instantiate a WASM VM per entrypoint call (and
+// bypass the node replay loop these tests assert on).
+process.env.WORKFLOW_VM = 'node';
+
 // Capture every promise handed to `waitUntil` so tests can assert that
 // progress-critical sends are never registered on a detached, unconsumed
 // promise (which would reject → unhandled rejection → process exit 128, and

packages/core/src/runtime/precondition-guard-replay.test.ts

@@ -46,6 +46,12 @@ import {
 } from './constants.js';
 import { setWorld } from './world.js';
 
+// These tests exercise the node:vm engine's replay loop internals against
+// mock worlds. Pin the engine explicitly — QuickJS is the default, and
+// dispatching there would instantiate a WASM VM per entrypoint call (and
+// bypass the node replay loop these tests assert on).
+process.env.WORKFLOW_VM = 'node';
+
 vi.mock('@vercel/functions', () => ({
   waitUntil: vi.fn(),
 }));