[core] [nextjs] Fix world.ts being tree-shaken out of the bundle and unavailable at runtime (#1951)

Author: VaguelySerious

.changeset/world-init-cold-start.md

@@ -0,0 +1,6 @@
+---
+"@workflow/core": patch
+"workflow": patch
+---
+
+Fix `world.ts` being tree-shaken out of the bundle and unavailable at runtime

docs/content/docs/v5/changelog/eager-processing.mdx

@@ -532,6 +532,28 @@ Additional changes for Turbopack compatibility:
 - Lazy-loaded `getPort` via `createRequire` with opaque specifier to prevent `@workflow/utils/get-port` filesystem operations from being traced
 - `getRuntimeRequire()` uses `process.cwd()` as primary resolution base (for custom world packages like `@workflow/world-postgres` that are app-level deps, not `@workflow/core` deps), with `import.meta.url` fallback
 
+### Cold-Start `MODULE_NOT_FOUND: './world.js'` From `getWorldLazy` Fallback
+
+The `getWorldLazy()` design assumed one of two paths would always succeed: either `globalThis[GetWorldFnKey]` is populated (because some prior code reached `world.ts`'s module body), or the dynamic `import('./world.js')` fallback resolves at runtime.
+
+Both assumptions break for routes that consume `start` (or any other `getWorldLazy` consumer) without going through the queue-driven flow handler first:
+
+1. Webpack and Turbopack tree-shake the named import `{ getWorld } from './runtime/world.js'` out of `runtime.ts` once a consumer only uses `start`. `world.ts` is dropped from the bundle entirely, so its module-load `globalThis[GetWorldFnKey] ??= getWorld` registration never fires.
+2. The dynamic-import fallback inside `get-world-lazy.ts` builds the specifier `./world.js` at runtime to evade bundler tracing — but webpack inlines `get-world-lazy.js` into the route bundle, so the relative specifier resolves against `/var/task/<app>/.next/server/app/<route>/route.js` where no sibling `world.js` exists. Node throws `MODULE_NOT_FOUND`.
+
+The symptom: the very first request that goes through `start()` on a cold serverless invocation fails. Once any other code path (typically the queue-driven `/.well-known/workflow/v1/flow` route, which uses `getWorld` directly via `workflowEntrypoint`) has loaded `world.ts`, subsequent `start()` calls succeed for the rest of the process lifetime — making the failure flake-shaped: hard to reproduce in dev where everything tends to be warmed, but reliable on first user traffic into a fresh function instance.
+
+**Fix**: Added `@workflow/core/runtime/world-init`, a server-only side-effect module that imports `./world.js` purely for its module-load side effect (the globalThis registration). It's exported via package conditions:
+
+- `default` → `./dist/runtime/world-init.js` (real, loads `world.ts`)
+- `workflow` → `./dist/workflow/world-init-stub.js` (empty, used by VM/step bundles)
+
+`packages/workflow/src/api.ts` (the host file behind `workflow/api`'s `default` condition) imports it for its side effect. The matching VM/step entry `api-workflow.ts` does not, so `world.ts` and its server-only deps (`@workflow/world-local`, `@workflow/world-vercel`, `cbor-x`, …) stay out of the workflow sandbox bundle.
+
+Reverification: built bundles for `vade-review` (Next.js webpack) show `createLocalWorld`/`createVercelWorld`/`GetWorldFnKey` present in the route's vendor chunk for `@workflow/core` (zero before the fix), and the workflow VM bundle's `flow/route.js` and `__step_registrations.js` continue to have zero references to either the world-init module or `world.ts`. Cold-start `POST /api/review/submit` succeeds on the first request after a fresh server boot — the regression case.
+
+The dynamic-import fallback in `get-world-lazy.ts` is preserved as defense-in-depth for environments outside the documented configurations (CJS test runners, scripts that import deeply into `@workflow/core` without going through `workflow/api`).
+
 ### Run#returnValue Worker Deadlock in V2 Inline Execution
 
 When a workflow calls `start()` to spawn child workflows (e.g., `fibonacciWorkflow`), the parent's `Run#returnValue` step polls the child's completion status in a blocking loop (`while (true) { ... sleep(1000) ... }`). In V2, this step is executed inline by the step executor, holding a worker thread slot. If the child workflow's queue message is waiting for the same worker pool, the parent blocks the child from starting — a classic deadlock.

packages/core/package.json

@@ -48,6 +48,11 @@
       "types": "./dist/runtime/resume-hook.d.ts",
       "default": "./dist/runtime/resume-hook.js"
     },
+    "./runtime/world-init": {
+      "types": "./dist/runtime/world-init.d.ts",
+      "workflow": "./dist/workflow/world-init-stub.js",
+      "default": "./dist/runtime/world-init.js"
+    },
     "./class-serialization": {
       "types": "./dist/class-serialization.d.ts",
       "default": "./dist/class-serialization.js"

packages/core/src/runtime.ts

@@ -680,7 +680,7 @@ export function workflowEntrypoint(
                         // when there are events, so this signals a bug in
                         // the World. Fall back to a full reload to avoid
                         // stale data.
-                        runtimeLogger.error(
+                        runtimeLogger.warn(
                           'Event cursor missing after initial load — falling back to full reload. ' +
                             'This indicates a bug in the World implementation.',
                           { workflowRunId: runId }

packages/core/src/runtime/get-world-lazy.ts

@@ -7,10 +7,25 @@
  * world-vercel, process.cwd(), etc.) into the step registrations bundle,
  * which triggers Turbopack NFT tracing errors in the V2 combined flow route.
  *
- * When the world is not yet cached, falls back to a dynamic import() of
- * ./world.js to initialize the world. The dynamic import is fine here
- * because get-world-lazy.ts is NOT in the step registrations bundle — it's
- * only used by modules that are already importing from this directory.
+ * Resolution order, in priority:
+ *
+ * 1. `globalThis[WorldCacheKey]` — populated by a successful prior
+ *    `getWorld()` call. This is the steady-state hot path.
+ * 2. `globalThis[GetWorldFnKey]` — populated by the module-load side
+ *    effect at the bottom of `./world.ts`. Fires on every server bundle
+ *    that reaches this file via `workflow/api` (which imports
+ *    `./world-init.ts` for its side effect; see that file for the full
+ *    rationale). This is the cold-start path for routes that consume
+ *    `start` without any prior workflow run.
+ * 3. Dynamic `import('./world.js')` — last-resort fallback for
+ *    environments where neither (1) nor (2) is available (CJS test
+ *    runners, scripts that import deeply into `@workflow/core` without
+ *    going through `workflow/api`, future bundlers we haven't validated).
+ *    The specifier is built at runtime so esbuild can't trace it into
+ *    step bundles. Note: this branch is unreliable in webpack-bundled
+ *    routes because webpack inlines this module into the route file and
+ *    the relative path resolves against the bundle location — paths (1)
+ *    and (2) cover those cases instead.
  */
 
 import type { World } from '@workflow/world';

packages/core/src/runtime/world-init.test.ts

@@ -0,0 +1,80 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+// Re-declare the symbols here (mirrors world.ts and get-world-lazy.ts)
+// instead of importing them, so the test fails loudly if either file
+// changes its symbol identity in a way that would silently break the
+// cross-module global handshake.
+const WorldCacheKey = Symbol.for('@workflow/world//cache');
+const WorldCachePromiseKey = Symbol.for('@workflow/world//cachePromise');
+const GetWorldFnKey = Symbol.for('@workflow/world//getWorldFn');
+
+type GlobalsShape = {
+  [WorldCacheKey]?: unknown;
+  [WorldCachePromiseKey]?: unknown;
+  [GetWorldFnKey]?: () => Promise<unknown>;
+};
+
+const g = globalThis as GlobalsShape;
+
+// Importing world-init for its side effect at the top of this test file is
+// itself the regression test: if `import '@workflow/core/runtime/world-init'`
+// stops loading `world.ts`, the `GetWorldFnKey` registration won't run and
+// the first assertion below fails. This mirrors what `workflow/api` (the
+// host file) does in production.
+import './world-init.js';
+
+describe('world-init', () => {
+  let priorFn: GlobalsShape[typeof GetWorldFnKey];
+
+  beforeEach(() => {
+    // Snapshot and clear the world cache. Each test wants to drive
+    // getWorldLazy down a deterministic path; leaving a previously-cached
+    // World instance around would short-circuit the test.
+    priorFn = g[GetWorldFnKey];
+    delete g[WorldCacheKey];
+    delete g[WorldCachePromiseKey];
+  });
+
+  afterEach(() => {
+    g[GetWorldFnKey] = priorFn;
+    delete g[WorldCacheKey];
+    delete g[WorldCachePromiseKey];
+  });
+
+  it('registers getWorld on globalThis at module-load time', () => {
+    expect(typeof g[GetWorldFnKey]).toBe('function');
+  });
+
+  it(
+    'getWorldLazy resolves via the registered global instead of falling ' +
+      'through to the dynamic-import branch',
+    async () => {
+      const { getWorldLazy } = await import('./get-world-lazy.js');
+
+      // Replace the registration with a sentinel-returning function so we can
+      // prove which branch getWorldLazy used. Using a Symbol means a real
+      // World instance from `world.ts`'s `getWorld()` (returned by the
+      // production registration) can't accidentally satisfy this assertion.
+      const sentinel = Symbol('sentinel-world');
+      g[GetWorldFnKey] = async () => sentinel as unknown;
+
+      const result = await getWorldLazy();
+      expect(result).toBe(sentinel);
+    }
+  );
+
+  it('uses ??= to register, so a prior registration is preserved', async () => {
+    // Simulate the case where some earlier code already set the registration
+    // (e.g., a setWorld() bypass in tests, or a future module that registers
+    // before world.ts). The world-init side effect must not clobber it.
+    const sentinel = async () => 'preserved' as unknown;
+    g[GetWorldFnKey] = sentinel;
+
+    // Re-evaluating world.ts is what would clobber. Importing world-init
+    // again returns the cached module, so the assignment doesn't re-run —
+    // this assertion is really documenting the contract.
+    await import('./world-init.js');
+
+    expect(g[GetWorldFnKey]).toBe(sentinel);
+  });
+});

packages/core/src/runtime/world-init.ts

@@ -0,0 +1,74 @@
+/**
+ * Server-only side-effect module that ensures `world.ts` is loaded so its
+ * module-load side effect — `globalThis[GetWorldFnKey] ??= getWorld` —
+ * fires in host bundles.
+ *
+ * # Why this exists
+ *
+ * `getWorldLazy()` in `./get-world-lazy.ts` checks the globalThis cache
+ * (populated by `world.ts`'s module-load side effect) before falling back
+ * to a runtime-built dynamic `import('./world.js')`. When a server route
+ * only consumes a single helper that goes through `getWorldLazy` — most
+ * commonly `start` from `workflow/api` — webpack/turbopack tree-shake the
+ * named import `{ getWorld } from './runtime/world.js'` out of
+ * `runtime.ts`, taking `world.ts`'s module evaluation with it. The
+ * globalThis registration never fires.
+ *
+ * `getWorldLazy` then falls through to its dynamic-import fallback, which
+ * itself fails: webpack inlines `get-world-lazy.js` into the bundled route
+ * file, so the relative specifier `./world.js` resolves against
+ * `/var/task/<app>/.next/server/app/<...>/route.js` — where no sibling
+ * `world.js` exists — and Node throws `MODULE_NOT_FOUND`. The symptom is a
+ * cold-start regression: the very first user request that goes through
+ * `start()` fails until some other code path (typically the queue-driven
+ * `/.well-known/workflow/v1/flow` route, which uses `getWorld` directly
+ * via `workflowEntrypoint`) has loaded `world.ts` and populated the
+ * cache.
+ *
+ * Importing this module for its side effect — exactly once, from the
+ * host-side `workflow/api` (`packages/workflow/src/api.ts`) — guarantees
+ * `world.ts` enters the bundle, the global is registered at module load,
+ * and `getWorldLazy()` short-circuits to the registered function on the
+ * first call.
+ *
+ * # Why a separate module instead of importing `./world.js` directly
+ *
+ * `world.ts` is internal to `@workflow/core` and not part of the public
+ * exports surface. Adding a dedicated public init entry (this file)
+ * keeps the side-effect intent obvious to anyone reading
+ * `packages/workflow/src/api.ts`, and lets the `workflow` export
+ * condition route to a stub for VM/step bundles (see below).
+ *
+ * # Why this doesn't break VM/step bundles
+ *
+ * The `@workflow/core/runtime/world-init` export resolves via the
+ * `workflow` condition to `./dist/workflow/world-init-stub.js`, an empty
+ * module. Esbuild runs the workflow VM and step bundlers with the
+ * `workflow` condition active, so they pick up the stub and never reach
+ * `world.ts`. Host bundlers (webpack, turbopack, Node.js) use the
+ * `default` (or `node`) condition and pick up this file, loading
+ * `world.ts` as intended. The split keeps `@workflow/world-vercel`,
+ * `@workflow/world-local`, `cbor-x`, and other server-only deps out of
+ * the workflow sandbox bundle.
+ *
+ * # Why we keep the `getWorldLazy` dynamic-import fallback
+ *
+ * The fallback remains in `./get-world-lazy.ts` as a defense-in-depth for
+ * environments we haven't accounted for (CJS test runners, scripts that
+ * import `start` without going through `workflow/api`, future bundlers
+ * with stricter tree-shaking). With this init module in place, the
+ * fallback should never fire in normal use — but if it does, the
+ * dynamic-import branch still resolves correctly when `world.js` is
+ * physically adjacent on disk (e.g., direct Node.js execution of
+ * unbundled source).
+ *
+ * # Maintenance notes
+ *
+ * If you add another `getWorldLazy()` consumer that's reachable from a
+ * host route without going through `workflow/api` (e.g., a new helper in
+ * `workflow/runtime`), make sure that entry also imports this module —
+ * or that it transitively reaches `world.ts` via a non-tree-shakeable
+ * path. Adding a regression test in `world-init.test.ts` is preferred to
+ * relying on careful manual tracing.
+ */
+import './world.js';

packages/core/src/runtime/world.ts

@@ -191,10 +191,20 @@ export const setWorld = (world: World | undefined): void => {
 
 // Register getWorld on globalThis so getWorldLazy can call it directly when
 // world.ts is statically present in the bundle. This avoids the relative
-// dynamic import('./world.js') fallback, which fails after Next.js inlines
-// get-world-lazy.js into a route bundle (no sibling world.js exists at the
-// bundled location). Step bundles never reach this branch because they
-// don't statically import world.ts.
+// dynamic import('./world.js') fallback in get-world-lazy.ts, which fails
+// after Next.js inlines get-world-lazy.js into a route bundle (no sibling
+// world.js exists at the bundled location).
+//
+// For server routes that only consume `start` (or another helper that goes
+// through getWorldLazy without statically using getWorld), webpack/turbopack
+// would otherwise tree-shake world.ts out of the bundle entirely. The
+// host-only `./world-init.ts` module imports world.ts for its side effect
+// and is itself imported by `packages/workflow/src/api.ts` so this
+// registration runs in every server bundle that touches `workflow/api`.
+//
+// Step/VM bundles never reach this branch: they don't statically import
+// world.ts, and `world-init` resolves to an empty stub via the `workflow`
+// export condition.
 const GetWorldFnKey = Symbol.for('@workflow/world//getWorldFn');
 (globalThis as { [GetWorldFnKey]?: () => Promise<World> })[GetWorldFnKey] ??=
   getWorld;

packages/core/src/workflow/world-init-stub.ts

@@ -0,0 +1,15 @@
+/**
+ * VM/step-bundle stub for `@workflow/core/runtime/world-init`.
+ *
+ * Resolved via the `workflow` export condition. Empty by design — the host
+ * is responsible for loading `world.ts` and populating the globalThis
+ * world cache before any VM or step code executes. Including this module
+ * (rather than letting the resolver fall through to the host file) keeps
+ * `world.ts` and its server-only deps (`@workflow/world-vercel`,
+ * `@workflow/world-local`, `cbor-x`, …) out of the workflow sandbox.
+ *
+ * See `../runtime/world-init.ts` for the host-side implementation and the
+ * full rationale.
+ */
+
+export {};

packages/workflow/src/api.ts

@@ -1,3 +1,20 @@
+// Side-effect import: ensure `world.ts` is loaded so its module-load
+// `globalThis[GetWorldFnKey] ??= getWorld` registration fires before any
+// host route reaches `getWorldLazy()`. Without this, webpack/turbopack
+// tree-shake `world.ts` out of routes that only use `start` (the most
+// common host-side entry point) and `getWorldLazy()`'s dynamic-import
+// fallback then fails because the bundler inlined `get-world-lazy.js`
+// into the route bundle. Resolved to an empty stub via the `workflow`
+// export condition in VM/step bundles, so this stays host-only.
+// See `@workflow/core/src/runtime/world-init.ts` for the full rationale.
+import '@workflow/core/runtime/world-init';
+
+export type {
+  Event,
+  StopSleepOptions,
+  StopSleepResult,
+  WorkflowRun,
+} from '@workflow/core/runtime';
 export {
   getHookByToken,
   resumeHook,
@@ -13,9 +30,3 @@ export {
   type StartOptions,
   start,
 } from '@workflow/core/runtime/start';
-export type {
-  Event,
-  StopSleepOptions,
-  StopSleepResult,
-  WorkflowRun,
-} from '@workflow/core/runtime';