workflow 4.1.0-beta.57 → 4.1.0-beta.58

package/docs/errors/corrupted-event-log.mdx

@@ -0,0 +1,73 @@
+---
+title: corrupted-event-log
+description: The workflow's event log contains an event that no consumer can process, indicating corruption or invalid state.
+type: troubleshooting
+summary: Resolve corrupted event log errors caused by duplicate or orphaned events.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/foundations/errors-and-retries
+---
+
+This error occurs when the Workflow runtime encounters an event in the event log that no registered consumer can process. This means the event log is in an invalid state — typically due to duplicate or orphaned events.
+
+This is a **workflow-level fatal error**. It cannot be caught or handled inside your workflow code. A corrupted event log immediately fails the entire run without executing any more user code. The run must be retried from outside the workflow.
+
+## Error Message
+
+```
+Unconsumed event in event log: eventType=<type>, correlationId=<id>, eventId=<id>. This indicates a corrupted or invalid event log.
+```
+
+## Why This Happens
+
+Workflows persist their progress as an ordered event log. During replay, the runtime processes each event in sequence — every event must be consumed by a matching callback (e.g., a step or sleep waiting for its result). When an event has no matching consumer, the runtime cannot advance past it, which would block all subsequent events and hang the workflow indefinitely.
+
+Instead of silently hanging, the runtime raises a `WorkflowRuntimeError` to fail the workflow fast and surface the problem.
+
+Common scenarios that produce this error:
+
+1. **Duplicate completion events** — Two `wait_completed` events for a single `wait_created`, or two `step_completed` events for the same step. The first is consumed normally, but the second has no consumer.
+2. **Orphaned events** — A `step_completed` or `wait_completed` event whose `correlationId` doesn't match any step or sleep in the workflow code.
+3. **Events after terminal state** — An event that arrives after its corresponding step or wait has already reached a terminal state (e.g., `step_retrying` after `step_completed`).
+
+## What To Do
+
+This error indicates a bug in the Workflow SDK or Workflow server — not in your workflow code. Your workflow code does not need to change. Follow these steps to resolve the issue:
+
+### 1. Upgrade to the latest `workflow` package
+
+The bug that caused the corrupted event log may have already been identified and fixed in a newer version. Update to the latest version:
+
+```bash
+npm install workflow@latest
+```
+
+### 2. Retry the failed run
+
+Since this is a fatal error, the run is automatically marked as `failed`. You can re-run it using the **Re-run** button in the Workflow Dashboard.
+
+### 3. Report the issue
+
+If the error persists after upgrading, please [open an issue on GitHub](https://github.com/vercel/workflow/issues/new) so we can investigate and fix the underlying bug. Include the following details to help us diagnose the problem:
+
+- The version of the `workflow` package you are using
+- The run ID(s) of the affected workflow run(s)
+- The error message (including `eventType`, `correlationId`, and `eventId`)
+- Any details about the event log or the workflow that triggered the error
+
+## This Error Cannot Be Caught
+
+Unlike other workflow errors, a corrupted event log error is **not catchable** inside your workflow function. Because the event log itself is invalid, the runtime cannot safely continue executing any user code. The entire run fails immediately and is marked as `failed`.
+
+To handle this programmatically from outside the workflow, you can check the run status:
+
+```typescript lineNumbers
+import { getRun } from "workflow/api";
+
+const run = getRun("wrun_abc123");
+const status = await run.status;
+if (status === "failed") {
+  console.error("Run failed");
+}
+```

package/docs/errors/index.mdx

@@ -34,6 +34,9 @@ Fix common mistakes when creating and executing workflows in the **Workflow DevK
     <Card href="/docs/errors/webhook-response-not-sent" title="webhook-response-not-sent">
         Learn how to send responses when using manual webhook response mode.
     </Card>
+    <Card href="/docs/errors/corrupted-event-log" title="corrupted-event-log">
+        Learn how to handle corrupted or invalid event logs.
+    </Card>
 </Cards>
 
 ## Learn More

package/docs/how-it-works/event-sourcing.mdx

@@ -33,7 +33,7 @@ In the Workflow DevKit, the following entity types are managed through events:
 - **Runs**: Workflow execution instances (materialized in storage)
 - **Steps**: Individual atomic operations within a workflow (materialized in storage)
 - **Hooks**: Suspension points that can receive external data (materialized in storage)
-- **Waits**: Sleep or delay operations (tracked via events only, not materialized)
+- **Waits**: Sleep or delay operations (materialized in storage)
 
 ## Entity Lifecycles
 
@@ -151,7 +151,7 @@ flowchart TD
 - `completed`: Delay period has elapsed, workflow can resume
 
 <Callout type="info">
-Unlike Runs, Steps, and Hooks, waits are conceptual entities tracked only through events. There is no separate "Wait" record in storage that can be queried—the wait state is derived entirely from the `wait_created` and `wait_completed` events in the event log.
+Like Runs, Steps, and Hooks, waits are materialized as entities in storage. When a `wait_created` event is processed, a wait entity is created with status `waiting`. When a `wait_completed` event is processed, the wait entity is atomically transitioned to `completed` — this guarantees that a wait can only be completed exactly once, even if multiple concurrent invocations attempt to complete it simultaneously.
 </Callout>
 
 ## Event Types Reference

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "4.1.0-beta.57",
+  "version": "4.1.0-beta.58",
   "description": "Workflow DevKit - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -38,7 +38,6 @@
       "default": "./dist/api.js"
     },
     "./internal/errors": "./dist/internal/errors.js",
-    "./internal/serialization": "./dist/internal/serialization.js",
     "./internal/builtins": "./dist/internal/builtins.js",
     "./internal/private": "./dist/internal/private.js",
     "./internal/class-serialization": "./dist/internal/class-serialization.js",
@@ -53,17 +52,17 @@
   },
   "dependencies": {
     "ms": "2.1.3",
-    "@workflow/astro": "4.0.0-beta.31",
-    "@workflow/cli": "4.1.0-beta.57",
-    "@workflow/core": "4.1.0-beta.57",
-    "@workflow/errors": "4.1.0-beta.15",
+    "@workflow/astro": "4.0.0-beta.32",
+    "@workflow/cli": "4.1.0-beta.58",
+    "@workflow/core": "4.1.0-beta.58",
+    "@workflow/errors": "4.1.0-beta.16",
     "@workflow/typescript-plugin": "4.0.1-beta.4",
-    "@workflow/next": "4.0.1-beta.53",
-    "@workflow/nest": "0.0.0-beta.6",
-    "@workflow/nitro": "4.0.1-beta.52",
-    "@workflow/nuxt": "4.0.1-beta.41",
-    "@workflow/sveltekit": "4.0.0-beta.46",
-    "@workflow/rollup": "4.0.0-beta.14"
+    "@workflow/next": "4.0.1-beta.54",
+    "@workflow/nest": "0.0.0-beta.7",
+    "@workflow/nitro": "4.0.1-beta.53",
+    "@workflow/nuxt": "4.0.1-beta.42",
+    "@workflow/sveltekit": "4.0.0-beta.47",
+    "@workflow/rollup": "4.0.0-beta.15"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",

package/dist/internal/serialization.d.ts

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

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

@@ -1 +0,0 @@
-{"version":3,"file":"serialization.d.ts","sourceRoot":"","sources":["../../src/internal/serialization.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC"}

package/dist/internal/serialization.js

@@ -1,2 +0,0 @@
-export * from '@workflow/core/serialization';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2VyaWFsaXphdGlvbi5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9pbnRlcm5hbC9zZXJpYWxpemF0aW9uLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsOEJBQThCLENBQUMifQ==