@workflow/core 5.0.0-beta.42 → 5.0.0-beta.44

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

@@ -1,5 +1,5 @@
 ---
-title: Event Sourcing
+title: Event sourcing
 description: Learn how Workflow SDK uses event sourcing internally for debugging and observability.
 type: conceptual
 summary: Understand the event log that powers workflow replay and debugging.
@@ -10,14 +10,12 @@ related:
 ---
 
 <Callout>
-This guide explores how the Workflow SDK uses event sourcing internally. Understanding these concepts is helpful for debugging and building observability tools, but is not required to use workflows. For getting started with workflows, see the [getting started](/docs/getting-started) guides for your framework.
+Workflow SDK uses event sourcing internally for debugging and observability tools. To start using workflows, see the [getting started](/docs/getting-started) guide for your framework.
 </Callout>
 
 The Workflow SDK uses event sourcing to track all state changes in workflow executions. Every mutation creates an event that is persisted to the event log, and entity state is derived by replaying these events.
 
-This page explains the event sourcing model and entity lifecycles.
-
-## Event Sourcing Overview
+## Event sourcing overview
 
 Event sourcing is a persistence pattern where state changes are stored as a sequence of events rather than by updating records in place. The current state of any entity is reconstructed by replaying its events from the beginning.
 
@@ -35,15 +33,15 @@ In the Workflow SDK, the following entity types are managed through events:
 - **Hooks**: Suspension points that can receive external data (materialized in storage)
 - **Waits**: Sleep or delay operations (materialized in storage)
 
-## Entity Lifecycles
+## Entity lifecycles
 
-Each entity type follows a specific lifecycle defined by the events that can affect it. Events transition entities between states, and certain states are terminal—once reached, no further transitions are possible.
+Each entity type follows a specific lifecycle defined by the events that can affect it. Events transition entities between states. Once an entity reaches a terminal state, no further transitions are possible.
 
 <Callout type="info">
 In the diagrams below, <span style={{color: '#8b5cf6', fontWeight: 'bold'}}>purple nodes</span> indicate terminal states that cannot be transitioned out of.
 </Callout>
 
-### Run Lifecycle
+### Run lifecycle
 
 A run represents a single execution of a workflow function. Runs begin in `pending` state when created, transition to `running` when execution starts, and end in one of three terminal states.
 
@@ -67,9 +65,9 @@ flowchart TD
 - `running`: Actively executing workflow code
 - `completed`: Finished successfully with an output value
 - `failed`: Terminated due to an unrecoverable error
-- `cancelled`: Explicitly cancelled by the user or system
+- `cancelled`: Explicitly canceled by the user or system
 
-### Step Lifecycle
+### Step lifecycle
 
 A step represents a single invocation of a step function. Steps can retry on failure, either transitioning back to `pending` via `step_retrying` or being re-executed directly with another `step_started` event.
 
@@ -94,7 +92,7 @@ flowchart TD
 - `cancelled`: Reserved for future use (not currently emitted)
 
 <Callout type="info">
-The `step_retrying` event is optional. Steps can retry without it - the retry mechanism works regardless of whether this event is emitted. You may see back-to-back `step_started` events in logs when a step retries after a timeout or when the error is not explicitly captured. See [Errors and Retries](/docs/foundations/errors-and-retries) for more on how retries work.
+The `step_retrying` event is optional. Steps can retry without it, regardless of whether the event is emitted. You may see consecutive `step_started` events when a step retries after a timeout, when the error isn't explicitly captured, or when concurrent replays each commit one. See [Duplicate events](#duplicate-events) and [Errors and retries](/docs/foundations/errors-and-retries) for more information.
 </Callout>
 
 When present, the `step_retrying` event moves a step back to `pending` state and records the error that caused the retry. This provides two benefits:
@@ -102,7 +100,7 @@ When present, the `step_retrying` event moves a step back to `pending` state and
 - **Cleaner observability**: The event log explicitly shows retry transitions rather than consecutive `step_started` events
 - **Error history**: The error that triggered the retry is preserved for debugging
 
