workflow 5.0.0-beta.39 → 5.0.0-beta.40

package/README.md

@@ -14,24 +14,83 @@
 
 </div>
 
-## Getting Started
+[Workflow SDK](https://workflow-sdk.dev) makes TypeScript and JavaScript
+functions durable. It persists workflow progress, retries failed steps, and
+provides built-in observability. Workflows can suspend without using compute
+while they wait.
 
-The **Workflow SDK** lets you easily add durability, reliability, and observability to async JavaScript. Build apps and AI agents that can suspend, resume, and maintain state with ease.
+## Quick start
 
-Visit [https://workflow-sdk.dev](https://workflow-sdk.dev) to view the full documentation.
+Install the SDK in an existing project:
+
+```bash
+npm install workflow
+```
+
+Configure the integration for your framework. For example, with Next.js:
+
+```ts
+// next.config.ts
+import { withWorkflow } from 'workflow/next';
+
+export default withWorkflow({});
+```
+
+Then start a workflow from an API route, Server Action, or other server-side
+code:
+
+```ts
+import { start } from 'workflow/api';
+import { onboardUser } from './workflows/onboard-user';
+
+await start(onboardUser, ['hello@example.com']);
+```
+
+Run your app, then open the local observability UI in another terminal:
+
+```bash
+npm run dev
+```
+
+```bash
+npx workflow web
+```
+
+Choose your framework in the
+[getting-started guides](https://workflow-sdk.dev/docs/getting-started).
+
+> [!NOTE]
+> The `workflow` package includes its full documentation, so coding agents can
+> read version-matched guides locally from `node_modules/workflow/docs`.
+
+## Run anywhere
+
+Local development uses the bundled backend with no configuration. Deploy to
+Vercel for managed storage, queuing, scaling, and observability. To self-host,
+use the Postgres backend or implement a custom
+[World](https://workflow-sdk.dev/docs/deploying).
+
+There are many third-party Worlds (both self-hosted or managed), see [the Worlds page](https://workflow-sdk.dev/worlds) for a list of maintainer-curated third party worlds. Submit your world by opening updating the [Worlds Manifest](https://github.com/vercel/workflow/blob/main/worlds-manifest.json).
 
 ## Community
 
-The Workflow SDK community can be found on [GitHub Discussions](https://github.com/vercel/workflow/discussions), where you can ask questions, voice ideas, and share your projects with other people.
+The Workflow SDK community lives on
+[GitHub Discussions](https://github.com/vercel/workflow/discussions), where you
+can ask questions, share ideas, and show what you have built.
 
 ## Contributing
 
-Contributions to Workflow SDK are welcome and highly appreciated. Please use GitHub [issues](https://github.com/vercel/workflow/issues) and [discussions](https://github.com/vercel/workflow/discussions) to collaborate with the team and wider community.
-
----
+Contributions are welcome. Use
+[issues](https://github.com/vercel/workflow/issues) and
+[discussions](https://github.com/vercel/workflow/discussions) to collaborate
+with the team and wider community. By participating, you agree to our
+[Code of Conduct](https://github.com/vercel/workflow/blob/main/CODE_OF_CONDUCT.md).
 
 ## Security
 
 If you believe you have found a security vulnerability in Workflow SDK, we encourage you to **_responsibly disclose this and not open a public issue_**.
 
-To participate in our Open Source Software Bug Bounty program, please email [responsible.disclosure@vercel.com](mailto:responsible.disclosure@vercel.com). We will add you to the program and provide further instructions for submitting your report.
+To participate in our Open Source Software Bug Bounty program, please email
+[responsible.disclosure@vercel.com](mailto:responsible.disclosure@vercel.com).
+We will add you to the program and provide further instructions for submitting
+your report.

package/docs/api-reference/workflow/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/api-reference/workflow-api/start.mdx

@@ -113,3 +113,28 @@ When using `deploymentId: "latest"`, the workflow run will execute on a potentia
 - **Workflow identity**: The workflow ID is derived from the function name and file path. If the latest deployment has renamed the workflow function or moved it to a different directory, the workflow ID will no longer match and the run will fail to start.
 - **Input and output compatibility**: The arguments passed to `start()` are serialized by the calling deployment but deserialized by the target deployment. Similarly, the workflow's return value is serialized by the target deployment but deserialized by the caller. If the workflow's expected arguments or return type have changed (e.g. added required fields, removed fields, or changed types), the run may fail or behave unexpectedly. Ensure that input and output schemas remain backward-compatible across deployments.
 </Callout>
+
+### Inside a Workflow Function
+
+`start()` can be called directly from a workflow function to spawn a child run. It is step-backed, so the spawn records a deterministic step boundary in the parent's event log.
+
+```typescript
+import { start } from "workflow/api";
+import { childWorkflow } from "./workflows/child";
+
+export async function parentWorkflow(value: number) {
+  "use workflow";
+
+  const childRun = await start(childWorkflow, [value]); // [!code highlight]
+  const result = await childRun.returnValue; // [!code highlight]
+  return { childRunId: childRun.runId, result };
+}
+```
+
+<Callout type="info">
+The returned `Run` object is fully functional inside a workflow. Each property access or method call (`.status`, `.returnValue`, `.cancel()`) executes as a separate step. See [Workflow Composition](/cookbook/common-patterns/workflow-composition) for choosing between spawning a child run and awaiting a workflow function directly.
+</Callout>
+
+<Callout type="warn">
+`returnValue` polls the child run every second and holds the polling step's worker slot open for as long as the child takes to finish. For long-running children, spawn without awaiting `returnValue` and have the child resume a [hook](/docs/foundations/hooks) when it completes — see the [`startAndWait()` pattern](/cookbook/advanced/child-workflows).
+</Callout>

package/docs/api-reference/workflow-runtime/world/analytics.mdx

@@ -111,7 +111,7 @@ Run-scoped listings mirroring their [Storage](/docs/api-reference/workflow-runti
 ```typescript lineNumbers
 const steps = await world.analytics.steps.list({ runId });
 const events = await world.analytics.events.list({ runId, eventType: "step_failed" });
-const related = await world.analytics.events.listByCorrelationId({ correlationId });
+const related = await world.analytics.events.listByCorrelationId({ runId, correlationId });
 const hooks = await world.analytics.hooks.list({ runId });
 const waits = await world.analytics.waits.list({ runId, status: "waiting" });
 ```

package/docs/api-reference/workflow-runtime/world/storage.mdx

@@ -96,16 +96,20 @@ const result = await world.events.list({ runId, pagination: { cursor } }); // [!
 
 ### events.listByCorrelationId()
 
-List events that share a correlation ID, useful for tracing related events across runs.
+List one run's events that share a correlation ID, useful for tracing a single step, hook or wait through its lifecycle.
+
+A correlation ID is unique within its run, not across runs: two runs can each hold a `step_…`, `hook_…` or `wait_…` ID that reads the same. `runId` is therefore required, and it is also what makes the pagination cursor unambiguous.
 
 ```typescript lineNumbers
 const result = await world.events.listByCorrelationId({ // [!code highlight]
+  runId,
   correlationId: "order-123",
 }); // [!code highlight]
 ```
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
+| `params.runId` | `string` | The run the correlation ID belongs to |
 | `params.correlationId` | `string` | The correlation ID to filter by |
 | `params.pagination.cursor` | `string` | Cursor for the next page |
 
@@ -159,6 +163,8 @@ const result = await world.runs.list({ // [!code highlight]
 
 To cancel a run, create a `run_cancelled` event via `world.events.create()` (see [world.events](#worldevents) above), or use the CLI or Web UI helpers.
 
+To cancel a batch in one call, a world may implement the optional `runs.cancelMany({ runIds })`. It returns a summary plus a per-run outcome (`cancelled`, `already_cancelled`, `not_cancellable`, `not_found`, or `failed`). Backends that omit it fall back to per-run cancellation automatically.
+
 ### WorkflowRun Type
 
 | Field | Type | Description |

package/docs/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>

package/docs/configuration/cli-and-web-ui.mdx

@@ -2,7 +2,7 @@
 title: CLI and Web UI
 description: CLI flags and environment variables for inspecting local, Postgres, and Vercel Workflow runs.
 type: reference
-summary: Configure workflow inspect, workflow web, workflow health, and observability tooling.
+summary: Configure workflow inspect, workflow cancel, workflow web, workflow health, and observability tooling.
 related:
   - /docs/observability
   - /docs/configuration/worlds
@@ -115,6 +115,34 @@ Vercel project and auth settings can often be inferred from `.vercel/project.jso
 - Default: disabled
 - Enables keyboard-controlled pagination for supported list commands.
 
+## Bulk cancel
+
+`workflow cancel <run-id>` cancels one run. Given a filter instead, it bulk-cancels a batch; bulk mode requires `--status` or `--workflowName`.
+
+### `--status`
+
+- Command: `workflow cancel`
+- Default: unset
+- Restricts the batch to this status. Only `pending` and `running` are accepted — terminal runs cannot be cancelled.
+
+### `--workflowName` / `-n`
+
+- Command: `workflow cancel`
+- Default: unset
+- Restricts the batch to one workflow. Expects the generated workflow ID from `workflow inspect runs`, not the short function name.
+
+### `--limit` (cancel)
+
+- Command: `workflow cancel`
+- Default: `50`
+- Maximum runs to cancel in one batch (1–500). Only one batch is cancelled per invocation; re-run to cancel the next.
+
+### `--confirm` / `-y`
+
+- Command: `workflow cancel`
+- Default: disabled
+- Skips the interactive confirmation prompt.
+
 ## Health checks
 
 ### `--port` / `-p`

package/docs/configuration/runtime-tuning.mdx

@@ -10,6 +10,16 @@ related:
 
 Runtime variables are read where workflows execute. Set them on the deployment or dev server.
 
+## Client polling
+
+### `WORKFLOW_RETURN_VALUE_POLL_INTERVAL_MS`
+
+- Default: `1000`
+- Minimum: `1`
+- Delay between status requests made by [`Run.returnValue`](/docs/api-reference/workflow-api/get-run) while a workflow run is not yet complete.
+- Increase it to reduce polling traffic at the cost of noticing completion later.
+- This variable is read by the process awaiting `Run.returnValue`, such as an E2E test runner, rather than by the workflow deployment.
+
 ## Replay and queue delivery
 
 ### `WORKFLOW_REPLAY_TIMEOUT_MS`
@@ -45,6 +55,14 @@ For example, a workflow can run a 10-minute inline step even with `WORKFLOW_REPL
 - The runtime falls back to the sequential path automatically when the consumer or backend does not attest dedup support (or the payload is too large to inline on the queue message). On the sequential path the event is written *before* dispatch and its failure fails the resume — the fallback trades that resilience away to stay safe when dedup is not enforced, it does not preserve it.
 - Set `1` to force the sequential path as a kill switch. The chosen strategy is reported on the resume span as `workflow.hook.resume_strategy`.
 
+### `WORKFLOW_DEPLOYMENT_MISMATCH_MAX_RETRIES`
+
+- Default: `3`
+- Times a delivery that reached a deployment other than the one its run is pinned to is re-routed to that deployment before the run is failed with [`DEPLOYMENT_MISMATCH`](/docs/errors/deployment-mismatch).
+- Re-routed deliveries back off exponentially (1s, 2s, 4s). Set to `0` to fail the run on the first misrouted delivery.
+- Only applies to Worlds with atomic, immutable deployments (the Vercel World). A run whose pinned deployment cannot be reached at all fails immediately regardless of this value.
+- Transient or unknown queue publishing failures use normal queue redelivery and do not consume this budget.
+
 ### `WORKFLOW_PRECONDITION_GUARD`
 
 - Default: enabled
@@ -75,6 +93,17 @@ For example, a workflow can run a 10-minute inline step even with `WORKFLOW_REPL
 - Delay before a re-invocation caused by a rejected event creation.
 - Unlike an in-process restart, which re-reads immediately, a re-invocation only happens once the in-process budget failed to catch up — so the delay gives the other writers a moment to quiesce.
 
+### `WORKFLOW_PER_KIND_CORRELATION_IDS`
+
+- Default: disabled
+- Experimental. Gives each kind of entity a workflow creates — steps, waits, hooks, attribute writes, abort controllers, stream IDs — its own sequence of correlation IDs.
+- With one sequence shared by every kind, an ID is an ordinal over the whole run, so a single extra draw of any kind shifts every ID after it. Two concurrent replays of the same run that disagree about one `sleep()` then assign different IDs to every step that follows, and each writes events the other can neither match nor consume, which fails the run with `CORRUPTED_EVENT_LOG`. Per-kind sequences confine that to the kind that actually differs.
+- IDs remain ordered within a kind, so hooks created by your workflow are still listed in creation order. A hook the runtime creates for you, such as the one backing an abort controller, draws from its own kind and so is listed at an arbitrary position relative to your hooks rather than at its creation position.
+- A run must replay under the scheme that minted its IDs. A replay that switches schemes mid-run assigns IDs its own earlier events do not carry, so it can consume none of them and the run fails.
+  - On Vercel, a run keeps replaying on the deployment it started on, so it only ever sees the value baked into that deployment. Changing the setting affects new runs only.
+  - Elsewhere — `@workflow/world-postgres`, `@workflow/world-local`, any self-hosted process — nothing pins a run to the code that started it. Turn the setting on during a quiet window with no runs in flight, and roll the new value out to your whole fleet at once: a rolling deploy that leaves both values live replays one run under two schemes concurrently, which is the failure the setting exists to reduce.
+- Set `1` to enable.
+
 ## Inline execution
 
 ### `WORKFLOW_V2_TIMEOUT_MS`
@@ -103,6 +132,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 made of plain data (objects, arrays, primitives) and standard built-ins (`Map`, `Set`, `Date`, `RegExp`, typed arrays, `ArrayBuffer`, `URL`, `Headers`) keep the VM retained. Patching or polyfilling built-in prototypes doesn't change that: serialization never calls them. A boundary falls back to a full replay only when serializing its arguments runs code the workflow controls — a getter, a proxy, a custom class serializer — or computes an `Error`'s stack trace.
+- Set `0` or `false` to replay from scratch in a fresh VM on every iteration.
+
 ### `WORKFLOW_INLINE_OWNERSHIP`
 
 - Default: enabled
@@ -116,6 +153,23 @@ For example, a workflow can run a 10-minute inline step even with `WORKFLOW_REPL
 - How long after an inline step's latest `step_started` other invocations assume its owner may still be executing the body. Within the lease they defer the step's backstop message; past it they enqueue immediately.
 - Raise this on self-hosted multi-instance deployments whose inline steps run longer than the default (the default is sized for Vercel's function duration ceiling).
 
+## Workflow VM engine
+
+### `WORKFLOW_VM`
+
+- Default: `node`
+- 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):
+  - `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.
+
 ## Compression and tracing
 
 ### `WORKFLOW_DISABLE_COMPRESSION`

package/docs/configuration/worlds.mdx

@@ -104,6 +104,13 @@ The Local World is the default outside Vercel and is intended for development.
 - Default: `true`
 - Re-enqueues pending and running local runs when the World starts. Set the environment variable to `0` or `false` to skip recovery; the factory option wins when both are set.
 
+### `WORKFLOW_LOCAL_HOOK_RETENTION_LIMIT_DAYS`
+
+- Factory option: none
+- Default: `30`
+- Maximum [`experimental_minRetention`](/docs/api-reference/workflow/create-hook#keep-a-token-unavailable-after-the-run-ends) accepted by the Local World, in days.
+- Set this to the same limit as your production World so oversized values fail during local development.
+
 ### `tag`
 
 - Environment variable: none
@@ -160,6 +167,13 @@ The Postgres World is a self-hosted durable backend for long-running server proc
 - Default: `pg` default
 - Maximum size of the internal `pg.Pool` when the World creates the pool.
 
+### `WORKFLOW_POSTGRES_HOOK_RETENTION_LIMIT_DAYS`
+
+- Factory option: none
+- Default: `30`
+- Maximum [`experimental_minRetention`](/docs/api-reference/workflow/create-hook#keep-a-token-unavailable-after-the-run-ends) accepted by the Postgres World, in days.
+- Set this to the same limit as your production World so oversized values fail during development.
+
 ### `namespace`
 
 - Environment variable fallback: `WORKFLOW_QUEUE_NAMESPACE`

package/docs/errors/deployment-mismatch.mdx

@@ -0,0 +1,71 @@
+---
+title: deployment-mismatch
+description: A workflow run was delivered to a deployment other than the one it is pinned to.
+type: troubleshooting
+summary: Understand how Workflow recovers from a misrouted delivery, and why a run eventually fails with DEPLOYMENT_MISMATCH.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/foundations/versioning
+  - /docs/errors/runtime-decryption-failed
+  - /docs/foundations/errors-and-retries
+---
+
+Every run is pinned to a single deployment when it starts. When a queued workflow or step callback is delivered to a **different** deployment, Workflow does not execute it there. Instead it re-routes the message to the deployment the run is pinned to, and only if the run keeps arriving elsewhere does it fail with the `DEPLOYMENT_MISMATCH` classification.
+
+This is an SDK/runtime signal, not an error thrown by your workflow code, and it is not catchable inside a workflow function.
+
+## Error Message
+
+```
+Workflow run "wrun_..." is pinned to deployment "dpl_A", but was received by deployment "dpl_B". The runtime re-routed the message to "dpl_A" 3 times and it kept arriving elsewhere, so the run was stopped to protect against code-skew errors. Verify that the run's deployment is still available and that queue callbacks are routed to it.
+```
+
+When the queue definitively reports that the run's deployment cannot be reached — it was deleted, or aged out of its retention window — no re-route is possible and the message omits the re-routing clause. Transient or unknown publishing failures leave the current delivery unacknowledged so the queue can redeliver it; they do not fail the run or consume this recovery budget.
+
+## Why A Run Is Pinned
+
+A run's deployment is chosen once, at [`start()`](/docs/api-reference/workflow-api/start):
+
+- By default it is the deployment that called `start()` — see [Versioning](/docs/foundations/versioning) for why runs are pinned this way.
+- With `start(workflow, args, { deploymentId })` it is the id you pass, so a run can deliberately target a deployment other than the one that created it.
+- With `deploymentId: "latest"` it is the most recent deployment for the current environment, resolved at start time.
+
+Whichever it is, that `deploymentId` is recorded on the run, and every subsequent workflow replay and step execution must happen on that deployment. Continuing on a different one is unsafe:
+
+1. **Code skew.** The workflow and step bundles on the receiving deployment may not match the code that produced the run's recorded history, so replay could diverge or produce incorrect results.
+2. **Encryption.** Step inputs and other event-log payloads are encrypted with a per-run key derived from the pinned deployment's key material. A different deployment derives the wrong key and cannot decrypt them — previously the source of a confusing [runtime-decryption-failed](/docs/errors/runtime-decryption-failed) that exhausted retries with no clear cause.
+
+So the runtime checks the pinned deployment before it executes anything, and `DEPLOYMENT_MISMATCH` names the result — instead of the mismatch surfacing later as an unrelated decryption failure.
+
+## Automatic Recovery
+
+A deployment that receives a run it does not own first tries to fix the delivery rather than fail the run:
+
+1. It re-enqueues the message **explicitly addressed** to the run's own deployment. This is strictly better-addressed than the send that misrouted, which inherited the producing deployment's ambient id.
+2. Delivery is delayed with a short exponential backoff (1s, 2s, 4s).
+3. If the run keeps arriving at the wrong deployment, the run is failed with `DEPLOYMENT_MISMATCH` after `WORKFLOW_DEPLOYMENT_MISMATCH_MAX_RETRIES` attempts (default `3`). Set it to `0` to fail on the first misrouted delivery instead.
+
+Nothing is executed on the wrong deployment during recovery: no workflow code, no step body, no `step_started`, and no hook resume. Whatever the delivery was carrying travels with it, so a pending step keeps its identity and a hook resume keeps its payload — they run on the deployment that can actually decrypt them.
+
+Recovery attempts do not create events on the run, so a run that self-heals looks completely normal. They are reported on the invocation's trace span (`workflow.deployment.pinned_id`, `workflow.deployment_mismatch.retry_count`, `workflow.deployment_mismatch.recovered`) and as a runtime warning in your function logs.
+
+## What To Do
+
+- **Re-run from the current deployment.** Trigger the workflow again from your latest deployment (or use the **Re-run** button in the Workflow Dashboard). The new run is pinned to the current deployment.
+- **Keep a run's deployment available** for the lifetime of that run. A run whose deployment has been deleted or has aged out cannot be resumed and must be re-run — recovery cannot help, so these fail on the first misrouted delivery. This applies to runs started with an explicit `deploymentId` too: pinning a run to an older deployment keeps it dependent on that deployment for its whole lifetime.
+- **Report it** if the pinned deployment was still available. Include both deployment ids and the run id from the error message, plus the trace span attributes above — a run that failed this way despite a reachable target is a routing fault worth investigating rather than something to work around.
+
+## This Error Cannot Be Caught
+
+Like other runtime signals, `DEPLOYMENT_MISMATCH` is **not catchable** inside your workflow function — the run is failed before any workflow or step code executes on the receiving deployment. Check the run status from outside instead:
+
+```typescript lineNumbers
+import { getRun } from "workflow/api";
+
+const run = getRun("wrun_abc123");
+const status = await run.status;
+if (status === "failed") {
+  console.error("Run failed");
+}
+```

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/docs/observability/index.mdx

@@ -42,6 +42,8 @@ npx workflow inspect runs --web
 
 ![Workflow SDK Web UI](/o11y-ui.png)
 
+In the runs table, select one or more runs and choose **Cancel** to cancel the batch in a single request. Runs that fail with a retryable error stay selected so you can retry them.
+
 To share a link to a specific run without opening a browser, use the `--url`
 flag. It prints the dashboard deep link to stdout and exits (no browser, no
 local server) — useful for scripts, PR comments, or automation. Add `--json` to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "5.0.0-beta.39",
+  "version": "5.0.0-beta.40",
   "description": "Workflow SDK - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -59,18 +59,18 @@
   },
   "dependencies": {
     "ms": "2.1.3",
-    "@workflow/astro": "5.0.0-beta.39",
-    "@workflow/cli": "5.0.0-beta.39",
-    "@workflow/core": "5.0.0-beta.39",
-    "@workflow/errors": "5.0.0-beta.15",
+    "@workflow/astro": "5.0.0-beta.40",
+    "@workflow/cli": "5.0.0-beta.40",
+    "@workflow/core": "5.0.0-beta.40",
+    "@workflow/errors": "5.0.0-beta.16",
     "@workflow/typescript-plugin": "5.0.0-beta.5",
     "@workflow/utils": "5.0.0-beta.8",
-    "@workflow/next": "5.0.0-beta.39",
-    "@workflow/nest": "5.0.0-beta.39",
-    "@workflow/nitro": "5.0.0-beta.39",
-    "@workflow/nuxt": "5.0.0-beta.39",
-    "@workflow/sveltekit": "5.0.0-beta.39",
-    "@workflow/rollup": "5.0.0-beta.39"
+    "@workflow/next": "5.0.0-beta.40",
+    "@workflow/nest": "5.0.0-beta.40",
+    "@workflow/nitro": "5.0.0-beta.40",
+    "@workflow/nuxt": "5.0.0-beta.40",
+    "@workflow/sveltekit": "5.0.0-beta.40",
+    "@workflow/rollup": "5.0.0-beta.40"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",