@workflow/core 5.0.0-beta.39 → 5.0.0-beta.40

package/docs/api-reference/create-hook.mdx

@@ -187,7 +187,7 @@ After the workflow ends, [`getHookByToken()`](/docs/api-reference/workflow-api/g
 </Callout>
 
 <Callout type="warn">
-This option is experimental. If the configured World does not support it, the workflow fails when registering the Hook. `createWebhook()` does not accept this option.
+This option is experimental. Worlds can limit how long tokens are retained; see [World configuration](/docs/configuration/worlds) for each World's limit. If the configured World does not support minimum retention, the workflow fails when registering the Hook. `createWebhook()` does not accept this option.
 </Callout>
 
 ### Waiting for Multiple Payloads

package/docs/foundations/starting-workflows.mdx

@@ -80,6 +80,35 @@ Most `Run` properties are async getters that return promises. You need to `await
 
 ## Common Patterns
 
+### Starting Workflows from Workflow Functions
+
+You can also call `start()` directly inside workflow functions to spawn child workflows. For choosing between this and awaiting a workflow function directly, see [Workflow Composition](/cookbook/common-patterns/workflow-composition).
+
+```typescript lineNumbers
+import { start } from "workflow/api";
+import { childWorkflow } from "./workflows/child";
+
+export async function parentWorkflow(inputValue: number) {
+  "use workflow";
+
+  const childRun = await start(childWorkflow, [inputValue]); // [!code highlight]
+
+  // childRun is a full Run object — use it like normal
+  const childResult = await childRun.returnValue;
+  return { childRunId: childRun.runId, childResult };
+}
+```
+
+When `start()` is called inside a workflow function, it automatically executes through an internal step to maintain deterministic replay. The returned `Run` object works just like it does outside workflows — properties like `.runId`, `.status`, `.returnValue`, and methods like `.cancel()` are all available. Each property access or method call executes as a separate step under the hood.
+
+<Callout type="info">
+Inside workflow functions, each `Run` property access (e.g., `run.status`, `run.returnValue`) triggers a workflow step. This means each access is recorded in the event log and replayed deterministically.
+</Callout>
+
+<Callout type="warn">
+Awaiting `returnValue` polls the child run every second, and the polling step holds its worker slot open for as long as the child takes to finish. Worker-based Worlds must be sized to cover the peak number of these polls in flight. If the child workflow is long-running, spawn it without awaiting `returnValue` and have it resume a [hook](/docs/foundations/hooks) when it completes — see the [`startAndWait()` pattern](/cookbook/advanced/child-workflows).
+</Callout>
+
 ### Fire and Forget
 
 The most common pattern is to start a workflow and immediately return, letting it execute in the background:
@@ -148,7 +177,7 @@ export async function POST(request: Request) {
 }
 ```
 
-Your workflow can obtain a writable stream using [`getWritable()`](/docs/api-reference/workflow/get-writable):
+Your workflow can write to the stream using [`getWritable()`](/docs/api-reference/workflow/get-writable):
 
 ```typescript lineNumbers
 import { getWritable } from "workflow";
@@ -213,6 +242,50 @@ export async function GET(request: Request) {
 }
 ```
 
+### Recursive and Repeating Workflows
+
+A workflow can start a new instance of itself. This is useful when a single long-running workflow would accumulate too many events — large event logs become slower to replay, more expensive to store, and harder to inspect in the UI. By breaking work into smaller runs that chain together, each run stays lean.
+
+```typescript lineNumbers
+import { start } from "workflow/api";
+declare function fetchBatch(cursor?: string): Promise<{ items: string[]; nextCursor?: string }>; // @setup
+declare function processBatch(items: string[]): Promise<void>; // @setup
+
+export async function processQueue(cursor?: string) {
+  "use workflow";
+
+  const { items, nextCursor } = await fetchBatch(cursor);
+  await processBatch(items);
+
+  if (nextCursor) {
+    // Continue processing in a new workflow run
+    await start(processQueue, [nextCursor]); // [!code highlight]
+  }
+}
+```
+
+This pattern also enables **repeating cron-like workflows**. A workflow can complete its work, sleep, and then schedule a new instance of itself — creating an indefinite chain without any single run growing too large:
+
+```typescript lineNumbers
+import { sleep } from "workflow";
+import { start } from "workflow/api";
+declare function refreshMetrics(): Promise<void>; // @setup
+
+export async function syncDashboard() {
+  "use workflow";
+
+  await refreshMetrics();
+  await sleep("1h");
+
+  // Schedule the next run
+  await start(syncDashboard); // [!code highlight]
+}
+```
+
+#### Starting against the latest deployment
+
+By default a chained run starts on the same deployment as its parent. For workflows that chain over long periods, pass [`deploymentId: "latest"`](/docs/api-reference/workflow-api/start#using-deploymentid-latest) so the next run picks up new code. [Versioning](/docs/foundations/versioning#self-upgrading-workflows) covers this pattern in full, including how the serialized state acts as the migration boundary between versions.
+
 ## Next Steps
 
 Now that you understand how to start workflows and track their execution:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workflow/core",
-  "version": "5.0.0-beta.39",
+  "version": "5.0.0-beta.40",
   "description": "Core runtime and engine for Workflow SDK",
   "type": "module",
   "main": "dist/index.js",
@@ -84,21 +84,22 @@
     "@jridgewell/trace-mapping": "0.3.31",
     "@standard-schema/spec": "1.0.0",
     "@types/ms": "2.1.0",
-    "@vercel/functions": "^3.4.3",
+    "@vercel/functions": "^3.8.0",
     "debug": "4.4.3",
     "devalue": "5.9.0",
     "ms": "2.1.3",
     "nanoid": "5.1.6",
+    "quickjs-wasi": "3.1.0",
     "seedrandom": "3.0.5",
     "semver": "7.7.4",
     "ulid": "~3.0.1",
     "zod": "~4.3.6",
-    "@workflow/errors": "5.0.0-beta.15",
+    "@workflow/errors": "5.0.0-beta.16",
     "@workflow/serde": "5.0.0-beta.2",
     "@workflow/utils": "5.0.0-beta.8",
-    "@workflow/world": "5.0.0-beta.24",
-    "@workflow/world-local": "5.0.0-beta.33",
-    "@workflow/world-vercel": "5.0.0-beta.35"
+    "@workflow/world": "5.0.0-beta.25",
+    "@workflow/world-local": "5.0.0-beta.34",
+    "@workflow/world-vercel": "5.0.0-beta.36"
   },
   "devDependencies": {
     "@opentelemetry/api": "1.9.0",
@@ -123,7 +124,7 @@
     }
   },
   "scripts": {
-    "build": "genversion --es6 src/version.ts && tsc",
+    "build": "genversion --es6 src/version.ts && node scripts/build-vm-serde-bundle.js && node scripts/build-quickjs-assets.js && tsc",
     "dev": "genversion --es6 src/version.ts && tsc --watch",
     "clean": "tsc --build --clean && rm -rf dist src/version.ts docs ||:",
     "test": "cross-env WORKFLOW_TARGET_WORLD=local vitest run src",