-### Hook Lifecycle
+### Hook lifecycle
 
 A hook represents a suspension point that can receive external data, created by [`createHook()`](/docs/api-reference/workflow/create-hook). Hooks enable workflows to pause and wait for external events, user interactions, or HTTP requests. Webhooks (created with [`createWebhook()`](/docs/api-reference/workflow/create-webhook)) are a higher-level abstraction built on hooks that adds automatic HTTP request/response handling.
 
@@ -125,15 +123,15 @@ flowchart TD
 - `disposed`: No longer accepting payloads
 - `conflicted`: Hook creation failed because the token is already in use by another workflow
 
-Unlike other entities, hooks don't have a `status` field—the states above are conceptual. When a `hook_disposed` event is created, the hook record is removed rather than updated.
+Unlike other entities, hooks don't have a `status` field. The states above are conceptual. When a `hook_disposed` event is created, the hook record is removed rather than updated.
 
-While a hook is active, its token is reserved and cannot be used by other workflows. If a workflow attempts to create a hook with a token reserved by another run — either by an active hook or by `experimental_minRetention` after its run ended — a `hook_conflict` event is recorded instead of `hook_created`. Current worlds include the token and the run ID that owns it, though older persisted events or world implementations may only include the token. This causes `hook.getConflict()` to resolve with the conflicting run and the hook's payload promise to reject with a `HookConflictError`, which you can detect with `HookConflictError.is(error)`. See the [hook-conflict error](/docs/errors/hook-conflict) documentation for more details.
+While a hook is active, its token is reserved and cannot be used by other workflows. If a workflow attempts to create a hook with a token reserved by another run, either by an active hook or by `experimental_minRetention` after its run ended, a `hook_conflict` event is recorded instead of `hook_created`. Current Worlds include the token and the run ID that owns it, though older persisted events or World implementations may only include the token. This causes `hook.getConflict()` to resolve with the conflicting run and the hook's payload promise to reject with a `HookConflictError`, which you can detect with `HookConflictError.is(error)`. See the [hook-conflict error](/docs/errors/hook-conflict) documentation for more details.
 
-When a workflow ends, its Hooks can no longer be resumed. They are normally removed and their tokens become available again. With `experimental_minRetention`, a Hook remains readable and its token remains unavailable until retention ends. A `hook_disposed` event removes the Hook and makes its token available immediately.
+When a workflow ends, its hooks can no longer be resumed. They are normally removed, and their tokens become available again. With `experimental_minRetention`, a hook remains readable, and its token remains unavailable until retention ends. A `hook_disposed` event removes the hook and makes its token available immediately.
 
-See [Hooks & Webhooks](/docs/foundations/hooks) for more on how hooks and webhooks work.
+See [Hooks and webhooks](/docs/foundations/hooks) for more on how hooks and webhooks work.
 
-### Wait Lifecycle
+### Wait lifecycle
 
 A wait represents a sleep operation created by [`sleep()`](/docs/api-reference/workflow/sleep). Waits track when a delay period has elapsed.
 
@@ -151,10 +149,10 @@ flowchart TD
 - `completed`: Delay period has elapsed, workflow can resume
 
 <Callout type="info">
-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.
+Like runs, steps, and hooks, waits are materialized as entities in storage. Processing a `wait_created` event creates a wait entity with the `waiting` status. Processing a `wait_completed` event atomically transitions the wait entity to `completed`. This process guarantees that a wait can only be completed once, even if multiple concurrent invocations attempt to complete it simultaneously.
 </Callout>
 
-## Event Types Reference
+## Event types reference
 
 Events are categorized by the entity type they affect. Each event contains metadata including a timestamp and a `correlationId` that links the event to a specific entity:
 
