implement event-sourced architecture

.changeset/backwards-compat.md

@@ -0,0 +1,15 @@
+---
+"@workflow/world": minor
+"@workflow/world-local": patch
+"@workflow/world-postgres": patch
+"@workflow/errors": patch
+---
+
+Add backwards compatibility for runs created with different spec versions
+
+- Add `RunNotSupportedError` for runs requiring newer world versions
+- Add semver-based version comparison utilities
+- Legacy runs (< 4.1): route to legacy handlers
+- `run_cancelled`: skip event storage, directly update run
+- `wait_completed`: store event only (no entity mutation)
+- Unknown legacy events: throw error

.changeset/cli-event-sourced.md

@@ -0,0 +1,5 @@
+---
+"@workflow/cli": patch
+---
+
+Use `events.create()` for run cancellation

.changeset/core-event-sourced.md

@@ -0,0 +1,9 @@
+---
+"@workflow/core": patch
+---
+
+Runtime uses event-sourced entity creation
+
+- Suspension handler creates entities via `events.create()`
+- Track `hasCreatedEvent` flag to avoid duplicate event creation on replay
+- Handle `hook_conflict` events during replay to reject duplicate token hooks

.changeset/event-sourced-storage.md

@@ -0,0 +1,12 @@
+---
+"@workflow/world": minor
+---
+
+**BREAKING**: Storage interface is now read-only; all mutations go through `events.create()`
+
+- Remove `cancel`, `pause`, `resume` from `runs`
+- Remove `create`, `update` from `runs`, `steps`, `hooks`
+- Add run lifecycle events: `run_created`, `run_started`, `run_completed`, `run_failed`, `run_cancelled`
+- Add `step_created` event type
+- Remove `fatal` field from `step_failed` (terminal failure is now implicit)
+- Add `step_retrying` event with error info for retriable failures

.changeset/hook-conflict-event.md

@@ -0,0 +1,9 @@
+---
+"@workflow/world": patch
+"@workflow/errors": patch
+---
+
+Add `hook_conflict` event type for duplicate token detection
+
+- World returns `hook_conflict` event when `hook_created` uses an existing token
+- Add `HOOK_CONFLICT` error slug

.changeset/remove-deprecated-workflow-events.md

@@ -0,0 +1,8 @@
+---
+"@workflow/world": patch
+"@workflow/world-local": patch
+"@workflow/world-postgres": patch
+"@workflow/web-shared": patch
+---
+
+Remove deprecated `workflow_completed`, `workflow_failed`, and `workflow_started` events in favor of `run_completed`, `run_failed`, and `run_started` events.

.changeset/spec-version.md

@@ -0,0 +1,13 @@
+---
+"@workflow/world": patch
+"@workflow/world-local": patch
+"@workflow/world-postgres": patch
+"@workflow/world-vercel": patch
+"@workflow/web-shared": patch
+---
+
+Add `specVersion` property to World interface
+
+- All worlds expose `@workflow/world` package version for protocol compatibility
+- Stored in `run_created` event and `WorkflowRun` schema
+- Displayed in observability UI

.changeset/world-local-event-sourced.md

@@ -0,0 +1,9 @@
+---
+"@workflow/world-local": patch
+---
+
+Implement event-sourced entity creation in `events.create()`
+
+- Atomically create run/step/hook entities when processing corresponding events
+- Return `hook_conflict` event when hook token already exists
+- Remove direct entity mutation methods from storage

.changeset/world-postgres-event-sourced.md

@@ -0,0 +1,9 @@
+---
+"@workflow/world-postgres": patch
+---
+
+Implement event-sourced entity creation in `events.create()`
+
+- Atomically create run/step/hook entities when processing corresponding events
+- Return `hook_conflict` event when hook token already exists
+- Add `spec_version` column to runs table

.changeset/world-vercel-event-sourced.md

@@ -0,0 +1,8 @@
+---
+"@workflow/world-vercel": patch
+---
+
+Route entity mutations through v2 events API
+
+- `events.create()` calls v2 endpoint for atomic entity creation
+- Remove `cancel`, `pause`, `resume` from storage interface

