@workflow/core 5.0.0-beta.5 → 5.0.0-beta.50

package/docs/foundations/idempotency.mdx

@@ -1,23 +1,27 @@
 ---
 title: Idempotency
-description: Ensure operations can be safely retried without producing duplicate side effects.
+description: Make step retries safe and coordinate duplicate workflow starts with hook tokens.
 type: conceptual
-summary: Prevent duplicate side effects when retrying operations in steps.
+summary: Use step IDs for retry-safe external calls, and route duplicate workflow-start requests through deterministic hook tokens.
 prerequisites:
   - /docs/foundations/workflows-and-steps
 related:
   - /docs/foundations/errors-and-retries
+  - /docs/foundations/starting-workflows
+  - /docs/foundations/hooks
 ---
 
-Idempotency is a property of an operation that ensures it can be safely retried without producing duplicate side effects.
+Idempotency is a property of an operation that ensures repeated attempts have the same effect as a single attempt.
 
-In distributed systems (calling external APIs), it is not always possible to ensure an operation has only been performed once just by seeing if it succeeds.
+In Workflow, idempotency shows up in two related places: step idempotency makes external calls safe when a step retries, and run idempotency coordinates duplicate requests that try to start the same workflow.
+
+## Step idempotency
+
+In distributed systems (calling external APIs), it is not always possible to ensure an operation has only been performed once by seeing if it succeeds.
 Consider a payment API that charges the user $10, but due to network failures, the confirmation response is lost. When the step retries (because the previous attempt was considered a failure), it will charge the user again.
 
 To prevent this, many external APIs support idempotency keys. An idempotency key is a unique identifier for an operation that can be used to deduplicate requests.
 
-## The core pattern: use the step ID as your idempotency key
-
 Every step invocation has a stable `stepId` that stays the same across retries.
 Use it as the idempotency key when calling third-party APIs.
 
