workflow 4.4.0 → 4.5.0

package/docs/{api-reference/workflow-api → v4/api-reference/workflow-runtime}/world/index.mdx

@@ -4,7 +4,7 @@ description: Low-level API for inspecting and managing workflow runs, steps, eve
 type: overview
 summary: Access workflow infrastructure directly via getWorld() for building observability dashboards, admin tools, and custom integrations.
 prerequisites:
-  - /docs/api-reference/workflow-api/get-world
+  - /docs/api-reference/workflow-runtime/get-world
 keywords:
   - getWorld
   - World SDK
@@ -25,18 +25,15 @@ const world = getWorld(); // [!code highlight]
 ## Interfaces
 
 <Cards>
-    <Card href="/docs/api-reference/workflow-api/world/storage" title="Storage">
+    <Card href="/docs/api-reference/workflow-runtime/world/storage" title="Storage">
         Query runs, steps, hooks, and the underlying event log.
     </Card>
-    <Card href="/docs/api-reference/workflow-api/world/streams" title="Streams">
+    <Card href="/docs/api-reference/workflow-runtime/world/streams" title="Streams">
         Read, write, and manage real-time data streams for workflow runs.
     </Card>
-    <Card href="/docs/api-reference/workflow-api/world/queue" title="Queue">
+    <Card href="/docs/api-reference/workflow-runtime/world/queue" title="Queue">
         Low-level queue dispatch (internal SDK infrastructure).
     </Card>
-    <Card href="/docs/api-reference/workflow-api/world/observability" title="Observability Utilities">
-        Hydrate step I/O, parse display names, and decrypt workflow data.
-    </Card>
 </Cards>
 
 <Callout type="info">
@@ -55,4 +52,4 @@ const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highl
 console.log(hydrated.input, hydrated.output);
 ```
 
-See [Observability Utilities](/docs/api-reference/workflow-api/world/observability) for the full API.
+See [`workflow/observability`](/docs/api-reference/workflow-observability) for the full API.

package/docs/v4/api-reference/workflow-runtime/world/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "World SDK",
+  "pages": ["storage", "streams", "queue"]
+}

package/docs/v4/api-reference/workflow-runtime/world/queue.mdx

@@ -0,0 +1,86 @@
+---
+title: Queue
+description: Low-level queue interface for dispatching workflow and step invocations.
+type: reference
+summary: "Methods: getDeploymentId(), queue(), createQueueHandler(). Internal queue dispatch — normally handled by the SDK."
+prerequisites:
+  - /docs/api-reference/workflow-runtime/get-world
+related:
+  - /docs/api-reference/workflow-api/start
+  - /docs/foundations/starting-workflows
+keywords:
+  - world.queue
+  - getDeploymentId
+  - queue
+  - createQueueHandler
+  - ValidQueueName
+  - queue dispatch
+---
+
+Queue methods live directly on the `world` object (not nested). They dispatch internal workflow and step invocations to the queue backend.
+
+<Callout type="warn">
+  These methods are used internally by the Workflow SDK to dispatch execution. You do not need to call them in normal operations — use [`start()`](/docs/api-reference/workflow-api/start) to trigger workflows instead. Direct queue access is only needed if you programmatically create a run via `world.events.create()` with a `run_created` event and need to kick off its initial execution, or for debugging resumption of a flow or step route.
+</Callout>
+
+## Import
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+
+const world = await getWorld(); // [!code highlight]
+// Queue methods are called directly on world — e.g. world.queue()
+```
+
+## Methods
+
+### getDeploymentId()
+
+Get the current deployment ID. Used internally for routing queue messages to the correct deployment.
+
+```typescript lineNumbers
+const deploymentId = await world.getDeploymentId(); // [!code highlight]
+```
+
+**Returns:** `string` — The current deployment ID
+
+### queue()
+
+Dispatch a message to a named queue. The message payload is an internal SDK type (`WorkflowInvokePayload`, `StepInvokePayload`, or `HealthCheckPayload`).
+
+```typescript lineNumbers
+const { messageId } = await world.queue(queueName, payload, opts); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `queueName` | `ValidQueueName` | The queue name (branded string) |
+| `message` | `QueuePayload` | Internal SDK payload |
+| `opts` | `QueueOptions` | Optional — `deploymentId`, `idempotencyKey`, `delaySeconds`, `headers` |
+
+**Returns:** `{ messageId: MessageId | null }`
+
+### createQueueHandler()
+
+Create an HTTP handler that processes messages from a queue. Used to set up the queue consumer endpoint.
+
+```typescript lineNumbers
+const handler = world.createQueueHandler(prefix, callback); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `prefix` | `QueuePrefix` | Queue name prefix to match |
+| `callback` | `(message, meta) => Promise<void \| { timeoutSeconds: number }>` | Handler called for each message. `meta` contains `attempt`, `queueName`, `messageId`, `requestId`. |
+
+**Returns:** `(req: Request) => Promise<Response>`
+
+## Related
+
+- [start()](/docs/api-reference/workflow-api/start) — The standard way to start workflow runs
+- [Starting Workflows](/docs/foundations/starting-workflows) — Core concepts for workflow invocation
+- [Storage](/docs/api-reference/workflow-runtime/world/storage) — Create events that trigger queue dispatch