@@ -163,7 +161,7 @@ Events are categorized by the entity type they affect. Each event contains metad
 - Wait events use the `waitId` as the correlation ID
 - Run events do not require a correlation ID since the `runId` itself identifies the entity
 
-### Run Events
+### Run events
 
 | Event | Description |
 |-------|-------------|
@@ -173,7 +171,7 @@ Events are categorized by the entity type they affect. Each event contains metad
 | `run_failed` | Transitions the run to `failed` state with error details and optional error code. |
 | `run_cancelled` | Transitions the run to `cancelled` state. Can be triggered from `pending` or `running` states. |
 
-### Step Events
+### Step events
 
 | Event | Description |
 |-------|-------------|
@@ -183,7 +181,7 @@ Events are categorized by the entity type they affect. Each event contains metad
 | `step_failed` | Transitions the step to `failed` state with error details. The step will not be retried. |
 | `step_retrying` | (Optional) Transitions the step back to `pending` state for retry. Contains the error that caused the retry and optional delay before the next attempt. When not emitted, retries appear as consecutive `step_started` events. |
 
-### Hook Events
+### Hook events
 
 | Event | Description |
 |-------|-------------|
@@ -192,14 +190,20 @@ Events are categorized by the entity type they affect. Each event contains metad
 | `hook_received` | Records that a payload was delivered to the hook. The hook remains `active` and can receive more payloads. |
 | `hook_disposed` | Deletes the hook from storage (conceptually transitioning to `disposed` state). The token is released for reuse by future workflows. |
 
-### Wait Events
+### Wait events
 
 | Event | Description |
 |-------|-------------|
 | `wait_created` | Creates a new wait in `waiting` state. Contains the timestamp when the wait should complete. |
 | `wait_completed` | Transitions the wait to `completed` state when the delay period has elapsed. |
 
