workflow 5.0.0-beta.2 → 5.0.0-beta.4

package/dist/api-workflow.d.ts

@@ -1,9 +1,9 @@
 export type { Event, StartOptions, StopSleepOptions, StopSleepResult, WorkflowReadableStreamOptions, WorkflowRun, } from '@workflow/core/runtime';
 export { Run } from '@workflow/core/runtime/run';
+export { start } from '@workflow/core/runtime/start';
 export declare const getRun: () => never;
 export declare const getHookByToken: () => never;
 export declare const resumeHook: () => never;
 export declare const resumeWebhook: () => never;
 export declare const runStep: () => never;
-export declare const start: () => never;
 //# sourceMappingURL=api-workflow.d.ts.map

package/dist/api-workflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-workflow.d.ts","sourceRoot":"","sources":["../src/api-workflow.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,KAAK,EACL,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,6BAA6B,EAC7B,WAAW,GACZ,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,GAAG,EAAE,MAAM,4BAA4B,CAAC;AAQjD,eAAO,MAAM,MAAM,aAA+B,CAAC;AACnD,eAAO,MAAM,cAAc,aAAuC,CAAC;AACnE,eAAO,MAAM,UAAU,aAAmC,CAAC;AAC3D,eAAO,MAAM,aAAa,aAAsC,CAAC;AACjE,eAAO,MAAM,OAAO,aAAgC,CAAC;AACrD,eAAO,MAAM,KAAK,aAA8B,CAAC"}
+{"version":3,"file":"api-workflow.d.ts","sourceRoot":"","sources":["../src/api-workflow.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,KAAK,EACL,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,6BAA6B,EAC7B,WAAW,GACZ,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,GAAG,EAAE,MAAM,4BAA4B,CAAC;AACjD,OAAO,EAAE,KAAK,EAAE,MAAM,8BAA8B,CAAC;AAQrD,eAAO,MAAM,MAAM,aAA+B,CAAC;AACnD,eAAO,MAAM,cAAc,aAAuC,CAAC;AACnE,eAAO,MAAM,UAAU,aAAmC,CAAC;AAC3D,eAAO,MAAM,aAAa,aAAsC,CAAC;AACjE,eAAO,MAAM,OAAO,aAAgC,CAAC"}

package/dist/api-workflow.js

@@ -1,4 +1,5 @@
 export { Run } from '@workflow/core/runtime/run';
+export { start } from '@workflow/core/runtime/start';
 const workflowStub = (item) => {
     throw new Error(`The workflow environment doesn't allow this runtime usage of ${item}. Move this call to a step function ("use step") or call it outside the workflow context.`);
 };
@@ -7,5 +8,4 @@ export const getHookByToken = () => workflowStub('getHookByToken');
 export const resumeHook = () => workflowStub('resumeHook');
 export const resumeWebhook = () => workflowStub('resumeWebhook');
 export const runStep = () => workflowStub('runStep');
-export const start = () => workflowStub('start');
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYXBpLXdvcmtmbG93LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2FwaS13b3JrZmxvdy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFTQSxPQUFPLEVBQUUsR0FBRyxFQUFFLE1BQU0sNEJBQTRCLENBQUM7QUFFakQsTUFBTSxZQUFZLEdBQUcsQ0FBQyxJQUFZLEVBQUUsRUFBRTtJQUNwQyxNQUFNLElBQUksS0FBSyxDQUNiLGdFQUFnRSxJQUFJLDJGQUEyRixDQUNoSyxDQUFDO0FBQ0osQ0FBQyxDQUFDO0FBRUYsTUFBTSxDQUFDLE1BQU0sTUFBTSxHQUFHLEdBQUcsRUFBRSxDQUFDLFlBQVksQ0FBQyxRQUFRLENBQUMsQ0FBQztBQUNuRCxNQUFNLENBQUMsTUFBTSxjQUFjLEdBQUcsR0FBRyxFQUFFLENBQUMsWUFBWSxDQUFDLGdCQUFnQixDQUFDLENBQUM7QUFDbkUsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHLEdBQUcsRUFBRSxDQUFDLFlBQVksQ0FBQyxZQUFZLENBQUMsQ0FBQztBQUMzRCxNQUFNLENBQUMsTUFBTSxhQUFhLEdBQUcsR0FBRyxFQUFFLENBQUMsWUFBWSxDQUFDLGVBQWUsQ0FBQyxDQUFDO0FBQ2pFLE1BQU0sQ0FBQyxNQUFNLE9BQU8sR0FBRyxHQUFHLEVBQUUsQ0FBQyxZQUFZLENBQUMsU0FBUyxDQUFDLENBQUM7QUFDckQsTUFBTSxDQUFDLE1BQU0sS0FBSyxHQUFHLEdBQUcsRUFBRSxDQUFDLFlBQVksQ0FBQyxPQUFPLENBQUMsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbImV4cG9ydCB0eXBlIHtcbiAgRXZlbnQsXG4gIFN0YXJ0T3B0aW9ucyxcbiAgU3RvcFNsZWVwT3B0aW9ucyxcbiAgU3RvcFNsZWVwUmVzdWx0LFxuICBXb3JrZmxvd1JlYWRhYmxlU3RyZWFtT3B0aW9ucyxcbiAgV29ya2Zsb3dSdW4sXG59IGZyb20gJ0B3b3JrZmxvdy9jb3JlL3J1bnRpbWUnO1xuXG5leHBvcnQgeyBSdW4gfSBmcm9tICdAd29ya2Zsb3cvY29yZS9ydW50aW1lL3J1bic7XG5cbmNvbnN0IHdvcmtmbG93U3R1YiA9IChpdGVtOiBzdHJpbmcpID0+IHtcbiAgdGhyb3cgbmV3IEVycm9yKFxuICAgIGBUaGUgd29ya2Zsb3cgZW52aXJvbm1lbnQgZG9lc24ndCBhbGxvdyB0aGlzIHJ1bnRpbWUgdXNhZ2Ugb2YgJHtpdGVtfS4gTW92ZSB0aGlzIGNhbGwgdG8gYSBzdGVwIGZ1bmN0aW9uIChcInVzZSBzdGVwXCIpIG9yIGNhbGwgaXQgb3V0c2lkZSB0aGUgd29ya2Zsb3cgY29udGV4dC5gXG4gICk7XG59O1xuXG5leHBvcnQgY29uc3QgZ2V0UnVuID0gKCkgPT4gd29ya2Zsb3dTdHViKCdnZXRSdW4nKTtcbmV4cG9ydCBjb25zdCBnZXRIb29rQnlUb2tlbiA9ICgpID0+IHdvcmtmbG93U3R1YignZ2V0SG9va0J5VG9rZW4nKTtcbmV4cG9ydCBjb25zdCByZXN1bWVIb29rID0gKCkgPT4gd29ya2Zsb3dTdHViKCdyZXN1bWVIb29rJyk7XG5leHBvcnQgY29uc3QgcmVzdW1lV2ViaG9vayA9ICgpID0+IHdvcmtmbG93U3R1YigncmVzdW1lV2ViaG9vaycpO1xuZXhwb3J0IGNvbnN0IHJ1blN0ZXAgPSAoKSA9PiB3b3JrZmxvd1N0dWIoJ3J1blN0ZXAnKTtcbmV4cG9ydCBjb25zdCBzdGFydCA9ICgpID0+IHdvcmtmbG93U3R1Yignc3RhcnQnKTtcbiJdfQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYXBpLXdvcmtmbG93LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2FwaS13b3JrZmxvdy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFTQSxPQUFPLEVBQUUsR0FBRyxFQUFFLE1BQU0sNEJBQTRCLENBQUM7QUFDakQsT0FBTyxFQUFFLEtBQUssRUFBRSxNQUFNLDhCQUE4QixDQUFDO0FBRXJELE1BQU0sWUFBWSxHQUFHLENBQUMsSUFBWSxFQUFFLEVBQUU7SUFDcEMsTUFBTSxJQUFJLEtBQUssQ0FDYixnRUFBZ0UsSUFBSSwyRkFBMkYsQ0FDaEssQ0FBQztBQUNKLENBQUMsQ0FBQztBQUVGLE1BQU0sQ0FBQyxNQUFNLE1BQU0sR0FBRyxHQUFHLEVBQUUsQ0FBQyxZQUFZLENBQUMsUUFBUSxDQUFDLENBQUM7QUFDbkQsTUFBTSxDQUFDLE1BQU0sY0FBYyxHQUFHLEdBQUcsRUFBRSxDQUFDLFlBQVksQ0FBQyxnQkFBZ0IsQ0FBQyxDQUFDO0FBQ25FLE1BQU0sQ0FBQyxNQUFNLFVBQVUsR0FBRyxHQUFHLEVBQUUsQ0FBQyxZQUFZLENBQUMsWUFBWSxDQUFDLENBQUM7QUFDM0QsTUFBTSxDQUFDLE1BQU0sYUFBYSxHQUFHLEdBQUcsRUFBRSxDQUFDLFlBQVksQ0FBQyxlQUFlLENBQUMsQ0FBQztBQUNqRSxNQUFNLENBQUMsTUFBTSxPQUFPLEdBQUcsR0FBRyxFQUFFLENBQUMsWUFBWSxDQUFDLFNBQVMsQ0FBQyxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiZXhwb3J0IHR5cGUge1xuICBFdmVudCxcbiAgU3RhcnRPcHRpb25zLFxuICBTdG9wU2xlZXBPcHRpb25zLFxuICBTdG9wU2xlZXBSZXN1bHQsXG4gIFdvcmtmbG93UmVhZGFibGVTdHJlYW1PcHRpb25zLFxuICBXb3JrZmxvd1J1bixcbn0gZnJvbSAnQHdvcmtmbG93L2NvcmUvcnVudGltZSc7XG5cbmV4cG9ydCB7IFJ1biB9IGZyb20gJ0B3b3JrZmxvdy9jb3JlL3J1bnRpbWUvcnVuJztcbmV4cG9ydCB7IHN0YXJ0IH0gZnJvbSAnQHdvcmtmbG93L2NvcmUvcnVudGltZS9zdGFydCc7XG5cbmNvbnN0IHdvcmtmbG93U3R1YiA9IChpdGVtOiBzdHJpbmcpID0+IHtcbiAgdGhyb3cgbmV3IEVycm9yKFxuICAgIGBUaGUgd29ya2Zsb3cgZW52aXJvbm1lbnQgZG9lc24ndCBhbGxvdyB0aGlzIHJ1bnRpbWUgdXNhZ2Ugb2YgJHtpdGVtfS4gTW92ZSB0aGlzIGNhbGwgdG8gYSBzdGVwIGZ1bmN0aW9uIChcInVzZSBzdGVwXCIpIG9yIGNhbGwgaXQgb3V0c2lkZSB0aGUgd29ya2Zsb3cgY29udGV4dC5gXG4gICk7XG59O1xuXG5leHBvcnQgY29uc3QgZ2V0UnVuID0gKCkgPT4gd29ya2Zsb3dTdHViKCdnZXRSdW4nKTtcbmV4cG9ydCBjb25zdCBnZXRIb29rQnlUb2tlbiA9ICgpID0+IHdvcmtmbG93U3R1YignZ2V0SG9va0J5VG9rZW4nKTtcbmV4cG9ydCBjb25zdCByZXN1bWVIb29rID0gKCkgPT4gd29ya2Zsb3dTdHViKCdyZXN1bWVIb29rJyk7XG5leHBvcnQgY29uc3QgcmVzdW1lV2ViaG9vayA9ICgpID0+IHdvcmtmbG93U3R1YigncmVzdW1lV2ViaG9vaycpO1xuZXhwb3J0IGNvbnN0IHJ1blN0ZXAgPSAoKSA9PiB3b3JrZmxvd1N0dWIoJ3J1blN0ZXAnKTtcbiJdfQ==

package/docs/cookbook/{common-patterns → advanced}/child-workflows.mdx

@@ -16,7 +16,7 @@ Child workflows are the right choice when:
 - **You want massive fan-out.** Spawning 50 or 500 children is practical because each runs on its own infrastructure.
 - **You need per-item observability.** Each child workflow has its own run ID, status, and event log for monitoring.
 
-For simpler cases where steps share a single event log, use [direct await composition](/docs/foundations/common-patterns#direct-await-flattening) instead.
+For simpler cases where steps share a single event log, use [direct await composition](/cookbook/common-patterns/workflow-composition#direct-await-flattening) instead.
 
 ## Basic pattern: spawn and poll
 

package/docs/cookbook/advanced/distributed-abort-controller.mdx

@@ -0,0 +1,318 @@
+---
+title: Distributed Abort Controller
+description: A distributed AbortController that uses durable workflows for cross-process cancellation signaling.
+type: guide
+summary: Build a distributed abort controller that uses workflow streams and hooks to propagate cancellation signals across process boundaries.
+---
+
+Use this pattern when you need an `AbortController`-like interface that works across distributed systems. The controller uses a durable workflow to coordinate cancellation — calling `.abort()` on one machine triggers the `.signal` on any other machine.
+
+## When to use this
+
+- **Cross-process cancellation** — Cancel a long-running operation from a different server, worker, or edge function
+- **Durable cancellation** — The abort signal persists even if the process that created it crashes
+- **UI stop buttons** — Let users cancel operations running on the server from the browser
+- **Timeout coordination** — The built-in TTL auto-expires stale controllers
+
+## Pattern
+
+The `DistributedAbortController` class encapsulates a workflow that:
+1. Accepts a user-provided unique ID (like a chat ID or task ID)
+2. Creates or reconnects to an existing workflow using that ID
+3. Waits for a hook signal OR TTL expiration
+4. Writes a cancellation message to the run's stream when triggered
+
+### Core Implementation
+
+```typescript lineNumbers
+import { defineHook, getWritable, sleep } from "workflow";
+import { start, getRun, getHookByToken } from "workflow/api";
+
+// Default TTL: 24 hours
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+// Default grace period: 1 hour (keeps hook alive after abort for late subscribers)
+const DEFAULT_GRACE_MS = 60 * 60 * 1000;
+
+// Hook to trigger the abort signal
+export const abortHook = defineHook<{ reason?: string }>();
+
+// The abort message written to the stream
+export type AbortMessage = {
+  type: "abort";
+  reason?: string;
+  expired?: boolean;
+};
+
+// Helper to create a consistent hook token from the user ID
+function getAbortToken(id: string): string {
+  return `abort:${id}`;
+}
+
+// Step function that writes the abort message to the stream
+async function writeAbortSignal(reason?: string, expired?: boolean) {
+  "use step";
+
+  const writable = getWritable<AbortMessage>();
+  const writer = writable.getWriter();
+  try {
+    await writer.write({ type: "abort", reason, expired });
+  } finally {
+    writer.releaseLock();
+  }
+  await writable.close();
+}
+
+// Workflow that waits for abort or TTL expiration
+export async function abortControllerWorkflow(
+  id: string,
+  ttlMs: number,
+  graceMs: number
+) {
+  "use workflow";
+
+  const startTime = Date.now();
+  const hook = abortHook.create({ token: getAbortToken(id) });
+
+  // Race: manual abort OR TTL expiration // [!code highlight]
+  const result = await Promise.race([
+    hook.then((payload) => ({
+      reason: payload.reason,
+      expired: false,
+    })),
+    sleep(`${ttlMs}ms`).then(() => ({
+      reason: "Controller expired",
+      expired: true,
+    })),
+  ]);
+
+  await writeAbortSignal(result.reason, result.expired);
+
+  // Only sleep through grace period on TTL expiration (keeps hook alive for late subscribers). // [!code highlight]
+  // Manual aborts complete immediately.
+  if (result.expired) {
+    const elapsed = Date.now() - startTime;
+    const remainingTime = graceMs - (elapsed - ttlMs);
+    if (remainingTime > 0) {
+      await sleep(`${remainingTime}ms`); // [!code highlight]
+    }
+  }
+
+  return { aborted: true, reason: result.reason, expired: result.expired };
+}
+
+/**
+ * A distributed abort controller that works across process boundaries.
+ * Uses a semantically meaningful ID (like a chat ID or task ID) to coordinate.
+ */
+export class DistributedAbortController {
+  private id: string;
+  readonly runId: string;
+
+  private constructor(id: string, runId: string) {
+    this.id = id;
+    this.runId = runId;
+  }
+
+  /**
+   * Creates or reconnects to a distributed abort controller.
+   * If a controller with this ID already exists, reconnects to it.
+   * Otherwise, starts a new workflow.
+   *
+   * @param id - A unique, semantically meaningful ID (e.g., "chat:123")
+   * @param options.ttlMs - Time-to-live in ms (default: 24 hours)
+   * @param options.graceMs - Grace period after abort (default: 1 hour)
+   */
+  static async create( // [!code highlight]
+    id: string,
+    options: { ttlMs?: number; graceMs?: number } = {}
+  ): Promise<DistributedAbortController> {
+    const { ttlMs = DEFAULT_TTL_MS, graceMs = DEFAULT_GRACE_MS } = options;
+    const token = getAbortToken(id);
+
+    // Try to find an existing run with this hook token
+    const existingHook = await getHookByToken(token).catch(() => null); // [!code highlight]
+
+    if (existingHook) {
+      // Reconnect to existing controller
+      return new DistributedAbortController(id, existingHook.runId);
+    }
+
+    // Create a new workflow
+    const run = await start(abortControllerWorkflow, [id, ttlMs, graceMs]); // [!code highlight]
+    return new DistributedAbortController(id, run.runId);
+  }
+
+  /**
+   * Triggers the abort signal.
+   * Idempotent: safe to call multiple times or after the workflow has completed.
+   */
+  async abort(reason?: string): Promise<void> { // [!code highlight]
+    try {
+      await abortHook.resume(getAbortToken(this.id), { reason });
+    } catch (error) {
+      const msg = error instanceof Error ? error.message.toLowerCase() : '';
+      if (msg.includes('not found') || msg.includes('expired')) {
+        return;
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Returns an AbortSignal that fires when abort() is called or TTL expires.
+   * The signal fires with a reason indicating what triggered it.
+   */
+  get signal(): AbortSignal { // [!code highlight]
+    const run = getRun<{ aborted: boolean; reason?: string; expired?: boolean }>(this.runId);
+    const controller = new AbortController();
+    const readable = run.getReadable<AbortMessage>();
+
+    (async () => {
+      const reader = readable.getReader();
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          if (value.type === "abort") {
+            const reason = value.expired
+              ? `${value.reason} (expired)`
+              : value.reason;
+            controller.abort(reason);
+            break;
+          }
+        }
+      } catch (error) {
+        if (!controller.signal.aborted) {
+          controller.abort(
+            error instanceof Error ? error.message : "Stream read failed"
+          );
+        }
+      } finally {
+        reader.releaseLock();
+      }
+    })();
+
+    return controller.signal;
+  }
+}
+```
+
+### Usage: Single Process
+
+```typescript lineNumbers
+import { DistributedAbortController } from "./distributed-abort-controller";
+
+// Create a controller with a meaningful ID
+const controller = await DistributedAbortController.create("chat:user-123");
+
+// Get the signal and use it with fetch
+const signal = controller.signal;
+const response = await fetch("https://api.example.com/long-operation", {
+  signal,
+});
+
+// Later: abort the operation
+await controller.abort("User cancelled");
+```
+
+### Usage: Cross-Process Coordination
+
+```typescript lineNumbers
+import { DistributedAbortController } from "./distributed-abort-controller";
+
+// Process A: Create the controller
+const controller = await DistributedAbortController.create("task:build-123");
+// start long operation using controller.signal...
+
+// Process B: Reconnect and abort (no run ID sharing needed!)
+const sameController = await DistributedAbortController.create("task:build-123"); // [!code highlight]
+await sameController.abort("Cancelled by admin");
+
+// Process C: Reconnect and listen
+const anotherRef = await DistributedAbortController.create("task:build-123");
+anotherRef.signal.addEventListener("abort", (e) => {
+  console.log("Task was cancelled:", (e.target as AbortSignal).reason);
+});
+```
+
+### Custom TTL
+
+```typescript lineNumbers
+import { DistributedAbortController } from "./distributed-abort-controller";
+
+// Short-lived controller for a quick operation (5 minutes)
+const shortLived = await DistributedAbortController.create("quick-task", {
+  ttlMs: 5 * 60 * 1000,
+});
+
+// Long-lived controller for batch jobs (7 days)
+const longLived = await DistributedAbortController.create("batch-job", {
+  ttlMs: 7 * 24 * 60 * 60 * 1000,
+});
+
+// When TTL expires, the signal fires with expired reason
+shortLived.signal.addEventListener("abort", (e) => {
+  const reason = (e.target as AbortSignal).reason;
+  if (reason?.includes("expired")) {
+    console.log("Controller expired, cleaning up...");
+  }
+});
+```
+
+### API Route for Remote Abort
+
+```typescript lineNumbers
+import { DistributedAbortController } from "@/lib/distributed-abort-controller";
+
+export async function POST(
+  request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params;
+  const { reason } = await request.json();
+
+  const controller = await DistributedAbortController.create(id);
+  await controller.abort(reason || "Cancelled via API");
+
+  return Response.json({ success: true });
+}
+```
+
+### Client Cancel Button
+
+```tsx lineNumbers
+"use client";
+
+export function CancelButton({ taskId }: { taskId: string }) {
+  const handleCancel = async () => {
+    await fetch(`/api/abort/${taskId}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ reason: "User clicked cancel" }),
+    });
+  };
+
+  return (
+    <button type="button" onClick={handleCancel}>
+      Cancel Operation
+    </button>
+  );
+}
+```
+
+## Tips
+
+- **Use semantic IDs** — Use meaningful IDs like `chat:123` or `task:abc` instead of random UUIDs
+- **Create is idempotent** — Calling `create()` with the same ID reconnects to the existing controller
+- **TTL auto-cleanup** — Workflows self-terminate after TTL expires; no manual cleanup needed
+- **Signal is a getter** — Each access to `.signal` creates a new listener; cache it if needed
+- **One-shot** — Once aborted or expired, the workflow completes; create a new controller for new operations
+
+## Key APIs
+
+- [`defineHook()`](/docs/api-reference/workflow/define-hook) — type-safe hook for the abort trigger
+- [`getWritable()`](/docs/api-reference/workflow/get-writable) — write abort messages to the stream
+- [`sleep()`](/docs/api-reference/workflow/sleep) — TTL timer for auto-expiration
+- [`start()`](/docs/api-reference/workflow-api/start) — start the abort controller workflow
+- [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token) — find existing run by hook token
+- [`getRun()`](/docs/api-reference/workflow-api/get-run) — reconnect to the workflow's readable stream

package/docs/cookbook/advanced/meta.json

@@ -1,10 +1,9 @@
 {
   "title": "Advanced",
   "pages": [
+    "child-workflows",
+    "distributed-abort-controller",
     "serializable-steps",
-    "durable-objects",
-    "isomorphic-packages",
-    "custom-serialization",
     "publishing-libraries"
   ]
 }

package/docs/cookbook/advanced/publishing-libraries.mdx

@@ -5,6 +5,8 @@ type: guide
 summary: Learn how to build, export, and test npm packages that ship workflow and step functions — including package.json exports, re-exporting for stable workflow IDs, keeping step I/O clean, and integration testing.
 ---
 
+import { File, Folder, Files } from "fumadocs-ui/components/files";
+
 <Callout>
 This is an advanced guide for library authors who want to publish reusable workflow functions as npm packages. It assumes familiarity with `"use workflow"`, `"use step"`, and the workflow execution model.
 </Callout>
@@ -13,23 +15,37 @@ This is an advanced guide for library authors who want to publish reusable workf
 
 A workflow library follows a standard TypeScript package layout with a dedicated `workflows/` directory. Each workflow file exports one or more workflow functions that consumers can import and pass to `start()`.
 
-```
-my-media-lib/
-├── src/
-│   ├── index.ts              # Package entry point
-│   ├── types.ts              # Shared types
-│   ├── workflows/
-│   │   ├── index.ts          # Re-exports all workflows
-│   │   ├── transcode.ts      # Workflow: transcode a video
-│   │   └── generate-thumbnails.ts
-│   └── lib/
-│       └── api-client.ts     # Internal helpers (NOT steps)
-├── test-server/
-│   └── workflows.ts          # Re-export for integration tests
-├── tsup.config.ts
-├── package.json
-└── tsconfig.json
-```
+<Files>
+  <Folder name="my-media-lib" defaultOpen>
+    <Folder name="src" defaultOpen>
+      <File name="index.ts" />
+      <File name="types.ts" />
+      <Folder name="workflows" defaultOpen>
+        <File name="index.ts" />
+        <File name="transcode.ts" />
+        <File name="generate-thumbnails.ts" />
+      </Folder>
+      <Folder name="lib" defaultOpen>
+        <File name="api-client.ts" />
+      </Folder>
+    </Folder>
+    <Folder name="test-server" defaultOpen>
+      <File name="workflows.ts" />
+    </Folder>
+    <File name="tsup.config.ts" />
+    <File name="package.json" />
+    <File name="tsconfig.json" />
+  </Folder>
+</Files>
+
+Key files:
+
+- **`src/index.ts`** — Package entry point. Exports the public API.
+- **`src/types.ts`** — Shared TypeScript types.
+- **`src/workflows/index.ts`** — Re-exports every workflow so consumers can pull them in under one specifier (see [Entry Points and Exports](#entry-points-and-exports)).
+- **`src/workflows/*.ts`** — One file per workflow function (e.g. `transcode.ts`, `generate-thumbnails.ts`).
+- **`src/lib/`** — Internal helpers. Plain async code, *not* marked with `"use workflow"` or `"use step"`.
+- **`test-server/workflows.ts`** — Re-export file used by integration tests (see [Testing Workflow Libraries](#testing-workflow-libraries)).
 
 ### Entry Points and Exports
 
@@ -126,7 +142,7 @@ When you publish a workflow library, every step function's inputs and outputs ar
 
 ### 1. Everything Must Be Serializable
 
-Step inputs and outputs must be serializable. The workflow runtime supports a rich set of types beyond plain JSON — including `Date`, `RegExp`, `Map`, `Set`, `BigInt`, `Uint8Array`, `URL`, `Error`, and class instances that implement [custom class serialization](/docs/cookbook/advanced/custom-serialization). See the [serialization reference](/docs/foundations/serialization) for the full list of supported types. Do not pass or return:
+Step inputs and outputs must be serializable. The workflow runtime supports a rich set of types beyond plain JSON — including `Date`, `RegExp`, `Map`, `Set`, `BigInt`, `Uint8Array`, `URL`, `Error`, and class instances that implement [custom class serialization](/docs/foundations/serialization#custom-class-serialization). See the [serialization reference](/docs/foundations/serialization) for the full list of supported types. Do not pass or return:
 
 - Functions or closures
 - `WeakRef`, `WeakMap`, or `WeakSet`
@@ -226,7 +242,18 @@ pnpm vitest run --config vitest.workflowsdk.config.ts
 
 ## Working With and Without Workflow Installed
 
-If your library should work both as a standalone package and inside Workflow SDK, declare `workflow` as an optional peer dependency:
+Some libraries want to be useful to consumers who *aren't* using Workflow SDK at all — the library picks up durable behavior when a workflow runtime is present and falls back to plain async execution otherwise.
+
+<Callout type="info">
+Two rules for isomorphic packages:
+
+1. **Any runtime reference to the `workflow` package must be loaded via dynamic `import("workflow")` inside a try/catch.** A static top-level import makes the module fail to load for consumers who haven't installed workflow.
+2. **The `"use workflow"` and `"use step"` directives are safe to keep in your library source.** When a consumer compiles your code with the Workflow SDK toolchain (via the [re-export pattern](#re-exporting-for-workflow-id-stability) above), the SWC plugin transforms them into durable-execution glue. When they're not compiled — plain Node, plain tests, a consumer without the runtime — they are just string expression statements and run as no-ops.
+</Callout>
+
+### Optional peer dependency
+
+Declare `workflow` as an **optional** peer so consumers without the runtime aren't forced to install it:
 
 ```json
 {
@@ -241,22 +268,52 @@ If your library should work both as a standalone package and inside Workflow SDK
 }
 ```
 
-Use dynamic imports and runtime detection so your library gracefully degrades when workflow is not installed:
+### Runtime detection
+
+Wrap a dynamic `import("workflow")` in try/catch. If either the module isn't installed *or* `getWorkflowMetadata()` throws (call site isn't inside a workflow run), fall through to the standalone path.
 
 ```typescript lineNumbers
-async function isWorkflowRuntime(): Promise<boolean> {
+async function getWorkflowRunId(): Promise<string | null> { // [!code highlight]
   try {
     const wf = await import("workflow");
-    if (typeof wf.getWorkflowMetadata !== "function") return false;
-    wf.getWorkflowMetadata(); // [!code highlight]
-    return true;
+    const { workflowRunId } = wf.getWorkflowMetadata();
+    return workflowRunId;
   } catch {
-    return false;
+    return null;
   }
 }
 ```
 
-See [Isomorphic Packages](/docs/cookbook/advanced/isomorphic-packages) for the full pattern including feature detection, dynamic imports, and dual-path execution.
+### A concrete use case: replay-safe idempotency keys
+
+A payments utility that uses the workflow run ID as a Stripe idempotency key when available, and a fresh UUID otherwise:
+
+{/* @skip-typecheck - depends on getWorkflowRunId defined in the previous block */}
+```typescript lineNumbers
+export async function processPayment(amount: number, currency: string) {
+  const runId = await getWorkflowRunId();
+  const idempotencyKey = runId ?? crypto.randomUUID(); // [!code highlight]
+
+  const res = await fetch("https://api.stripe.com/v1/charges", {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${process.env.STRIPE_SECRET_KEY}`,
+      "Idempotency-Key": idempotencyKey, // [!code highlight]
+    },
+    body: new URLSearchParams({ amount: String(amount), currency }),
+  });
+  return res.json();
+}
+```
+
+When called from inside a workflow run, the step wrapping this utility gets a stable idempotency key across replays — Stripe dedupes retries for free. When called from a plain Node.js process, it behaves like any other function and a fresh UUID is generated.
+
+### In production
+
+Packages in the wild built on Workflow SDK:
+
+- **[`@mux/ai`](https://github.com/muxinc/ai)** — Reusable video AI workflows (summaries, chapters, content moderation, translation, embeddings) exported with `"use workflow"` / `"use step"` directives. In a standard Node environment the directives are no-ops and the SDK runs as a plain async library; in a Workflow SDK environment the consumer's compiler transforms them into durable, resumable steps with automatic retries and observability. Written up in detail in [*How Mux shipped durable video workflows with their @mux/ai SDK*](https://vercel.com/blog/how-mux-shipped-durable-video-workflows-with-their-mux-ai-sdk) on the Vercel blog.
+- **World ID** — Human-in-the-loop "proof of human" primitive for agent workflows. Developers drop a World ID step into any workflow to require a zero-knowledge cryptographic proof that a real, unique human authorized a specific action (deploy approvals, large payments, sensitive data access, etc.). Because it runs as a workflow step, every verification is durable, replay-safe, and viewable inside the run's execution timeline — giving you a provable audit record of which human approved what. Available on npm and announced in [*World ID for agents: Browserbase, Exa, Okta, and Vercel*](https://world.org/blog/announcements/browserbase-exa-okta-world-id-for-agentic-web) on the World blog.
 
 ## Checklist
 

package/docs/cookbook/advanced/serializable-steps.mdx

@@ -1,17 +1,28 @@
 ---
 title: Serializable Steps
-description: Wrap non-serializable objects (like AI model providers) inside step functions so they can cross the workflow boundary.
+description: Wrap non-serializable third-party objects (like AI model providers) inside step factory functions so they can cross the workflow boundary.
 type: guide
-summary: Return a callback from a step to defer provider initialization, making non-serializable AI SDK models work inside durable workflows.
+summary: Return a callback from a step to defer construction of a non-owned class (AI SDK models, cloud SDK clients) until execution time, making them usable inside durable workflows.
+related:
+  - /docs/foundations/serialization
+  - /docs/foundations/serialization#custom-class-serialization
+  - /docs/api-reference/workflow/use-step
 ---
 
 <Callout>
 This is an advanced guide. It dives into workflow internals and is not required reading to use workflow.
 </Callout>
 
+## When to use this pattern
+
+Workflow functions run inside a sandboxed VM where every value that crosses a function boundary must be serializable. There are two ways to get a non-serializable object across that boundary, depending on whether you own the class:
+
+- **You own the class** — implement the [`WORKFLOW_SERIALIZE` / `WORKFLOW_DESERIALIZE` protocol](/docs/foundations/serialization#custom-class-serialization). The instance becomes a first-class serializable value: you can pass it as a workflow input, return it from a step, and call `"use step"` instance methods on it directly. This is the right tool when the class is yours to modify.
+- **You don't own the class** — you can't add methods to `openai("gpt-4o")` from `@ai-sdk/openai` or `new S3Client({...})` from `@aws-sdk/client-s3`. Instead, wrap construction in a `"use step"` factory function and pass the factory across the boundary. That's what this page covers.
+
 ## The Problem
 
-Workflow functions run inside a sandboxed VM where every value that crosses a function boundary must be serializable (JSON-safe). AI SDK model providers — `openai("gpt-4o")`, `anthropic("claude-sonnet-4-20250514")`, etc. — return complex objects with methods, closures, and internal state. Passing one directly into a step causes a serialization error.
+AI SDK model providers — `openai("gpt-4o")`, `anthropic("claude-sonnet-4-20250514")`, etc. — return complex objects with methods, closures, and internal state. Passing one directly into a step causes a serialization error, and you can't bolt `WORKFLOW_SERIALIZE` onto a third-party class.
 
 ```typescript lineNumbers
 import { openai } from "@ai-sdk/openai";
@@ -133,3 +144,4 @@ async function uploadFile(
 - [`"use step"`](/docs/api-reference/workflow/use-step) — marks a function for extraction and serialization
 - [`"use workflow"`](/docs/api-reference/workflow/use-workflow) — declares the orchestrator function
 - [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) — accepts a model factory for durable AI agent streaming
+- [Custom class serialization](/docs/foundations/serialization#custom-class-serialization) — the companion pattern for classes you own (`WORKFLOW_SERIALIZE` / `WORKFLOW_DESERIALIZE`)