implement event-sourced architecture

.changeset/event-sourced-entities.md

@@ -0,0 +1,19 @@
+---
+"@workflow/core": patch
+"@workflow/world": patch
+"@workflow/world-local": patch
+"@workflow/world-postgres": patch
+"@workflow/world-vercel": patch
+
+"@workflow/web-shared": patch
+---
+
+perf: implement event-sourced architecture for runs, steps, and hooks
+
+- Add run lifecycle events (run_created, run_started, run_completed, run_failed, run_cancelled)
+- Add step_retrying event for non-fatal step failures that will be retried
+- Remove `fatal` field from step_failed event (step_failed now implies terminal failure)
+- Rename step's `lastKnownError` to `error` for consistency with server
+- Update world implementations to create/update entities from events via events.create()
+- Entities (runs, steps, hooks) are now materializations of the event log
+- This makes the system faster, easier to reason about, and resilient to data inconsistencies

.changeset/hook-conflict-events.md

@@ -0,0 +1,9 @@
+---
+"@workflow/world": patch
+"@workflow/world-local": patch
+"@workflow/world-postgres": patch
+"@workflow/core": patch
+"@workflow/errors": patch
+---
+
+Add hook_conflict event type for duplicate token detection

.changeset/remove-paused-resumed.md

@@ -0,0 +1,15 @@
+---
+"@workflow/world": patch
+"@workflow/world-local": patch
+"@workflow/world-vercel": patch
+"@workflow/cli": patch
+"@workflow/web": patch
+"@workflow/web-shared": patch
+---
+
+Remove the unused paused/resumed run events and states
+
+- Remove `run_paused` and `run_resumed` event types
+- Remove `paused` status from `WorkflowRunStatus`
+- Remove `PauseWorkflowRunParams` and `ResumeWorkflowRunParams` types
+- Remove `pauseWorkflowRun` and `resumeWorkflowRun` functions from world-vercel

.changeset/shiny-falcons-fix.md

@@ -0,0 +1,15 @@
+---
+"@workflow/world": patch
+"@workflow/world-vercel": patch
+"@workflow/world-local": patch
+"@workflow/world-postgres": patch
+"@workflow/web-shared": patch
+---
+
+Add `specVersion` property to World interface for backwards compatibility
+
+- Added `specVersion` property to the World interface that exposes the npm package version
+- Added `specVersion` to WorkflowRun schema and run_created event data
+- World implementations (world-vercel, world-local, world-postgres) now set specVersion from their package version using genversion
+- Server can use specVersion to route operations based on the world version that created the run
+- Added specVersion display to the observability UI attribute panel

.claude/agents/docs-writer.md

@@ -67,6 +67,16 @@ You are an expert technical writer specializing in developer documentation for t
    - Cross-reference related documentation when helpful
    - Provide "what you'll learn" context at the beginning of longer guides
 
+11. **Mermaid Diagram Standards**:
+   - Use `flowchart TD` (top-down) or `flowchart LR` (left-right) for flow diagrams
+   - Use square brackets with double quotes for rectangular nodes: `A["Label Text"]`
+   - Avoid unquoted labels or rounded nodes for consistency
+   - Use pipe syntax with double quotes for edge labels: `A -->|"label"| B`
+   - Highlight terminal states or key components with purple: `style NodeId fill:#a78bfa,stroke:#8b5cf6,color:#000`
+   - Place all `style` declarations at the end of the diagram
+   - Keep diagrams simple and readable - split into multiple diagrams if needed
+   - Add a legend or callout explaining highlighted nodes when appropriate
+
 **When Creating New Documentation:**
 - Review existing docs in the docs/ folder first to understand patterns
 - Identify the target audience and their likely knowledge level
@@ -99,4 +109,35 @@ You are an expert technical writer specializing in developer documentation for t
 - Are highlights used sparingly and only on the most relevant lines?
 - Do links to API references and external docs work correctly?
 
+**IMPORTANT - Validation Before Completing:**
+After completing any documentation changes, you MUST run both validation tests to ensure quality:
+
+**1. Link Validation:**
+```bash
+cd docs && pnpm postinstall && bun run lint:links
+```
+
+This validates that:
+- All internal links point to existing pages (pages must be registered in their parent index.mdx to be discoverable)
+- All anchor links point to existing headings
+- Card href attributes use valid URLs
+
+If link validation fails, common fixes include:
+- Add new pages to the appropriate index.mdx file (e.g., docs/content/docs/errors/index.mdx for error pages)
+- Fix broken links to use correct paths (check the docs/content/ folder structure)
+- Ensure linked pages exist
+
+**2. TypeScript Code Sample Validation:**
+```bash
+pnpm test:docs
+```
+
+This type-checks all TypeScript code samples in documentation to ensure they compile correctly. If type checking fails:
+- Fix syntax errors in code samples
+- Add missing imports (the type checker auto-infers common workflow imports)
+- Use `{/* @skip-typecheck: reason */}` comment before code blocks that intentionally show incomplete or invalid code
+- Use `{/* @expect-error:2304,2307 */}` to mark code samples that intentionally demonstrate errors
+
+**Both validations must pass before your work is considered complete.**
+
 Your goal is to make Workflow DevKit accessible and immediately useful to developers while maintaining the high technical bar of the existing documentation. Every piece of documentation you create should empower developers to start building with confidence.

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).