@workflow/core 5.0.0-beta.15 → 5.0.0-beta.17

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 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 just 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,235 @@ 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 active hook can own `order:${orderId}`, so duplicate workflow runs converge on one active 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 is active-run coordination. When the workflow completes and disposes the hook, the token can be used again. If a duplicate request after completion must return the original result instead of starting fresh work, persist that completed result under the same domain key.
+
+### 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.** Branch on the owner's live state:
+
+```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 === "running") {
+      return { status: "duplicate" as const, runId: conflict.runId };
+    }
+    // Owner already reached a terminal state; its hook will be released.
+  }
+
+  return await processOwnedOrder(orderId);
+}
+```
+
+**Signal the owner instead of doing the work.** The duplicate run knows the token, so it can deliver this run's input to the owner's hook from a step:
+
+```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) {
+    await forwardToOwner(token, { confirmed }); // [!code highlight]
+    return { status: "forwarded" as const, runId: conflict.runId };
+  }
+
+  // ... own the token and do the work
+}
+```
+
+**Supersede the owner.** Newest-wins: cancel the active run, then claim the released token. Cancellation disposes the owner's hooks; the retry loop covers the window where that disposal 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 cancelling the owner`);
+}
+```
+
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workflow/core",
-  "version": "5.0.0-beta.15",
+  "version": "5.0.0-beta.17",
   "description": "Core runtime and engine for Workflow SDK",
   "type": "module",
   "main": "dist/index.js",
@@ -89,15 +89,18 @@
     "semver": "7.7.4",
     "ulid": "~3.0.1",
     "zod": "4.3.6",
-    "@workflow/errors": "5.0.0-beta.7",
+    "@workflow/errors": "5.0.0-beta.8",
     "@workflow/serde": "5.0.0-beta.2",
-    "@workflow/utils": "5.0.0-beta.3",
-    "@workflow/world": "5.0.0-beta.9",
-    "@workflow/world-local": "5.0.0-beta.16",
-    "@workflow/world-vercel": "5.0.0-beta.14"
+    "@workflow/utils": "5.0.0-beta.4",
+    "@workflow/world": "5.0.0-beta.10",
+    "@workflow/world-local": "5.0.0-beta.18",
+    "@workflow/world-vercel": "5.0.0-beta.16"
   },
   "devDependencies": {
     "@opentelemetry/api": "1.9.0",
+    "@opentelemetry/context-async-hooks": "1.30.1",
+    "@opentelemetry/core": "1.30.1",
+    "@opentelemetry/sdk-trace-base": "1.30.1",
     "@types/debug": "4.1.12",
     "@types/node": "22.19.0",
     "@types/seedrandom": "3.0.8",