workflow 5.0.0-beta.34 → 5.0.0-beta.36

package/dist/internal/errors.d.ts

@@ -1,2 +1,2 @@
-export { EntityConflictError, HookConflictError, HookNotFoundError, RunExpiredError, RunNotSupportedError, StepNotRegisteredError, ThrottleError, TooEarlyError, WorkflowError, WorkflowNotRegisteredError, WorkflowRunCancelledError, WorkflowRunFailedError, WorkflowRunNotCompletedError, WorkflowRunNotFoundError, WorkflowRuntimeError, WorkflowWorldError, } from '@workflow/errors';
+export { EntityConflictError, HookConflictError, HookNotFoundError, PreconditionFailedError, RunExpiredError, RunNotSupportedError, StepNotRegisteredError, ThrottleError, TooEarlyError, WorkflowError, WorkflowNotRegisteredError, WorkflowRunCancelledError, WorkflowRunFailedError, WorkflowRunNotCompletedError, WorkflowRunNotFoundError, WorkflowRuntimeError, WorkflowWorldError, } from '@workflow/errors';
 //# sourceMappingURL=errors.d.ts.map

package/dist/internal/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/internal/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,aAAa,EACb,aAAa,EACb,aAAa,EACb,0BAA0B,EAC1B,yBAAyB,EACzB,sBAAsB,EACtB,4BAA4B,EAC5B,wBAAwB,EACxB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/internal/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,uBAAuB,EACvB,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,aAAa,EACb,aAAa,EACb,aAAa,EACb,0BAA0B,EAC1B,yBAAyB,EACzB,sBAAsB,EACtB,4BAA4B,EAC5B,wBAAwB,EACxB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC"}

package/dist/internal/errors.js

@@ -1,2 +1,2 @@
-export { EntityConflictError, HookConflictError, HookNotFoundError, RunExpiredError, RunNotSupportedError, StepNotRegisteredError, ThrottleError, TooEarlyError, WorkflowError, WorkflowNotRegisteredError, WorkflowRunCancelledError, WorkflowRunFailedError, WorkflowRunNotCompletedError, WorkflowRunNotFoundError, WorkflowRuntimeError, WorkflowWorldError, } from '@workflow/errors';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXJyb3JzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2ludGVybmFsL2Vycm9ycy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQ0wsbUJBQW1CLEVBQ25CLGlCQUFpQixFQUNqQixpQkFBaUIsRUFDakIsZUFBZSxFQUNmLG9CQUFvQixFQUNwQixzQkFBc0IsRUFDdEIsYUFBYSxFQUNiLGFBQWEsRUFDYixhQUFhLEVBQ2IsMEJBQTBCLEVBQzFCLHlCQUF5QixFQUN6QixzQkFBc0IsRUFDdEIsNEJBQTRCLEVBQzVCLHdCQUF3QixFQUN4QixvQkFBb0IsRUFDcEIsa0JBQWtCLEdBQ25CLE1BQU0sa0JBQWtCLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyJleHBvcnQge1xuICBFbnRpdHlDb25mbGljdEVycm9yLFxuICBIb29rQ29uZmxpY3RFcnJvcixcbiAgSG9va05vdEZvdW5kRXJyb3IsXG4gIFJ1bkV4cGlyZWRFcnJvcixcbiAgUnVuTm90U3VwcG9ydGVkRXJyb3IsXG4gIFN0ZXBOb3RSZWdpc3RlcmVkRXJyb3IsXG4gIFRocm90dGxlRXJyb3IsXG4gIFRvb0Vhcmx5RXJyb3IsXG4gIFdvcmtmbG93RXJyb3IsXG4gIFdvcmtmbG93Tm90UmVnaXN0ZXJlZEVycm9yLFxuICBXb3JrZmxvd1J1bkNhbmNlbGxlZEVycm9yLFxuICBXb3JrZmxvd1J1bkZhaWxlZEVycm9yLFxuICBXb3JrZmxvd1J1bk5vdENvbXBsZXRlZEVycm9yLFxuICBXb3JrZmxvd1J1bk5vdEZvdW5kRXJyb3IsXG4gIFdvcmtmbG93UnVudGltZUVycm9yLFxuICBXb3JrZmxvd1dvcmxkRXJyb3IsXG59IGZyb20gJ0B3b3JrZmxvdy9lcnJvcnMnO1xuIl19
+export { EntityConflictError, HookConflictError, HookNotFoundError, PreconditionFailedError, RunExpiredError, RunNotSupportedError, StepNotRegisteredError, ThrottleError, TooEarlyError, WorkflowError, WorkflowNotRegisteredError, WorkflowRunCancelledError, WorkflowRunFailedError, WorkflowRunNotCompletedError, WorkflowRunNotFoundError, WorkflowRuntimeError, WorkflowWorldError, } from '@workflow/errors';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXJyb3JzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2ludGVybmFsL2Vycm9ycy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQ0wsbUJBQW1CLEVBQ25CLGlCQUFpQixFQUNqQixpQkFBaUIsRUFDakIsdUJBQXVCLEVBQ3ZCLGVBQWUsRUFDZixvQkFBb0IsRUFDcEIsc0JBQXNCLEVBQ3RCLGFBQWEsRUFDYixhQUFhLEVBQ2IsYUFBYSxFQUNiLDBCQUEwQixFQUMxQix5QkFBeUIsRUFDekIsc0JBQXNCLEVBQ3RCLDRCQUE0QixFQUM1Qix3QkFBd0IsRUFDeEIsb0JBQW9CLEVBQ3BCLGtCQUFrQixHQUNuQixNQUFNLGtCQUFrQixDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiZXhwb3J0IHtcbiAgRW50aXR5Q29uZmxpY3RFcnJvcixcbiAgSG9va0NvbmZsaWN0RXJyb3IsXG4gIEhvb2tOb3RGb3VuZEVycm9yLFxuICBQcmVjb25kaXRpb25GYWlsZWRFcnJvcixcbiAgUnVuRXhwaXJlZEVycm9yLFxuICBSdW5Ob3RTdXBwb3J0ZWRFcnJvcixcbiAgU3RlcE5vdFJlZ2lzdGVyZWRFcnJvcixcbiAgVGhyb3R0bGVFcnJvcixcbiAgVG9vRWFybHlFcnJvcixcbiAgV29ya2Zsb3dFcnJvcixcbiAgV29ya2Zsb3dOb3RSZWdpc3RlcmVkRXJyb3IsXG4gIFdvcmtmbG93UnVuQ2FuY2VsbGVkRXJyb3IsXG4gIFdvcmtmbG93UnVuRmFpbGVkRXJyb3IsXG4gIFdvcmtmbG93UnVuTm90Q29tcGxldGVkRXJyb3IsXG4gIFdvcmtmbG93UnVuTm90Rm91bmRFcnJvcixcbiAgV29ya2Zsb3dSdW50aW1lRXJyb3IsXG4gIFdvcmtmbG93V29ybGRFcnJvcixcbn0gZnJvbSAnQHdvcmtmbG93L2Vycm9ycyc7XG4iXX0=