@@ -27,7 +31,7 @@ import { getStepMetadata } from "workflow";
 async function chargeUser(userId: string, amount: number) {
   "use step";
 
-  const { stepId } = getStepMetadata();
+  const { stepId } = getStepMetadata(); // [!code highlight]
 
   // Example: Stripe-style idempotency key
   // This guarantees only one charge is created even if the step retries
@@ -49,14 +53,242 @@ Why this works:
 - **Stable across retries**: `stepId` does not change between attempts.
 - **Globally unique per step**: Fulfills the uniqueness requirement for an idempotency key.
 
-## Best practices
+## Run idempotency
+
+Step idempotency protects side effects **inside** a workflow run. Run idempotency answers a different question: if the same API request is sent twice, should it create one workflow run or two?
+
+Because [hooks](/docs/foundations/hooks) already ensure globally unique active tokens, Workflow can use the same mechanism to coordinate duplicate requests while a run is active.
+
+Use a hook token as the idempotency key for an active workflow run. Hook tokens are globally unique while they are active: if another run tries to create a hook with the same token, the runtime records a conflict, `hook.getConflict()` resolves with a `Run` handle for the run that owns the token, and the hook rejects with [`HookConflictError`](/docs/errors/hook-conflict) when the workflow awaits or iterates its payload.
+
+The token should come from your domain, such as an order ID, invoice ID, import ID, or request ID. Create the hook near the beginning of the workflow and check `await hook.getConflict()` before doing duplicate-sensitive work that depends on owning the active token. Calling `createHook()` alone does not register the hook; awaiting `getConflict()` suspends the workflow to commit the registration.
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+type OrderRequest = { confirmed: boolean };
+type OrderResult =
+  | { status: "processed" | "cancelled" }
+  | { status: "duplicate"; runId: string };
+declare function chargeOrder(orderId: string): Promise<void>; // @setup
+
+export async function processOrder(orderId: string): Promise<OrderResult> {
+  "use workflow";
+
+  using request = createHook<OrderRequest>({ // [!code highlight]
+    token: `order:${orderId}`, // [!code highlight]
+  }); // [!code highlight]
+
+  const conflict = await request.getConflict(); // [!code highlight]
+  if (conflict) { // [!code highlight]
+    // Another active run already owns this order's token. // [!code highlight]
+    return { status: "duplicate" as const, runId: conflict.runId }; // [!code highlight]
+  } // [!code highlight]
+
+  const { confirmed } = await request;
+
+  if (!confirmed) {
+    return { status: "cancelled" as const };
+  }
+
+  await chargeOrder(orderId);
+  return { status: "processed" as const };
+}
+```
+
+The runtime creates the hook atomically. At most one hook can own `order:${orderId}`, so duplicate workflow runs converge on one owner. A duplicate run observes `getConflict()` resolving with the owner's `Run` and returns before it reaches `chargeOrder()`. The conflicting run's accessors (`status`, `returnValue`, `cancel()`, …) are durable steps, so the duplicate run can do more than report the owner. See [conflict-handling strategies](#conflict-handling-strategies) below.
+
+Outside the workflow, try to resume the hook first. If the hook is not registered yet, start the workflow and retry the resume until the new run creates the hook:
+
+```typescript lineNumbers
+import { resumeHook, start } from "workflow/api";
+import { HookNotFoundError } from "workflow/errors";
+import { processOrder } from "./workflows/process-order";
+
+type OrderRequest = { confirmed: boolean };
+
+async function resumeOrder(token: string, payload: OrderRequest) {
+  for (let attempt = 0; attempt < 5; attempt++) {
+    try {
+      return await resumeHook(token, payload); // [!code highlight]
+    } catch (error) {
+      if (!HookNotFoundError.is(error)) throw error;
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+  }
+
+  throw new Error("Order workflow did not register its hook in time");
+}
+
+export async function POST(request: Request) {
+  const { orderId, confirmed } = await request.json();
+  const token = `order:${orderId}`;
+  const payload = { confirmed };
+
+  try {
+    const hook = await resumeHook(token, payload); // [!code highlight]
+    return Response.json({ runId: hook.runId, reused: true });
+  } catch (error) {
+    if (!HookNotFoundError.is(error)) throw error;
+  }
+
+  const run = await start(processOrder, [orderId]); // [!code highlight]
+  const resumed = await resumeOrder(token, payload);
+
+  // A concurrent request's run may have won the race between `start()` // [!code highlight]
+  // and hook registration. The resume always reaches the actual active // [!code highlight]
+  // owner, so compare run IDs instead of waiting for this run to finish. // [!code highlight]
+  return Response.json({ // [!code highlight]
+    runId: resumed.runId, // [!code highlight]
+    reused: resumed.runId !== run.runId, // [!code highlight]
+  }); // [!code highlight]
+}
+```
+
+<Callout type="warn">
+This avoids creating a new run only after the first run has registered its hook. Because `start()` returns before the run body executes and calls `createHook()`, two concurrent requests can both observe "no hook yet" and each call `start()`. The race is resolved inside the workflow body, where the losing run observes `getConflict()` resolving with the active owner and returns without doing duplicate-sensitive work, and the route detects it by comparing the resumed hook's `runId` against the run it just started, without waiting for either run to finish. A native API for atomically starting a run and registering a hook is in the works. Until then, model recovery inside the workflow by checking `hook.getConflict()`.
+</Callout>
+
+This coordinates active runs by default: the token becomes available when its workflow ends. Set `experimental_minRetention` to keep it unavailable to late duplicates. After the workflow ends, the Hook can still be found with `getHookByToken()` until retention ends, but it cannot be resumed. See [`createHook()` minimum retention](/docs/api-reference/workflow/create-hook#keep-a-token-unavailable-after-the-run-ends) for examples and supported values.
+
+### Conflict-handling strategies
+
+Some workflow systems resolve duplicate IDs with a fixed, pre-declared policy, typically a static choice between rejecting the new execution, deferring to the existing one, or terminating it. Workflow has no policy enum. `hook.getConflict()` hands the duplicate run the conflicting `Run` itself, and the policy is ordinary code, including policies that inspect state before deciding, which static configuration can't express.
+
+The example above implements **reject the duplicate**: return the owner's `runId` and let the caller decide. Other common strategies:
+
+**Adopt the owner's result.** Wait for the active run to finish and return its result, so callers cannot tell which run did the work:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+type OrderRequest = { confirmed: boolean };
+declare function processOwnedOrder(orderId: string): Promise<{ status: string }>; // @setup
+
+export async function processOrder(orderId: string) {
+  "use workflow";
+
+  using request = createHook<OrderRequest>({
+    token: `order:${orderId}`,
+  });
+
+  const conflict = await request.getConflict();
+  if (conflict) {
+    // Callers get the same result regardless of which run did the work.
+    return await conflict.returnValue; // [!code highlight]
+  }
+
+  return await processOwnedOrder(orderId);
+}
+```
+
+**Inspect the owner before deciding.** Reuse a completed owner's result, but reject other duplicates:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+type OrderRequest = { confirmed: boolean };
+declare function processOwnedOrder(orderId: string): Promise<{ status: string }>; // @setup
+
+export async function processOrder(orderId: string) {
+  "use workflow";
+
+  using request = createHook<OrderRequest>({
+    token: `order:${orderId}`,
+  });
+
+  const conflict = await request.getConflict();
+  if (conflict) {
+    const status = await conflict.status; // [!code highlight]
+    if (status === "completed") {
+      return await conflict.returnValue;
+    }
+    return { status: "duplicate" as const, runId: conflict.runId };
+  }
+
+  return await processOwnedOrder(orderId);
+}
+```
+
+**Signal the owner instead of doing the work.** A conflict can refer to a finished run when `experimental_minRetention` is set, so check its status before sending data to its Hook:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+import { resumeHook } from "workflow/api";
+
+type OrderRequest = { confirmed: boolean };
+
+async function forwardToOwner(token: string, payload: OrderRequest) {
+  "use step";
+  await resumeHook(token, payload); // [!code highlight]
+}
+
+export async function processOrder(orderId: string, confirmed: boolean) {
+  "use workflow";
+
+  const token = `order:${orderId}`;
+  using request = createHook<OrderRequest>({ token });
+
+  const conflict = await request.getConflict();
+  if (conflict && ["pending", "running"].includes(await conflict.status)) {
+    await forwardToOwner(token, { confirmed }); // [!code highlight]
+    return { status: "forwarded" as const, runId: conflict.runId };
+  }
+  if (conflict) {
+    return { status: "duplicate" as const, runId: conflict.runId };
+  }
+
+  // ... own the token and do the work
+}
+```
+
+**Supersede the owner.** Without minimum retention, cancel the active run, then claim the released token. The retry loop covers the window where cancellation cleanup has not propagated yet:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+type OrderRequest = { confirmed: boolean };
+declare function chargeOrder(orderId: string): Promise<void>; // @setup
+
+export async function processOrderNewestWins(orderId: string) {
+  "use workflow";
+
+  const token = `order:${orderId}`;
+
+  for (let attempt = 0; attempt < 3; attempt++) {
+    using request = createHook<OrderRequest>({ token });
+
+    const conflict = await request.getConflict();
+    if (!conflict) {
+      // Token claimed: this run is now the owner.
+      const { confirmed } = await request;
+      if (confirmed) {
+        await chargeOrder(orderId);
+      }
+      return { status: "processed" as const };
+    }
+
+    await conflict.cancel(); // [!code highlight]
+  }
+
+  throw new Error(`Could not claim ${token} after canceling the owner`);
+}
+```
+
+<Callout type="warn">
+This pattern does not work with `experimental_minRetention`: canceling the old run does not make its token available early.
+</Callout>
+
+If duplicate requests should only reuse the active run without sending data, use [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token) as an advisory pre-check before calling `start()`. The workflow should still check `hook.getConflict()`, because the lookup and `start()` are not atomic.
 
-- **Always provide idempotency keys to external side effects that are not idempotent** inside steps (payments, emails, SMS, queues).
-- **Prefer `stepId` as your key**; it is stable across retries and unique per step.
-- **Keep keys deterministic**; avoid including timestamps or attempt counters.
-- **Handle 409/conflict responses** gracefully; treat them as success if the prior attempt completed.
+Because this pattern uses hooks for idempotency, duplicate requests can also inject additional data and steer the existing run. The route example above uses `resumeHook()` for that: if the hook already exists, the duplicate request resumes the active workflow; if the hook is not registered yet, the route starts the workflow and retries `resumeHook()` so the payload is not dropped.
 
 ## Related docs
 
 - Learn about retries in [Errors & Retrying](/docs/foundations/errors-and-retries)
 - API reference: [`getStepMetadata`](/docs/api-reference/workflow/get-step-metadata)
+- API reference: [`createHook()`](/docs/api-reference/workflow/create-hook)
+- API reference: [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token)
+- API reference: [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook)
+- API reference: [`start()`](/docs/api-reference/workflow-api/start)
+- Learn about deterministic hook tokens in [Hooks](/docs/foundations/hooks)

package/docs/foundations/index.mdx

@@ -10,26 +10,4 @@ related:
 
 Workflow programming can be a slight shift from how you traditionally write real-world applications. Learning the foundations now will go a long way toward helping you use workflows effectively.
 
-<Cards>
-    <Card href="/docs/foundations/workflows-and-steps" title="Workflows and Steps">
-        Learn about the building blocks of durability
-    </Card>
-    <Card href="/docs/foundations/starting-workflows" title="Starting Workflows">
-        Trigger workflows and track their execution using the `start()` function.
-    </Card>
-    <Card href="/docs/foundations/errors-and-retries" title="Errors & Retrying">
-        Types of errors and how retrying work in workflows.
-    </Card>
-    <Card href="/docs/foundations/hooks" title="Webhooks (and hooks)">
-        Respond to external events in your workflow using hooks and webhooks.
-    </Card>
-    <Card href="/docs/foundations/streaming" title="Streaming">
-        Stream data in real-time to clients without waiting for the workflow to complete.
-    </Card>
-    <Card href="/docs/foundations/serialization" title="Serialization">
-        Understand which types can be passed between workflow and step functions.
-    </Card>
-    <Card href="/docs/foundations/idempotency" title="Idempotency">
-        Prevent duplicate side effects when retrying operations.
-    </Card>
-</Cards>
+<AutoCards />

package/docs/foundations/meta.json

@@ -8,7 +8,8 @@
     "streaming",
     "cancellation",
     "serialization",
-    "idempotency"
+    "idempotency",
+    "versioning"
   ],
   "defaultOpen": true
 }

package/docs/foundations/serialization.mdx

@@ -15,11 +15,11 @@ All function arguments and return values passed between workflow and step functi
 The serialization system ensures that all data persists correctly across workflow suspensions and resumptions, enabling durable execution.
 </Callout>
 
-## Supported Serializable Types
+## Supported serializable types
 
 The following types can be serialized and passed through workflow functions:
 
-**Standard JSON Types:**
+**Standard JSON types:**
 
 - `string`
 - `number`
@@ -28,7 +28,7 @@ The following types can be serialized and passed through workflow functions:
 - Arrays of serializable values
 - Objects with string keys and serializable values
 
-**Extended Types:**
+**Extended types:**
 
 - `undefined`
 - `bigint`
@@ -58,7 +58,7 @@ These types have special handling and are explained in detail in the sections be
 - `AbortController`
 - `AbortSignal`
 
-## Pass-by-Value Semantics
+## Pass-by-value semantics
 
 **Parameters are passed by value, not by reference.** Steps receive deserialized copies of data. Mutations inside a step won't affect the original in the workflow.
 
@@ -81,7 +81,7 @@ async function updateUserStep(user: { id: string; name: string; email: string })
 }
 ```
 
-**Correct - return the modified data:**
+**Correct, return the modified data:**
 
 ```typescript title="workflows/correct-mutation.ts" lineNumbers
 export async function updateUserWorkflow(userId: string) {
@@ -100,7 +100,7 @@ async function updateUserStep(user: { id: string; name: string; email: string })
 }
 ```
 
-**Custom Classes:**
+**Custom classes:**
 
 - Class instances that implement [`WORKFLOW_SERIALIZE` and `WORKFLOW_DESERIALIZE`](#custom-class-serialization)
 
@@ -110,7 +110,7 @@ async function updateUserStep(user: { id: string; name: string; email: string })
 
 For complete information about using streams in workflows, including patterns for AI streaming, file processing, and progress updates, see the [Streaming Guide](/docs/foundations/streaming).
 
-## Request & Response
+## Request & response
 
 The Web API [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) and [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) APIs are supported by the serialization system,
 and can be passed around between workflow and step functions similarly to other data types.
@@ -140,7 +140,7 @@ export async function handleWebhookWorkflow() {
 }
 ```
 
-### Using `fetch` in Workflows
+### Using `fetch` in workflows
 
 Because `Request` and `Response` are serializable, Workflow SDK provides a `fetch` function that can be used directly in workflow functions:
 
@@ -158,7 +158,7 @@ export async function apiWorkflow() {
 }
 ```
 
-The implementation is straightforward - `fetch` from workflow is a step function that wraps the standard `fetch`:
+The `fetch` implementation from `workflow` is a step function that wraps the standard `fetch`:
 
 ```typescript title="Implementation" lineNumbers
 export async function fetch(...args: Parameters<typeof globalThis.fetch>) {
@@ -202,11 +202,11 @@ async function fetchData(signal: AbortSignal) {
 
 For usage patterns including timeouts, parallel cancellation, user-triggered cancellation, and run cancellation, see the [Cancellation Guide](/docs/foundations/cancellation). For details on the hook and stream backing that makes this work, see [How Cancellation Works](/docs/how-it-works/cancellation).
 
-## Custom Class Serialization
+## Custom class serialization
 
 By default, custom class instances cannot be serialized because the serialization system doesn't know how to reconstruct them. You can make your classes serializable by implementing two static methods using special symbols from the `@workflow/serde` package.
 
-### Basic Example
+### Basic example
 
 {/* @expect-error:2351 */}
 
@@ -256,13 +256,13 @@ async function doublePoint(point: Point) {
 }
 ```
 
-### How It Works
+### How it works
 
 1. **`WORKFLOW_SERIALIZE`**: A static method that receives a class instance and returns serializable data (primitives, plain objects, arrays, etc.)
 
 2. **`WORKFLOW_DESERIALIZE`**: A static method that receives the serialized data and returns a new class instance
 
-3. **Automatic Registration**: The SWC compiler plugin automatically detects classes that implement these symbols and registers them for serialization. Each class receives a deterministic `classId` derived from its file path and class name, and is registered into the global `Symbol.for("workflow-class-registry")` registry at build time — no manual registration step is required
+3. **Automatic Registration**: The SWC compiler plugin automatically detects classes that implement these symbols and registers them for serialization. Each class receives a deterministic `classId` derived from its file path and class name, and is registered into the global `Symbol.for("workflow-class-registry")` registry at build time. No manual registration step is required
 
 ### Requirements
 
@@ -279,12 +279,12 @@ The `WORKFLOW_SERIALIZE` and `WORKFLOW_DESERIALIZE` methods run inside the workf
 - No non-deterministic operations (like `Math.random()` or `Date.now()`)
 - No external network calls
 
-Keep these methods simple and focused on data transformation only.
+Keep these methods focused on data transformation only.
 </Callout>
 
-### Instance Methods as Steps
+### Instance methods as steps
 
-In practice, many classes have methods that need Node.js APIs, perform network calls, or interact with databases — operations that are not allowed in the `"use workflow"` execution context. You can make these methods workflow-compatible by adding `"use step"` to them. The SWC compiler will strip the method bodies from the workflow bundle and replace them with proxy functions that invoke the method as a step — with full Node.js runtime access. The `this` context (the class instance) is automatically serialized and deserialized across the workflow/step boundary.
+In practice, many classes have methods that need Node.js APIs, perform network calls, or interact with databases, operations that are not allowed in the `"use workflow"` execution context. You can make these methods workflow-compatible by adding `"use step"` to them. The SWC compiler will strip the method bodies from the workflow bundle and replace them with proxy functions that invoke the method as a step, with full Node.js runtime access. The `this` context (the class instance) is automatically serialized and deserialized across the workflow/step boundary.
 
 This requires the class to implement `WORKFLOW_SERIALIZE` and `WORKFLOW_DESERIALIZE`, so that the instance can be passed to the step execution context.
 
@@ -301,7 +301,7 @@ class Order {
     public createdAt: Date
   ) {}
 
-  // Custom serialization — data must be serializable types
+  // Custom serialization: data must be serializable types
   static [WORKFLOW_SERIALIZE](instance: Order) { // [!code highlight]
     return { // [!code highlight]
       id: instance.id, // [!code highlight]
@@ -329,7 +329,7 @@ class Order {
   }
 
   // Instance methods with "use step" run as step functions
-  // with full Node.js access — `this` is automatically serialized
+  // with full Node.js access; `this` is automatically serialized
   async save(): Promise<void> {
     "use step"; // [!code highlight]
     await db.orders.insert({ // [!code highlight]
@@ -355,7 +355,7 @@ class Order {
 }
 ```
 
-The class can then be used naturally inside a workflow function. Instance methods marked with `"use step"` are each executed as a step — with automatic caching, retry semantics, and full Node.js runtime access. Methods _without_ `"use step"` run directly in the workflow context, so they must follow the same constraints as workflow functions:
+The class can then be used naturally inside a workflow function. Instance methods marked with `"use step"` are each executed as a step, with automatic caching, retry semantics, and full Node.js runtime access. Methods _without_ `"use step"` run directly in the workflow context, so they must follow the same constraints as workflow functions:
 
 {/* @expect-error:2693 */}
 
@@ -369,7 +369,7 @@ export async function processOrderWorkflow(
 
   const order = new Order(orderId, items, new Date()); // [!code highlight]
 
-  // Runs in the workflow context — no "use step" needed
+  // Runs in the workflow context; no "use step" needed
   const itemCount = order.total(); // [!code highlight]
 
   // Each "use step" instance method call runs as a separate step
@@ -380,7 +380,7 @@ export async function processOrderWorkflow(
 }
 ```
 
-Note that [pass-by-value semantics](#pass-by-value-semantics) also apply to the `this` context of `"use step"` instance methods. Modifying instance properties inside a step method will not affect the original instance in the workflow. If you need to update instance state, return `this` from the step method and re-assign the variable in the workflow:
+[Pass-by-value semantics](#pass-by-value-semantics) also apply to the `this` context of `"use step"` instance methods. Modifying instance properties inside a step method will not affect the original instance in the workflow. If you need to update instance state, return `this` from the step method and re-assign the variable in the workflow:
 
 {/* @expect-error:2351 */}
 
@@ -408,4 +408,3 @@ export async function processOrderWorkflow() {
   order = await order.addItem("Widget", 3); // [!code highlight]
 }
 ```
-