docs/content/docs/errors/hook-conflict.mdx

@@ -0,0 +1,111 @@
+---
+title: hook-conflict
+---
+
+This error occurs when you try to create a hook with a token that is already in use by another active workflow run. Hook tokens must be unique across all running workflows in your project.
+
+## Error Message
+
+```
+Hook token conflict: Hook with token <token> already exists for this project
+```
+
+## Why This Happens
+
+Hooks use tokens to identify incoming webhook payloads. When you create a hook with `createHook({ token: "my-token" })`, the Workflow runtime reserves that token for your workflow run. If another workflow run is already using that token, a conflict occurs.
+
+This typically happens when:
+
+1. **Two workflows start simultaneously** with the same hardcoded token
+2. **A previous workflow run is still waiting** for a hook when a new run tries to use the same token
+
+## Common Causes
+
+### Hardcoded Token Values
+
+{/* @skip-typecheck: incomplete code sample */}
+```typescript lineNumbers
+// Error - multiple concurrent runs will conflict
+export async function processPayment() {
+  "use workflow";
+
+  const hook = createHook({ token: "payment-hook" }); // [!code highlight]
+  // If another run is already waiting on "payment-hook", this will fail
+  const payment = await hook;
+}
+```
+
+**Solution:** Use unique tokens that include the run ID or other unique identifiers.
+
+```typescript lineNumbers
+export async function processPayment(orderId: string) {
+  "use workflow";
+
+  // Include unique identifier in token
+  const hook = createHook({ token: `payment-${orderId}` }); // [!code highlight]
+  const payment = await hook;
+}
+```
+
+### Omitting the Token (Auto-generated)
+
+The safest approach is to let the Workflow runtime generate a unique token automatically:
+
+```typescript lineNumbers
+export async function processPayment() {
+  "use workflow";
+
+  const hook = createHook(); // Auto-generated unique token // [!code highlight]
+  console.log(`Send webhook to token: ${hook.token}`);
+  const payment = await hook;
+}
+```
+
+## Handling Hook Conflicts in Your Workflow
+
+When a hook conflict occurs, awaiting the hook will throw a `WorkflowRuntimeError`. You can catch this error to handle the conflict gracefully:
+
+```typescript lineNumbers
+import { WorkflowRuntimeError } from "@workflow/errors";
+
+export async function processPayment(orderId: string) {
+  "use workflow";
+
+  const hook = createHook({ token: `payment-${orderId}` });
+
+  try {
+    const payment = await hook; // [!code highlight]
+    return { success: true, payment };
+  } catch (error) {
+    if (error instanceof WorkflowRuntimeError && error.slug === "hook-conflict") { // [!code highlight]
+      // Another workflow is already processing this order
+      return { success: false, reason: "duplicate-processing" };
+    }
+    throw error; // Re-throw other errors
+  }
+}
+```
+
+This pattern is useful when you want to detect and handle duplicate processing attempts instead of letting the workflow fail.
+
+## When Hook Tokens Are Released
+
+Hook tokens are automatically released when:
+
+- The workflow run **completes** (successfully or with an error)
+- The workflow run is **cancelled**
+- The hook is explicitly **disposed**
+
+After a workflow completes, its hook tokens become available for reuse by other workflows.
+
+## Best Practices
+
+1. **Use auto-generated tokens** when possible - they are guaranteed to be unique
+2. **Include unique identifiers** if you need custom tokens (order ID, user ID, etc.)
+3. **Avoid reusing the same token** across multiple concurrent workflow runs
+4. **Consider using webhooks** (`createWebhook`) if you need a fixed, predictable URL that can receive multiple payloads
+
+## Related
+
+- [Hooks](/docs/foundations/hooks) - Learn more about using hooks in workflows
+- [createWebhook](/docs/api-reference/workflow/create-webhook) - Alternative for fixed webhook URLs

