perf(core): retain workflow VM across inline steps (primitives-gated)

.changeset/retain-workflow-vm.md

@@ -0,0 +1,6 @@
+---
+'@workflow/core': minor
+'workflow': minor
+---
+
+Retain workflow execution across inline steps within one invocation; `WORKFLOW_RETAINED_VM=0` disables retention. Boundaries whose step arguments are not primitive values fall back to ordinary replay.

docs/content/docs/v5/api-reference/workflow-serde/workflow-serialize.mdx

@@ -69,6 +69,7 @@ This method runs inside the workflow context and is subject to the same constrai
 - No Node.js-specific APIs (like `fs`, `path`, `crypto`, etc.)
 - No non-deterministic operations (like `Math.random()` or `Date.now()`)
 - No external network calls
+- No side effects on workflow state — the method may run outside deterministic replay, so mutations would not be reconstructed
 
 Keep this method simple and focused on extracting data from the instance.
 </Callout>

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

@@ -96,6 +96,14 @@ For example, a workflow can run a 10-minute inline step even with `WORKFLOW_REPL
 - Use only when step side effects are idempotent.
 - Set `0` or `false` to force it off, including the first-delivery fast path used by `WORKFLOW_TURBO`.
 
+### `WORKFLOW_RETAINED_VM`
+
+- Default: enabled
+- Keeps the suspended workflow VM alive across inline steps within one invocation, so each iteration of the inline loop appends only the newly written events instead of replaying the whole event log in a fresh VM.
+- Suspensions involving hooks, waits, or attributes — and any replay divergence — always fall back to a full replay.
+- Step inputs of primitive values remain retainable; anything whose serialization could execute workflow code falls back to replay for that boundary. (Support for plain objects, arrays, and standard built-ins lands in a follow-up.)
+- Set `0` or `false` to replay from scratch in a fresh VM on every iteration.
+
 ### `WORKFLOW_INLINE_OWNERSHIP`
 
 - Default: enabled

packages/core/e2e/e2e.test.ts

@@ -445,6 +445,31 @@ describe('e2e', () => {
     expect(returnValue).toBe('B');
   });
 
+  // Interleaves VM-retention modes: retained boundaries (primitive step
+  // args), demoted boundaries (object args), sleeps, a step-vs-sleep race,
+  // and a hook resolved in parallel with a step. Asserts the exact composite
+  // result so a dropped/duplicated/misordered boundary fails loudly.
+  test('retainedInterleavingWorkflow', { timeout: 90_000 }, async () => {
+    const token = Math.random().toString(36).slice(2);
+    const run = await start(await e2e('retainedInterleavingWorkflow'), [token]);
+
+    const hook = await waitForHook(token, { runId: run.runId });
+    await resumeHook(hook, { delta: 5 });
+
+    const returnValue = await run.returnValue;
+    expect(returnValue).toEqual({
+      a: 3,
+      b: 3,
+      c: 13,
+      d: 23,
+      e: 13,
+      f: 24,
+      winner: 'step',
+      g: 137,
+      h: 142,
+    });
+  });
+
   test.skipIf(!isNext)(
     'importedStepOnlyWorkflow',
     { timeout: 60_000 },

packages/core/src/delivery-barrier-coverage.test.ts

@@ -72,6 +72,7 @@ function setupWorkflowContext(events: Event[]): WorkflowOrchestratorContext {
   const promiseQueueHolder = { current: Promise.resolve() };
   const ctxRef: { current?: WorkflowOrchestratorContext } = {};
   const ctx: WorkflowOrchestratorContext = {
+    suspensionGeneration: 0,
     runId: 'wrun_test',
     encryptionKey: undefined,
     replayPayloadCache: new ReplayPayloadCache(undefined),

packages/core/src/events-consumer.ts

@@ -69,7 +69,7 @@ export interface EventsConsumerOptions {
 
 export class EventsConsumer {
   eventIndex: number;
-  readonly events: Event[] = [];
+  readonly events: Event[];
   readonly callbacks: EventConsumerCallback[] = [];
   private onConsumedEvent?: (event: Event) => void;
   private onUnconsumedEvent: (event: Event) => void;
@@ -79,13 +79,21 @@ export class EventsConsumer {
   private unconsumedCheckVersion = 0;
 
   constructor(events: Event[], options: EventsConsumerOptions) {
-    this.events = events;
+    // Own copy: the runtime mutates its event array in place, and a retained
+    // session must only observe new events through append() so resume()'s
+    // strict-extension check stays meaningful.
+    this.events = [...events];
     this.eventIndex = 0;
     this.onConsumedEvent = options.onConsumedEvent;
     this.onUnconsumedEvent = options.onUnconsumedEvent;
     this.getPromiseQueue = options.getPromiseQueue;
   }
 
+  append(events: Event[]): void {
+    for (const event of events) this.events.push(event);
+    process.nextTick(this.consume);
+  }
+
   /**
    * Registers a callback function to be called after an event has been consumed
    * by a different callback. The callback can return:

packages/core/src/hook-sleep-interaction.test.ts

@@ -42,6 +42,7 @@ function setupWorkflowContext(events: Event[]): WorkflowOrchestratorContext {
   // silently dropping them.
   const ctxRef: { current?: WorkflowOrchestratorContext } = {};
   const ctx: WorkflowOrchestratorContext = {
+    suspensionGeneration: 0,
     runId: 'wrun_test',
     encryptionKey: undefined,
     replayPayloadCache: new ReplayPayloadCache(undefined),

packages/core/src/private.ts

@@ -135,6 +135,16 @@ export interface WorkflowOrchestratorContext {
   encryptionKey: PayloadKey | undefined;
   worldCapabilities?: WorldCapabilities;
   globalThis: typeof globalThis;
+  /**
+   * Increments when a suspension is accepted and on every retained-session
+   * resume. STEP suspension signals capture it when scheduled and no-op if
+   * it moved (see step.ts) — this drops same-boundary sibling signals and
+   * timers queued at boundary N that would fire after the session resumed
+   * into boundary N+1. Sleep/hook/attribute signals are intentionally
+   * unguarded: their presence makes the boundary unretainable, so a late
+   * signal correctly demotes the session (workflow.ts `onWorkflowError`).
+   */
+  suspensionGeneration: number;
   eventsConsumer: EventsConsumer;
   /**
    * Map of pending invocations keyed by correlationId.