-## Terminal States
+### System events
+
+| Event | Description |
+|-------|-------------|
+| `noop` | Seals an abandoned log position (`specVersion` 7 and above). Only the backend writes this event; the create endpoints reject it. See [Sealed positions](#sealed-positions-noop-events). |
+
+## Terminal states
 
 Terminal states represent the end of an entity's lifecycle. Once an entity reaches a terminal state, no further events can transition it to another state.
 
@@ -207,7 +211,7 @@ Terminal states represent the end of an entity's lifecycle. Once an entity reach
 
 - `completed`: Workflow finished successfully
 - `failed`: Workflow encountered an unrecoverable error
-- `cancelled`: Workflow was explicitly cancelled
+- `cancelled`: Workflow was explicitly canceled
 
 **Step terminal states:**
 
@@ -225,7 +229,59 @@ Terminal states represent the end of an entity's lifecycle. Once an entity reach
 
 Attempting to create an event that would transition an entity out of a terminal state will result in an error. This prevents inconsistent state and ensures the integrity of the event log.
 
-## Event Correlation
+That guard sits on the write path. Replay handles duplicates that the write path permits, such as a second `step_created` for a step that isn't terminal.
+
+## Duplicate events
+
+Concurrent invocations replaying the same run share one event log. An invocation working from a stale prefix that predates another invocation's write can commit its own `step_created`, `step_started`, or `wait_created` for an entity that already has one in the log. These writes pass the terminal-state guard, so the write path commits them even when a backend validates transitions atomically with the insert.
+
+Those duplicates are committed but inert. The outcome was decided by the first event of its kind at a lower position in the log, and every replay reads that same event at that same position, so a later copy cannot change what the workflow observes.
+
+To prevent an inert copy from failing an otherwise healthy run, the runtime groups event types into **classes**. For each entity, it tracks which classes the current replay has consumed. If no registered consumer accepts an event and its class is already recorded for that entity, replay skips it instead of reporting a [replay divergence](/docs/errors/replay-divergence). After exhausting the recovery budget, a replay divergence ends the run with [`CORRUPTED_EVENT_LOG`](/docs/errors/corrupted-event-log).
+
+| Class | Event types |
+|-------|-------------|
+| `run_started` | `run_started` |
+| `step_created` | `step_created` |
+| `step_started` | `step_started` |
+| `step_retrying` | `step_retrying` |
+| `step_terminal` | `step_completed`, `step_failed` |
+| `wait_created` | `wait_created` |
+| `wait_completed` | `wait_completed` |
+| `hook_created` | `hook_created` |
+| `hook_disposed` | `hook_disposed` |
+
+Types that share a class are the mutually exclusive outcomes of one decision. A step either completes or fails, and the first recorded outcome counts. Classes are independent, so skipping one doesn't suppress another. A step whose result is already in the log has still recorded exactly one `step_created`, making a second one independently ignorable.
+
+The two hook classes cover the same shape of duplicate, and replay reaches them less often because the write path resolves most hook duplicates before they reach the log: a run re-creating a hook it already owns converges on the existing `hook_created` rather than appending a second one, and a second `hook_disposed` for the same hook is refused as an idempotent no-op. A log that holds either anyway is read past like any other repeat.
+
+The remaining event types belong to no class and are never skipped:
+
+- `hook_received`: a hook legitimately receives many payloads under one ID, so a second `hook_received` is not a repeat of anything.
+- `hook_conflict`: records a failed acquisition of a hook's token, which the same run can hit repeatedly over its lifetime as other runs take and release that token. The hook's own consumer stays registered and claims every copy it is offered, so a repeat is consumed rather than reaching the class check.
+- `attr_set`: written on every [`setAttributes()`](/docs/api-reference/workflow/set-attributes) call, so a second write of the same key is a new fact rather than a repeat.
+- `run_created` precedes every replay and is always consumed.
+- `run_completed`, `run_failed`, and `run_cancelled` never reach the check. The runtime exits before replaying the workflow body once the log holds one of them, so no consumer ever takes one and no class is ever recorded for them.
+
+Both kinds of skip are logged at `debug`, so neither reaches the console unless you run with `DEBUG=workflow:runtime:*`. A duplicate is a permanent part of the log. Every later replay reads it and reaches the same check, so an unconditional message would print once per replay for the life of the run without requiring action. A repeat that decides a class differently, such as a `step_failed` after a `step_completed` or the reverse, gets its own message. Unlike a recommit of the same outcome, both writers cannot be correct.
+
+The observability UI grays out events it can identify this way and shows the reason on hover. Its set is narrower than the runtime's because it reads the log without consumer state. A consumer for an entity that is still open can legitimately claim a repeat because each step retry writes another `step_started`. The UI marks a repeat only when no consumer can remain for it: after a terminal event for the same entity or at a second `run_started`, of which the log records one per run. The UI marks nothing on a partial log view, such as one page of a paginated list or search results, because identifying the first copy requires the entire log.
+
+## Sealed positions (noop events)
+
+Runs at `specVersion` 7 and above use a *sealed log*. The backend gives each write its position from a per-run sequencer **before** the write commits, so concurrent writers hold distinct positions and never race for a slot. New runs use this behavior by default. [`WORKFLOW_SEALED_LOG=0`](/docs/configuration/runtime-tuning#workflow_sealed_log) returns a deployment to the previous scheme. Every runtime reads a sealed log regardless, and a run's version is fixed at creation, so changing the setting never affects an in-flight run. However, a writer can claim a position and then stop because of a crashed process or canceled transaction. This leaves a hole that no writer will fill, and a hole looks like an event the reader failed to load.
+
+The backend restores the dense log at read time by **sealing** these positions. Once a hole is provably abandoned, bounded by the commit time of later positions, the backend writes a `noop` event into it. Positions are assigned in order, so a committed later position proves how long the hole has been open. A `noop` occupies its position, and length-based completeness checks, cursors, and pagination all count it. It has no other effect:
+
+- It is **never offered to any consumer** during replay. The walk steps over it in the same synchronous pass that delivers the events around it, so its presence cannot perturb delivery order, promise scheduling, or which branch of a `Promise.all` resumes first.
+- It **never advances the deterministic clock**. A `noop`'s `createdAt` is the *sealer's* wall clock and can postdate events at higher positions. Allowing it to feed the replay clock would make a log containing a seal replay differently from one whose original writer filled the hole. This behavior uses the same rule and mechanism as skipped duplicates.
+- Its `correlationId` is `noop_` followed by the sealed position's zero-padded digits. This deterministic format ensures that two sealers racing for the same hole create an identical event that is recognizable in the log.
+
+A sealed position races its original writer at the same uniqueness fence as every other write. Losing that race means the real event landed first, so readers receive it instead. A live writer that gets sealed over derives a new position and commits there, using the same recovery as any other lost write race. Sealing can require a retry but cannot produce an incorrect log.
+
+`noop` is not user-creatable: it does not exist in the create schemas, and backends reject it on every create endpoint. Only a backend's own read path writes one.
+
+## Event correlation
 
 Events use a `correlationId` to link related events together. For step, hook, and wait events, the correlation ID identifies the specific entity instance:
 
@@ -241,7 +297,7 @@ This correlation enables:
 - Building timelines of entity lifecycle transitions
 - Debugging by tracing the complete history of any entity
 
-### Request ID Correlation
+### Request ID correlation
 
 Some `World` implementations also attach a `requestId` to events for platform-log correlation. This is different from `correlationId`:
 
@@ -273,7 +329,7 @@ All entities in the Workflow SDK use a consistent ID format: a 4-character prefi
 
 **Why this format?**
 
-- **Prefixes enable introspection**: Given any ID, you can immediately identify what type of entity it refers to. This makes debugging, logging, and cross-referencing entities across the system straightforward.
+- **Prefixes enable introspection**: Given any ID, you can immediately identify what type of entity it refers to. This helps you debug, log, and cross-reference entities across the system.
 
 - **Fixed-width bodies enable ordering**: Unlike UUIDs, these bodies sort lexicographically in creation order, so the event log is stored and retrieved in the correct order by sorting IDs alone. Slot numbers get that from counting at a fixed width, which makes string order the same as numeric order. ULIDs get it from the timestamp in their first 48 bits, which also makes a ULID's creation time recoverable from the ID itself.
 

package/docs/how-it-works/framework-integrations.mdx

@@ -10,7 +10,7 @@ related:
 ---
 
 <Callout>
-  **For users:** If you just want to use Workflow SDK with an existing framework, see [Getting Started](/docs/getting-started). This page is for framework authors.
+  **For users:** If you want to use Workflow SDK with an existing framework, see [Getting Started](/docs/getting-started). This page is for framework authors.
 </Callout>
 
 This guide uses Bun as a concrete example, but the same build and routing model applies to other JavaScript frameworks and runtimes.
@@ -48,7 +48,7 @@ Steps do not have their own HTTP route. A queued step invocation contains `stepI
 
 ### 1. Generate the bundles
 
-The standalone CLI scans `workflows/` and creates the combined flow handler, an internal step registration module, and the webhook handler.
+The standalone Workflow CLI scans `workflows/` and creates the combined flow handler, an internal step registration module, and the webhook handler.
 
 ```json title="package.json"
 {
@@ -60,17 +60,17 @@ The standalone CLI scans `workflows/` and creates the combined flow handler, an
 
 The default output is:
 
-- `/.well-known/workflow/v1/flow.mjs` — the combined workflow and step queue consumer
-- `/.well-known/workflow/v1/__step_registrations.mjs` — an internal module imported by `flow.mjs`; do not route to it
-- `/.well-known/workflow/v1/webhook.mjs` — webhook delivery
+- `/.well-known/workflow/v1/flow.mjs`: the combined workflow and step queue consumer
+- `/.well-known/workflow/v1/__step_registrations.mjs`: an internal module imported by `flow.mjs`; do not route to it
+- `/.well-known/workflow/v1/webhook.mjs`: webhook delivery
 
 <Callout>
   Production integrations should extend `BaseBuilder` from `@workflow/builders` so they can participate in the framework's build, watch, and routing lifecycle.
 </Callout>
 
-### 2. Add the client transform
+### 2. Add the app-code transform
 
-Client mode gives application code the workflow IDs used by `start()` and prevents accidental direct workflow execution.
+Applying the step-mode transform to application code gives it the workflow IDs used by `start()` and prevents accidental direct workflow execution. (Earlier releases used a separate `client` mode for this; it merged into `step` in 5.0.)
 
 {/* @skip-typecheck: incomplete code sample */}
 ```typescript title="workflow-plugin.ts" lineNumbers
@@ -91,7 +91,7 @@ plugin({
         jsc: {
           experimental: {
             plugins: [
-              [require.resolve("@workflow/swc-plugin"), { mode: "client" }],
+              [require.resolve("@workflow/swc-plugin"), { mode: "step" }],
             ],
           },
         },
@@ -149,10 +149,10 @@ console.log(`Server listening on http://localhost:${server.port}`);
 
 The handler consumes every workflow queue message. Depending on the payload and event log, it can:
 
-- start or replay workflow orchestration in the sandboxed VM;
-- execute a queued step in the host runtime;
-- continue replay inline after a step completes;
-- resume a run after a hook, webhook, sleep, retry, or recovery event.
+- Start or replay workflow orchestration in the sandboxed VM.
+- Execute a queued step in the host runtime.
+- Continue replay inline after a step completes.
+- Resume a run after a hook, webhook, sleep, retry, or recovery event.
 
 ### Webhook endpoint
 

package/docs/how-it-works/understanding-directives.mdx

@@ -21,7 +21,7 @@ This page explores how directives enable this execution model and the design pri
 
 To understand how directives work, let's first understand what workflows and steps are in the Workflow SDK.
 
-## Workflows and Steps Primer
+## Workflows and steps primer
 
 The Workflow SDK has two types of functions:
 
@@ -58,7 +58,7 @@ export async function onboardUser(userId: string) {
 **The key insight:** Workflows resume from suspension by replaying their code using cached step results from the [event log](/docs/how-it-works/event-sourcing). When a step like `await fetchUserData(userId)` is called:
 
 - **If already executed:** Returns the cached result immediately from the event log
-- **If not yet executed:** Suspends the workflow, enqueues the step for background execution, and resumes later with the result
+- **If not yet executed:** Suspends the workflow, executes the step (usually inline in the same invocation, or through the queue when the invocation runs out of inline budget or nears its timeout), then resumes with the result
 
 This replay mechanism requires deterministic code. If `Math.random()` weren't seeded, the first execution might return `0.7` (sending the email) but replay might return `0.3` (skipping it), thus breaking resumption. The Workflow SDK sandbox provides seeded `Math.random()` and `Date` to ensure consistent behavior across replays.
 
@@ -66,9 +66,9 @@ This replay mechanism requires deterministic code. If `Math.random()` weren't se
 For a deeper dive into workflows and steps, see [Workflows and Steps](/docs/foundations/workflows-and-steps).
 </Callout>
 
-## The Core Challenge
+## The core challenge
 
-This execution model enables powerful durability features - workflows can suspend for days, survive restarts, and resume from any point. However, it also requires a semantic boundary in the code that tells **the compiler, runtime, and developer** that execution semantics have changed.
+This execution model provides durability: workflows can suspend for days, survive restarts, and resume from any point. However, it also requires a semantic boundary in the code that tells **the compiler, runtime, and developer** that execution semantics have changed.
 
 The challenge: how do we mark this boundary in a way that:
 
@@ -77,7 +77,7 @@ The challenge: how do we mark this boundary in a way that:
 3. Allows static analysis of workflow structure
 4. Feels natural to JavaScript developers
 
-Let's look at where directives have been used before, and the alternatives we considered:
+Directives have prior uses, and we considered several alternatives:
 
 ## Prior art on directives
 
@@ -104,11 +104,11 @@ The `"use workflow"` directive is also used by the Language Server Plugin shippe
 
 But we didn't get here immediately. This took some discovery to arrive at:
 
-## Alternatives We Explored
+## Alternatives we explored
 
-Before settling on directives, we prototyped several other approaches. Each had significant limitations that made them unsuitable for production use.
+Before settling on directives, we prototyped several other approaches. Each had limitations that made them unsuitable for production use.
 
-### Runtime-Only "Suspense" API
+### Runtime-only "Suspense" API
 
 Our first proof of concept used a wrapper-based API without a build step:
 
@@ -140,7 +140,7 @@ export const myWorkflow = workflow(async () => {
 });
 ```
 
-This was verbose and easy to forget. Moreover, if a developer forgot to wrap something innocent like using `Date.now()`, it led to unstable runtime behavior.
+This was verbose and developers could forget it. If a developer forgot to wrap something like `Date.now()`, it led to unstable runtime behavior.
 
 For example:
 
@@ -200,7 +200,7 @@ export const myWorkflow = workflow(async () => {
 });
 ```
 
-### Generator-Based API
+### Generator-based API
 
 We explored using generators for explicit suspension points, inspired by libraries like Effect.ts:
 
@@ -220,7 +220,7 @@ We're big fans of [Effect.ts](https://effect.website/) and the power of generato
 
 **1. Syntax felt more like a DSL than JavaScript**
 
-Generators require a custom mental model that differs significantly from familiar async/await patterns. The `yield*` syntax and generator delegation were unfamiliar to many developers:
+Generators require a custom mental model that differs from familiar async/await patterns. The `yield*` syntax and generator delegation were unfamiliar to many developers:
 
 {/* @skip-typecheck: incomplete code sample */}
 ```typescript lineNumbers
@@ -267,7 +267,7 @@ export const myWorkflow = workflow(function*() {
 
 The generator syntax addressed suspension but didn't solve the fundamental sandboxing problem.
 
-### File System-Based Conventions
+### File system-based conventions
 
 We explored using file system conventions to identify workflows and steps, similar to how modern frameworks handle routing (Next.js, Hono, Nitro, SvelteKit):
 
@@ -282,7 +282,7 @@ We explored using file system conventions to identify workflows and steps, simil
   </Folder>
 </Files>
 
-With this approach, any function in the `workflows/` directory would be transformed as a workflow, and any function in `steps/` would be a step. No directives needed, just file locations.
+With this approach, any function in the `workflows/` directory would be transformed as a workflow, and any function in `steps/` would be a step. File locations would replace directives.
 
 **Why this could work:**
 
@@ -308,7 +308,7 @@ The directive approach solved all these issues: it works in any project structur
 
 ### Decorators
 
-We considered decorators, but they presented significant challenges both technical and ergonomic.
+We considered decorators, but they presented technical and ergonomic challenges.
 
 **Decorators are non-yet-standard and class-focused**
 
@@ -349,7 +349,7 @@ While decorators can be handled at compile-time with build tool support, they pr
 See the [Macro Wrapper](#macro-wrapper-approach) section below for a deeper dive into why this approach breaks down with concrete examples.
 </Callout>
 
-### Macro Wrapper Approach
+### Macro wrapper approach
 
 We also explored compile-time macro approaches - using a compiler to transform wrapper functions or decorators into directive-based code:
 
@@ -385,7 +385,7 @@ export const processOrder = async (orderId: string) => {
 };
 ```
 
-The benefit is that macros could enforce types and provide "Go To Definition" or other LSP features out of the box.
+The benefit is that macros could enforce types and provide "Go To Definition" or other LSP features without additional configuration.
 
 However, **the core problem remains: Workflows aren't runtime values**
 
@@ -431,7 +431,7 @@ To detect that `processOrder` is actually a workflow, the compiler would need wh
 
 This level of cross-function analysis is impractical for build tools - it would require analyzing every function call chain in your entire codebase and all dependencies. The compiler can only reliably detect direct `useWorkflow` calls, not calls hidden behind abstractions.
 
-## How Directives Solve These Problems
+## How directives solve these problems
 
 Directives address all the issues we encountered with previous approaches:
 
@@ -527,7 +527,7 @@ export async function processOrder(orderId: string) {
 
 The `"use step"` directive maintains consistency. While steps run in the full Node.js runtime and *could* work without a directive, they need some way to signal to the workflow runtime that they're steps.
 
-We could have used a function wrapper just for steps:
+We could have used a function wrapper for steps:
 
 {/* @skip-typecheck: incomplete code sample */}
 ```typescript lineNumbers
@@ -584,7 +584,7 @@ By requiring explicit `"use step"` directives, developers have fine-grained cont
 To understand how directives are transformed at compile time, see [How the Code Transform Works](/docs/how-it-works/code-transform).
 </Callout>
 
-## What Directives Enable
+## What directives enable
 
 Because `"use workflow"` defines a compile-time semantic boundary, we can provide:
 
@@ -603,7 +603,7 @@ Because `"use workflow"` defines a compile-time semantic boundary, we can provid
   </Card>
 </Cards>
 
-## Directives as a JavaScript Pattern
+## Directives as a JavaScript pattern
 
 Directives in JavaScript have always been contracts between the developer and the execution environment. `"use strict"` made this pattern familiar - it's a string literal that changes how code is interpreted.
 
@@ -611,7 +611,7 @@ While JavaScript doesn't yet have first-class support for custom directives (lik
 
 As TC39 members, we at Vercel are actively working with the standards body and broader ecosystem to explore formal specifications for pragma-like syntax or macro annotations that can express execution semantics.
 
-## Closing Thoughts
+## Closing thoughts
 
 Directives aren't about syntax preference, they're about expressing semantic boundaries. `"use workflow"` tells the compiler, developer, and runtime that this code is deterministic, resumable, and sandboxed.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workflow/core",
-  "version": "5.0.0-beta.42",
+  "version": "5.0.0-beta.44",
   "description": "Core runtime and engine for Workflow SDK",
   "type": "module",
   "main": "dist/index.js",
@@ -94,12 +94,12 @@
     "semver": "7.7.4",
     "ulid": "~3.0.1",
     "zod": "~4.3.6",
-    "@workflow/errors": "5.0.0-beta.17",
+    "@workflow/errors": "5.0.0-beta.18",
     "@workflow/serde": "5.0.0-beta.2",
-    "@workflow/utils": "5.0.0-beta.8",
-    "@workflow/world": "5.0.0-beta.27",
-    "@workflow/world-local": "5.0.0-beta.36",
-    "@workflow/world-vercel": "5.0.0-beta.38"
+    "@workflow/utils": "5.0.0-beta.9",
+    "@workflow/world": "5.0.0-beta.29",
+    "@workflow/world-local": "5.0.0-beta.38",
+    "@workflow/world-vercel": "5.0.0-beta.40"
   },
   "devDependencies": {
     "@opentelemetry/api": "1.9.0",
@@ -127,7 +127,7 @@
     "build": "genversion --es6 src/version.ts && node scripts/build-quickjs-assets.js && tsc",
     "dev": "genversion --es6 src/version.ts && tsc --watch",
     "clean": "tsc --build --clean && rm -rf dist src/version.ts docs ||:",
-    "test": "cross-env WORKFLOW_TARGET_WORLD=local vitest run src",
+    "test": "cross-env WORKFLOW_TARGET_WORLD=local vitest run src e2e/utils.test.ts",
     "test:e2e": "vitest run e2e",
     "typecheck": "genversion --es6 src/version.ts && tsc --noEmit"
   }