docs/content/docs/errors/index.mdx

@@ -8,6 +8,9 @@ Fix common mistakes when creating and executing workflows in the **Workflow DevK
     <Card href="/docs/errors/fetch-in-workflow" title="fetch-in-workflow">
         Learn how to use fetch in workflow functions.
     </Card>
+    <Card href="/docs/errors/hook-conflict" title="hook-conflict">
+        Learn how to handle hook token conflicts between workflows.
+    </Card>
     <Card href="/docs/errors/node-js-module-in-workflow" title="node-js-module-in-workflow">
         Learn how to use Node.js modules in workflows.
     </Card>

docs/content/docs/foundations/streaming.mdx

@@ -83,7 +83,7 @@ This allows clients to reconnect and continue receiving data from where they lef
 
 [`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.
 
-Unlike regular values that are fully serialized to the event log, streams maintain their streaming capabilities when passed between functions.
+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
@@ -151,7 +151,7 @@ async function processInputStream(input: ReadableStream<Uint8Array>) {
 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 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. 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.
 
 For more on determinism and replay, see [Workflows and Steps](/docs/foundations/workflows-and-steps).
 

docs/content/docs/foundations/workflows-and-steps.mdx

@@ -36,10 +36,10 @@ export async function processOrderWorkflow(orderId: string) {
 **Key Characteristics:**
 
 - Runs in a sandboxed environment without full Node.js access
-- All step results are persisted to the event log
+- All step results are persisted to the [event log](/docs/how-it-works/event-sourcing)
 - Must be **deterministic** to allow resuming after failures
 
-Determinism in the workflow is required to resume the workflow from a suspension. Essentially, the workflow code gets re-run multiple times during its lifecycle, each time using an event log to resume the workflow to the correct spot.
+Determinism in the workflow is required to resume the workflow from a suspension. Essentially, the workflow code gets re-run multiple times during its lifecycle, each time using the [event log](/docs/how-it-works/event-sourcing) to resume the workflow to the correct spot.
 
 The sandboxed environment that workflows run in already ensures determinism. For instance, `Math.random` and `Date` constructors are fixed in workflow runs, so you are safe to use them, and the framework ensures that the values don't change across replays.
 
@@ -112,7 +112,7 @@ Keep in mind that calling a step function outside of a workflow function will no
 
 ### Suspension and Resumption
 
-Workflow functions have the ability to automatically suspend while they wait on asynchronous work. While suspended, the workflow's state is stored via the event log and no compute resources are used until the workflow resumes execution.
+Workflow functions have the ability to automatically suspend while they wait on asynchronous work. While suspended, the workflow's state is stored via the [event log](/docs/how-it-works/event-sourcing) and no compute resources are used until the workflow resumes execution.
 
 There are multiple ways a workflow can suspend:
 

docs/content/docs/how-it-works/code-transform.mdx

@@ -145,7 +145,7 @@ handleUserSignup.workflowId = "workflow//workflows/user.js//handleUserSignup"; /
 - The workflow function gets a `workflowId` property for runtime identification
 - The `"use workflow"` directive is removed
 
-**Why this transformation?** When a workflow executes, it needs to replay past steps from the event log rather than re-executing them. The `WORKFLOW_USE_STEP` symbol is a special runtime hook that:
+**Why this transformation?** When a workflow executes, it needs to replay past steps from the [event log](/docs/how-it-works/event-sourcing) rather than re-executing them. The `WORKFLOW_USE_STEP` symbol is a special runtime hook that:
 
 1. Checks if the step has already been executed (in the event log)
 2. If yes: Returns the cached result
@@ -290,7 +290,7 @@ Because workflow functions are deterministic and have no side effects, they can
 
 - Can make API calls, database queries, etc.
 - Have full access to Node.js runtime and APIs
-- Results are cached in the event log after first execution
+- Results are cached in the [event log](/docs/how-it-works/event-sourcing) after first execution
 
 Learn more about [Workflows and Steps](/docs/foundations/workflows-and-steps).