package/dist/nest-builder.d.ts

@@ -0,0 +1,2 @@
+export * from '@workflow/nest/builder';
+//# sourceMappingURL=nest-builder.d.ts.map

package/dist/nest-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nest-builder.d.ts","sourceRoot":"","sources":["../src/nest-builder.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC"}

package/dist/nest-builder.js

@@ -0,0 +1,2 @@
+export * from '@workflow/nest/builder';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibmVzdC1idWlsZGVyLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL25lc3QtYnVpbGRlci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxjQUFjLHdCQUF3QixDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiZXhwb3J0ICogZnJvbSAnQHdvcmtmbG93L25lc3QvYnVpbGRlcic7XG4iXX0=

package/dist/nest-vercel-builder.d.ts

@@ -0,0 +1,2 @@
+export * from '@workflow/nest/vercel-builder';
+//# sourceMappingURL=nest-vercel-builder.d.ts.map

package/dist/nest-vercel-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nest-vercel-builder.d.ts","sourceRoot":"","sources":["../src/nest-vercel-builder.ts"],"names":[],"mappings":"AAAA,cAAc,+BAA+B,CAAC"}

package/dist/nest-vercel-builder.js

@@ -0,0 +1,2 @@
+export * from '@workflow/nest/vercel-builder';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibmVzdC12ZXJjZWwtYnVpbGRlci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy9uZXN0LXZlcmNlbC1idWlsZGVyLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsK0JBQStCLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyJleHBvcnQgKiBmcm9tICdAd29ya2Zsb3cvbmVzdC92ZXJjZWwtYnVpbGRlcic7XG4iXX0=

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

