@workflow/core 5.0.0-beta.42 → 5.0.0-beta.44

package/docs/foundations/serialization.mdx

@@ -15,11 +15,11 @@ All function arguments and return values passed between workflow and step functi
 The serialization system ensures that all data persists correctly across workflow suspensions and resumptions, enabling durable execution.
 </Callout>
 
-## Supported Serializable Types
+## Supported serializable types
 
 The following types can be serialized and passed through workflow functions:
 
-**Standard JSON Types:**
+**Standard JSON types:**
 
 - `string`
 - `number`
@@ -28,7 +28,7 @@ The following types can be serialized and passed through workflow functions:
 - Arrays of serializable values
 - Objects with string keys and serializable values
 
-**Extended Types:**
+**Extended types:**
 
 - `undefined`
 - `bigint`
@@ -58,7 +58,7 @@ These types have special handling and are explained in detail in the sections be
 - `AbortController`
 - `AbortSignal`
 
-## Pass-by-Value Semantics
+## Pass-by-value semantics
 
 **Parameters are passed by value, not by reference.** Steps receive deserialized copies of data. Mutations inside a step won't affect the original in the workflow.
 
@@ -81,7 +81,7 @@ async function updateUserStep(user: { id: string; name: string; email: string })
 }
 ```
 
-**Correct - return the modified data:**
+**Correct, return the modified data:**
 
 ```typescript title="workflows/correct-mutation.ts" lineNumbers
 export async function updateUserWorkflow(userId: string) {
@@ -100,7 +100,7 @@ async function updateUserStep(user: { id: string; name: string; email: string })
 }
 ```
 
-**Custom Classes:**
+**Custom classes:**
 
 - Class instances that implement [`WORKFLOW_SERIALIZE` and `WORKFLOW_DESERIALIZE`](#custom-class-serialization)
 
@@ -110,7 +110,7 @@ async function updateUserStep(user: { id: string; name: string; email: string })
 
 For complete information about using streams in workflows, including patterns for AI streaming, file processing, and progress updates, see the [Streaming Guide](/docs/foundations/streaming).
 
-## Request & Response
+## Request & response
 
 The Web API [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) and [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) APIs are supported by the serialization system,
 and can be passed around between workflow and step functions similarly to other data types.
@@ -140,7 +140,7 @@ export async function handleWebhookWorkflow() {
 }
 ```
 
-### Using `fetch` in Workflows
+### Using `fetch` in workflows
 
 Because `Request` and `Response` are serializable, Workflow SDK provides a `fetch` function that can be used directly in workflow functions:
 
