workflow 4.2.0-beta.71 → 4.2.0-beta.72

package/docs/errors/webhook-invalid-respond-with-value.mdx

@@ -43,6 +43,8 @@ export async function webhookWorkflow() {
 **Solution:** Use `"manual"` or provide a `Response` object.
 
 ```typescript lineNumbers
+import { createWebhook } from "workflow";
+
 // Fixed - use "manual"
 export async function webhookWorkflow() {
   "use workflow";
@@ -74,6 +76,8 @@ export async function webhookWorkflow() {
 **Solution:** Create a proper `Response` object.
 
 ```typescript lineNumbers
+import { createWebhook } from "workflow";
+
 // Fixed - use Response constructor
 export async function webhookWorkflow() {
   "use workflow";
@@ -89,6 +93,8 @@ export async function webhookWorkflow() {
 ### Default Behavior (202 Response)
 
 ```typescript lineNumbers
+import { createWebhook } from "workflow";
+
 // Returns 202 Accepted automatically
 const webhook = await createWebhook();
 const request = await webhook;
@@ -98,6 +104,8 @@ const request = await webhook;
 ### Manual Response
 
 ```typescript lineNumbers
+import { createWebhook } from "workflow";
+
 // Manual response control
 const webhook = await createWebhook({
   respondWith: "manual",
@@ -120,6 +128,8 @@ await request.respondWith(
 ### Pre-defined Response
 
 ```typescript lineNumbers
+import { createWebhook } from "workflow";
+
 // Immediate response
 const webhook = await createWebhook({
   respondWith: new Response("Request received", { status: 200 }),

package/docs/errors/webhook-response-not-sent.mdx

@@ -49,6 +49,8 @@ export async function webhookWorkflow() {
 **Solution:** Always call `request.respondWith()` when using manual response mode.
 
 ```typescript lineNumbers
+import { createWebhook } from "workflow";
+
 // Fixed - response sent
 export async function webhookWorkflow() {
   "use workflow";
@@ -92,6 +94,8 @@ export async function webhookWorkflow() {
 **Solution:** Ensure all code paths send a response.
 
 ```typescript lineNumbers
+import { createWebhook } from "workflow";
+
 // Fixed - response sent in all branches
 export async function webhookWorkflow() {
   "use workflow";
@@ -135,6 +139,8 @@ export async function webhookWorkflow() {
 **Solution:** Use try-catch to handle errors and send appropriate responses.
 
 ```typescript lineNumbers
+import { createWebhook } from "workflow";
+
 // Fixed - error handling with response
 export async function webhookWorkflow() {
   "use workflow";
@@ -163,6 +169,8 @@ export async function webhookWorkflow() {
 If you don't need custom response control, consider using the default response mode which automatically returns a `202 Accepted` response:
 
 ```typescript lineNumbers
+import { createWebhook } from "workflow";
+
 // Automatic 202 response - no manual response needed
 export async function webhookWorkflow() {
   "use workflow";

package/docs/errors/workflow-not-registered.mdx

@@ -0,0 +1,64 @@
+---
+title: workflow-not-registered
+description: A workflow function is not registered in the current deployment.
+type: troubleshooting
+summary: Resolve workflow not registered errors caused by deployment targeting or build issues.
+prerequisites:
+  - /docs/foundations/starting-workflows
+related:
+  - /docs/errors/step-not-registered
+  - /docs/api-reference/workflow-errors/workflow-not-registered-error
+---
+
+This error occurs when the Workflow runtime tries to execute a workflow function that is not registered in the current deployment. When this happens, the run fails with a `RUNTIME_ERROR` error code.
+
+## Error Message
+
+```
+Workflow "<workflowName>" is not registered in the current deployment.
+This usually means a run was started against a deployment that does not
+have this workflow, or there was a build/bundling issue.
+```
+
+## Why This Happens
+
+This error means the deployment that received the workflow execution request does not have the specified workflow function in its bundle. This is an **infrastructure error**, not a user code error.
+
+## Common Causes
+
+### Run started against a deployment without the workflow
+
+A run was started (or restarted from the dashboard UI) targeting a deployment where the workflow was renamed, moved to a different file, or removed entirely.
+
+{/* @skip-typecheck: incomplete code sample */}
+```typescript lineNumbers title="workflows/order.ts (original)"
+export async function processOrder(orderId: string) {
+  "use workflow";
+  // workflow logic
+}
+```
+
+{/* @skip-typecheck: incomplete code sample */}
+```typescript lineNumbers title="workflows/order.ts (current deployment)"
+// Renamed from processOrder to handleOrder
+export async function handleOrder(orderId: string) { // [!code highlight]
+  "use workflow";
+  // workflow logic
+}
+```
+
+If a new run is started targeting the current deployment using the old name `processOrder`, the runtime will not find it.
+
+### Build tooling issue
+
+Something went wrong during the build process that caused the workflow function to not be included in the workflow bundle. Check your build logs for errors related to workflow bundling. Common issues include:
+
+- The workflow file is missing a valid `"use workflow"` directive
+- The workflow function is not exported from the workflow file
+- An esbuild or SWC plugin error silently excluded the workflow
+
+## How to Resolve
+
+1. **If the workflow was renamed or moved:** Deploy with the workflow restored to its original name and location, then retry the run. Alternatively, start a new run using the updated workflow name against the current deployment.
+
+2. **If it's a build issue:** Check your build logs for errors related to workflow bundling. Ensure the workflow file contains a valid `"use workflow"` directive and is properly exported.

package/docs/foundations/errors-and-retries.mdx

@@ -139,6 +139,35 @@ callApi.maxRetries = 5; // Retry up to 5 times on failure (6 total attempts)
   step can run up to 4 times total (1 initial attempt + 3 retries).
 </Callout>
 
+## Error Codes
+
+When a workflow run fails, the error may include a `code` that classifies the failure. You can access it programmatically via the `Run` class:
+
+```typescript lineNumbers
+import { WorkflowRunFailedError } from "@workflow/errors";
+import { start } from "workflow/api";
+
+const run = await start(myWorkflow, [input]);
+
+try {
+  const result = await run.returnValue;
+} catch (err) {
+  if (WorkflowRunFailedError.is(err)) {
+    console.log(err.cause.code); // "USER_ERROR", "RUNTIME_ERROR", or undefined
+    console.log(err.cause.message); // The error message
+  }
+}
+```
+
+| Code | Meaning |
+| --- | --- |
+| `USER_ERROR` | An error thrown in your workflow or step code (including propagated step failures like `FatalError`) |
+| `RUNTIME_ERROR` | An internal runtime error such as a corrupted event log or missing data. If you see this, please [file an issue](https://github.com/vercel/workflow/issues) |
+
+<Callout type="info">
+  The error code is also available on the run entity via the CLI (`npx workflow inspect runs <runId>`) in the `error.code` field, and as an OTEL span attribute (`workflow.error.code`) for observability.
+</Callout>
+
 ## Rolling Back Failed Steps
 
 When a workflow fails partway through, it can leave the system in an inconsistent state.

package/docs/foundations/streaming.mdx

@@ -87,6 +87,22 @@ export async function GET(
 
 This allows clients to reconnect and continue receiving data from where they left off, rather than 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.
+
+On an active (not-yet-closed) stream, the negative index resolves relative to the chunk count at connection time; any chunks written afterward are still delivered normally.
+
+{/* @skip-typecheck: incomplete code sample */}
+```typescript
+// Read only the last 10 chunks
+const stream = run.getReadable({ startIndex: -10 });
+```
+
+If the absolute value exceeds the total number of chunks, reading starts from the beginning (the value is clamped to 0).
+
+<Callout type="warn">
+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
 
 [`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 DevKit makes serializable. These are not custom types - they follow the web standard - but Workflow DevKit adds the ability to pass them between functions while maintaining their streaming capabilities.
@@ -164,6 +180,8 @@ Workflow functions must be deterministic to support replay. Since streams bypass
 For more on determinism and replay, see [Workflows and Steps](/docs/foundations/workflows-and-steps).
 
 ```typescript title="workflows/bad-example.ts" lineNumbers
+import { getWritable } from "workflow";
+
 export async function badWorkflow() {
   "use workflow";
 
@@ -176,6 +194,8 @@ export async function badWorkflow() {
 ```
 
 ```typescript title="workflows/good-example.ts" lineNumbers
+import { getWritable } from "workflow";
+
 export async function goodWorkflow() {
   "use workflow";
 
@@ -501,6 +521,8 @@ If a lock is not released, the step function's HTTP request cannot terminate. Ev
 **Close streams when done:**
 
 ```typescript lineNumbers
+import { getWritable } from "workflow";
+
 async function finalizeStream() {
   "use step";
 

package/docs/getting-started/index.mdx

@@ -63,11 +63,11 @@ import { Next, Nitro, SvelteKit, Nuxt, Hono, Bun, AstroDark, AstroLight, TanStac
         <span className="font-medium">SvelteKit</span>
      </div>
     </Card>
-    <Card href="/docs/getting-started/nestjs">
+    <Card className="opacity-50">
       <div className="flex flex-col items-center justify-center gap-2">
-        <Nest className="size-16" />
+        <Nest className="size-16 dark:invert grayscale" />
         <span className="font-medium">NestJS</span>
-        <Badge variant="secondary">Experimental</Badge>
+        <Badge variant="secondary">Coming soon</Badge>
       </div>
     </Card>
     <Card className="opacity-50">

package/docs/getting-started/meta.json

@@ -0,0 +1,15 @@
+{
+  "title": "Getting Started",
+  "pages": [
+    "next",
+    "astro",
+    "express",
+    "fastify",
+    "hono",
+    "nitro",
+    "nuxt",
+    "sveltekit",
+    "vite"
+  ],
+  "defaultOpen": true
+}

package/docs/getting-started/nestjs.mdx

@@ -11,6 +11,10 @@ related:
 
 This guide will walk through setting up your first workflow in a NestJS app. Along the way, you'll learn more about the concepts that are fundamental to using the development kit in your own projects.
 
+<Callout>
+NestJS integration is experimental and not yet supported for deployment to Vercel.
+</Callout>
+
 ---
 
 <Steps>
@@ -323,14 +327,6 @@ WorkflowModule.forRoot({
 });
 ```
 
-## Deploying to production
-
-Workflow DevKit apps currently work best when deployed to [Vercel](https://vercel.com/home) and needs no special configuration.
-
-<FluidComputeCallout />
-
-Check the [Deploying](/docs/deploying) section to learn how your workflows can be deployed elsewhere.
-
 ## Next Steps
 
 - Learn more about the [Foundations](/docs/foundations).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "4.2.0-beta.71",
+  "version": "4.2.0-beta.72",
   "description": "Workflow DevKit - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -37,6 +37,7 @@
       "workflow": "./dist/api-workflow.js",
       "default": "./dist/api.js"
     },
+    "./errors": "./dist/internal/errors.js",
     "./internal/errors": "./dist/internal/errors.js",
     "./internal/builtins": "./dist/internal/builtins.js",
     "./internal/private": "./dist/internal/private.js",
@@ -48,21 +49,26 @@
     "./astro": "./dist/astro.js",
     "./vite": "./dist/vite.js",
     "./nest": "./dist/nest.js",
-    "./runtime": "./dist/runtime.js"
+    "./runtime": "./dist/runtime.js",
+    "./observability": {
+      "types": "./dist/observability.d.ts",
+      "default": "./dist/observability.js"
+    }
   },
   "dependencies": {
     "ms": "2.1.3",
-    "@workflow/astro": "4.0.0-beta.45",
-    "@workflow/cli": "4.2.0-beta.71",
-    "@workflow/core": "4.2.0-beta.71",
-    "@workflow/errors": "4.1.0-beta.18",
+    "@workflow/astro": "4.0.0-beta.46",
+    "@workflow/cli": "4.2.0-beta.72",
+    "@workflow/core": "4.2.0-beta.72",
+    "@workflow/errors": "4.1.0-beta.19",
     "@workflow/typescript-plugin": "4.0.1-beta.5",
-    "@workflow/next": "4.0.1-beta.67",
-    "@workflow/nest": "0.0.0-beta.20",
-    "@workflow/nitro": "4.0.1-beta.66",
-    "@workflow/nuxt": "4.0.1-beta.55",
-    "@workflow/sveltekit": "4.0.0-beta.60",
-    "@workflow/rollup": "4.0.0-beta.28"
+    "@workflow/utils": "4.1.0-beta.13",
+    "@workflow/next": "4.0.1-beta.68",
+    "@workflow/nest": "0.0.0-beta.21",
+    "@workflow/nitro": "4.0.1-beta.67",
+    "@workflow/nuxt": "4.0.1-beta.56",
+    "@workflow/sveltekit": "4.0.0-beta.61",
+    "@workflow/rollup": "4.0.0-beta.29"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",