@@ -66,7 +66,7 @@ export default Hook;`}
 
 The returned `Hook` object also implements `AsyncIterable<T>`, which allows you to iterate over incoming payloads using `for await...of` syntax.
 
-Use `hook.getConflict()` to check whether the hook token is already claimed by another active hook, without waiting for hook payload data. Calling `createHook()` on its own does not register the hook — registration is only committed when the workflow suspends. Awaiting `hook.getConflict()` suspends the workflow to commit the registration, then resolves with `null` once `hook_created` is recorded, or with the conflicting [`Run`](/docs/api-reference/workflow-api/get-run) if another active hook already owns the same token.
+Use `hook.getConflict()` to check whether the hook token is already claimed by another hook, including one kept reserved after its run ends, without waiting for hook payload data. Calling `createHook()` on its own does not register the hook — registration is only committed when the workflow suspends. Awaiting `hook.getConflict()` suspends the workflow to commit the registration, then resolves with `null` once `hook_created` is recorded, or with the conflicting [`Run`](/docs/api-reference/workflow-api/get-run).
 
 ## Examples
 
@@ -143,12 +143,53 @@ async function processOrder(orderId: string) {
 
 Because `createHook()` alone does not suspend the workflow, awaiting `hook.getConflict()` is what actually suspends the run and commits the hook registration. It only waits for registration — to receive payload data from a future `resumeHook()` call, await the hook itself or iterate it with `for await...of`.
 
-On a conflict, the resolved value is a `Run` handle for the run that currently owns the token, with durable step-backed accessors. The duplicate run can decide in code how to handle it: return or log `conflict.runId`, inspect `await conflict.status`, wait on `await conflict.returnValue`, or cancel the owner with `await conflict.cancel()` and continue in the current run. See [Run idempotency](/docs/foundations/idempotency#run-idempotency) for these strategies in context.
+On a conflict, the resolved value is a `Run` handle for the run that owns the token, with durable step-backed accessors. The duplicate run can decide in code how to handle it: return or log `conflict.runId`, inspect `await conflict.status`, wait on `await conflict.returnValue`, or cancel the owner with `await conflict.cancel()` and continue in the current run. See [Run idempotency](/docs/foundations/idempotency#run-idempotency) for these strategies in context.
 
 <Callout type="info">
 Custom hook tokens are the recommended way to coordinate active workflow runs. Use a deterministic token from your domain, such as an order ID or conversation ID, create the hook near the beginning of the workflow, and check `await hook.getConflict()` before work that depends on owning the token. See [Run idempotency](/docs/foundations/idempotency#run-idempotency).
 </Callout>
 
+### Keep a Token Unavailable After the Run Ends
+
+By default, another Hook can use the token after its workflow ends. Set `experimental_minRetention` to keep the token unavailable for at least a specific time after `createHook()` runs:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+declare function processOwnedOrder(orderId: string): Promise<void>; // @setup
+
+export async function processOrder(orderId: string) {
+  "use workflow";
+
+  const hook = createHook({ // [!code highlight]
+    token: `order:${orderId}`, // [!code highlight]
+    experimental_minRetention: "30d", // [!code highlight]
+  }); // [!code highlight]
+
+  const conflict = await hook.getConflict();
+  if (conflict) {
+    return { status: "duplicate" as const, runId: conflict.runId };
+  }
+
+  await processOwnedOrder(orderId);
+  return { status: "processed" as const };
+}
+```
+
+`experimental_minRetention` accepts the same values as [`sleep()`](/docs/api-reference/workflow/sleep): a duration string such as `"30d"`, a number of milliseconds, or an absolute `Date`. Durations start when `createHook()` runs.
+
+The Hook remains active until the workflow ends, even if the configured time passes first. Another Hook can use the token only after both the workflow has ended and the configured time has passed. For example, `"30d"` keeps the token unavailable for 29 more days if the workflow ends after 1 day. A workflow that runs for more than 30 days releases the token when it ends.
+
+After the workflow ends, [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token) can still find the Hook until retention ends, but the Hook cannot be resumed.
+
+<Callout type="warn">
+`using` auto-disposes the Hook at scope exit, which releases the token immediately and defeats `experimental_minRetention`. Declare retained Hooks with `const` and let the runtime clean them up when the run ends.
+</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.
+</Callout>
+
 ### Waiting for Multiple Payloads
 
 You can also wait for multiple payloads by using the `for await...of` syntax.

package/docs/api-reference/workflow/define-hook.mdx

@@ -46,24 +46,21 @@ showSections={['parameters']}
 
 ### Returns
 
+`defineHook()` returns a `TypedHook<TInput, TOutput>`:
+
 <TSDoc
 definition={`
-interface DefineHook<T> {
-  /**
-
-* Creates a new hook with the defined payload type.
-  */
-  create: (options?: HookOptions) => Hook<T>;
-
-  /**
-
-* Resumes a hook by sending a payload with the defined type.
-   */
-  resume: (token: string, payload: T) => Promise<HookEntity | null>;
+interface TypedHook<TInput, TOutput> {
+  /** Creates the hook. Call inside a "use workflow" function. */
+  create(options?: HookOptions): Hook<TOutput>;
+  /** Resumes the hook from runtime code. Resolves to the resumed hook; throws HookNotFoundError if the token does not match an active hook. */
+  resume(token: string, payload: TInput): Promise<HookEntity>;
 }
-export default DefineHook;`}
+export default TypedHook;`}
 />
 
+`create()` is called inside a `"use workflow"` function to create the hook; `resume()` is called from runtime code (an API route or server action). When a `schema` is provided, `resume()` accepts the raw input type (`TInput`) and the workflow receives the validated and possibly transformed output type (`TOutput`); without a schema, `TOutput` defaults to `TInput`. `resume()` throws [`HookNotFoundError`](/docs/api-reference/workflow-errors/hook-not-found-error) if the token does not match an active hook — it does not return `null`.
+
 ## Examples
 
 ### Basic Type-Safe Hook Definition
@@ -93,24 +90,29 @@ export async function workflowWithApproval() {
 
 ### Resuming with Type Safety
 
-Hooks can be resumed using the same defined hook and a token. By using the same hook, you can ensure that the payload matches the defined type when resuming a hook.
+Hooks can be resumed using the same defined hook and a token. By using the same hook, you can ensure that the payload matches the defined type when resuming a hook. `resume()` resolves to the resumed hook and throws [`HookNotFoundError`](/docs/api-reference/workflow-errors/hook-not-found-error) if the token does not match an active hook.
 
 ```typescript lineNumbers