@@ -158,7 +158,7 @@ export async function apiWorkflow() {
 }
 ```
 
-The implementation is straightforward - `fetch` from workflow is a step function that wraps the standard `fetch`:
+The `fetch` implementation from `workflow` is a step function that wraps the standard `fetch`:
 
 ```typescript title="Implementation" lineNumbers
 export async function fetch(...args: Parameters<typeof globalThis.fetch>) {
@@ -202,11 +202,11 @@ async function fetchData(signal: AbortSignal) {
 
 For usage patterns including timeouts, parallel cancellation, user-triggered cancellation, and run cancellation, see the [Cancellation Guide](/docs/foundations/cancellation). For details on the hook and stream backing that makes this work, see [How Cancellation Works](/docs/how-it-works/cancellation).
 
-## Custom Class Serialization
+## Custom class serialization
 
 By default, custom class instances cannot be serialized because the serialization system doesn't know how to reconstruct them. You can make your classes serializable by implementing two static methods using special symbols from the `@workflow/serde` package.
 
-### Basic Example
+### Basic example
 
 {/* @expect-error:2351 */}
 
@@ -256,13 +256,13 @@ async function doublePoint(point: Point) {
 }
 ```
 
-### How It Works
+### How it works
 
 1. **`WORKFLOW_SERIALIZE`**: A static method that receives a class instance and returns serializable data (primitives, plain objects, arrays, etc.)
 
 2. **`WORKFLOW_DESERIALIZE`**: A static method that receives the serialized data and returns a new class instance
 
-3. **Automatic Registration**: The SWC compiler plugin automatically detects classes that implement these symbols and registers them for serialization. Each class receives a deterministic `classId` derived from its file path and class name, and is registered into the global `Symbol.for("workflow-class-registry")` registry at build time — no manual registration step is required
+3. **Automatic Registration**: The SWC compiler plugin automatically detects classes that implement these symbols and registers them for serialization. Each class receives a deterministic `classId` derived from its file path and class name, and is registered into the global `Symbol.for("workflow-class-registry")` registry at build time. No manual registration step is required
 
 ### Requirements
 
@@ -279,12 +279,12 @@ The `WORKFLOW_SERIALIZE` and `WORKFLOW_DESERIALIZE` methods run inside the workf
 - No non-deterministic operations (like `Math.random()` or `Date.now()`)
 - No external network calls
 
-Keep these methods simple and focused on data transformation only.
+Keep these methods focused on data transformation only.
 </Callout>
 
-### Instance Methods as Steps
+### Instance methods as steps
 
-In practice, many classes have methods that need Node.js APIs, perform network calls, or interact with databases — operations that are not allowed in the `"use workflow"` execution context. You can make these methods workflow-compatible by adding `"use step"` to them. The SWC compiler will strip the method bodies from the workflow bundle and replace them with proxy functions that invoke the method as a step — with full Node.js runtime access. The `this` context (the class instance) is automatically serialized and deserialized across the workflow/step boundary.
+In practice, many classes have methods that need Node.js APIs, perform network calls, or interact with databases, operations that are not allowed in the `"use workflow"` execution context. You can make these methods workflow-compatible by adding `"use step"` to them. The SWC compiler will strip the method bodies from the workflow bundle and replace them with proxy functions that invoke the method as a step, with full Node.js runtime access. The `this` context (the class instance) is automatically serialized and deserialized across the workflow/step boundary.
 
 This requires the class to implement `WORKFLOW_SERIALIZE` and `WORKFLOW_DESERIALIZE`, so that the instance can be passed to the step execution context.
 
@@ -301,7 +301,7 @@ class Order {
     public createdAt: Date
   ) {}
 
-  // Custom serialization — data must be serializable types
+  // Custom serialization: data must be serializable types
   static [WORKFLOW_SERIALIZE](instance: Order) { // [!code highlight]
     return { // [!code highlight]
       id: instance.id, // [!code highlight]
@@ -329,7 +329,7 @@ class Order {
   }
 
   // Instance methods with "use step" run as step functions
-  // with full Node.js access — `this` is automatically serialized
+  // with full Node.js access; `this` is automatically serialized
   async save(): Promise<void> {
     "use step"; // [!code highlight]
     await db.orders.insert({ // [!code highlight]
@@ -355,7 +355,7 @@ class Order {
 }
 ```
 
-The class can then be used naturally inside a workflow function. Instance methods marked with `"use step"` are each executed as a step — with automatic caching, retry semantics, and full Node.js runtime access. Methods _without_ `"use step"` run directly in the workflow context, so they must follow the same constraints as workflow functions:
+The class can then be used naturally inside a workflow function. Instance methods marked with `"use step"` are each executed as a step, with automatic caching, retry semantics, and full Node.js runtime access. Methods _without_ `"use step"` run directly in the workflow context, so they must follow the same constraints as workflow functions:
 
 {/* @expect-error:2693 */}
 
@@ -369,7 +369,7 @@ export async function processOrderWorkflow(
 
   const order = new Order(orderId, items, new Date()); // [!code highlight]
 
-  // Runs in the workflow context — no "use step" needed
+  // Runs in the workflow context; no "use step" needed
   const itemCount = order.total(); // [!code highlight]
 
   // Each "use step" instance method call runs as a separate step
@@ -380,7 +380,7 @@ export async function processOrderWorkflow(
 }
 ```
 
-Note that [pass-by-value semantics](#pass-by-value-semantics) also apply to the `this` context of `"use step"` instance methods. Modifying instance properties inside a step method will not affect the original instance in the workflow. If you need to update instance state, return `this` from the step method and re-assign the variable in the workflow:
+[Pass-by-value semantics](#pass-by-value-semantics) also apply to the `this` context of `"use step"` instance methods. Modifying instance properties inside a step method will not affect the original instance in the workflow. If you need to update instance state, return `this` from the step method and re-assign the variable in the workflow:
 
 {/* @expect-error:2351 */}
 
@@ -408,4 +408,3 @@ export async function processOrderWorkflow() {
   order = await order.addItem("Widget", 3); // [!code highlight]
 }
 ```
-

package/docs/foundations/starting-workflows.mdx

@@ -1,5 +1,5 @@
 ---
-title: Starting Workflows
+title: Starting workflows
 description: Trigger workflow execution with the start() function and track progress with Run objects.
 type: guide
 summary: Trigger workflows and track their execution using the start() function.
@@ -9,11 +9,11 @@ related:
   - /docs/api-reference/workflow-api/start
 ---
 
-Once you've defined your workflow functions, you need to trigger them to begin execution. This is done using the `start()` function from `workflow/api`, which enqueues a new workflow run and returns a `Run` object that you can use to track its progress.
+After you define a workflow function, use the `start()` function from `workflow/api` to trigger it. The function enqueues a new workflow run and returns a `Run` object for tracking its progress.
 
-## The `start()` Function
+## The `start()` function
 
-The [`start()`](/docs/api-reference/workflow-api/start) function is used to programmatically trigger workflow executions from runtime contexts like API routes, Server Actions, or any server-side code. In v5, you can also call `start()` from inside a workflow function when you want to spawn a child run or continue work in a new run.
+The [`start()`](/docs/api-reference/workflow-api/start) function programmatically triggers workflow executions from runtime contexts such as API routes, Server Actions, or other server-side code. In v5, you can also call `start()` inside a workflow function to spawn a child run or continue work in a new run.
 
 ```typescript lineNumbers
 import { start } from "workflow/api";
@@ -32,20 +32,21 @@ export async function POST(request: Request) {
 }
 ```
 
-**Key Points:**
+**Key points:**
 
-- `start()` returns immediately after enqueuing the workflow - it doesn't wait for completion
+- `start()` returns immediately after enqueuing the workflow. It doesn't wait for completion
 - The first argument is your workflow function
 - The second argument is an array of arguments to pass to the workflow (optional if the workflow takes no arguments)
 - All arguments must be [serializable](/docs/foundations/serialization)
+- On Worlds with a regional dimension, the optional `region` option pins the new run's storage, queuing, and streams to a specific region. See [Multi-region on the Vercel World](/worlds/vercel#multi-region)
 
-**Learn more**: [`start()` API Reference](/docs/api-reference/workflow-api/start)
+**Learn more**: [`start()` API reference](/docs/api-reference/workflow-api/start)
 
 <Callout type="info">
 For parent-child workflow patterns, see [Workflow Composition](/cookbook/common-patterns/workflow-composition). For long-lived workflows that intentionally hand off to newer deployments with `deploymentId: "latest"`, see [Versioning](/docs/foundations/versioning).
 </Callout>
 
-## The `Run` Object
+## The `Run` object
 
 When you call `start()`, it returns a [`Run`](/docs/api-reference/workflow-api/start#returns) object that provides access to the workflow's status and results.
 
@@ -65,22 +66,22 @@ const status = await run.status; // "running" | "completed" | "failed"
 const result = await run.returnValue;
 ```
 
-**Key Properties:**
+**Key properties:**
 
-- `runId` - Unique identifier for this workflow run
-- `status` - Current status of the workflow (async)
-- `returnValue` - The value returned by the workflow function (async, blocks until completion)
-- `readable` - ReadableStream for streaming updates from the workflow
+- `runId`: Unique identifier for this workflow run
+- `status`: Current status of the workflow (async)
+- `returnValue`: The value returned by the workflow function (async, blocks until completion)
+- `readable`: `ReadableStream` for streaming updates from the workflow
 
 <Callout type="info">
-Most `Run` properties are async getters that return promises. You need to `await` them to get their values. For a complete list of properties and methods, see the API reference below.
+Most `Run` properties are async getters that return promises. `await` them to get their values. For a complete list of properties and methods, see the API reference below.
 </Callout>
 
-**Learn more**: [`Run` API Reference](/docs/api-reference/workflow-api/start#returns)
+**Learn more**: [`Run` API reference](/docs/api-reference/workflow-api/start#returns)
 
-## Common Patterns
+## Common patterns
 
-### Starting Workflows from Workflow Functions
+### 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).
 
@@ -93,25 +94,25 @@ export async function parentWorkflow(inputValue: number) {
 
   const childRun = await start(childWorkflow, [inputValue]); // [!code highlight]
 
-  // childRun is a full Run object — use it like normal
+  // 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.
+When you call `start()` inside a workflow function, it automatically executes through an internal step to maintain deterministic replay. The returned `Run` object works as it does outside workflows. Properties such as `.runId`, `.status`, and `.returnValue`, and methods such as `.cancel()`, are all available. Each property access or method call executes as a separate step.
 
 <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).
+Awaiting `returnValue` polls the child run every second, and the polling step holds its worker slot open until the child finishes. Size worker-based Worlds 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
+### Fire and forget
 
-The most common pattern is to start a workflow and immediately return, letting it execute in the background:
+Start a workflow and immediately return to let it execute in the background:
 
 ```typescript lineNumbers
 import { start } from "workflow/api";
@@ -129,7 +130,7 @@ export async function POST(request: Request) {
 }
 ```
 
-### Wait for Completion
+### Wait for completion
 
 If you need to wait for the workflow to complete before responding:
 
@@ -148,12 +149,12 @@ export async function POST(request: Request) {
 ```
 
 <Callout type="warn">
-Be cautious when waiting for `returnValue` - if your workflow takes a long time, your API route may timeout.
+Waiting for `returnValue` can cause your API route to time out if the workflow takes a long time.
 </Callout>
 
-### Stream Updates to Client
+### Stream updates to client
 
-Stream real-time updates from your workflow as it executes, without waiting for completion:
+Stream updates from your workflow as it executes without waiting for completion:
 
 ```typescript lineNumbers
 import { start } from "workflow/api";
@@ -211,12 +212,12 @@ async function streamContentToClient(
 ```
 
 <Callout type="info">
-Streams are particularly useful for AI workflows where you want to show progress to users in real-time, or for long-running processes that produce intermediate results.
+Use streams to show users real-time progress from AI workflows or intermediate results from long-running processes.
 </Callout>
 
-**Learn more**: [Streaming in Workflows](/docs/foundations/serialization#streaming)
+**Learn more**: [Streaming in workflows](/docs/foundations/serialization#streaming)
 
-### Check Status Later
+### Check status later
 
 You can retrieve a workflow run later using its `runId` with [`getRun()`](/docs/api-reference/workflow-api/get-run):
 
@@ -242,9 +243,9 @@ export async function GET(request: Request) {
 }
 ```
 
-### Recursive and Repeating Workflows
+### 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.
+A workflow can start a new instance of itself. This pattern prevents a single long-running workflow from accumulating too many events. Large event logs are slower to replay, more expensive to store, and harder to inspect in the UI. Breaking work into smaller runs that chain together keeps each run lean.
 
 ```typescript lineNumbers
 import { start } from "workflow/api";
@@ -264,7 +265,7 @@ export async function processQueue(cursor?: string) {
 }
 ```
 
-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:
+This pattern also enables **repeating cron-like workflows**. A workflow can complete its work, sleep, and then schedule a new instance of itself. This creates an indefinite chain without allowing any single run to grow too large:
 
 ```typescript lineNumbers
 import { sleep } from "workflow";
@@ -286,10 +287,8 @@ export async function syncDashboard() {
 
 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:
+## Next steps
 
 - Browse the [Cookbook](/cookbook) for copy-paste recipes covering composition, scheduling, timeouts, and more
-- Explore [Errors & Retrying](/docs/foundations/errors-and-retries) to handle failures gracefully
-- Check the [`start()` API Reference](/docs/api-reference/workflow-api/start) for complete details
+- Explore [Errors and retrying](/docs/foundations/errors-and-retries) to handle failures
+- Check the [`start()` API reference](/docs/api-reference/workflow-api/start) for complete details

package/docs/foundations/streaming.mdx

@@ -1,8 +1,8 @@
 ---
 title: Streaming
-description: Stream data in real-time to clients for progress updates and incremental content delivery.
+description: Stream data in real time to clients for progress updates and incremental content delivery.
 type: conceptual
-summary: Stream real-time data to clients without waiting for workflow completion.
+summary: Stream data to clients in real time without waiting for workflow completion.
 prerequisites:
   - /docs/foundations/workflows-and-steps
 related:
@@ -10,9 +10,9 @@ related:
   - /docs/ai/resumable-streams
 ---
 
-Workflows can stream data in real-time to clients without waiting for the entire workflow to complete. This enables progress updates, AI-generated content, log messages, and other incremental data to be delivered as workflows execute.
+Workflows can stream data to clients in real time without waiting for the entire workflow to complete. Clients can receive progress updates, AI-generated content, log messages, and other incremental data as workflows execute.
 
-## Getting Started with `getWritable()`
+## Getting started with `getWritable()`
 
 Every workflow run has a default writable stream that steps can write to using [`getWritable()`](/docs/api-reference/workflow/get-writable). Data written to this stream becomes immediately available to clients consuming the workflow's output.
 
@@ -38,7 +38,7 @@ export async function simpleStreamingWorkflow() {
 }
 ```
 
-### Consuming the Stream
+### Consuming the stream
 
 Use the `Run` object's `readable` property to consume the stream from your API route:
 
@@ -58,7 +58,31 @@ export async function POST() {
 
 When a client makes a request to this endpoint, they'll receive each message as it's written, without waiting for the workflow to complete.
 
-### Resuming Streams from a Specific Point
+### Avoiding function timeouts after client disconnects
+
+On Vercel, `run.readable` and `run.getReadable()` reconnect to Workflow's stream storage while the workflow is still running. By default, a client disconnect does not terminate the Vercel Function serving the stream. If a user closes the page or stops the request, the function can therefore keep reconnecting until it reaches its maximum duration and fails with `FUNCTION_INVOCATION_TIMEOUT`.
+
+For streaming routes using the Node.js runtime, opt in to [request cancellation](https://vercel.com/docs/functions/functions-api-reference#enable-cancellation) in `vercel.json`:
+
+```json filename="vercel.json"
+{
+  "functions": {
+    "app/api/stream/route.ts": {
+      "supportsCancellation": true
+    }
+  }
+}
+```
+
+Replace the function path with the path or glob for your streaming route. When the downstream client disconnects, Vercel terminates the matching function invocation instead of leaving its stream reader running. The workflow run and its durable stream continue independently, so the client can reconnect through another route invocation later.
+
+<Callout type="warn">
+Cancellation applies to every function matching the configured path or glob, even if the route does not listen to `request.signal`. Any other work in that invocation which is not wrapped in [`waitUntil`](https://vercel.com/docs/functions/functions-api-reference/vercel-functions-package#waituntil) or [`after`](https://nextjs.org/docs/app/api-reference/functions/after) can be lost. Only enable it for routes that are safe to terminate when their client disconnects.
+</Callout>
+
+This setting prevents abandoned stream readers from consuming the rest of a function invocation. It does not extend the function's maximum duration. An actively connected streaming response can still reach the configured limit, at which point the client should reconnect to the durable stream.
+
+### Resuming streams from a specific point
 
 Use `run.getReadable({ startIndex })` to resume a stream from a specific position. This is useful for reconnecting after timeouts or network interruptions:
 
@@ -85,7 +109,7 @@ export async function GET(
 }
 ```
 
-This allows clients to reconnect and continue receiving data from where they left off, rather than restarting from the beginning.
+Clients can reconnect and continue receiving data from where they left off instead of restarting from the beginning.
 
 `startIndex` also supports **negative values** to read relative to the end of the stream. For example, `startIndex: -5` starts 5 chunks before the current end. This is useful when you want to show the most recent output without reading the entire stream history.
 
@@ -103,31 +127,32 @@ If the absolute value exceeds the total number of chunks, reading starts from th
 Because streams are live and continue receiving chunks, negative `startIndex` values resolve to different absolute positions on each call. Accurate pagination over a live stream requires cursor-based access, which is not yet supported. Keep this in mind when building clients that paginate over stream data.
 </Callout>
 
-## Streams as Data Types
+## Streams as data types
 
-[`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) and [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) are standard Web Streams API types that Workflow SDK makes serializable. These are not custom types - they follow the web standard - but Workflow SDK adds the ability to pass them between functions while maintaining their streaming capabilities.
+[`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) and [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) are standard Web Streams API types that Workflow SDK makes serializable. Workflow SDK lets you pass these standard types between functions while maintaining their streaming capabilities.
 
 Unlike regular values that are fully serialized to the [event log](/docs/how-it-works/event-sourcing), streams maintain their streaming capabilities when passed between functions.
 
 **Key properties:**
+
 - Stream references can be passed between workflow and step functions
 - Stream data flows directly without being stored in the event log
 - Streams preserve their state across workflow suspension points
 
 <Callout type="info">
-**How Streams Persist Across Workflow Suspensions**
+**How streams persist across workflow suspensions**
 
-Streams in Workflow SDK are backed by persistent, resumable storage provided by the "world" implementation. This is what enables streams to maintain their state even when workflows suspend and resume:
+Persistent, resumable storage from the World implementation lets Workflow SDK streams maintain their state when workflows suspend and resume:
 
 - **Vercel deployments**: Streams are backed by a performant Redis-based stream
 - **Local development**: Stream chunks are stored in the filesystem
 </Callout>
 
-### Passing Streams as Arguments
+### Passing streams as arguments
 
-Since streams are serializable data types, you don't need to use the special [`getWritable()`](/docs/api-reference/workflow/get-writable). You can even wire your own streams through workflows, passing them as arguments from outside into steps.
+Because streams are serializable data types, you don't need to use [`getWritable()`](/docs/api-reference/workflow/get-writable). You can pass your own streams as arguments from outside a workflow into steps.
 
-Here's an example of passing a request body stream through a workflow to a step that processes it:
+The following example passes a request body stream through a workflow to a step that processes it:
 
 ```typescript title="app/api/upload/route.ts" lineNumbers
 import { start } from "workflow/api";
@@ -167,15 +192,15 @@ async function processInputStream(input: ReadableStream<Uint8Array>) {
 }
 ```
 
-## Important Limitation
+## Important limitation
 
 <Callout type="info">
-**Streams Cannot Be Used Directly in Workflow Context**
+**Streams cannot be used directly in workflow context**
 
 You cannot read from or write to streams directly within a workflow function. All stream operations must happen in step functions.
 </Callout>
 
-Workflow functions must be deterministic to support replay. Since streams bypass the [event log](/docs/how-it-works/event-sourcing) for performance, reading stream data in a workflow would break determinism - each replay could see different data. By requiring all stream operations to happen in steps, the framework ensures consistent behavior.
+Workflow functions must be deterministic to support replay. Streams bypass the [event log](/docs/how-it-works/event-sourcing) for performance, so reading stream data in a workflow would break determinism because each replay could see different data. Requiring all stream operations to happen in steps ensures consistent behavior.
 
 For more on determinism and replay, see [Workflows and Steps](/docs/foundations/workflows-and-steps).
 
@@ -214,7 +239,7 @@ async function writeToStream(data: string) {
 }
 ```
 
-## Namespaced Streams
+## Namespaced streams
 
 Use `getWritable({ namespace: 'name' })` to create multiple independent streams for different types of data. This is useful when you want to separate logs, metrics, data outputs, or other distinct channels.
 
@@ -264,7 +289,7 @@ export async function multiStreamWorkflow() {
 }
 ```
 
-### Consuming Namespaced Streams
+### Consuming namespaced streams
 
 Use `run.getReadable({ namespace: 'name' })` to access specific streams:
 
@@ -289,9 +314,9 @@ export async function POST(request: Request) {
 }
 ```
 
-## Common Patterns
+## Common patterns
 
-### Progress Updates for Long-Running Tasks
+### Progress updates for long-running tasks
 
 Send incremental progress updates to keep users informed during lengthy workflows:
 
@@ -345,7 +370,7 @@ export async function batchProcessingWorkflow(items: string[]) {
 }
 ```
 
-### Streaming AI Responses with `WorkflowAgent`
+### Streaming AI responses with `WorkflowAgent`
 
 Stream AI-generated content using AI SDK's [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) from `@ai-sdk/workflow`. The agent writes `ModelCallStreamPart` chunks to the workflow stream, and route handlers convert them to UI message chunks with `createModelCallToUIChunkTransform()` before returning the response:
 
@@ -406,7 +431,7 @@ export async function POST(request: Request) {
 For the full agent API and migration notes, see the [`WorkflowAgent` documentation](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent).
 </Callout>
 
-### Streaming Between Steps
+### Streaming between steps
 
 One step produces a stream and another step consumes it:
 
@@ -447,7 +472,7 @@ async function consumeData(readable: ReadableStream<number>) {
 }
 ```
 
-### Processing Large Files Without Memory Overhead
+### Processing large files without memory overhead
 
 Process large files by streaming chunks through transformation steps:
 
@@ -488,7 +513,11 @@ async function uploadResult(stream: ReadableStream<Uint8Array>) {
 }
 ```
 
-## Best Practices
+## Best practices
+
+**Batching and first-chunk latency:**
+
+Writes are flushed immediately by default. The leading chunk of an idle stream dispatches as soon as it is written, and chunks arriving while a flush is in flight coalesce into the next batch. If you write bursts of many tiny chunks and prefer fewer round trips over first-chunk latency, set a group-commit window with the World's `streamFlushIntervalMs` option or the `WORKFLOW_STREAM_FLUSH_INTERVAL_MS` environment variable. See [Worlds configuration](/docs/configuration/worlds#streamflushintervalms).
 
 **Release locks properly:**
 
@@ -506,7 +535,7 @@ Stream locks acquired in a step only apply within that step, not across other st
 </Callout>
 
 <Callout type="warn">
-If a lock is not released, the step function's HTTP request cannot terminate. Even though the step returns and the workflow continues, the underlying request will remain active until it times out—wasting compute resources unnecessarily.
+If a lock is not released, the invocation that ran the step cannot terminate. Even though the step returns and the workflow continues, the underlying request remains active until it times out and wastes compute resources.
 </Callout>
 
 **Close streams when done:**
@@ -532,7 +561,7 @@ const writer = writable.getWriter();
 await writer.write({ /* typed data */ });
 ```
 
-## Stream Failures
+## Stream failures
 
 When a step returns a stream, the step is considered successful once it returns, even if the stream later encounters an error. The workflow won't automatically retry the step. The consumer of the stream must handle errors gracefully. For more on retry behavior, see [Errors and Retries](/docs/foundations/errors-and-retries).
 
@@ -575,17 +604,17 @@ export async function streamErrorWorkflow() {
 ```
 
 <Callout type="info">
-Stream errors don't trigger automatic retries for the producer step. Design your stream consumers to handle errors appropriately. Since the stream is already in an errored state, retrying the consumer won't help - use `FatalError` to fail the workflow immediately.
+Stream errors don't trigger automatic retries for the producer step. Design your stream consumers to handle errors. Because the stream is already in an errored state, retrying the consumer won't help. Use `FatalError` to fail the workflow immediately.
 </Callout>
 
-## Related Documentation
-
-- [`getWritable()` API Reference](/docs/api-reference/workflow/get-writable) - Get the workflow's writable stream
-- [`sleep()` API Reference](/docs/api-reference/workflow/sleep) - Pause workflow execution for a duration
-- [`start()` API Reference](/docs/api-reference/workflow-api/start) - Start workflows and access the `Run` object
-- [`getRun()` API Reference](/docs/api-reference/workflow-api/get-run) - Retrieve runs and their streams later
-- [world.streams](/docs/api-reference/workflow-runtime/world/streams) - Low-level stream read/write/close via World SDK
-- [WorkflowAgent](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) - AI agents with durable, resumable streaming support
-- [Errors and Retries](/docs/foundations/errors-and-retries) - Understanding error handling and retry behavior
-- [Serialization](/docs/foundations/serialization) - Understanding what data types can be passed in workflows
-- [Workflows and Steps](/docs/foundations/workflows-and-steps) - Core concepts of workflow execution
+## Related documentation
+
+- [`getWritable()` API reference](/docs/api-reference/workflow/get-writable): Get the workflow's writable stream
+- [`sleep()` API reference](/docs/api-reference/workflow/sleep): Pause workflow execution for a duration
+- [`start()` API reference](/docs/api-reference/workflow-api/start): Start workflows and access the `Run` object
+- [`getRun()` API reference](/docs/api-reference/workflow-api/get-run): Retrieve runs and their streams later
+- [`world.streams`](/docs/api-reference/workflow-runtime/world/streams): Use low-level stream read, write, and close operations through the World SDK
+- [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent): Build AI agents with durable, resumable streaming support
+- [Errors and retries](/docs/foundations/errors-and-retries): Understand error handling and retry behavior
+- [Serialization](/docs/foundations/serialization): Understand which data types you can pass in workflows
+- [Workflows and steps](/docs/foundations/workflows-and-steps): Learn the core concepts of workflow execution

package/docs/foundations/versioning.mdx

@@ -75,7 +75,7 @@ Sometimes you deploy because the old code had a bug. The safest fix is usually e
 3. Cancel the old runs if they are still running.
 4. Rerun them on the latest deployment with the same inputs.
 
-This keeps the version boundary visible. The old run ends as cancelled or failed, and the replacement run starts fresh on the fixed deployment. This is a good fit for one-off, ad-hoc upgrades where you explicitly opt in to moving affected runs onto a new version.
+This keeps the version boundary visible. The old run ends as canceled or failed, and the replacement run starts fresh on the fixed deployment. This is a good fit for one-off, ad-hoc upgrades where you explicitly opt in to moving affected runs onto a new version.
 
 ```bash
 # Inspect affected runs and copy the exact workflowName value.
@@ -121,9 +121,9 @@ export async function POST(request: Request) {
 
 ## Self upgrading workflows
 
-Some workflows are expected to run for a very long time. Scheduled loops, recurring jobs, agents, and chat sessions often should not stay on one deployment forever.
+Some workflows are expected to run for long periods. Scheduled loops, recurring jobs, agents, and chat sessions often should not stay on one deployment forever.
 
-Model those as a sequence of runs. Each run does a bounded piece of work, then starts the next run on the latest deployment and exits. This is similar to `continueAsNew` in other durable execution systems, but in Workflow SDK it is just [explicit recursion through `start()`](/cookbook/common-patterns/workflow-composition).
+Model those as a sequence of runs. Each run does a bounded piece of work, then starts the next run on the latest deployment and exits. This is similar to `continueAsNew` in other durable execution systems, but Workflow SDK uses [explicit recursion through `start()`](/cookbook/common-patterns/workflow-composition).
 
 ```typescript title="workflows/daily-digest.ts" lineNumbers
 import { sleep } from "workflow";