package/docs/{api-reference/workflow-api → v4/api-reference/workflow-runtime}/world/storage.mdx

@@ -4,11 +4,11 @@ description: Query workflow runs, steps, hooks, and the underlying event log via
 type: reference
 summary: "Interfaces: world.events, world.runs, world.steps, world.hooks. Events are the source of truth; runs, steps, and hooks are materialized views."
 prerequisites:
-  - /docs/api-reference/workflow-api/get-world
+  - /docs/api-reference/workflow-runtime/get-world
 related:
   - /docs/api-reference/workflow-api/get-run
   - /docs/how-it-works/event-sourcing
-  - /docs/api-reference/workflow-api/world/observability
+  - /docs/api-reference/workflow-observability
 keywords:
   - world.events
   - world.runs
@@ -229,7 +229,7 @@ const result = await world.steps.list({ // [!code highlight]
 | `retryAfter` | `string \| null` | ISO timestamp for next retry attempt |
 
 <Callout type="info">
-  Step I/O is serialized using the [devalue](https://github.com/Rich-Harris/devalue) format. Use `hydrateResourceIO()` from `workflow/observability` to deserialize it for display. See [Observability Utilities](/docs/api-reference/workflow-api/world/observability).
+  Step I/O is serialized using the [devalue](https://github.com/Rich-Harris/devalue) format. Use `hydrateResourceIO()` from `workflow/observability` to deserialize it for display. See [`hydrateResourceIO()`](/docs/api-reference/workflow-observability/hydrate-resource-io).
 </Callout>
 
 <Callout type="warn">
@@ -402,7 +402,7 @@ for (const event of events.data) {
 
 - [Event Sourcing](/docs/how-it-works/event-sourcing) — How the event log powers workflow replay and state
 - [getRun()](/docs/api-reference/workflow-api/get-run) — Higher-level API for working with individual runs
-- [Observability Utilities](/docs/api-reference/workflow-api/world/observability) — Hydrate step I/O, parse display names, decrypt data
+- [`workflow/observability`](/docs/api-reference/workflow-observability) — Hydrate step I/O and parse display names
 - [resumeHook()](/docs/api-reference/workflow-api/resume-hook) — Resume a workflow by sending a payload to a hook
 - [Hooks](/docs/foundations/hooks) — Core concepts for hooks and pause points
 - [Workflows and Steps](/docs/foundations/workflows-and-steps) — Core concepts for steps

package/docs/v4/api-reference/workflow-runtime/world/streams.mdx

@@ -0,0 +1,216 @@
+---
+title: Streams
+description: Read, write, and manage real-time data streams for workflow runs.
+type: reference
+summary: "Methods: streams.write(), streams.writeMulti(), streams.get(), streams.close(), streams.list(), streams.getChunks(), streams.getInfo(). Stream methods live on world.streams."
+prerequisites:
+  - /docs/api-reference/workflow-runtime/get-world
+related:
+  - /docs/foundations/streaming
+  - /docs/api-reference/workflow/get-writable
+keywords:
+  - streams.write
+  - streams.writeMulti
+  - streams.get
+  - streams.close
+  - streams.list
+  - streams.getChunks
+  - streams.getInfo
+  - Streamer interface
+  - real-time streaming
+  - stream lifecycle
+---
+
+Stream methods live on `world.streams` (the `streams` sub-object of the `World` instance returned by `await getWorld()`). Use them to write chunks, read streams, and manage stream lifecycle outside of the standard `getWritable()` pattern.
+
+<Callout type="info">
+  For most streaming use cases, use [`getWritable()`](/docs/api-reference/workflow/get-writable) inside steps. Direct stream methods are for advanced scenarios like building custom stream consumers or managing streams from outside a workflow.
+</Callout>
+
+## Import
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+
+const world = await getWorld(); // [!code highlight]
+// Stream methods are called on world.streams — e.g. world.streams.write()
+```
+
+## Methods
+
+### write()
+
+Write a data chunk to a named stream.
+
+```typescript lineNumbers
+await world.streams.write(runId, "default", chunk); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `runId` | `string` | The workflow run ID |
+| `name` | `string` | The stream name |
+| `chunk` | `string \| Uint8Array` | Data to write |
+
+### writeMulti()
+
+Write multiple chunks in a single operation. Optional optimization — not all World implementations support it. Falls back to sequential `write()` calls if unavailable.
+
+```typescript lineNumbers
+await world.streams.writeMulti?.(runId, "default", [chunk1, chunk2]); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `runId` | `string` | The workflow run ID |
+| `name` | `string` | The stream name |
+| `chunks` | `(string \| Uint8Array)[]` | Chunks to write, in order |
+
+### get()
+
+Read data from a named stream as a live `ReadableStream` that waits for new chunks in real time.
+
+```typescript lineNumbers
+const readable = await world.streams.get(runId, "default"); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `runId` | `string` | The workflow run ID |
+| `name` | `string` | The stream name |
+| `startIndex` | `number` | Optional. Positive values skip chunks from the start (0-based). Negative values read from the tail (e.g. `-3` starts 3 chunks from the end). Clamped to 0. |
+
+**Returns:** `ReadableStream<Uint8Array>`
+
+### close()
+
+Close a stream when done writing.
+
+```typescript lineNumbers
+await world.streams.close(runId, "default"); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `runId` | `string` | The workflow run ID |
+| `name` | `string` | The stream name |
+
+### list()
+
+List all stream names associated with a workflow run.
+
+```typescript lineNumbers
+const streamNames = await world.streams.list(runId); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `runId` | `string` | The workflow run ID |
+
+**Returns:** `string[]`
+
+### getChunks()
+
+Fetch stream chunks with cursor-based pagination. Unlike `get()` (which returns a live `ReadableStream`), this returns a snapshot of currently available chunks.
+
+```typescript lineNumbers
+const result = await world.streams.getChunks(runId, "default", { // [!code highlight]
+  limit: 50,
+}); // [!code highlight]
+// result.data: StreamChunk[], result.cursor, result.hasMore, result.done
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `runId` | `string` | The workflow run ID |
+| `name` | `string` | The stream name |
+| `options.limit` | `number` | Max chunks per page (default: 100, max: 1000) |
+| `options.cursor` | `string` | Cursor from a previous response |
+
+**Returns:** `StreamChunksResponse`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `data` | `StreamChunk[]` | Chunks in index order. Each has `index` (0-based) and `data` (`Uint8Array`). |
+| `cursor` | `string \| null` | Cursor for the next page |
+| `hasMore` | `boolean` | Whether more pages of already-written chunks exist |
+| `done` | `boolean` | Whether the stream is fully closed. When `false`, new chunks may appear in future requests even after `hasMore` is `false`. |
+
+### getInfo()
+
+Retrieve lightweight metadata about a stream without fetching chunks.
+
+```typescript lineNumbers
+const info = await world.streams.getInfo(runId, "default"); // [!code highlight]
+// info.tailIndex: last chunk index (-1 if empty), info.done: whether stream is closed
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `runId` | `string` | The workflow run ID |
+| `name` | `string` | The stream name |
+
+**Returns:** `StreamInfoResponse`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `tailIndex` | `number` | Index of the last known chunk (0-based). `-1` when no chunks have been written. |
+| `done` | `boolean` | Whether the stream is fully complete (closed). |
+
+## Examples
+
+### Read a Stream as a Response
+
+```typescript lineNumbers
+// app/api/workflow-streams/read/route.ts
+import { getWorld } from "workflow/runtime";
+
+export async function GET(req: Request) {
+  const url = new URL(req.url);
+  const streamName = url.searchParams.get("name") ?? "default";
+  const runId = url.searchParams.get("runId")!;
+  const world = await getWorld();
+  const readable = await world.streams.get(runId, streamName); // [!code highlight]
+
+  return new Response(readable, {
+    headers: { "Content-Type": "application/octet-stream" },
+  });
+}
+```
+
+### Paginate Through Stream Chunks
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+
+const world = await getWorld();
+let cursor: string | undefined;
+
+do {
+  const result = await world.streams.getChunks(runId, "default", { cursor }); // [!code highlight]
+  for (const chunk of result.data) {
+    console.log(`Chunk ${chunk.index}:`, chunk.data);
+  }
+  cursor = result.cursor ?? undefined;
+} while (cursor);
+```
+
+## Related
+
+- [Streaming](/docs/foundations/streaming) — Core concepts for streaming data from workflows
+- [getWritable()](/docs/api-reference/workflow/get-writable) — The standard way to write to streams from within steps
+- [Storage](/docs/api-reference/workflow-runtime/world/storage) — Query runs, steps, hooks, and events

package/docs/v4/api-reference/workflow-sveltekit/index.mdx

@@ -0,0 +1,18 @@
+---
+title: "workflow/sveltekit"
+description: SvelteKit integration for automatic workflow bundling via Vite.
+type: overview
+summary: Explore the SvelteKit integration for automatic workflow bundling and runtime support.
+related:
+  - /docs/getting-started/sveltekit
+---
+
+SvelteKit integration for Workflow SDK that configures Vite to transform workflow code and build the workflow bundles.
+
+## Functions
+
+<Cards>
+    <Card title="workflowPlugin()" href="/docs/api-reference/workflow-sveltekit/workflow-plugin">
+        Vite plugin that transforms workflow code (`"use step"`/`"use workflow"` directives) in SvelteKit apps
+    </Card>
+</Cards>

package/docs/v4/api-reference/workflow-sveltekit/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "workflow/sveltekit",
+  "pages": ["workflow-plugin"]
+}

package/docs/v4/api-reference/workflow-sveltekit/workflow-plugin.mdx

@@ -0,0 +1,34 @@
+---
+title: workflowPlugin
+description: Configure Vite to transform workflow directives in SvelteKit.
+type: reference
+summary: Add workflowPlugin to your Vite config to enable workflow directive transformation in SvelteKit apps.
+prerequisites:
+  - /docs/getting-started/sveltekit
+---
+
+Returns the Vite plugins that transform workflow code (`"use step"`/`"use workflow"` directives) and build the workflow bundles in a SvelteKit app.
+
+## Usage
+
+To enable `"use step"` and `"use workflow"` directives while developing locally or deploying to production, add `workflowPlugin()` to the `plugins` array of your Vite config.
+
+```typescript title="vite.config.ts" lineNumbers
+import { sveltekit } from "@sveltejs/kit/vite";
+import { defineConfig } from "vite";
+import { workflowPlugin } from "workflow/sveltekit"; // [!code highlight]
+
+export default defineConfig({
+  plugins: [sveltekit(), workflowPlugin()], // [!code highlight]
+});
+```
+
+## API Signature
+
+### Parameters
+
+This function does not accept any parameters in workflow 4.x. (5.x adds an options object with a `sourcemap` setting.)
+
+### Returns
+
+Returns an array of Vite `Plugin` objects. Spread or pass the array directly to the `plugins` option of your Vite config — Vite flattens nested plugin arrays automatically.

package/docs/v4/api-reference/workflow-vite/index.mdx

@@ -0,0 +1,18 @@
+---
+title: "workflow/vite"
+description: Vite plugin for automatic workflow bundling in Vite + Nitro apps.
+type: overview
+summary: Explore the Vite plugin for automatic workflow bundling and runtime support.
+related:
+  - /docs/getting-started/vite
+---
+
+Vite integration for Workflow SDK. It wraps the [`workflow/nitro`](/docs/api-reference/workflow-nitro) module as a Vite plugin, for apps using Nitro's Vite plugin (`nitro/vite`).
+
+## Functions
+
+<Cards>
+    <Card title="workflow()" href="/docs/api-reference/workflow-vite/workflow">
+        Vite plugin that transforms workflow code (`"use step"`/`"use workflow"` directives) and configures the Nitro server
+    </Card>
+</Cards>

package/docs/v4/api-reference/workflow-vite/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "workflow/vite",
+  "pages": ["workflow"]
+}

package/docs/v4/api-reference/workflow-vite/workflow.mdx

@@ -0,0 +1,47 @@
+---
+title: workflow
+description: Configure Vite and Nitro to transform workflow directives.
+type: reference
+summary: Add the workflow plugin to your Vite config to enable workflow directive transformation in Vite + Nitro apps.
+prerequisites:
+  - /docs/getting-started/vite
+---
+
+Returns the Vite plugins that transform workflow code (`"use step"`/`"use workflow"` directives) and configure the [`workflow/nitro`](/docs/api-reference/workflow-nitro) module on the Nitro server. It is designed to be used alongside `nitro()` from `nitro/vite`, which provides the server framework for API routes and deployment.
+
+## Usage
+
+To enable `"use step"` and `"use workflow"` directives while developing locally or deploying to production, add `workflow()` to the `plugins` array of your Vite config, together with `nitro()`.
+
+```typescript title="vite.config.ts" lineNumbers
+import { nitro } from "nitro/vite";
+import { defineConfig } from "vite";
+import { workflow } from "workflow/vite"; // [!code highlight]
+
+export default defineConfig({
+  plugins: [nitro(), workflow()], // [!code highlight]
+  nitro: {
+    serverDir: "./",
+  },
+});
+```
+
+## API Signature
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options` | `ModuleOptions` | Optional. Forwarded to the `workflow/nitro` module as its module options. |
+
+#### ModuleOptions
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `dirs` | `string[]` | — | Directories to scan for workflows and steps. By default, the `workflows/` directory is scanned from the project root and all layer source directories. |
+| `typescriptPlugin` | `boolean` | `false` | Adds the `workflow` TypeScript plugin to the generated `tsconfig.json` for IDE IntelliSense. |
+| `runtime` | `string` | — | Node.js runtime version for Vercel Functions (e.g. `'nodejs22.x'`, `'nodejs24.x'`). Only applies when deploying to Vercel. |
+
+### Returns
+
+Returns an array of Vite `Plugin` objects. Spread or pass the array directly to the `plugins` option of your Vite config — Vite flattens nested plugin arrays automatically.

package/docs/v4/errors/step-executed-multiple-times.mdx

@@ -0,0 +1,23 @@
+---
+title: Step executed multiple times
+description: A step ran more than once because its function invocation crashed before it could report a result.
+type: troubleshooting
+summary: Diagnose duplicate step_started events caused by function timeouts, OOMs, or network issues.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/observability
+  - /docs/foundations/errors-and-retries
+---
+
+There may be cases where you see multiple `step_started` events for the same step in a workflow run. This happens if the function invocation executing the step crashes unexpectedly, and the step can not report the error. The step will be re-tried according to your retry policy in this case, but no error will be visible in the [Observability UI](/docs/observability).
+
+## Common Causes
+
+- **Function timeouts**: if your step code runs longer than the configured maximum function duration, it will be killed. Compare the gap between the `step_started` events to your configured function duration to be sure.
+- **Out of memory (OOM)**: if your step code loads enough data into memory, especially if the step is invoked concurrently, the function invocation might run out of memory. You can see your function's peak memory use by going to the [Observability Query page](https://vercel.com/docs/observability) and showing the **Function Invocation Peak Memory** metric, then filtering down the **Route** to `/.well-known/workflow` endpoints.
+- **Network issues**: persistent firewall, network stability, and related issues might prevent your function from reporting results or errors. This should be temporary.
+
+## Getting Help
+
+If you consistently see multiple `step_started` events and have ruled out function timeouts, OOMs, and firewall issues, please [contact support](https://vercel.com/help).

package/docs/v5/api-reference/workflow-astro/index.mdx

@@ -0,0 +1,18 @@
+---
+title: "workflow/astro"
+description: Astro integration for automatic workflow bundling and route registration.
+type: overview
+summary: Explore the Astro integration for automatic workflow bundling and runtime support.
+related:
+  - /docs/getting-started/astro
+---
+
+Astro integration for Workflow SDK that transforms workflow code and builds the workflow bundles.
+
+## Functions
+
+<Cards>
+    <Card title="workflow()" href="/docs/api-reference/workflow-astro/workflow">
+        Astro integration that transforms workflow code (`"use step"`/`"use workflow"` directives)
+    </Card>
+</Cards>

package/docs/v5/api-reference/workflow-astro/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "workflow/astro",
+  "pages": ["workflow"]
+}

package/docs/v5/api-reference/workflow-astro/workflow.mdx

@@ -0,0 +1,45 @@
+---
+title: workflow
+description: Configure Astro to transform workflow directives.
+type: reference
+summary: Add the workflow integration to your Astro config to enable workflow directive transformation.
+prerequisites:
+  - /docs/getting-started/astro
+---
+
+Returns an Astro integration that transforms workflow code (`"use step"`/`"use workflow"` directives) and builds the workflow bundles.
+
+## Usage
+
+To enable `"use step"` and `"use workflow"` directives while developing locally or deploying to production, add `workflow()` to the `integrations` array of your Astro config.
+
+```typescript title="astro.config.mjs" lineNumbers
+// @ts-check
+import { defineConfig } from "astro/config";
+import { workflow } from "workflow/astro"; // [!code highlight]
+
+// https://astro.build/config
+export default defineConfig({
+  integrations: [workflow()], // [!code highlight]
+});
+```
+
+The integration registers the workflow Vite transform plugins during `astro:config:setup` and builds the workflow bundles — locally during config setup, or via the Vercel builder after `astro:build:done` when deploying to Vercel.
+
+## API Signature
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options` | `WorkflowPluginOptions` | Optional. Configures the workflow build. |
+
+#### WorkflowPluginOptions
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `sourcemap` | `boolean \| 'inline' \| 'linked' \| 'external' \| 'both'` | `'inline'` | Controls source maps on generated workflow bundles. Accepts the same values as esbuild's `sourcemap` option. Set to `false` for smaller function bundles (useful for staying under the Vercel 250MB function size limit) at the cost of stack traces pointing at generated code. Can also be set via the `WORKFLOW_SOURCEMAP` environment variable. |
+
+### Returns
+
+Returns an `AstroIntegration` object to include in the `integrations` array of your Astro config.

package/docs/v5/api-reference/workflow-errors/hook-conflict-error.mdx

@@ -0,0 +1,60 @@
+---
+title: HookConflictError
+description: Thrown when creating a hook with a token that is already in use by another workflow run.
+type: reference
+summary: Catch HookConflictError when a hook token is already claimed by another active workflow run.
+related:
+  - /docs/api-reference/workflow/create-hook
+  - /docs/foundations/hooks
+  - /docs/errors/hook-conflict
+---
+
+`HookConflictError` is thrown when creating a hook with a token that is already in use by another active workflow run. Hook tokens must be unique across all running workflows — see the [hook-conflict](/docs/errors/hook-conflict) error guide for resolution strategies.
+
+```typescript lineNumbers
+import { HookConflictError } from "workflow/errors"
+declare function startApprovalWorkflow(token: string): Promise<void>; // @setup
+declare const token: string; // @setup
+
+try {
+  await startApprovalWorkflow(token);
+} catch (error) {
+  if (HookConflictError.is(error)) { // [!code highlight]
+    console.error(
+      `Token "${error.token}" already in use by run ${error.conflictingRunId}`
+    );
+  }
+}
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface HookConflictError {
+  /** The hook token that conflicted. */
+  token: string;
+  /** The run ID of the workflow currently holding the token, when known. */
+  conflictingRunId?: string;
+  /** The error message. */
+  message: string;
+}
+export default HookConflictError;`}
+/>
+
+### Static Methods
+
+#### `HookConflictError.is(value)`
+
+Type-safe check for `HookConflictError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { HookConflictError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (HookConflictError.is(error)) {
+  // error is typed as HookConflictError
+}
+```