+import { HookNotFoundError } from "workflow/errors";
+
 // Use the same defined hook to resume
 export async function POST(request: Request) {
   const { token, approved, comment } = await request.json();
 
-  // Type-safe resumption - TypeScript ensures the payload matches
-  const result = await approvalHook.resume(token, { // [!code highlight]
-    approved, // [!code highlight]
-    comment, // [!code highlight]
-  }); // [!code highlight]
-
-  if (!result) {
-    return Response.json({ error: "Hook not found" }, { status: 404 });
+  try {
+    // Type-safe resumption - TypeScript ensures the payload matches
+    const hook = await approvalHook.resume(token, { // [!code highlight]
+      approved, // [!code highlight]
+      comment, // [!code highlight]
+    }); // [!code highlight]
+
+    return Response.json({ success: true, runId: hook.runId });
+  } catch (error) {
+    if (HookNotFoundError.is(error)) { // [!code highlight]
+      return Response.json({ error: "Hook not found" }, { status: 404 });
+    }
+    throw error;
   }
-
-  return Response.json({ success: true, runId: result.runId });
 }
 ```
 

package/docs/api-reference/workflow/fatal-error.mdx

@@ -29,16 +29,38 @@ async function fallibleStep() {
 
 ## API Signature
 
-### Parameters
+### Constructor
+
+`new FatalError(message)`
+
+| Parameter | Type     | Description        |
+| --------- | -------- | ------------------ |
+| `message` | `string` | The error message. |
+
+### Properties
 
 <TSDoc
 definition={`
-interface Error {
-  /**
-
-* The error message.
-   */
+interface FatalError {
+  /** The error message. */
   message: string;
+  /** Always true. Marks the error as non-retryable. */
+  fatal: boolean;
 }
-export default Error;`}
+export default FatalError;`}
 />
+
+### Static Methods
+
+#### `FatalError.is(value)`
+
+Type-safe check for `FatalError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { FatalError } from "workflow"
+declare const error: unknown; // @setup
+
+if (FatalError.is(error)) {
+  // error is typed as FatalError
+}
+```

package/docs/api-reference/workflow/fetch.mdx

@@ -93,7 +93,7 @@ This API is provided as a convenience to easily use `fetch` in workflow, but oft
 
 ### Customizing Fetch Behavior
 
-Here's an example of a custom fetch wrapper that provides more sophisticated error handling with custom retry logic:
+Here's an example of a custom fetch wrapper that provides more sophisticated error handling with custom retry logic. Call `globalThis.fetch` inside your own `"use step"` function — calling the workflow `fetch` imported from `workflow` would nest a step inside a step:
 
 ```typescript lineNumbers
 import { FatalError, RetryableError } from "workflow"
@@ -104,7 +104,7 @@ export async function customFetch(
 ) {
     "use step"
 
-    const response = await fetch(url, init)
+    const response = await globalThis.fetch(url, init)
 
     // Handle client errors (4xx) - don't retry
     if (response.status >= 400 && response.status < 500) {
@@ -145,7 +145,6 @@ export async function customFetch(
 
 This example demonstrates:
 
-- Setting custom `maxRetries` to 5 retries (6 total attempts including the initial attempt).
 - Throwing [`FatalError`](/docs/api-reference/workflow/fatal-error) for client errors (400-499) to prevent retries.
 - Handling 429 rate limiting by reading the `Retry-After` header and using [`RetryableError`](/docs/api-reference/workflow/retryable-error).
-- Allowing automatic retries for server errors (5xx).
+- Allowing automatic retries for server errors (5xx) by throwing a plain `Error`.

package/docs/api-reference/workflow/sleep.mdx

@@ -14,7 +14,7 @@ Suspends a workflow for a specified duration or until an end date without consum
 This is useful when you want to resume a workflow after some duration or date.
 
 <Callout>
-`sleep` is a *special* type of step function and should be called directly inside workflow functions.
+`sleep` is a built-in workflow runtime function (backed by a timer event in the event log, not a step) and should be called directly inside workflow functions.
 </Callout>
 
 ```typescript lineNumbers

package/docs/api-reference/workflow-api/get-hook-by-token.mdx

@@ -11,6 +11,8 @@ related:
 
 Retrieves a hook by its unique token, returning the associated workflow run information and any metadata that was set when the hook was created. This function is useful for inspecting hook details before deciding whether to resume a workflow.
 
+When `experimental_minRetention` is set, this function continues to return the Hook after its workflow ends until retention ends. That Hook cannot be resumed. Use `getRun(hook.runId)` to inspect the finished run.
+
 <Callout type="warn">
 `getHookByToken` is a runtime function that must be called from outside a workflow function.
 </Callout>

package/docs/api-reference/workflow-api/resume-hook.mdx

@@ -14,6 +14,8 @@ Resumes a workflow run by sending a payload to a hook identified by its token.
 
 It creates a `hook_received` event and re-triggers the workflow to continue execution.
 
+A Hook kept by `experimental_minRetention` after its workflow ends cannot be resumed. `resumeHook()` throws `HookNotFoundError` in that case.
+
 <Callout type="warn">
 `resumeHook` is a runtime function that must be called from outside a workflow function.
 </Callout>

package/docs/api-reference/workflow-api/resume-webhook.mdx

@@ -50,11 +50,13 @@ showSections={['parameters']}
 
 ### Returns
 
-Returns a `Promise<Response>` that resolves to:
+Returns a `Promise<Response>` that resolves to one of:
 
-- `Response`: The HTTP response from the workflow's `respondWith()` call
+- A `202 Accepted` response when the webhook was created in the default mode (no `respondWith` option).
+- The exact `Response` object configured via `createWebhook({ respondWith: new Response(...) })`.
+- The workflow's manual `Response` when the webhook was created with `createWebhook({ respondWith: "manual" })` and a step calls `request.respondWith(response)`.
 
-Throws an error if the webhook token is not found or invalid.
+Throws [`HookNotFoundError`](/docs/api-reference/workflow-errors/hook-not-found-error) if the token does not match an active webhook.
 
 ## Usage Note
 
@@ -81,7 +83,7 @@ export async function POST(request: Request) {
 
   try {
     const response = await resumeWebhook(token, request); // [!code highlight]
-    return response; // Returns the workflow's custom response
+    return response; // 202 Accepted, a configured static Response, or a manual workflow response
   } catch (error) {
     return new Response("Webhook not found", { status: 404 });
   }

package/docs/api-reference/workflow-api/start.mdx

@@ -62,7 +62,7 @@ Learn more about [`WorkflowReadableStreamOptions`](/docs/api-reference/workflow-
 * `attributes` seeds plaintext run metadata as part of creation and requires a World implementing spec version 4 or later. Keys that start with `$` are reserved for framework and library code; framework-level callers can pass `allowReservedAttributes: true` to seed reserved keys, with the same semantics as the [`setAttributes`](/docs/api-reference/workflow/set-attributes) option of the same name.
 
 <Callout type="info">
-If `start()` throws `'start' received an invalid workflow function. Ensure the Workflow Development Kit is configured correctly and the function includes a 'use workflow' directive.`, the passed function was not transformed as a workflow. The two most common causes are a missing `"use workflow"` directive or missing framework integration. See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function).
+If `start()` throws `'start' received an invalid workflow function. Ensure the Workflow SDK is configured correctly and the function includes a 'use workflow' directive.`, the passed function was not transformed as a workflow. The two most common causes are a missing `"use workflow"` directive or missing framework integration. See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function).
 </Callout>
 
 ## Examples

package/docs/api-reference/workflow-errors/index.mdx

@@ -79,6 +79,9 @@ All errors extend [`WorkflowError`](/docs/api-reference/workflow-errors/workflow
     <Card href="/docs/api-reference/workflow-errors/entity-conflict-error" title="EntityConflictError">
         Thrown when a storage operation conflicts with the current entity state.
     </Card>
+    <Card href="/docs/api-reference/workflow-errors/precondition-failed-error" title="PreconditionFailedError">
+        Thrown when an event creation is rejected because the client's event-log snapshot is stale.
+    </Card>
     <Card href="/docs/api-reference/workflow-errors/too-early-error" title="TooEarlyError">
         Thrown when a request is made before the system is ready to process it.
     </Card>

package/docs/api-reference/workflow-errors/meta.json

@@ -14,6 +14,7 @@
     "workflow-world-error",
     "throttle-error",
     "entity-conflict-error",
+    "precondition-failed-error",
     "run-expired-error",
     "run-not-supported-error",
     "too-early-error"

package/docs/api-reference/workflow-errors/precondition-failed-error.mdx

@@ -0,0 +1,62 @@
+---
+title: PreconditionFailedError
+description: Thrown when an event creation is rejected because the client's event-log snapshot is stale.
+type: reference
+summary: Catch PreconditionFailedError when a world rejects an event creation made from a stale event-log snapshot.
+related:
+  - /docs/api-reference/workflow-errors/workflow-world-error
+  - /docs/api-reference/workflow-errors/entity-conflict-error
+---
+
+`PreconditionFailedError` is thrown by world implementations when an event creation is rejected because the client's event-log snapshot is stale — a newer out-of-band event (such as a received hook or a completed step) was recorded after the snapshot the client replayed from. It corresponds to HTTP 412 Precondition Failed semantics.
+
+This only occurs when the optimistic-concurrency guard is enabled via `WORKFLOW_PRECONDITION_GUARD=1` (see [Runtime Tuning](/docs/configuration/runtime-tuning)); event creations that carry no snapshot are never rejected with this error.
+
+<Callout>
+The Workflow runtime handles this error automatically: it reloads the event log and retries, ultimately re-enqueueing the run for a fresh replay if it cannot catch up. You will only encounter it when interacting with world storage APIs directly.
+</Callout>
+
+```typescript lineNumbers
+import { PreconditionFailedError } from "workflow/errors"
+declare const world: { events: { create(...args: any[]): Promise<any> } }; // @setup
+declare const runId: string; // @setup
+declare const event: any; // @setup
+
+try {
+  await world.events.create(runId, event);
+} catch (error) {
+  if (PreconditionFailedError.is(error)) { // [!code highlight]
+    console.log("Snapshot is stale; reload the event log and retry");
+  }
+}
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface PreconditionFailedError {
+  /** Delay in seconds before the operation should be retried. Present when the server sends a Retry-After header. */
+  retryAfter?: number;
+  /** The error message. */
+  message: string;
+}
+export default PreconditionFailedError;`}
+/>
+
+### Static Methods
+
+#### `PreconditionFailedError.is(value)`
+
+Type-safe check for `PreconditionFailedError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { PreconditionFailedError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (PreconditionFailedError.is(error)) {
+  // error is typed as PreconditionFailedError
+}
+```

package/docs/api-reference/workflow-nest/nest-local-builder.mdx

@@ -12,7 +12,7 @@ Builder that scans a NestJS project for workflow files and compiles them into th
 ## Usage
 
 ```typescript title="scripts/build-workflows.ts" lineNumbers
-import { NestLocalBuilder } from "workflow/nest"; // [!code highlight]
+import { NestLocalBuilder } from "workflow/nest/builder"; // [!code highlight]
 
 const builder = new NestLocalBuilder({
   dirs: ["src"],

package/docs/comparisons/index.mdx

@@ -0,0 +1,66 @@
+---
+title: Comparisons
+description: How the Workflow SDK compares to other durable execution, workflow, and AI-agent frameworks — Temporal, Cloudflare Workflows, AWS Step Functions, AWS Bedrock AgentCore, Inngest, and trigger.dev.
+type: overview
+summary: Side-by-side comparisons of the Workflow SDK against Temporal, Cloudflare Workflows, AWS Step Functions, AWS Bedrock AgentCore, Inngest, and trigger.dev.
+related:
+  - /docs/foundations/workflows-and-steps
+  - /docs/how-it-works/event-sourcing
+  - /worlds/vercel
+---
+
+The Workflow SDK overlaps with several categories: durable execution engines, background-job platforms, managed orchestrators, and AI-agent runtimes. This section compares it against the most common alternatives, one deep dive per tool.
+
+## What makes the Workflow SDK different
+
+- **It's an open-source SDK, not a hosted product.** Your workflows are plain TypeScript in your existing app. Run them on the managed [Vercel World](/worlds/vercel), or self-host on the [Postgres World](/worlds/postgres) — the [World abstraction](/worlds/building-a-world) lets you own and swap the storage, queue, and streaming layers independently.
+- **Versioning is safe by default.** Runs are pinned to the immutable deployment that started them, so shipping new code never disturbs in-flight runs. Upgrading a run is explicit and opt-in. See [Versioning](/docs/comparisons/workflow-sdk-vs-temporal#versioning).
+- **Realtime durable streaming is built in.** Stream partial output (LLM tokens, progress) to clients with [streams](/docs/foundations/streaming) that survive reconnects, cold starts, and replays — essential for chat and agent UIs.
+- **First-class AI agents.** `WorkflowAgent` ships inside the [AI SDK](/docs/ai), turning an agent loop into a durable workflow with automatic step retries and human-in-the-loop pauses.
+
+## Snapshot
+
+<Callout type="info">
+These comparisons are compiled from each product's public documentation and are **not** based on head-to-head benchmarks — durable engines differ enough that a single number rarely compares cleanly. Treat them as directional and verify current pricing and limits against each vendor's docs.
+</Callout>
+
+| Tool | Category | Durability model | Open source / self-host | Language(s) |
+| --- | --- | --- | --- | --- |
+| **Workflow SDK** | Durable functions SDK | Event-log + deterministic replay | ✅ Apache-2.0 — self-host (Postgres) or Vercel | TypeScript (Python beta) |
+| [Temporal](/docs/comparisons/workflow-sdk-vs-temporal) | Durable execution platform | Event-sourced replay | ✅ MIT server — self-host or Temporal Cloud | Go, Java, TS, Python, .NET, PHP, Ruby |
+| [Cloudflare Workflows](/docs/comparisons/workflow-sdk-vs-cloudflare-workflows) | Durable execution engine | Step-result memoization + replay | ❌ Cloudflare-only | TypeScript (Python beta) |
+| [AWS Step Functions](/docs/comparisons/workflow-sdk-vs-aws-step-functions) | Managed state-machine orchestrator | Declarative ASL state machine | ❌ AWS-only | ASL JSON (tasks: any language) |
+| [AWS Bedrock AgentCore](/docs/comparisons/workflow-sdk-vs-aws-agentcore) | AI-agent hosting platform | Not durable execution (ephemeral sessions) | ❌ AWS-only | Python, Node.js |
+| [Inngest](/docs/comparisons/workflow-sdk-vs-inngest) | Durable functions / event platform | Step-result memoization | ◑ SSPL — self-host (community/best-effort) or SaaS | TypeScript (Python/Go pre-1.0) |
+| [trigger.dev](/docs/comparisons/workflow-sdk-vs-trigger-dev) | Durable task platform | Process checkpoint/restore (CRIU) | ✅ Apache-2.0 — self-host or Cloud | TypeScript only |
+
+## Deep dives
+
+<Cards>
+    <Card href="/docs/comparisons/workflow-sdk-vs-temporal" title="vs Temporal">
+        The mature, language-agnostic durable-execution platform. You run the workers; Workflow SDK runs in your app.
+    </Card>
+    <Card href="/docs/comparisons/workflow-sdk-vs-cloudflare-workflows" title="vs Cloudflare Workflows">
+        A durable engine on Workers + Durable Objects. Both replay; they handle versioning and encryption very differently.
+    </Card>
+    <Card href="/docs/comparisons/workflow-sdk-vs-aws-step-functions" title="vs AWS Step Functions">
+        Declarative ASL JSON state machines vs. plain TypeScript control flow.
+    </Card>
+    <Card href="/docs/comparisons/workflow-sdk-vs-aws-agentcore" title="vs AWS Bedrock AgentCore">
+        An AI-agent hosting platform — not a durable-execution engine. Different axis.
+    </Card>
+    <Card href="/docs/comparisons/workflow-sdk-vs-inngest" title="vs Inngest">
+        Event-driven durable functions that run on your own infra over HTTP.
+    </Card>
+    <Card href="/docs/comparisons/workflow-sdk-vs-trigger-dev" title="vs trigger.dev">
+        A TypeScript task platform that achieves durability by snapshotting the process (CRIU).
+    </Card>
+</Cards>
+
+<Callout type="info">
+Moving an existing system over? Each deep dive includes a concept-mapping section, and the Workflow SDK migration skill can translate code for you:
+
+```bash
+npx skills add https://github.com/vercel/workflow --skill migrating-to-workflow-sdk
+```
+</Callout>

package/docs/comparisons/meta.json

@@ -0,0 +1,11 @@
+{
+  "title": "Comparisons",
+  "pages": [
+    "workflow-sdk-vs-temporal",
+    "workflow-sdk-vs-cloudflare-workflows",
+    "workflow-sdk-vs-aws-step-functions",
+    "workflow-sdk-vs-aws-agentcore",
+    "workflow-sdk-vs-inngest",
+    "workflow-sdk-vs-trigger-dev"
+  ]
+}

package/docs/comparisons/workflow-sdk-vs-aws-agentcore.mdx

@@ -0,0 +1,55 @@
+---
+title: Workflow SDK vs AWS Bedrock AgentCore
+description: How the Workflow SDK compares to AWS Bedrock AgentCore — a durable-execution framework versus an AI-agent hosting platform. They solve different problems.
+type: conceptual
+summary: AgentCore hosts and operates AI agents in isolated microVMs but is not a durable-execution engine. The Workflow SDK provides durable orchestration and resumable streaming for agents.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/ai
+  - /docs/ai/resumable-streams
+  - /docs/foundations/streaming
+---
+
+[Amazon Bedrock AgentCore](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/what-is-bedrock-agentcore.html) is AWS's platform for **hosting and operating AI agents** — secure microVM runtime, plus building blocks for Memory, tool Gateways, and Identity. It is *not* a durable-execution engine, which makes this less a head-to-head and more a "different axis" comparison.
+
+<Callout type="info">
+**These solve different problems.** AgentCore answers "where do I securely run and operate an agent on AWS?" The Workflow SDK answers "how do I make a multi-step, tool-calling agent loop durable, resumable, and streamable?" AWS itself pairs AgentCore with a durable layer (Step Functions, or Temporal) for resumability — the Workflow SDK provides that durable layer natively, in your own app.
+</Callout>
+
+## At a glance
+
+| | Workflow SDK | AWS Bedrock AgentCore |
+| --- | --- | --- |
+| **Category** | Open-source durable-functions SDK | AI-agent hosting & operations platform |
+| **Durable execution?** | ✅ Event-log replay; the agent loop resumes from its last checkpoint after a crash | ❌ Not built-in — sessions are ephemeral microVMs; durability is opt-in via Memory or a framework checkpointer |
+| **What it gives you** | Durable orchestration, steps, hooks, streaming, observability | Runtime (microVM hosting), Harness (managed agent loop), Memory, Gateway (tools/MCP), Identity, Browser, Code Interpreter, Observability, Policy, Evaluations |
+| **Languages** | TypeScript / JS (Python beta) | Python-first for authoring; TypeScript or Python project scaffolding via the `@aws/agentcore` CLI; framework-agnostic (LangGraph, CrewAI, Strands, etc.) |
+| **Isolation** | VM-sandboxed workflow code + full-Node steps | Dedicated Firecracker microVM per session (strong hardware isolation) |
+| **Max duration** | No limit ([Vercel World limits](https://vercel.com/docs/workflows/pricing)) | 8-hour hard cap per session |
+| **AI streaming** | Native **durable, resumable** streaming (survives reconnect, cold start, replay) | Live SSE / WebSocket only — no buffering or replay of missed tokens |
+| **Versioning** | Runs pinned to immutable deployment | Immutable runtime versions + endpoints; in-flight sessions stay on their launch version (deployment/rollback only — no replay) |
+| **Portability** | Apache-2.0; runs anywhere Node runs; World abstraction | AWS-only; agent *code* is portable, the operating platform is not |
+| **Compliance** | Inherits your platform | HIPAA-eligible; SOC/PCI/ISO not third-party certified; not FedRAMP-authorized |
+| **Pricing** | SDK free; pay your platform | Per-module consumption (vCPU-hr / GB-hr, etc.) + model inference billed via Bedrock; no minimums |
+
+**What the limits mean in practice:** AgentCore's 8-hour session cap means an agent that waits on a human, a long-running job, or a slow external system can't span that wait in one session. Workflow SDK runs have [no duration cap](https://vercel.com/docs/workflows/pricing) — they suspend durably at `sleep()` and hooks for hours or weeks.
+
+## The core distinction: durability
+
+AgentCore Runtime gives each session an isolated microVM with up to 8 hours of runtime, but the compute is **ephemeral** — on a crash or stop, the next invocation gets a fresh microVM with no automatic replay of the agent loop. AWS's own guidance is to use AgentCore Memory or a framework checkpointer for state durability, and to layer a workflow engine (Step Functions or Temporal) on top when you need durable orchestration.
+
+The Workflow SDK *is* that durable layer. With `WorkflowAgent` (in the [AI SDK](/docs/ai)), the agent loop becomes a durable workflow: each model call and tool execution is a checkpointed step, the run resumes mid-loop after a failure, and partial output streams to the client through [resumable streams](/docs/ai/resumable-streams) that survive disconnects and cold starts.
+
+## Where AgentCore leads
+
+AgentCore is purpose-built for operating agents on AWS, and brings things the Workflow SDK doesn't try to be:
+
+- **MicroVM isolation per session** — the strongest hardware isolation among the tools in this section.
+- **Managed agent infrastructure** — Memory, a tool Gateway (turn APIs/Lambda/MCP servers into tools), and Identity (credential vaulting, OAuth) as first-class managed services.
+- **Enterprise/AWS compliance breadth** and VPC/PrivateLink networking.
+
+If your priority is running agents inside AWS with managed memory, tools, and identity, AgentCore is a strong fit. If your priority is **durable, resumable, streamable** agent execution that lives in your own TypeScript app and isn't tied to AWS, the Workflow SDK fits better — and the two can be combined (host on AgentCore, orchestrate durably with the Workflow SDK).
+
+---
+*Compiled from public documentation. AgentCore cold-start figures are community-sourced (no published SLA). Verify against [the AgentCore docs](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/what-is-bedrock-agentcore.html). Not based on head-to-head benchmarks.*